|
ActiveTcl User Guide |
|
clock(n) 8.5 Tcl "Tcl commands"
clock - Obtain and manipulate dates and times
TABLE OF
CONTENTS
SYNOPSIS
DESCRIPTION
PARAMETERS
OPTIONS
CLOCK
ARITHMETIC
HIGH
RESOLUTION TIMERS
FORMATTING
TIMES
SCANNING
TIMES
FORMAT
GROUPS
TIME ZONES
LOCALIZATION
FREE FORM
SCAN
SEE ALSO
COPYRIGHT
package require Tcl 8.5
The clock 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.
- clock add timeVal ?count unit...? ?-option value?
- Adds a (possibly negative) offset to a time that is expressed
as an integer number of seconds. See CLOCK ARITHMETIC for a full description.
- clock clicks ?-option?
- If no -option 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. See HIGH RESOLUTION
TIMERS for a full description.
If the -option argument is -milliseconds, then the command is synonymous with clock milliseconds (see below). This usage is
obsolete, and clock milliseconds is to be
considered the preferred way of obtaining a count of
milliseconds.
It the -option argument is -microseconds, then the command is synonymous with clock microseconds (see below). This usage is
obsolete, and clock microseconds is to be
considered the preferred way of obtaining a count of
microseconds.
- clock format timeVal ?-option value...?
- Formats a time that is expressed as an integer number of
seconds into a format intended for consumption by users or external
programs. See FORMATTING TIMES for a
full description.
- clock microseconds
- Returns the current time as an integer number of microseconds.
See HIGH RESOLUTION TIMERS for
a full description.
- clock milliseconds
- Returns the current time as an integer number of milliseconds.
See HIGH RESOLUTION TIMERS for
a full description.
- clock scan inputString ?-option
value...?
- Scans a time that is expressed as a character string and
produces an integer number of seconds. See SCANNING TIMES for a full description.
- clock seconds
- Returns the current time as an integer number of seconds.
- count
- An integer representing a count of some unit of time. See CLOCK ARITHMETIC for the details.
- timeVal
- An integer value passed to the clock command
that represents an absolute time as a number of seconds from the
epoch time 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.
- unit
- One of the words, seconds,
minutes, hours,
days, weeks,
months, or years, or any unique
prefix of such a word. Used in conjuction with count to identify an interval of time, for example, 3
seconds or 1 year.
- -base time
- Specifies that any relative times present in a clock scan command are to be given relative to time. time must be expressed as a
count of nominal seconds from the epoch time of 1 January 1970,
00:00 UTC.
- -format format
- Specifies the desired output format for clock
format or the expected input format for clock
scan. The format string consists of any
number of characters other than the per-cent sign ('%')
interspersed with any number of format groups, which are
two-character sequences beginning with the per-cent sign. The
permissible format groups, and their interpretation, are described
under FORMAT GROUPS.
- -gmt boolean
- If boolean is true, specifies that a time
specified to clock add, clock
format or clock scan should be processed in
UTC. If boolean 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
'-timezone :UTC' or any of the
equivalent ways to specify it.
- -locale 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 localeName. The locale name may be any of the locales
acceptable to the msgcat command, or it may be
the special name system, which represents the
current locale of the process, or the null string, which represents
Tcl's default locale.
The effect of locale on scanning and formatting is discussed in the
descriptions of the individual format groups under FORMAT GROUPS. The effect of locale on clock
arithmetic is discussed under CLOCK
ARITHMETIC.
- -timezone zoneName
- Specifies that clock arithmetic, formatting, and scanning are
to be done according to the rules for the time zone specified by zoneName. The permissible values, and their
interpretation, are discussed under TIME
ZONES. On subcommands that expect a -timezone
argument, the default is to use the current time zone. The
current time zone is determined, in order of preference, by:
- the environment variable TCL_TZ.
- the environment variable TZ.
- on Windows systems, the time zone settings from the Control
Panel.
If none of these is present, the C localtime and
mktime 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.
The clock add 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
-timezone, -locale and
-gmt options) are integers and keywords in
alternation, where the keywords are chosen from
seconds, minutes,
hours, days,
weeks, months, or
years, or any unique prefix of such a word.
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 timeVal given to the clock add
command. The result is interpreted as a nominal number of seconds
from the Epoch.
Surprising results may be obtained when crossing a point at
which a leap second is inserted or removed; the clock add 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.
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 x to
04:00:00 because the clock has changed in the
interval in question.
|
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]
|
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.
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 same local time on the day in
question. For instance, the following code sets the value of
x to 05:00:00.
|
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]
|
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 x to
03:30:00.
|
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]
|
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
z to 1752-09-14.
|
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]
|
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.
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.
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.
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.
If multiple count unit pairs are present on
the command, they are evaluated consecutively, from left to
right.
Most of the subcommands supported by the clock command deal with times represented as a count of
seconds from the epoch time, and this is the representation that clock seconds returns. There are three exceptions,
which are all intended for use where higher-resolution times are
required. clock milliseconds returns the count
of milliseconds from the epoch time, and clock
microseconds returns the count of microseconds from the epoch
time. In addition, there js a clock clicks
command that returns a platform-dependent high-resolution timer.
Unlike clock seconds and clock
milliseconds, the value of clock clicks 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.
The clock format 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 clock
seconds, clock scan, clock
add, file atime or file
mtime.
If a -format 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 ('%') interspersed with any number
of format groups, which are two-character sequences
beginning with the per-cent sign. The permissible format groups,
and their interpretation, are described under FORMAT GROUPS.
If a -timezone 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
-timezone :UTC, the obsolete
usage -gmt true may be used.
See TIME ZONES for the permissible
variants for the time zone.
If a -locale 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 msgcat command. Note that the default, if
-locale is not specified, is the root locale
{} rather than the current locale. The current
locale may be obtained by using -locale
current. In addition, some platforms support a
system 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 system locale. On platforms that do
not define a user selection of date and time formats separate from
LC_TIME, -locale
system is synonymous with -locale
current.
The clock scan 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
-format option that is followed by a string
describing the expected format of the input. (See FREE FORM SCAN for the effect of clock scan without such an argument.) The string consists
of any number of characters other than the per-cent sign
('%'), interspersed with any number of format
groups, which are two-character sequences beginning with the
per-cent sign. The permissible format groups, and their
interpretation, are described under FORMAT
GROUPS.
If a -timezone 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
-timezone :UTC, the obsolete
usage -gmt true may be used.
See TIME ZONES for the permissible
variants for the time zone.
If a -locale 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 msgcat command. Note that the default, if
-locale is not specified, is the root locale
{} rather than the current locale. The current
locale may be obtained by using -locale
current. In addition, some platforms support a
system 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 system locale. On platforms that do
not define a user selection of date and time formats separate from
LC_TIME, -locale
system is synonymous with -locale
current.
If a -base option is present, the following
argument is a time (expressed in seconds from the epoch time) that
is used as a base time for interpreting relative times. If
no -base option is present, the base time is the
current time.
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.
Before scanning begins, the format string is preprocessed to
replace %c, %Ec,
%x, %Ex, %X.
%Ex, %r, %R,
%T, %D, %EY and
%+ format groups with counterparts that are
appropriate to the current locale and contain none of the above
groups. For instance, %D will (in the
en_US locale) be replaced with
%m/%d/%Y.
The date is determined according to the fields that are present
in the preprocessed format string. In order of preference:
- If the string contains a %s format group,
representing seconds from the epoch, that group is used to
determine the date.
- If the string contains a %J format group,
representing the Julian Day Number, that group is used to determine
the date.
- 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.
- 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.
- 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.
- 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.
- If none of the above rules results in a usable date, the date
of the base time in the given time zone is used.
The time is also determined according to the fields that are
present in the preprocessed format string. In order of preference:
- If the string contains a %s format group,
representing seconds from the epoch, that group determines the time
of day.
- 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.
- If the string contains neither a %s format
group nor a group specifying the hour of the day, then midnight
(00:00, the start of the given date) is used.
The time zone is determined by either the
-timezone or -gmt options, or by
using the current time zone.
If a format string lacks a %z or
%Z 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.)
The following format groups are recognized by the clock scan and clock format
commands.
- %a
- On output, receives an abbreviation (e.g.,
Mon) 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).
- %A
- On output, receives the full name (e.g.,
Monday) 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).
- %b
- On output, receives an abbreviation (e.g.,
Jan) 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).
- %B
- On output, receives the full name (e.g.,
January) 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).
- %c
- 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.
- %C
- 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.
- %d
- 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.
- %D
- This format group is synonymous with %m/%d/%Y.
It should be used only in exchanging data within the
en_US locale, since other locales typically do not
use this order for the fields of the date.
- %e
- 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.
- %Ec
- 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.
- %EC
- 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.
- %Ex
- 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.
- %EX
- On output, produces a locale-dependent representation of the
time of day in the locale's alternative numerals. On input, matches
whatever %EX produces.
- %Ey
- 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.
- %EY
- On output, produces a representation of the year in the
locale's alternative calendar and numerals. On input, matches what
%EY produces. Often synonymous with
%EC%Ey.
- %g
- 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 %V. On
input, accepts such a two-digit year number, possibly with leading
whitespace.
- %G
- 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 %V. On
input, accepts such a four-digit year number, possibly with leading
whitespace.
- %h
- This format group is synonymous with %b.
- %H
- 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.
- %I
- 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.
- %j
- On output, produces a three-digit number giving the day of the
year (001-366). On input, accepts such a number.
- %J
- 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.
- %k
- 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.
- %l
- 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.
- %m
- 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.
- %M
- 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.
- %N
- 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.
- %Od, %Oe,
%OH, %OI, %Ok,
%Ol, %Om, %OM,
%OS, %Ou, %Ow,
%Oy
- All of these format groups are synonymous with their
counterparts without the 'O', except that the
string is produced and parsed in the locale-dependent alternative
numerals.
- %p
- On output, produces an indicator for the part of the day,
A.M. or P.M., appropriate to the
given locale. If the script of the given locale supports multiple
letterforms, uppercase is preferred. On input, matches the
representation A.M. or P.M. in
the given locale, in either case.
- %P
- On output, produces an indicator for the part of the day,
A.M. or P.M., appropriate to the
given locale. If the script of the given locale supports multiple
letterforms, lowercase is preferred. On input, matches the
representation A.M. or P.M. in
the given locale, in either case.
- %Q
- This format group is reserved for internal use within the Tcl
library.
- %r
- On output, produces a locale-dependent time of day
representation on a 12-hour clock. On input, accepts whatever
%r produces.
- %R
- On output, produces a locale-dependent time of day
representation on a 24-hour clock. On input, accepts whatever
%R produces.
- %s
- On output, simply formats the timeVal
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 %s
uniquely determines a point in time, it overrides all other input
formats.
- %S
- 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.
- %t
- On output, produces a TAB character. On input, matches a TAB
character.
- %T
- Synonymous with %H:%M:%S.
- %u
- On output, produces the number of the day of the week
(1-Monday, 7-Sunday). On input,
accepts a single digit and interprets it as the day of the week.
Sunday may be either 0 or 7.
- %U
- 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 %V for
the ISO8601 week number.
- %V
- 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.
- %w
- 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
%V.
- %x
- On output, produces the date in a locale-dependent
representation. On input, accepts whatever %x
produces and is used to determine calendar date.
- %X
- On output, produces the time of day in a locale-dependent
representation. On input, accepts whatever %X
produces and is used to determine time of day.
- %y
- 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 %y does not yield a year appropriate for use
with the ISO8601 week number %V; programs should
use %g for that purpose.
- %Y
- On output, produces the four-digit calendar year. On input,
accepts four digits and may be used to determine calendar date.
Note that %Y does not yield a year appropriate for
use with the ISO8601 week number %V; programs
should use %G for that purpose.
- %z
- 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 TIME
ZONES below) that will be used to determine the time zone.
- %Z
- On output, produces the current time zone's name, possibly
translated to the given locale. On input, accepts a time zone
specifier (see TIME ZONES 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
BST 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.
- %%
- On output, produces a literal '%' charater. On
input, matches a literal '%' character.
- %+
- Synonymous with '%a %b %e %H:%M:%S %Z
%Y'.
When the clock command is processing a local
time, it has several possible sources for the time zone to use. In
order of preference, they are:
- A time zone specified inside a string being parsed and matched
by a %z or %Z format group.
- A time zone specified with the -timezone
option to the clock command (or, equivalently,
by -gmt 1).
- A time zone specified in an environment variable
TCL_TZ.
- A time zone specified in an environment variable
TZ.
- The local time zone from the Control Panel on Windows
systems.
- The C library's idea of the local time zone, as defined by the
mktime and localtime
functions.
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
%z or %Z format group, it is
checked to see if it is one of the strings,
|
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
|
If it is a string in the above list, it designates a known time
zone, and is interpreted as such.
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 :America/New_York 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
"/no_backup/tmp/lib/tcl8.4/clock/tzdata". On some
Unix systems, these files are omitted, and the definitions are
instead obtained from system files in
"/usr/share/zoneinfo",
"/usr/share/lib/zoneinfo" or
"/usr/local/etc/zoneinfo". As a special case, the
name :localtime refers to the local time zone as
defined by the C library.
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.
A string conforming to the Posix specification of the
TZ environment variable will be recognized. The
specification may be found at
http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html.
Any other string is processed by prefixing a colon and
attempting to use it as a location name, as above.
Developers wishing to localize the date and time formatting and
parsing are referred to http://www.tcl.tk/cgi-bin/tct/tip/173
for a specification.
If the clock scan command is invoked without
a -format option, then it requests a free-form
scan. This form of scan is deprecated. 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.
If free-form scan is used, only the -base and
-gmt options are accepted. The
-timezone and -locale options
will result in an error if -format is not
supplied.
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:
If only a time is specified, the current date is assumed. If the
inputString does not contain a time zone
mnemonic, the local time zone is assumed, unless the
-gmt argument is true, in which case the clock
value is calculated assuming that the specified time is relative to
Greenwich Mean Time. -gmt, if specified, affects
only the computed time value; it does not impact the interpretation
of -base.
If the -base 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.
The inputString argument consists of zero or
more specifications of the following form:
- time
- A time of day, which is of the form: hh?:mm?:ss??
?meridian? ?zone? or hhmm ?meridian?
?zone? If no meridian is specified, hh is
interpreted on a 24-hour clock.
- date
- A specific month and day with optional year. The acceptable
formats are "mm/dd?/yy?", "monthname dd?,
yy?", "day, dd monthname ?yy?",
"dd monthname yy", "?CC?yymmdd",
and "dd-monthname-?CC?yy. 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.
- ISO 8601 point-in-time
- An ISO 8601 point-in-time specification, such as
CCyymmddThhmmss, where T is the
literal T, "CCyymmdd hhmmss", or
CCyymmddThh:mm:ss.
- relative time
- A specification relative to the current time. The format is
number unit. Acceptable units are
year, fortnight,
month, week,
day, hour,
minute (or min), and
second (or sec). The unit can be
specified as a singular or plural, as in 3 weeks.
These modifiers may also be specified: tomorrow,
yesterday, today,
now, last, this,
next, ago.
The actual date is calculated according to the following steps.
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
specified, and no absolute or relative time is given, midnight is
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.
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 clock scan "1 day" and clock scan "24
hours":
|
% clock scan "1 day" -base [clock scan 1999-10-31]
941443200
% clock scan "24 hours" -base [clock scan 1999-10-31]
941439600
|
msgcat
Copyright © 2004 Kevin B. Kenny <kennykb@acm.org>.
All rights reserved.