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. Table 13-1 summarizes the clock command:

Table 13-1. The clock command

clock clicks ?-milliseconds?	A high resolution counter. The precision is milliseconds, if specified (Tcl 8.4), or a system-dependent value.
clock format value ?-format str?	Formats a clock value according to str. See Table 13-2.
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]
=> Fri Nov 22 4:09:14 PM PST 2002

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 summarizes the clock formatting strings:

Table 13-2. clock format 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).
%C	First two digits of the four-digit year (19 or 20).
%d	Day of month (01 – 31).
%D	Date as %m/%d/%y (e.g., 02/19/97).
%e	Day of month (1 – 31), no leading zeros.
%h	Abbreviated month name.
%H	Hour in 24-hour format (00 – 23).
%I	Hour in 12-hour format (01 – 12).
%j	Day of year (001 – 366).
%k	Hour in 24-hour format, without leading zeros (0 - 23).
%l	Hour in 12-hour format, without leading zeros (1 – 12).
%m	Month number (01 – 12).
%M	Minute (00 – 59).
%n	Inserts a newline.
%p	AM/PM indicator.
%r	Time as %I:%M:%S %p (e.g., 02:39:29 PM).
%R	Time as %H:%M (e.g., 14:39).
%s	Seconds since the epoch.
%S	Seconds (00 – 59).
%t	Inserts a tab.
%T	Time as %H:%M:%S (e.g., 14:34:29).
%u	Weekday number (Monday = 1, Sunday = 7).
%U	Week of year (00 – 52) when Sunday starts the week.
%V	Week of year according to ISO-8601 rules (Week 1 contains January 4).
%w	Weekday number (Sunday = 0).
%W	Week of year (00 – 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.

The clock clicks command returns the value of the system's highest resolution clock. The units of the clicks is milliseconds if -milliseconds is specified, otherwise it is undefined. The main use of this command is to measure the relative time of different performance tuning trials. The -milliseconds flag was added in Tcl 8.4. Example 13-1 shows how to calibrate the clicks value by counting 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 228
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.

Tcl implements the standard interpretation of two-digit year values, which is that 70–99 are 1970–1999, 00–69 are 2000–2069. 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. Some 64-bit systems (such as Solaris 8 64-bit) use 64-bit integers for the system clock, which Tcl 8.4 supports. This extends the recognized range into the billions of years.

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]
=> 2931690644

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"]
=> Fri Nov 29 10:30:44 PM PST 2002
clock format [clock scan "10:30:44 PM -1 week"]
Fri Nov 15 10:30:44 PM PST 2002

You can also use tomorrow, yesterday, today, now, last, this, next, and ago, as modifiers.

clock format [clock scan "3 years ago"]
=> Mon Nov 22 4:18:34 PM PST 1999

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
=> Sat Nov 23 12:19:13 AM GMT 2002
clock format [clock seconds] -gmt false
=> Fri Nov 22 4:19:35 PM PST 2002