The clock Command
The clock command has facilities for getting the current time, formatting time values, and scanning printed time strings to get an integer time value. The clock command was added in Tcl 7.5. Table 13-1 summarizes the clock command:
Table 13-1. The clock command.
|clock clicks||A system-dependent high resolution counter.|
|clock format value ?-format str?||Formats a clock value according to str.|
|clock scan string ?-base clock? ?-gmt boolean?||Parses date string and return seconds value. The clock value determines the date.|
|clock seconds||Returns the current time in seconds.|
The following command prints the current time:
clock format [clock seconds]
=> Sun Nov 24 14:57:04 1996
The clock seconds command returns the current time, in seconds since a starting epoch. The clock format command formats an integer value into a date string. It takes an optional argument that controls the format. The format strings contains % keywords that are replaced with the year, month, day, date, hours, minutes, and seconds, in various formats. The default string is:
%a %b %d %H:%M:%S %Z %Y
Tables 13-2 and 13-3 summarize the clock formatting strings:
Table 13-2. Clock formatting keywords.
|%%||Inserts a %. |
|%a||Abbreviated weekday name (Mon, Tue, etc.). |
|%A||Full weekday name (Monday, Tuesday, etc.). |
|%b||Abbreviated month name (Jan, Feb, etc.). |
|%B||Full month name. |
|%c||Locale specific date and time (e.g., Nov 24 16:00:59 1996).|
|%d||Day of month (01 ?31). |
|%H||Hour in 24-hour format (00 ?23). |
|%I||Hour in 12-hour format (01 ?12). |
|%j||Day of year (001 ?366). |
|%m||Month number (01 ?12). |
|%M||Minute (00 ?59). |
|%p||AM/PM indicator. |
|%S||Seconds (00 ?59). |
|%U||Week of year (00 ?52) when Sunday starts the week.|
|%w||Weekday number (Sunday = 0). |
|%W||Week of year (01 ?52) when Monday starts the week. |
|%x||Locale specific date format (e.g., Feb 19 1997).|
|%X||Locale specific time format (e.g., 20:10:13).|
|%y||Year without century (00 ?99).|
|%Y||Year with century (e.g. 1997).|
|%Z||Time zone name.|
Table 13-3. UNIX-specific clock formatting keywords.
|%D||Date as %m/%d/%y (e.g., 02/19/97).|
|%e||Day of month (1 ?31), no leading zeros. |
|%h||Abbreviated month name. |
|%n||Inserts a newline. |
|%r||Time as %I:%M:%S %p (e.g., 02:39:29 PM).|
|%R||Time as %H:%M (e.g., 14:39).|
|%t||Inserts a tab. |
|%T||Time as %H:%M:%S (e.g., 14:34:29).|
The clock clicks command returns the value of the system's highest resolution clock. The units of the clicks are not defined. The main use of this command is to measure the relative time of different performance tuning trials. The following command counts the clicks per second over 10 seconds, which will vary from system to system:
Example 13-1 Calculating clicks per second.
set t1 [clock clicks]
after 10000 ;# See page 218
set t2 [clock clicks]
puts "[expr ($t2 - $t1)/10] Clicks/second"
=> 1001313 Clicks/second
The clock scan command parses a date string and returns a seconds value. The command handles a variety of date formats. If you leave off the year, the current year is assumed.
Year 2000 Compliance
Tcl implements the standard interpretation of two-digit year values, which is that 70?9 are 1970?999, 00?9 are 2000?069. Versions of Tcl before 8.0 did not properly deal with two-digit years in all cases. Note, however, that Tcl is limited by your system's time epoch and the number of bits in an integer. On Windows, Macintosh, and most UNIX systems, the clock epoch is January 1, 1970. A 32-bit integer can count enough seconds to reach forward into the year 2037, and backward to the year 1903. If you try to clock scan a date outside that range, Tcl will raise an error because the seconds counter will overflow or underflow. In this case, Tcl is just reflecting limitations of the underlying system.
If you leave out a date, clock scan assumes the current date. You can also use the -base option to specify a date. The following example uses the current time as the base, which is redundant:
clock scan "10:30:44 PM" -base [clock seconds]
The date parser allows these modifiers: year, month, fortnight (two weeks), week, day, hour, minute, second. You can put a positive or negative number in front of a modifier as a multiplier. For example:
clock format [clock scan "10:30:44 PM 1 week"]
=> Sun Dec 01 22:30:44 1996
clock format [clock scan "10:30:44 PM -1 week"]
Sun Nov 17 22:30:44 1996
You can also use tomorrow, yesterday, today, now, last, this, next, and ago, as modifiers.
clock format [clock scan "3 years ago"]
=> Wed Nov 24 17:06:46 1993
Both clock format and clock scan take a -gmt option that uses Greenwich Mean Time. Otherwise, the local time zone is used.
clock format [clock seconds] -gmt true
=> Sun Nov 24 09:25:29 1996
clock format [clock seconds] -gmt false
=> Sun Nov 24 17:25:34 1996