diff options
Diffstat (limited to 'doc/clock.n')
| -rw-r--r-- | doc/clock.n | 1016 |
1 files changed, 784 insertions, 232 deletions
diff --git a/doc/clock.n b/doc/clock.n index b23e976..31b919c 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -1,252 +1,822 @@ '\" -'\" Copyright (c) 1992-1995 Karl Lehenbauer and Mark Diekhans. -'\" Copyright (c) 1995-1997 Sun Microsystems, Inc. -'\" Copyright (c) 1998-1999 Scriptics Corporation -'\" Copyright (c) 2002 ActiveState Corporation +'\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. '\" -'\" This documentation is derived from the time and date facilities of -'\" TclX, by Mark Diekhans and Karl Lehenbauer. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: clock.n,v 1.17 2004/05/24 23:31:42 dkf Exp $ -'\" .so man.macros -.TH clock n 8.4 Tcl "Tcl Built-In Commands" +.TH "clock" n 8.5 Tcl "Tcl commands" .BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -clock \- Obtain and manipulate time -.SH SYNOPSIS -\fBclock \fIoption\fR ?\fIarg arg ...\fR? +.SH "NAME" +clock \- Obtain and manipulate dates and times +.SH "SYNOPSIS" +package require \fBTcl 8.5\fR +.sp +\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR? +.sp +\fBclock clicks\fR ?\fI-option\fR? +.sp +\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...? +.sp +\fBclock microseconds\fR +.sp +\fBclock milliseconds\fR +.sp +\fBclock scan\fR \fIinputString\fR ?\fI-option value\fR...? +.sp +\fBclock seconds\fR +.sp .BE - -.SH DESCRIPTION +.SH "DESCRIPTION" .PP -This command performs one of several operations that may obtain -or manipulate strings or values that represent some notion of -time. The \fIoption\fR argument determines what action is carried -out by the command. The legal \fIoptions\fR (which may be -abbreviated) are: +The \fBclock\fR command performs several operations that obtain and +manipulate values that represent times. The command supports several +subcommands that determine what action is carried out by the command. .TP -\fBclock clicks\fR ?\fI\-option\fR? -If no \fIoption\fR argument is supplied, returns a high-resolution +\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR? +Adds a (possibly negative) offset to a time that is expressed as an +integer number of seconds. See \fBCLOCK ARITHMETIC\fR for a full description. +.TP +\fBclock clicks\fR ?\fI-option\fR? +If no \fI-option\fR argument is supplied, returns a high-resolution time value as a system-dependent integer value. The unit of the value is system-dependent but should be the highest resolution clock available -on the system such as a CPU cycle counter. -.TP -.VS 8.5 -If the \fIoption\fR argument is \fB\-milliseconds\fR, then the value is -guaranteed to be an approximate count of milliseconds returned as -a wide integer; the rule should -always hold that \fBclock clicks -milliseconds\fR divided by 1000 is the -same as \fBclock seconds\fR. -.TP -It the \fIoption\fR argument is \fB-microseconds\fR, then the value is -guaranteed to be an approximate count of microseconds returned as a wide -integer; the rule should hold that \fBclock clicks -microseconds\fR -divided by 1000 is the same as \fBclock clicks -milliseconds\fR. -.TP -On some hardware, the counts of milliseconds and microseconds may diverge -from the system clock for short periods; the reason is that they can -be derived from different sources, and a complex procedure is required -to calibrate them. Moreover, Tcl makes an effort never to have the clock -leap forward nor appear to run backward, preferring instead to slow or -speed up the clock frequency slightly until it's back in synchronization. -For this reason, most Tcl programmers need never worry about such -phenomena as leap seconds. -.VE 8.5 -.TP -\fBclock format \fIclockValue\fR ?\fB\-format \fIstring\fR? ?\fB\-gmt \fIboolean\fR? -Converts an integer time value, typically returned by -\fBclock seconds\fR, \fBclock scan\fR, or the \fBatime\fR or \fBmtime\fR -options of the \fBfile\fR command, to human-readable -form. If the \fB\-format\fR argument is present the next argument is a -string that describes how the date and time are to be formatted. -Field descriptors consist of a \fB%\fR followed by a field -descriptor character. All other characters are copied into the result. -Valid field descriptors are: -.RS -.IP \fB%%\fR -Insert a %. -.IP \fB%a\fR -Abbreviated weekday name (Mon, Tue, etc.). -.IP \fB%A\fR -Full weekday name (Monday, Tuesday, etc.). -.IP \fB%b\fR -Abbreviated month name (Jan, Feb, etc.). -.IP \fB%B\fR -Full month name. -.IP \fB%c\fR -Locale specific date and time. The format for date and time -in the default "C" locale on Unix is "%a %b %d %H:%M:%S %Y". -On Windows, this value is the locale specific long date and time, as -specified in the Regional Options control panel settings. -.IP \fB%C\fR -First two digits of the four-digit year (19 or 20). -.IP \fB%d\fR -Day of month (01 - 31). -'\" Since the inclusion of compat/strftime.c, %D, %e, %h should work on all -'\" platforms. -.IP \fB%D\fR -Date as %m/%d/%y. -.IP \fB%e\fR -Day of month (1 - 31), no leading zeros. -.IP \fB%g\fR -The ISO8601 year number corresponding to the ISO8601 week (%V), expressed -as a two-digit year-of-the-century, with leading zero if necessary. -.IP \fB%G\fR -The ISO8601 year number corresponding to the ISO8601 week (%V), expressed -as a four-digit number. -.IP \fB%h\fR -Abbreviated month name. -.IP \fB%H\fR -Hour in 24-hour format (00 - 23). -.IP \fB%I\fR -Hour in 12-hour format (01 - 12). -.IP \fB%j\fR -Day of year (001 - 366). -.IP \fB%k\fR -Hour in 24-hour format, without leading zeros (0 - 23). -.IP \fB%l\fR -Hour in 12-hour format, without leading zeros (1 - 12). -.IP \fB%m\fR -Month number (01 - 12). -.IP \fB%M\fR -Minute (00 - 59). -.IP \fB%n\fR -Insert a newline. -.IP \fB%p\fR -AM/PM indicator. -.IP \fB%r\fR -Time in a locale-specific "meridian" format. The "meridian" -format in the default "C" locale is "%I:%M:%S %p". -.IP \fB%R\fR -Time as %H:%M. -.IP \fB%s\fR -Count of seconds since the epoch, expressed as a decimal integer. -.IP \fB%S\fR -Seconds (00 - 59). -.IP \fB%t\fR -Insert a tab. -.IP \fB%T\fR -Time as %H:%M:%S. -.IP \fB%u\fR -Weekday number (Monday = 1, Sunday = 7). -.IP \fB%U\fR -Week of year (00 - 52), Sunday is the first day of the week. -.IP \fB%V\fR -Week of year according to ISO-8601 rules. Week 1 of a given -year is the week containing 4 January. -.IP \fB%w\fR -Weekday number (Sunday = 0, Saturday = 6). -.IP \fB%W\fR -Week of year (00 - 52), Monday is the first day of the week. -.IP \fB%x\fR -Locale specific date format. The format for a date in the default "C" -locale for Unix is "%m/%d/%y". -On Windows, this value is the locale specific short date format, as -specified in the Regional Options control panel settings. -.IP \fB%X\fR -Locale specific 24-hour time format. The format for a -24-hour time in the default "C" locale for Unix is "%H:%M:%S". -On Windows, this value is the locale specific time format, as -specified in the Regional Options control panel settings. -.IP \fB%y\fR -Year without century (00 - 99). -.IP \fB%Y\fR -Year with century (e.g. 1990) -.IP \fB%Z\fR -Time zone name. -.RE +on the system such as a CPU cycle counter. See \fBHIGH RESOLUTION TIMERS\fR for a full description. +.sp +If the \fI-option\fR argument is \fI-milliseconds\fR, then the command +is synonymous with \fBclock milliseconds\fR (see below). This +usage is obsolete, and \fBclock milliseconds\fR is to be +considered the preferred way of obtaining a count of milliseconds. .sp -'\" All the field descriptors should be portable now that -'\" compat/strftime.c is in place, with the possible exception -'\" of the time zone name. -'\".RS -'\"In addition, the following field descriptors may be supported on some -'\"systems (e.g. Unix but not Windows): -'\".IP \fB%D\fR -'\"Date as %m/%d/%y. -'\".IP \fB%e\fR -'\"Day of month (1 - 31), no leading zeros. -'\".IP \fB%h\fR -'\"Abbreviated month name. -'\".IP \fB%n\fR -'\"Insert a newline. -'\".IP \fB%r\fR -'\"Time as %I:%M:%S %p. -'\".IP \fB%R\fR -'\"Time as %H:%M. -'\".IP \fB%t\fR -'\"Insert a tab. -'\".IP \fB%T\fR -'\"Time as %H:%M:%S. -'\".RE -'\".sp +It the \fI-option\fR argument is \fI-microseconds\fR, then the command +is synonymous with \fBclock microseconds\fR (see below). This +usage is obsolete, and \fBclock microseconds\fR is to be +considered the preferred way of obtaining a count of microseconds. +.TP +\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...? +Formats a time that is expressed as an integer number of seconds into a format +intended for consumption by users or external programs. +See \fBFORMATTING TIMES\fR for a full description. +.TP +\fBclock microseconds\fR +Returns the current time as an integer number of microseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. +.TP +\fBclock milliseconds\fR +Returns the current time as an integer number of milliseconds. See \fBHIGH RESOLUTION TIMERS\fR for a full description. +.TP +\fBclock scan\fR \fIinputString\fR ?\fI-option value\fR...? +Scans a time that is expressed as a character string and produces an +integer number of seconds. +See \fBSCANNING TIMES\fR for a full description. +.TP +\fBclock seconds\fR +Returns the current time as an integer number of seconds. +.SH "PARAMETERS" +.TP +\fIcount\fR +An integer representing a count of some unit of time. See +\fBCLOCK ARITHMETIC\fR for the details. +.TP +\fItimeVal\fR +An integer value passed to the \fBclock\fR command that represents an +absolute time as a number of seconds from the \fIepoch time\fR of +1 January 1970, 00:00 UTC. Note that the count of seconds does not +include any leap seconds; seconds are counted as if each UTC day has +exactly 86400 seconds. Tcl responds to leap seconds by speeding or +slowing its clock by a tiny fraction for some minutes until it is +back in sync with UTC; its data model does not represent minutes that +have 59 or 61 seconds. +.TP +\fIunit\fR +One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR, +\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or +any unique prefix of such a word. Used in conjuction with \fIcount\fR +to identify an interval of time, for example, \fI3 seconds\fR or +\fI1 year\fR. +.SH "OPTIONS" +.TP +\fB-base\fR time +Specifies that any relative times present in a \fBclock scan\fR command +are to be given relative to \fItime\fR. \fItime\fR must be expressed as +a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC. +.TP +\fB-format\fR format +Specifies the desired output format for \fBclock format\fR or the +expected input format for \fBclock scan\fR. The \fIformat\fR string consists +of any number of characters other than the per-cent sign ('\fI%\fR') +interspersed with any number of \fIformat groups\fR, which are two-character +sequences beginning with the per-cent sign. The permissible format groups, +and their interpretation, are described under \fBFORMAT GROUPS\fR. +.TP +\fB-gmt\fR boolean +If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR, +\fBclock format\fR or \fBclock scan\fR should be processed in +UTC. If \fIboolean\fR is false, the processing defaults to the local time +zone. This usage is obsolete; the correct current usage is to +specify the UTC time zone with '\fB-timezone\fR \fI:UTC\fR' or any of +the equivalent ways to specify it. +.TP +\fB-locale\fR localeName +Specifies that locale-dependent scanning and formatting (and date arithmetic +for dates preceding the adoption of the Gregorian calendar) is to be done in +the locale identified by \fIlocaleName\fR. The locale name may be any of +the locales acceptable to the \fBmsgcat\fR command, or it may be the special +name \fIsystem\fR, which represents the current locale of the process, or +the null string, which represents Tcl's default locale. +.sp +The effect of locale on scanning and formatting is discussed in the +descriptions of the individual format groups under \fBFORMAT GROUPS\fR. +The effect of locale on clock arithmetic is discussed under +\fBCLOCK ARITHMETIC\fR. +.TP +\fB-timezone\fR zoneName +Specifies that clock arithmetic, formatting, and scanning are to be done +according to the rules for the time zone specified by \fIzoneName\fR. +The permissible values, and their interpretation, are discussed under +\fBTIME ZONES\fR. +On subcommands that expect a \fB-timezone\fR argument, the default +is to use the \fIcurrent time zone\fR. The current time zone is +determined, in order of preference, by: .RS -If the \fB\-format\fR argument is not specified, the format string -\fB"%a %b %d %H:%M:%S %Z %Y"\fR is used. If the \fB\-gmt\fR argument -is present the next argument must be a boolean which if true specifies -that the time will be formatted as Greenwich Mean Time. If false -then the local timezone will be used as defined by the operating -environment. +.IP [1] +the environment variable \fBTCL_TZ\fR. +.IP [2] +the environment variable \fBTZ\fR. +.IP [3] +on Windows systems, the time zone settings from the Control Panel. .RE +If none of these is present, the C \fBlocaltime\fR and \fBmktime\fR +functions are used to attempt to convert times between local and +Greenwich. On 32-bit systems, this approach is likely to have bugs, +particularly for times that lie outside the window (approximately the +years 1902 to 2037) that can be represented in a 32-bit integer. +.SH "CLOCK ARITHMETIC" +The \fBclock add\fR command performs clock arithmetic on a value +(expressed as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC) +given as its first argument. The remaining arguments (other than the +possible \fB-timezone\fR, \fB-locale\fR and \fB-gmt\fR options) +are integers and keywords in alternation, where the keywords are chosen +from \fBseconds\fR, \fBminutes\fR, \fBhours\fR, +\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or +any unique prefix of such a word. +.PP +Addition of seconds, minutes and hours is fairly straightforward; +the given time increment (times sixty for minutes, or 3600 for hours) +is simply added to the \fItimeVal\fR given +to the \fBclock add\fR command. The result is interpreted as +a nominal number of seconds from the Epoch. +.PP +Surprising results +may be obtained when crossing a point at which a leap second is +inserted or removed; the \fBclock add\fR command simply ignores +leap seconds and therefore assumes that times come in sequence, +23:59:58, 23:59:59, 00:00:00. (This assumption is handled by +the fact that Tcl's model of time reacts to leap seconds by speeding +or slowing the clock by a minuscule amount until Tcl's time +is back in step with the world. +.PP +The fact that adding and subtracting hours is defined in terms of +absolute time means that it will add fixed amounts of time in time zones +that observe summer time (Daylight Saving Time). For example, +the following code sets the value of \fBx\fR to \fB04:00:00\fR because +the clock has changed in the interval in question. +.CS +set s [clock scan {2004-10-30 05:00:00} \\ + -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] +set a [clock add $s 24 hours -timezone :America/New_York] +set x [clock format $a \\ + -format {%H:%M:%S} -timezone :America/New_York] +.CE +.PP +Adding and subtracting days and weeks is accomplished by converting +the given time to a calendar day and time of day in the appropriate +time zone and locale. The requisite number of days (weeks are converted +to days by multiplying by seven) is added to the calendar day, and +the date and time are then converted back to a count of seconds from +the epoch time. +.PP +Adding and subtracting a given number of days across the point that +the time changes at the start or end of summer time (Daylight Saving Time) +results in the \fIsame local time\fR on the day in question. For +instance, the following code sets the value of \fBx\fR to \fB05:00:00\fR. +.CS +set s [clock scan {2004-10-30 05:00:00} \\ + -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] +set a [clock add $s 1 day -timezone :America/New_York] +set x [clock format $a \\ + -format {%H:%M:%S} -timezone :America/New_York] +.CE +.PP +In cases of ambiguity, where the same local time happens twice +on the same day, the earlier time is used. In cases where the conversion +yields an impossible time (for instance, 02:30 during the Spring +Daylight Saving Time change using US rules), the time is converted +as if the clock had not changed. Thus, the following code +will set the value of \fBx\fR to \fB03:30:00\fR. +.CS +set s [clock scan {2004-04-03 02:30:00} \\ + -format {%Y-%m-%d %H:%M:%S} -timezone :America/New_York] +set a [clock add $s 1 day -timezone :America/New_York] +set x [clock format $a \\ + -format {%H:%M:%S} -timezone :America/New_York] +.CE +.PP +Adding a given number of days or weeks works correctly across the conversion +between the Julian and Gregorian calendars; the omitted days are skipped. +The following code sets \fBz\fR to \fB1752-09-14\fR. +.CS +set x [clock scan 1752-09-02 -format %Y-%m-%d -locale en_US] +set y [clock add $x 1 day -locale en_US] +set z [clock format $y -format %Y-%m-%d -locale en_US] +.CE +.PP +In the bizarre case that adding the given number of days yields a date +that does not exist because it falls within the dropped days of the +Julian-to-Gregorian conversion, the date is converted as if it was +on the Julian calendar. +.PP +Adding a number of months, or a number of years, is similar; it +converts the given time to a calendar date and time of day. It then +adds the requisite number of months or years, and reconverts the resulting +date and time of day to an absolute time. +.PP +If the resulting date is impossible because the month has too few days +(for example, when adding 1 month to 31 January), the last day of the +month is substituted. Thus, adding 1 month to 31 January will result in +28 February in a common year or 29 February in a leap year. +.PP +The rules for handling anomalies relating to summer time and to the +Gregorian calendar are the same when adding/subtracting months and +years as they are when adding/subtracting days and weeks. +.PP +If multiple \fIcount unit\fR pairs are present on the command, they +are evaluated consecutively, from left to right. +.SH "HIGH RESOLUTION TIMERS" +Most of the subcommands supported by the \fBclock\fR command deal with +times represented as a count of seconds from the epoch time, and this is the +representation that \fBclock seconds\fR returns. There are three exceptions, +which are all intended for use where higher-resolution times are required. +\fBclock milliseconds\fR returns the count of milliseconds from the +epoch time, and \fBclock microseconds\fR returns the count of microseconds +from the epoch time. In addition, there js a \fBclock clicks\fR command +that returns a platform-dependent high-resolution timer. Unlike +\fBclock seconds\fR and \fBclock milliseconds\fR, the value +of \fBclock clicks\fR is not guaranteed to be tied to any fixed +epoch; it is simply intended to be the most precise interval timer +available, and is intended only for relative timing studies such as +benchmarks. +.SH "FORMATTING TIMES" +The \fBclock format\fR command produces times for display to a user +or writing to an external medium. The command accepts times that are +expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC, +as returned by \fBclock seconds\fR, \fBclock scan\fR, \fBclock add\fR, +\fBfile atime\fR or \fBfile mtime\fR. +.PP +If a \fB-format\fR option is present, the following argument is +a string that specifies how the date and time are to be formatted. +The string consists +of any number of characters other than the per-cent sign ('\fI%\fR') +interspersed with any number of \fIformat groups\fR, which are two-character +sequences beginning with the per-cent sign. The permissible format groups, +and their interpretation, are described under \fBFORMAT GROUPS\fR. +.PP +If a \fB-timezone\fR option is present, the following +argument is a string that specifies the time zone in which the date and time +are to be formatted. As an alternative to \fB-timezone\fR \fI:UTC\fR, +the obsolete usage \fB-gmt\fR \fItrue\fR may be used. See +\fBTIME ZONES\fR for the permissible variants for the time zone. +.PP +If a \fB-locale\fR option is present, the following argument is +a string that specifies the locale in which the time is to be formatted, +in the same format that is used for the \fBmsgcat\fR command. Note +that the default, if \fB-locale\fR is not specified, is the root locale +\fB{}\fR rather than the current locale. The current locale may +be obtained by using \fB-locale\fR \fBcurrent\fR. +In addition, some platforms support a \fBsystem\fR locale that +reflects the user's current choices. For instance, on Windows, the +format that the user has selected from dates and times in the Control +Panel can be obtained by using the \fBsystem\fR locale. On +platforms that do not define a user selection of date and time formats +separate from \fBLC_TIME\fR, \fB-locale\fR \fBsystem\fR is +synonymous with \fB-locale\fR \fBcurrent\fR. +.SH "SCANNING TIMES" +The \fBclock scan\fR command accepts times that are formatted as +strings and converts them to counts of seconds from the epoch time +of 1 January 1970, 00:00 UTC. It normally takes a \fB-format\fR +option that is followed by a string describing +the expected format of the input. (See +\fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR +without such an argument.) The string consists of any number of +characters other than the per-cent sign ('\fI%\fR'), +interspersed with any number of \fIformat groups\fR, which are two-character +sequences beginning with the per-cent sign. The permissible format groups, +and their interpretation, are described under \fBFORMAT GROUPS\fR. +.PP +If a \fB-timezone\fR option is present, the following +argument is a string that specifies the time zone in which the date and time +are to be interpreted. As an alternative to \fB-timezone\fR \fI:UTC\fR, +the obsolete usage \fB-gmt\fR \fItrue\fR may be used. See +\fBTIME ZONES\fR for the permissible variants for the time zone. +.PP +If a \fB-locale\fR option is present, the following argument is +a string that specifies the locale in which the time is to be interpreted, +in the same format that is used for the \fBmsgcat\fR command. Note +that the default, if \fB-locale\fR is not specified, is the root locale +\fB{}\fR rather than the current locale. The current locale may +be obtained by using \fB-locale\fR \fBcurrent\fR. +In addition, some platforms support a \fBsystem\fR locale that +reflects the user's current choices. For instance, on Windows, the +format that the user has selected from dates and times in the Control +Panel can be obtained by using the \fBsystem\fR locale. On +platforms that do not define a user selection of date and time formats +separate from \fBLC_TIME\fR, \fB-locale\fR \fBsystem\fR is +synonymous with \fB-locale\fR \fBcurrent\fR. +.PP +If a \fB-base\fR option is present, the following argument is +a time (expressed in seconds from the epoch time) that is used as +a \fIbase time\fR for interpreting relative times. If no +\fB-base\fR option is present, the base time is the current time. +.PP +Scanning of times in fixed format works by determining three things: +the date, the time of day, and the time zone. These three are then +combined into a point in time, which is returned as the number of seconds +from the epoch. +.PP +Before scanning begins, the format string is preprocessed +to replace \fB%c\fR, \fB%Ec\fR, \fB%x\fR, \fB%Ex\fR, +\fB%X\fR. \fB%Ex\fR, \fB%r\fR, \fB%R\fR, \fB%T\fR, +\fB%D\fR, \fB%EY\fR and \fB%+\fR format groups with counterparts +that are appropriate to the current locale and contain none of the +above groups. For instance, \fB%D\fR will (in the \fBen_US\fR locale) +be replaced with \fB%m/%d/%Y\fR. +.PP +The date is determined according to the fields that are present in the +preprocessed format string. In order of preference: +.IP [1] +If the string contains a \fB%s\fR format group, representing +seconds from the epoch, that group is used to determine the date. +.IP [2] +If the string contains a \fB%J\fR format group, representing +the Julian Day Number, that group is used to determine the date. +.IP [3] +If the string contains a complete set of format groups specifying +century, year, month, and day of month; century, year, and day of year; +or ISO8601 fiscal year, week of year, and day of week; those groups are +combined and used to determine the date. If more than one complete +set is present, the one at the rightmost position in the string is +used. +.IP [4] +If the string lacks a century but contains a set of format +groups specifying year of century, month and day of month; year of +century and day of year; or two-digit ISO8601 fiscal year, week of year, +and day of week; those groups are +combined and used to determine the date. If more than one complete +set is present, the one at the rightmost position in the string is +used. The year is presumed to lie in the range 1938 to 2037 inclusive. +.IP [5] +If the string entirely lacks any specification for the year, +but contains a set of format groups specifying month and day of month, +day of year, or week of year and day of week, those groups are +combined and used to determine the date. If more than one complete +set is present, the one at the rightmost position in the string is +used. The year is determined by interpreting the base time in the given +time zone. +.IP [6] +If the string contains none of the above sets, but has a day +of the month or day of the week, the day of the month or day of the week +are used to determine the date by interpreting the base time in the +given time zone and returning the given day of the current week or month. +(The week runs from Monday to Sunday, ISO8601-fashion.) If both day +of month and day of week are present, the day of the month takes +priority. +.IP [7] +If none of the above rules results in a usable date, the date +of the base time in the given time zone is used. +.PP +The time is also determined according to the fields that are present in the +preprocessed format string. In order of preference: +.IP [1] +If the string contains a \fB%s\fR format group, representing +seconds from the epoch, that group determines the time of day. +.IP [2] +If the string contains either an hour on the 24-hour clock +or an hour on the 12-hour clock plus an AM/PM indicator, that hour determines +the hour of the day. If the string further contains a group specifying +the minute of the hour, that group combines with the hour. If the string +further contains a group specifying the second of the minute, that group +combines with the hour and minute. +.IP [3] +If the string contains neither a \fB%s\fR format group nor +a group specifying the hour of the day, then midnight (\fB00:00\fR, the start +of the given date) is used. +The time zone is determined by either the \fB-timezone\fR or \fB-gmt\fR +options, or by using the current time zone. +.PP +If a format string lacks a \fB%z\fR or \fB%Z\fR format group, +it is possible for the time to be ambiguous because it appears twice +in the same day, once without and once with Daylight Saving Time. +If this situation occurs, the first occurrence of the time is chosen. +(For this reason, it is wise to have the input string contain the +time zone when converting local times. This caveat does not apply to +UTC times.) +.SH "FORMAT GROUPS" +The following format groups are recognized by the \fBclock scan\fR and +\fBclock format\fR commands. +.TP +\fB%a\fR +On output, receives an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day +of the week in the given locale. On input, matches the name of the day +of the week in the given locale (in either abbreviated or full form, or +any unique prefix of either form). +.TP +\fB%A\fR +On output, receives the full name (\fIe.g.,\fR \fBMonday\fR) of the day +of the week in the given locale. On input, matches the name of the day +of the week in the given locale (in either abbreviated or full form, or +any unique prefix of either form). +.TP +\fB%b\fR +On output, receives an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name +of the month in the given locale. On input, matches the name of the month +in the given locale (in either abbreviated or full form, or +any unique prefix of either form). +.TP +\fB%B\fR +On output, receives the full name (\fIe.g.,\fR \fBJanuary\fR) +of the month in the given locale. On input, matches the name of the month +in the given locale (in either abbreviated or full form, or +any unique prefix of either form). +.TP +\fB%c\fR +On output, receives a localized representation of date and time of day; +the localized representation is expected to use the Gregorian calendar. +On input, matches whatever %c produces. +.TP +\fB%C\fR +On output, receives the number of the century in Indo-Arabic numerals. +On input, matches one or two digits, possibly with leading whitespace, +that are expected to be the number of the century. +.TP +\fB%d\fR +On output, produces the number of the day of the month, as two decimal +digits. On input, matches one or two digits, possibly with leading +whitespace, that are expected to be the number of the day of the month. +.TP +\fB%D\fR +This format group is synonymous with \fB%m/%d/%Y\fR. It should be +used only in exchanging data within the \fBen_US\fR locale, since +other locales typically do not use this order for the fields of the date. .TP -\fBclock scan \fIdateString\fR ?\fB\-base \fIclockVal\fR? ?\fB\-gmt \fIboolean\fR? -Convert \fIdateString\fR to an integer clock value (see \fBclock seconds\fR). -This command can parse and convert virtually any standard date and/or time -string, which can include standard time zone mnemonics. If only a time is -specified, the current date is assumed. If the string does not contain a -time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR +\fB%e\fR +On output, produces the number of the day of the month, as one or +two decimal digits (with a leading blank for one-digit dates). +On input, matches one or two digits, possibly with leading +whitespace, that are expected to be the number of the day of the month. +.TP +\fB%Ec\fR +On output, produces a locale-dependent representation of the date and +time of day in the locale's alternative calendar. On input, matches +whatever %Ec produces. The locale's alternative calendar need not +be the Gregorian calendar. +.TP +\fB%EC\fR +On output, produces a locale-dependent name of an era in the locale's +alternative calendar. On input, matches the name of the era or any +unique prefix. +.TP +\fB%Ex\fR +On output, produces a locale-dependent representation of the date +in the locale's alternative calendar. On input, matches +whatever %Ex produces. The locale's alternative calendar need not +be the Gregorian calendar. +.TP +\fB%EX\fR +On output, produces a locale-dependent representation of the +time of day in the locale's alternative numerals. On input, matches +whatever %EX produces. +.TP +\fB%Ey\fR +On output, produces a locale-dependent number of the year of the era +in the locale's alternative calendar and numerals. On input, matches +such a number. +.TP +\fB%EY\fR +On output, produces a representation of the year in the locale's +alternative calendar and numerals. On input, matches what \fB%EY\fR +produces. Often synonymous with \fB%EC%Ey\fR. +.TP +\fB%g\fR +On output, produces a two-digit year number suitable for use with +the week-based ISO8601 calendar; that is, the year number corresponds +to the week number produced by \fB%V\fR. On input, accepts such +a two-digit year number, possibly with leading whitespace. +.TP +\fB%G\fR +On output, produces a four-digit year number suitable for use with +the week-based ISO8601 calendar; that is, the year number corresponds +to the week number produced by \fB%V\fR. On input, accepts such +a four-digit year number, possibly with leading whitespace. +.TP +\fB%h\fR +This format group is synonymous with \fB%b\fR. +.TP +\fB%H\fR +On output, produces a two-digit number giving the hour of the day +(00-23) on a 24-hour clock. On input, accepts such a number. +.TP +\fB%I\fR +On output, produces a two-digit number giving the hour of the day +(12-11) on a 12-hour clock. On input, accepts such a number. +.TP +\fB%j\fR +On output, produces a three-digit number giving the day of the year +(001-366). On input, accepts such a number. +.TP +\fB%J\fR +On output, produces a string of digits giving the Julian Day Number. +On input, accepts a string of digits and interprets it as a Julian Day Number. +The Julian Day Number is a count of the number of calendar days +that have elapsed since 1 January, 4713 BCE of the proleptic +Julian calendar. The epoch time of 1 January 1970 corresponds +to Julian Day Number 2440588. +.TP +\fB%k\fR +On output, produces a one- or two-digit number giving the hour of the day +(0-23) on a 24-hour clock. On input, accepts such a number. +.TP +\fB%l\fR +On output, produces a one- or two-digit number giving the hour of the day +(12-11) on a 12-hour clock. On input, accepts such a number. +.TP +\fB%m\fR +On output, produces the number of the month (01-12) with exactly two +digits. On input, accepts two digits and interprets them as the number +of the month. +.TP +\fB%M\fR +On output, produces the number of the minute of the hour (00-59) +with exactly two digits. On input, accepts two digits and interprets them +as the number of the minute of the hour. +.TP +\fB%N\fR +On output, produces the number of the month (1-12) with one or two digits. +digits. On input, accepts one or two digits, possibly with leading whitespace, +and interprets them as the number of the month. +.TP +\fB%Od\fR, \fB%Oe\fR, \fB%OH\fR, \fB%OI\fR, \fB%Ok\fR, \fB%Ol\fR, \fB%Om\fR, \fB%OM\fR, \fB%OS\fR, \fB%Ou\fR, \fB%Ow\fR, \fB%Oy\fR +All of these format groups are synonymous with their counterparts +without the '\fBO\fR', except that the string is produced and parsed in the +locale-dependent alternative numerals. +.TP +\fB%p\fR +On output, produces an indicator for the part of the day, \fBA.M.\fR +or \fBP.M.\fR, appropriate to the given locale. If the script of the +given locale supports multiple letterforms, uppercase is preferred. +On input, matches the representation \fBA.M.\fR or \fBP.M.\fR in +the given locale, in either case. +.TP +\fB%P\fR +On output, produces an indicator for the part of the day, \fBA.M.\fR +or \fBP.M.\fR, appropriate to the given locale. If the script of the +given locale supports multiple letterforms, lowercase is preferred. +On input, matches the representation \fBA.M.\fR or \fBP.M.\fR in +the given locale, in either case. +.TP +\fB%Q\fR +This format group is reserved for internal use within the Tcl library. +.TP +\fB%r\fR +On output, produces a locale-dependent time of day representation on a +12-hour clock. On input, accepts whatever \fB%r\fR produces. +.TP +\fB%R\fR +On output, produces a locale-dependent time of day representation on a +24-hour clock. On input, accepts whatever \fB%R\fR produces. +.TP +\fB%s\fR +On output, simply formats the \fItimeVal\fR argument as a decimal +integer and inserts it into the output string. On input, accepts +a decimal integer and uses is as the time value without any further +processing. Since \fB%s\fR uniquely determines a point in time, it +overrides all other input formats. +.TP +\fB%S\fR +On output, produces a two-digit number of the second of the minute +(00-59). On input, accepts two digits and uses them as the second of the +minute. +.TP +\fB%t\fR +On output, produces a TAB character. On input, matches a TAB character. +.TP +\fB%T\fR +Synonymous with \fB%H:%M:%S\fR. +.TP +\fB%u\fR +On output, produces the number of the day of the week +(\fB1\fR-Monday, \fB7\fR-Sunday). On input, accepts a single digit and +interprets it as the day of the week. Sunday may be either \fB0\fR or +\fB7\fR. +.TP +\fB%U\fR +On output, produces the ordinal number of the week of the year +(00-53). The first Sunday of the year is the first day of week 01. On +input accepts two digits which are otherwise ignored. This format +group is never used in determining an input date. This interpretation +of the week of the year was once common in US banking but is now +largely obsolete. See \fB%V\fR for the ISO8601 week number. +.TP +\fB%V\fR +On output, produces the number of the ISO8601 week as a two digit +number (01-53). Week 01 is the week containing January 4; or the first +week of the year containing at least 4 days; or the week containing +the first Thursday of the year (the three statements are +equivalent). Each week begins on a Monday. On input, accepts the +ISO8601 week number. +.TP +\fB%w\fR +On output, produces a week number (00-53) within the year; week 01 +begins on the first Monday of the year. On input, accepts two digits, +which are otherwise ignored. This format group is never used in +determining an input date. It is not the ISO8601 week number; that +week is produced and accepted by \fB%V\fR. +.TP +\fB%x\fR +On output, produces the date in a locale-dependent representation. On +input, accepts whatever \fB%x\fR produces and is used to determine +calendar date. +.TP +\fB%X\fR +On output, produces the time of day in a locale-dependent +representation. On input, accepts whatever \fB%X\fR produces and is used +to determine time of day. +.TP +\fB%y\fR +On output, produces the two-digit year of the century. On input, +accepts two digits, and is used to determine calendar date. The +date is presumed to lie between 1938 and 2037 inclusive. Note +that \fB%y\fR does not yield a year appropriate for use with the ISO8601 +week number \fB%V\fR; programs should use \fB%g\fR for that purpose. +.TP +\fB%Y\fR +On output, produces the four-digit calendar year. On input, +accepts four digits and may be used to determine calendar date. Note +that \fB%Y\fR does not yield a year appropriate for use with the ISO8601 +week number \fB%V\fR; programs should use \fB%G\fR for that purpose. +.TP +\fB%z\fR +On output, produces the current time zone, expressed in hours and +minutes east (+hhmm) or west (-hhmm) of Greenwich. On input, accepts a +time zone specifier (see \fBTIME ZONES\fR below) that will be used to +determine the time zone. +.TP +\fB%Z\fR +On output, produces the current time zone's name, possibly +translated to the given locale. On input, accepts a time zone +specifier (see \fBTIME ZONES\fR below) that will be used to determine the +time zone. This option should, in general, be used on input only when +parsing RFC822 dates. Other uses are fraught with ambiguity; for +instance, the string \fBBST\fR may represent British Summer Time or +Brazilian Standard Time. It is recommended that date/time strings for +use by computers use numeric time zones instead. +.TP +\fB%%\fR +On output, produces a literal '\fB%\fR' charater. On input, matches +a literal '\fB%\fR' character. +.TP +\fB%+\fR +Synonymous with '\fB%a %b %e %H:%M:%S %Z %Y\fR'. +.SH "TIME ZONES" +When the \fBclock\fR command is processing a local time, it has several +possible sources for the time zone to use. In order of preference, they +are: +.IP [1] +A time zone specified inside a string being parsed and matched by a \fB%z\fR +or \fB%Z\fR format group. +.IP [2] +A time zone specified with the \fB-timezone\fR option to the \fBclock\fR +command (or, equivalently, by \fB-gmt\fR \fB1\fR). +.IP [3] +A time zone specified in an environment variable \fBTCL_TZ\fR. +.IP [4] +A time zone specified in an environment variable \fBTZ\fR. +.IP [5] +The local time zone from the Control Panel on Windows systems. +.IP [6] +The C library's idea of the local time zone, as defined by the +\fBmktime\fR and \fBlocaltime\fR functions. +.PP +Whatever the source of the time zone string, the same set of rules +is used to parse it. First, if it was obtained from a \fB%z\fR +or \fB%Z\fR format group, it is checked to see if it is one of +the strings, +.CS + gmt ut utc bst wet wat at + nft nst ndt ast adt est edt + cst cdt mst mdt pst pdt yst + ydt hst hdt cat ahst nt idlw + cet cest met mewt mest swt sst + eet eest bt it zp4 zp5 ist + zp6 wast wadt jt cct jst cast + cadt east eadt gst nzt nzst nzdt + idle +.CE +If it is a string in the above list, it designates a known +time zone, and is interpreted as such. +.PP +The next check is for a string beginning with a colon. +If the time zone begins with a colon, it is one of a +standardized list of names like \fB:America/New_York\fR +that give the rules for various locales. A complete list +of the location names is too lengthy to be listed here. +On most Tcl installations, the definitions of the locations +are to be found in named files in the directory +"\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR". On some Unix systems, these +files are omitted, and the definitions are instead +obtained from system files in "\fI/usr/share/zoneinfo\fR", +"\fI/usr/share/lib/zoneinfo\fR" or "\fI/usr/local/etc/zoneinfo\fR". +As a special case, the name \fB:localtime\fR refers to +the local time zone as defined by the C library. +.PP +A string consisting of a plus or minus sign followed by +four or six decimal digits is interpreted as an offset in +hours, minutes, and seconds (if six digits are present) from +UTC. The plus sign denotes a sign east of Greenwich; +the minus sign one west of Greenwich. +.PP +A string conforming to the Posix specification of the \fBTZ\fR +environment variable will be recognized. The specification +may be found at +\fIhttp://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR. +.PP +Any other string is processed by prefixing a colon and attempting +to use it as a location name, as above. +.SH "LOCALIZATION" +Developers wishing to localize the date and time formatting and parsing +are referred to \fIhttp://www.tcl.tk/cgi-bin/tct/tip/173\fR for a +specification. +.SH "FREE FORM SCAN" +If the \fBclock scan\fR command is invoked without a \fB-format\fR +option, then it requests a \fIfree-form scan.\fR \fI +This form of scan is deprecated.\fR The reason for the deprecation +is that there are too many ambiguities. (Does the string '2000' +represent a year, a time of day, or a quantity?) No set of rules +for interpreting free-form dates and times has been found to +give unsurprising results in all cases. +.PP +If free-form scan is used, only the \fB-base\fR and \fB-gmt\fR +options are accepted. The \fB-timezone\fR and \fB-locale\fR +options will result in an error if \fB-format\fR is not supplied. +.PP +For the benefit of users who need to understand legacy code that +uses free-form scan, the documentation for how free-form scan +interprets a string is included here: +.PP +If only a time is +specified, the current date is assumed. If the \fIinputString\fR +does not contain a +time zone mnemonic, the local time zone is assumed, unless the \fB-gmt\fR argument is true, in which case the clock value is calculated assuming that the specified time is relative to Greenwich Mean Time. \fB-gmt\fR, if specified, affects only the computed time value; it does not impact the interpretation of \fB-base\fR. -.sp -If the \fB\-base\fR flag is specified, the next argument should contain +.PP +If the \fB-base\fR flag is specified, the next argument should contain an integer clock value. Only the date in this value is used, not the time. This is useful for determining the time on a specific day or doing other date-relative conversions. -.sp -The \fIdateString\fR consists of zero or more specifications of the +.PP +The \fIinputString\fR argument consists of zero or more specifications of the following form: -.RS .TP \fItime\fR -A time of day, which is of the form: \fIhh\fR?\fI:mm\fR?\fI:ss\fR?? -?\fImeridian\fR? ?\fIzone\fR? or \fIhhmm \fR?\fImeridian\fR? -?\fIzone\fR?. If no meridian is specified, \fIhh\fR is interpreted on +A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR +or \fBhhmm ?meridian? ?zone?\fR +If no meridian is specified, \fBhh\fR is interpreted on a 24-hour clock. .TP \fIdate\fR A specific month and day with optional year. The -acceptable formats are \fImm/dd\fR?\fI/yy\fR?, \fImonthname dd\fR -?, \fIyy\fR?, \fIdd monthname \fR?\fIyy\fR?, \fIday, dd monthname -yy\fR, \fI?CC?yymmdd\fR, \fI?CC?yy-mm-dd\fR, \fIdd-monthname-?CC?yy\fR. +acceptable formats are "\fBmm/dd?/yy?\fR", "\fBmonthname dd?, yy?\fR", +"\fBday, dd monthname ?yy?\fR", "\fBdd monthname yy\fR", +"\fB?CC?yymmdd\fR", and "\fBdd-monthname-?CC?yy\fR. The default year is the current year. If the year is less than 100, we treat the years 00-68 as 2000-2068 and the years 69-99 as 1969-1999. Not all platforms can represent the years 38-70, so an error may result if these years are used. .TP \fIISO 8601 point-in-time\fR -An ISO 8601 point-in-time specification, such as \fICCyymmddThhmmss\fR, where -T is the literal T, \fICCyymmdd hhmmss\fR, or -\fICCyymmddThh:mm:ss\fR. +An ISO 8601 point-in-time specification, such as \fBCCyymmddThhmmss\fR, +where \fBT\fR is the literal T, "\fBCCyymmdd hhmmss\fR", or +\fBCCyymmddThh:mm:ss\fR. .TP \fIrelative time\fR -A specification relative to the current time. The format is \fInumber -unit\fR acceptable units are \fByear\fR, \fBfortnight\fR, \fBmonth\fR, \fBweek\fR, \fBday\fR, +A specification relative to the current time. The format is \fBnumber +unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR, \fBmonth\fR, \fBweek\fR, \fBday\fR, \fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR). The unit can be specified as a singular or plural, as in \fB3 weeks\fR. These modifiers may also be specified: \fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR, \fBlast\fR, \fBthis\fR, \fBnext\fR, \fBago\fR. -.RE -.sp -.RS The actual date is calculated according to the following steps. +.PP First, any absolute date and/or time is processed and converted. Using that time as the base, day-of-week specifications are added. Next, relative specifications are used. If a date or day is @@ -255,38 +825,20 @@ used. Finally, a correction is applied so that the correct hour of the day is produced after allowing for daylight savings time differences and the correct date is given when going from the end of a long month to a short month. -.sp +.PP Daylight savings time correction is applied only when the relative time is specified in units of days or more, ie, days, weeks, fortnights, months or years. This means that when crossing the daylight savings time boundary, different results will be given for \fBclock scan "1 day"\fR and \fBclock scan "24 hours"\fR: .CS -.ta 6c -\fB% clock scan "1 day" -base [clock scan 1999-10-31] +% clock scan "1 day" -base [clock scan 1999-10-31] 941443200 % clock scan "24 hours" -base [clock scan 1999-10-31] -941439600\fR -.CE -.RE -.TP -\fBclock seconds\fR -Return the current date and time as a system-dependent integer value. The -unit of the value is seconds, allowing it to be used for relative time -calculations. The value is usually defined as total elapsed time from -an ``epoch''. You shouldn't assume the value of the epoch. -.SH EXAMPLE -Print out the current date and time, first using the default format -and then using an ISO 8601 format: -.CS -set now [clock seconds] -set isoFmt "%Y-%m-%dT%H:%M:%SZ" -puts "DEFAULT: [clock format $now]" -puts "ISO8601: [clock format $now -format $isoFmt -gmt 1]" +941439600 .CE - .SH "SEE ALSO" -date(1), time(n) +msgcat +.SH "COPYRIGHT" +Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. -.SH KEYWORDS -clock, date, time |