Previous section   Next section

Practical Programming in Tcl & Tk, Third Edition
By Brent B. Welch

Table of Contents
Chapter 13.  Reflection and Debugging

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 clicksA 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 secondsReturns 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 %.
%aAbbreviated weekday name (Mon, Tue, etc.).
%AFull weekday name (Monday, Tuesday, etc.).
%bAbbreviated month name (Jan, Feb, etc.).
%BFull month name.
%cLocale specific date and time (e.g., Nov 24 16:00:59 1996).
%dDay of month (01 ?31).
%HHour in 24-hour format (00 ?23).
%IHour in 12-hour format (01 ?12).
%jDay of year (001 ?366).
%mMonth number (01 ?12).
%MMinute (00 ?59).
%pAM/PM indicator.
%SSeconds (00 ?59).
%UWeek of year (00 ?52) when Sunday starts the week.
%wWeekday number (Sunday = 0).
%WWeek of year (01 ?52) when Monday starts the week.
%xLocale specific date format (e.g., Feb 19 1997).
%XLocale specific time format (e.g., 20:10:13).
%yYear without century (00 ?99).
%YYear with century (e.g. 1997).
%ZTime zone name.

Table 13-3. UNIX-specific clock formatting keywords.
%DDate as %m/%d/%y (e.g., 02/19/97).
%eDay of month (1 ?31), no leading zeros.
%hAbbreviated month name.
%nInserts a newline.
%rTime as %I:%M:%S %p (e.g., 02:39:29 PM).
%RTime as %H:%M (e.g., 14:39).
%tInserts a tab.
%TTime 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]
=> 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"]
=> 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

      Previous section   Next section