'''[[`[clock] scan`] scans a string and extracts a time.



** See Also **

   [Tcl Chatroom] ,2013-10-19:   [KBK] dishes some of the details of [[`[clock] scan`]

   [Time and date validator], [sbron]:   



** Documentation **

   [http://www.tcl.tk/man/tcl/TclCmd/clock.htm%|%official reference]:   



** Synopsis **


    :   '''clock scan''' ''inputString'' ?''-option value...''?



** Description **

Parses the time described in ''inputString'' and returns the number of seconds
(since the start of the Unix epoch) that that time corresponds to. Supported
''-option''s are:

    :   '''-base''' ''time''
    :   '''-format''' ''format''
    :   '''-gmt''' ''boolean''
    :   '''-locale''' ''localeName''
    :   '''-timezone''' ''zoneName''



** Incomplete Times **

[[`clock scan`] does what it can to make sense of incomplete times, but the
results can be surprising.  If possible, make sure at least the year, month,
and day are part of the string to scan.  If the results of scanning an
incomplete or impossible date like `March 0` or `Arpil 34` are surprising,
carefully re-read the seven rules that are applied, in order of preference, to
make sense of a time.



** Removing /etc/localtime **

[JMN] 2007-11-14:

On FreeBSD - you can configure the timezone to UTC by removing
`/etc/localtime`.  I don't know if this is actually a legitimate way to set it
to UTC, but it was the only way I knew of until now, and it does seem to cause
a problem with Tcl's clock scan.

======
% clock scan "2007-11-01" -format "%Y-%m-%d"
time value too large/small to represent
% clock scan "2007-11-01" -format "%Y-%m-%d"
1193875200
======

The call always fails the first time in each process, and seems to work for all
calls thereafter. (including in other interps)


If you configure the timezone to UTC by instead making `/etc/localtime` a link
to `/usr/share/zoneinfo/Etc/UTC`  the problem doesn't occur.  I have a number
of systems configured with no `/etc/localtime` - but I guess I'll change that
now in light of this.

This issue also shows up in the FAQ on http://amsn-project.net/ . 

Is a missing `/etc/localtime` something that clock scan should be able to
handle - or is it would it be considered an OS configuration issue?

[DKF]: Ultimately, I'd consider this to be OS misconfiguration as it feels like
stating that the system has ''no'' local timezone instead of that it is UTC.

----

[TCV] 2013-02-11:  providing only a year (e.g. `%Y`) in the format string will
''not'' produce the time for the first day of that year. Similarly, providing
only the year and month (e.g. `%m/%Y`) in the format string will ''not''
produce the time for the first day of that month. In both of these cases, you
will instead get the time corresponding to midnight on the current day.
Currently in `clock scan`, to avoid this behaviour, day level accuracy is
required; this can be done by specifying:

   * year and day-of-year
   * week and day-of-week
   * month and day-of-month

So in the examples above, just adding to the input string `01` for each of the
missing fields will give you the time you're interested in (first day of the
year or month, respectively).

Examples:

======
# Things you might think would behave differently.

% clock scan 2000 -format %Y
1360558800
% clock scan 10/1900 -format %m/%Y
1360558800

# They're actually midnight today!

% clock format [clock seconds] -format %Y-%m-%d
2013-02-11
% clock format 1360558800 -format %Y-%m-%d %H:%M:%S
2013-02-11 00:00:00

# A simple solution. That's what I really meant!

% clock scan "2000-01-01" -format "%Y-%m-%d"
946702800
% clock scan "1900-10-01" -format "%Y-%m-%d"
-2185387200
======



** Misc **



<<categories>> Command | Date and Time