diff options
Diffstat (limited to 'doc/clock.n')
| -rw-r--r-- | doc/clock.n | 125 |
1 files changed, 35 insertions, 90 deletions
diff --git a/doc/clock.n b/doc/clock.n index 7b3ea14..0460a54 100644 --- a/doc/clock.n +++ b/doc/clock.n @@ -8,7 +8,7 @@ .SH NAME clock \- Obtain and manipulate dates and times .SH "SYNOPSIS" -package require \fBTcl 8.5-\fR +package require \fBTcl 8.5\fR .sp \fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR? .sp @@ -42,12 +42,12 @@ is system-dependent but should be the highest resolution clock available on the system such as a CPU cycle counter. See \fBHIGH RESOLUTION TIMERS\fR for a full description. .RS .PP -If the \fI\-option\fR argument is \fB\-milliseconds\fR, then the command +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. .PP -If the \fI\-option\fR argument is \fB\-microseconds\fR, then the command +If 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. @@ -89,9 +89,10 @@ have 59 or 61 seconds. .TP \fIunit\fR One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR, -\fBdays\fR, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR. -Used in conjunction with \fIcount\fR to identify an interval of time, -for example, \fI3 seconds\fR or \fI1 year\fR. +\fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or +any unique prefix of such a word. Used in conjunction with \fIcount\fR +to identify an interval of time, for example, \fI3 seconds\fR or +\fI1 year\fR. .SS "OPTIONS" .TP \fB\-base\fR time @@ -110,12 +111,11 @@ and their interpretation, are described under \fBFORMAT GROUPS\fR. .RS .PP On \fBclock format\fR, the default format is -.PP .CS %a %b %d %H:%M:%S %Z %Y .CE .PP -On \fBclock scan\fR, the lack of a \fB\-format\fR option indicates that a +On \fBclock scan\fR, the lack of a \fI\-format\fR option indicates that a .QW "free format scan" is requested; see \fBFREE FORM SCAN\fR for a description of what happens. .RE @@ -160,21 +160,20 @@ the environment variable \fBTZ\fR. .IP [3] on Windows systems, the time zone settings from the Control Panel. .RE -.PP 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" -.PP 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, \fBweekdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\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) @@ -186,9 +185,9 @@ 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 +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 miniscule amount until Tcl's time +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 @@ -196,7 +195,6 @@ 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. -.PP .CS set s [\fBclock scan\fR {2004-10-30 05:00:00} \e -format {%Y-%m-%d %H:%M:%S} \e @@ -211,14 +209,12 @@ 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. The \fBweekdays\fR keyword is similar to \fBdays\fR, -with the only difference that weekends - Saturdays and Sundays - are skipped. +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. -.PP .CS set s [\fBclock scan\fR {2004-10-30 05:00:00} \e -format {%Y-%m-%d %H:%M:%S} \e @@ -234,7 +230,6 @@ 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. -.PP .CS set s [\fBclock scan\fR {2004-04-03 02:30:00} \e -format {%Y-%m-%d %H:%M:%S} \e @@ -247,7 +242,6 @@ set x [\fBclock format\fR $a \e 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. -.PP .CS set x [\fBclock scan\fR 1752-09-02 -format %Y-%m-%d -locale en_US] set y [\fBclock add\fR $x 1 day -locale en_US] @@ -276,7 +270,6 @@ years as they are when adding/subtracting days and weeks. If multiple \fIcount unit\fR pairs are present on the command, they are evaluated consecutively, from left to right. .SH "HIGH RESOLUTION TIMERS" -.PP 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, @@ -291,7 +284,6 @@ 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" -.PP 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, @@ -330,7 +322,6 @@ 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" -.PP 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 @@ -452,55 +443,41 @@ 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.) -.PP -If the interpretation of the groups yields an impossible time because -a field is out of range, enough of that field's unit will be added to -or subtracted from the time to bring it in range. Thus, if attempting to -scan or format day 0 of the month, one day will be subtracted from day -1 of the month, yielding the last day of the previous month. -.PP -If the interpretation of the groups yields an impossible time because -a Daylight Saving Time change skips over that time, or an ambiguous -time because a Daylight Saving Time change skips back so that the clock -observes the given time twice, and no time zone specifier (\fB%z\fR -or \fB%Z\fR) is present in the format, the time is interpreted as -if the clock had not changed. .SH "FORMAT GROUPS" -.PP The following format groups are recognized by the \fBclock scan\fR and \fBclock format\fR commands. .TP \fB%a\fR -On output, produces an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day +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, produces the full name (\fIe.g.,\fR \fBMonday\fR) of the day +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, produces an abbreviation (\fIe.g.,\fR \fBJan\fR) for the name +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, produces the full name (\fIe.g.,\fR \fBJanuary\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, produces a localized representation of date and time of day; +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 \fB%c\fR produces. .TP \fB%C\fR -On output, produces the number of the century in Indo-Arabic numerals. +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 @@ -757,7 +734,6 @@ character. Synonymous with .QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" . .SH "TIME ZONES" -.PP 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: @@ -779,7 +755,6 @@ The C library's idea of the local time zone, as defined by the .PP In case [1] \fIonly,\fR the string is tested to see if it is one of the strings: -.PP .CS gmt ut utc bst wet wat at nft nst ndt ast adt est edt @@ -791,7 +766,6 @@ of the strings: cadt east eadt gst nzt nzst nzdt idle .CE -.PP If it is a string in the above list, it designates a known time zone, and is interpreted as such. .PP @@ -823,34 +797,15 @@ the minus sign one west of Greenwich. A time zone string conforming to the Posix specification of the \fBTZ\fR environment variable will be recognized. The specification may be found at -\fIhttps://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR. -.PP -If the Posix time zone string contains a DST (Daylight Savings Time) -part, but doesn't contain a rule stating when DST starts or ends, -then default rules are used. For Timezones with an offset between 0 -and +12, the current European/Russian rules are used, otherwise the -current US rules are used. In Europe (offset +0 to +2) the switch -to summertime is done each last Sunday in March at 1:00 GMT, and -the switch back is each last Sunday in October at 2:00 GMT. In -Russia (offset +3 to +12), the switch dates are the same, only -the switch to summertime is at 2:00 local time, and the switch -back is at 3:00 local time in all time zones. The US switch to -summertime takes place each second Sunday in March at 2:00 local -time, and the switch back is each first Sunday in November at -3:00 local time. These default rules mean that in all European, -Russian and US (or compatible) time zones, DST calculations will -be correct for dates in 2007 and later, unless in the future the -rules change again. +\fIhttp://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html\fR. .PP Any other time zone string is processed by prefixing a colon and attempting to use it as a location name, as above. .SH "LOCALIZATION" -.PP Developers wishing to localize the date and time formatting and parsing -are referred to \fIhttps://tip.tcl-lang.org/173\fR for a +are referred to \fIhttp://tip.tcl.tk/173\fR for a specification. .SH "FREE FORM SCAN" -.PP 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 @@ -886,47 +841,40 @@ The \fIinputString\fR argument consists of zero or more specifications of the following form: .TP \fItime\fR -. -A time of day, which is of the form: -.QW "\fIhh\fR?\fB:\fImm\fR?\fB:\fIss\fR?? ?\fImeridian\fR? ?\fIzone\fR?" -or -.QW "\fBhhmm \fR?\fBmeridian\fR? ?\fBzone\fR?" . -If no \fImeridian\fR 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 -.QW "\fImm\fB/\fIdd\fR?\fB/\fIyy\fR?" , -.QW "\fImonthname dd\fR?\fB, \fIyy\fR?" , -.QW "\fIday\fB, \fIdd monthname \fR?\fIyy\fR?" , -.QW "\fIdd monthname yy\fR" , -.QW "?\fICC\fR?\fIyymmdd\fR" , +.QW "\fBmm/dd\fR?\fB/yy\fR?" , +.QW "\fBmonthname dd\fR?\fB, yy\fR?" , +.QW "\fBday, dd monthname \fR?\fByy\fR?" , +.QW "\fBdd monthname yy\fR" , +.QW "?\fBCC\fR?\fByymmdd\fR" , and -.QW "\fIdd\fB-\fImonthname\fB-\fR?\fICC\fR?\fIyy\fR" . +.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\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 -.QW "\fICCyymmdd\fBT\fIhhmmss\fR" , +.QW \fICCyymmdd\fBT\fIhhmmss\fR, where \fBT\fR is the literal .QW T , .QW "\fICCyymmdd hhmmss\fR" , -.QW "\fICCyymmdd\fBT\fIhh:mm:ss\fR" , or -.QW "\fICCyy-mm-dd\fBT\fIhh:mm:ss\fR" . -Note that only these four formats are accepted. +.QW \fICCyymmdd\fBT\fIhh:mm:ss\fR . +Note that only these three formats are accepted. The command does \fInot\fR accept the full range of point-in-time specifications specified in ISO8601. Other formats can be recognized by -giving an explicit \fB\-format\fR option to the \fBclock scan\fR command. +giving an explicit \fI\-format\fR option to the \fBclock scan\fR command. .TP \fIrelative time\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, @@ -951,7 +899,4 @@ msgcat(n) .SH KEYWORDS clock, date, time .SH "COPYRIGHT" -Copyright \(co 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. -'\" Local Variables: -'\" mode: nroff -'\" End: +Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. |