'\"
'\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
.so man.macros
.TH "clock" n 8.5 Tcl "Tcl Built-In Commands"
.BS
.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
\fBclock clicks\fR ?\fI-option\fR?
.sp
\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...?
.sp

.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} \\
set s [\fBclock\fR 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 \\
set a [\fBclock\fR add $s 24 hours -timezone :America/New_York]
set x [\fBclock\fR 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} \\
set s [\fBclock\fR 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 \\
set a [\fBclock\fR add $s 1 day -timezone :America/New_York]
set x [\fBclock\fR 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} \\
set s [\fBclock\fR 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 \\
set a [\fBclock\fR add $s 1 day -timezone :America/New_York]
set x [\fBclock\fR 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]
set x [\fBclock\fR scan 1752-09-02 -format %Y-%m-%d -locale en_US]
set y [\fBclock\fR add $x 1 day -locale en_US]
set z [\fBclock\fR 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

impact the interpretation of \fB-base\fR.
.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.
.PP
The \fIinputString\fR argument  consists of zero or more specifications of the
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: \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.

.PP
Daylight savings time correction is applied only when the relative time
is specified in units of days or more, i.e.\ 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
% clock scan "1 day" -base [clock scan 1999-10-31]
% \fBclock\fR scan "1 day" -base [\fBclock\fR scan 1999-10-31]
941443200
% clock scan "24 hours" -base [clock scan 1999-10-31]
% \fBclock\fR scan "24 hours" -base [\fBclock\fR scan 1999-10-31]
941439600
.CE
.SH "SEE ALSO"
msgcat
.SH "COPYRIGHT"
Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.