'\"
'\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
.TH "clock" n 8.5 Tcl "Tcl Built-In Commands"
.so man.macros
.BS
.SH NAME
clock \- Obtain and manipulate dates and times
.SH "SYNOPSIS"
.nf
package require \fBTcl 8.5-\fR

\fBclock add\fI timeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?

\fBclock clicks\fR ?\fI\-option\fR?

\fBclock format\fI timeVal\fR ?\fI\-option value\fR...?

\fBclock microseconds\fR

\fBclock milliseconds\fR

\fBclock scan\fI inputString\fR ?\fI\-option value\fR...?

\fBclock seconds\fR
.fi
.BE
.SH "DESCRIPTION"
.PP
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.
.\" METHOD: add
.TP
\fBclock add\fI timeVal\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.
.\" METHOD: clicks
.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.
See \fBHIGH RESOLUTION TIMERS\fR for a full description.
.RS
.PP
If the \fI\-option\fR argument is \fB\-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
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.
.RE
.\" METHOD: format
.TP
\fBclock format\fI timeVal\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.
.\" METHOD: microseconds
.TP
\fBclock microseconds\fR
.
Returns the current time as an integer number of microseconds.
See \fBHIGH RESOLUTION TIMERS\fR for a full description.
.\" METHOD: milliseconds
.TP
\fBclock milliseconds\fR
.
Returns the current time as an integer number of milliseconds.
See \fBHIGH RESOLUTION TIMERS\fR for a full description.
.\" METHOD: scan
.TP
\fBclock scan\fI inputString\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.
.\" METHOD: seconds
.TP
\fBclock seconds\fR
.
Returns the current time as an integer number of seconds.
.SS "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
\fInow\fR
Instead of \fItimeVal\fR a non-integer value \fBnow\fR can be used as
replacement for today, which is simply interpolated to the runt-time as value
of \fBclock seconds\fR. For example:
.sp
\fBclock format now -f %a; # current day of the week\fR
.sp
\fBclock add now 1 month; # next month\fR
.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.
.SS "OPTIONS"
.\" OPTION: -base
.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.
.\" OPTION: -format
.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
.PQ \fB%\fR
interspersed with any number of \fIformat groups\fR, which are two- or three-character
sequences beginning with the per-cent sign.  The permissible format groups,
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
.QW "free format scan"
is requested; see \fBFREE FORM SCAN\fR for a description of what happens.
.RE
.\" OPTION: -gmt
.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
.QW "\fB\-timezone\fI :UTC\fR"
or any of the equivalent ways to specify it.
.\" OPTION: -locale
.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 package, 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.
.RS
.PP
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.
.RE
.\" OPTION: -timezone
.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:

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
.QW "\fB\-timezone\fI :UTC\fR" ,
the obsolete usage
.QW "\fB\-gmt\fI true\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 package.  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 current\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 system\fR is
synonymous with \fB\-locale current\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
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
.PQ \fB%\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\fI :UTC\fR,
the obsolete usage \fB\-gmt\fI true\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 package.  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 current\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 system\fR is
synonymous with \fB\-locale current\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:

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.

.IP \fB%a\fR
On output, produces an abbreviation (\fIe.g., \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).

.IP \fB%A\fR
On output, produces the full name (\fIe.g., \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).

.IP \fB%b\fR
On output, produces an abbreviation (\fIe.g., \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).

.IP \fB%B\fR
On output, produces the full name (\fIe.g., \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).

.IP \fB%c\fR
On output, produces 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.

.IP \fB%C\fR
On output, produces 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.

.IP \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.

.IP \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.

.IP \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.

.IP \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 \fB%Ec\fR produces.  The locale's alternative calendar need not
be the Gregorian calendar.

.IP \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.

.IP \fB%EE\fR
On output, produces the string \fBB.C.E.\fR or \fBC.E.\fR, or a
string of the same meaning in the locale, to indicate whether \fB%Y\fR refers
to years before or after Year 1 of the Common Era.  On input, accepts
the string \fBB.C.E.\fR, \fBB.C.\fR, \fBC.E.\fR, \fBA.D.\fR, or the
abbreviation appropriate to the current locale, and uses it to fix
whether \fB%Y\fR refers to years before or after Year 1 of the
Common Era.

.IP \fB%Ej\fR
On output, produces a string of digits giving the Astronomical Julian Date or
Astronomical Julian Day Number (JDN/JD). In opposite to calendar julian day
\fB%J\fR, it starts the day at noon.
On input, accepts a string of digits (or floating point with the time fraction)
and interprets it as an Astronomical Julian Day Number (JDN/JD).
The Astronomical Julian Date is a count of the number of calendar days
that have elapsed since 1 January, 4713 BCE of the proleptic
Julian calendar, which contains also the time fraction (after floating point).
The epoch time of 1 January 1970 corresponds to Astronomical JDN 2440587.5.
This value corresponds the julian day used in sqlite-database, and is the same
as result of \fBselect julianday(:seconds, 'unixepoch')\fR.

.IP \fB%EJ\fR
On output, produces a string of digits giving the Calendar Julian Date.
In opposite to julian day \fB%J\fR format group, it produces float number.
In opposite to astronomical julian day \fB%Ej\fR group, it starts at midnight.
On input, accepts a string of digits (or floating point with the time fraction)
and interprets it as a Calendar Julian Day Number.
The Calendar Julian Date is a count of the number of calendar days
that have elapsed since 1 January, 4713 BCE of the proleptic
Julian calendar, which contains also the time fraction (after floating point).
The epoch time of 1 January 1970 corresponds to Astronomical JDN 2440588.

.IP \fB%Es\fR
This affects similar to \fB%s\fR, but in opposition to \fB%s\fR it parses
or formats local seconds (not the posix seconds).
Because \fB%s\fR has the same precedence as \fB%s\fR (uniquely determines
a point in time), it overrides all other input formats.

.IP \fB%Ex\fR
On output, produces a locale-dependent representation of the date
in the locale's alternative calendar.  On input, matches
whatever \fB%Ex\fR produces.  The locale's alternative calendar need not
be the Gregorian calendar.

.IP \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 \fB%EX\fR produces.

.IP \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.

.IP \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.

.IP \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.

.IP \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.

.IP \fB%h\fR
This format group is synonymous with \fB%b\fR.

.IP \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.

.IP \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.

.IP \fB%j\fR
On output, produces a three-digit number giving the day of the year
(001-366).  On input, accepts such a number.

.IP \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.

.IP \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.

.IP \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.

.IP \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.

.IP \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.

.IP \fB%N\fR
On output, produces the number of the month (1-12) with one or two digits,
and a leading blank for one-digit dates.
On input, accepts one or two digits, possibly with leading whitespace,
and interprets them as the number of the month.

.IP "\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
.QW \fBO\fR ,
except that the string is produced and parsed in the
locale-dependent alternative numerals.

.IP \fB%p\fR
On output, produces an indicator for the part of the day, \fBAM\fR
or \fBPM\fR, appropriate to the given locale.  If the script of the
given locale supports multiple letterforms, lowercase is preferred.
On input, matches the representation \fBAM\fR or \fBPM\fR in
the given locale, in either case.

.IP \fB%P\fR
On output, produces an indicator for the part of the day, \fBam\fR
or \fBpm\fR, appropriate to the given locale.  If the script of the
given locale supports multiple letterforms, uppercase is preferred.
On input, matches the representation \fBAM\fR or \fBPM\fR in
the given locale, in either case.

.IP \fB%Q\fR
This format group is reserved for internal use within the Tcl library.

.\" It's the STARDATE! We're so Enterprise-ready...
.IP \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.

.IP \fB%R\fR
On output, the time in 24-hour notation (%H:%M). For a version
including the seconds, see \fB%T\fR below. On input, accepts whatever
\fB%R\fR produces.

.IP \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.

.IP \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.

.IP \fB%t\fR
On output, produces a TAB character. On input, matches a TAB character.

.IP \fB%T\fR
Synonymous with \fB%H:%M:%S\fR.

.IP \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.

.IP \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.

.IP \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.

.IP \fB%w\fR
On output, produces the ordinal number of the day of the week
(Sunday==0; Saturday==6).  On input, accepts a single digit and
interprets it as the day of the week; Sunday may be represented as
either 0 or 7.  Note that \fB%w\fR is not the ISO8601 weekday number,
which is produced and accepted by \fB%u\fR.

.IP \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.

.IP \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.

.IP \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.

.IP \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.

.IP \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.

.IP \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 (this token is optionally applicable on input,
so the value is not mandatory and can be missing in input).

.IP \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 (token is also like \fB%z\fR optionally applicable on input).
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.

.IP \fB%%\fR
On output, produces a literal
.QW \fB%\fR
character. On input, matches a literal
.QW \fB%\fR
character.

.IP \fB%+\fR
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:
.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 1\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]

.PP
Developers wishing to localize the date and time formatting and parsing
are referred to \fIhttps://tip.tcl-lang.org/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.
\fIThis form of scan is deprecated.\fR
The reason for the deprecation
is that there are too many ambiguities. (Does the string
.QW 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