:TITLE: Time and Date - clock
;#
;# RCSID: $Header: /home/cvs/TclTutor3/lesson/Tcl_English/Tcl_English41.lsn,v 1.1 2008/08/02 12:37:17 clif Exp $
;# Copyright (c) 1995 Clif Flynt
;# 9300 Fleming Rd.
;# Dexter, MI  48130
;# clif@cflynt.com
;# See file "NOTICE" for licensing terms.
;#
:LESSON_TEXT_START_LEVEL 0:
The <B>clock</B> command provides access to the time and date functions
in Tcl.  Depending on the subcommands invoked, it can acquire the current
time, or convert between different representations of time and date.
<DL>
<B><DT>clock seconds </B>
<DD> The <B>clock seconds</B> command returns the time in seconds since
the epoch.  The date of the epoch varies for different operating systems,
thus this value is useful for comparison purposes, or as an input to the
<B>clock format</B> command.
<P>
<B><DT>clock format</B> <I>clockValue</I> ?<B>-gmt</B> <I>boolean</I>? ?<B>-format</B> <I>string</I>? 
<DD> The <B>format</B> subcommand formats a <I>clockvalue</I> (as returned by
<B>clock clicks</B> into a human readable string.
<P>
The <B>-gmt</B> switch takes a boolean as the second argument.  If the boolean
is <B>1</B> or <B>True</B>, then the time will be formatted as Greenwich Mean
Time, otherwise, it will be formatted as local time.
<P>
The <B>-format</B> option controls what format the return will be in.  The
contents of the <I>string</I> argument to format has similar contents as
the format statement (as discussed in lesson 19, 33 and 34).  In addition,
there are several more <B>%*</B> descriptors that can be used to describe
the output.  
<P>
These include:
<UL>
<B><LI>%a</B> . . . . Abbreviated weekday name (Mon, Tue, etc.)
<B><LI>%A</B> . . . . Full weekday name (Monday, Tuesday, etc.)
<B><LI>%b</B> . . . . Abbreviated month name (Jan, Feb, etc.)
<B><LI>%B</B> . . . . Full month name (January, February, etc.)
<B><LI>%d</B>. . . . . Day of month
<B><LI>%j</B> . . . . . Julian day of year
<B><LI>%m</B> . . . . Month number (01-12)
<B><LI>%y</B>. . . . . Year in century
<B><LI>%Y</B> . . . . Year with 4 digits
<P>
<B><LI>%H</B> . . . . Hour (00-23)
<B><LI>%I</B> . . . . . Hour (00-12)
<B><LI>%M</B> . . . . Minutes (00-59)
<B><LI>%S</B> . . . . . Seconds(00-59)
<B><LI>%p</B> . . . . . PM or AM
<P>
<B><LI>%D</B> . . . . Date as %m/%d/%y
<B><LI>%r</B>. . . . . Time as %I:%M:%S %p
<B><LI>%R</B> . . . . Time as %I:%M
<B><LI>%T</B> . . . . Time as %I:%M:%S
<B><LI>%Z</B> . . . . Time Zone Name
</UL>
<B><DT>clock scan</B> <I>dateString</I>
<DD> The <B>scan</B> subcommand converts a human readable string to a
system clock value, as would be returned by <B>clock seconds</B>
<P>
The <I>dateString</I> argument contains strings in these forms:
<DL>
<DT>time
<DD>A time of day in one of the formats shown below.  Meridian may be
AM, or PM, or a capitalization variant.  If it is not
sepcified, then the hour (hh) is interpreted as a 24 hour clock.  Zone
may be a three letter description of a time zone, EST, PDT, etc.
<UL>
<LI>hh:mm:ss ?meridian? ?zone?
<LI> hhmm ?meridian? ?zone?
</UL>
<DT>date
<DD> A date in one of the formats shown below.
<UL>
<LI> mm/dd/yy
<LI> mm/dd
<LI> monthname dd, yy
<LI> monthname dd
<LI> dd monthname yy
<LI> dd monthname
<LI> day, dd monthname yy
</UL>
</DL>
</DL>

:TEXT_END:

:LESSON_TEXT_START_LEVEL 1:
The <B>clock</B> command provides access to the time and date functions
in Tcl.  Depending on the subcommands invoked, it can acquire the current
time, or convert between different representations of time and date.
<P>
The <B>clock</B> command is a platform independent method of getting
the display functionality of the unix <B>date</B> command, and provides
access to the values returned by a unix <B>gettime()</B> call.
<P>
<DL>
<B><DT>clock seconds </B>
<DD> The <B>clock seconds</B> command returns the time in seconds since
the epoch.  The date of the epoch varies for different operating systems,
thus this value is useful for comparison purposes, or as an input to the
<B>clock format</B> command.
<P>
<B><DT>clock format</B> <I>clockValue</I> ?<B>-gmt</B> <I>boolean</I>? ?<B>-format</B> <I>string</I>? 
<DD> The <B>format</B> subcommand formats a <I>clockvalue</I> (as returned by
<B>clock clicks</B> into a human readable string.
<P>
The <B>-gmt</B> switch takes a boolean as the second argument.  If the boolean
is <B>1</B> or <B>True</B>, then the time will be formatted as Greenwich Mean
Time, otherwise, it will be formatted as local time.
<P>
The <B>-format</B> option controls what format the return will be in.  The
contents of the <I>string</I> argument to format has similar contents as
the format statement (as discussed in lesson 19, 33 and 34).  In addition,
there are several more <B>%*</B> descriptors that can be used to describe
the output.  
<P>
These include:
<UL>
<B><LI>%a</B> . . . . Abbreviated weekday name (Mon, Tue, etc.)
<B><LI>%A</B> . . . . Full weekday name (Monday, Tuesday, etc.)
<B><LI>%b</B> . . . . Abbreviated month name (Jan, Feb, etc.)
<B><LI>%B</B> . . . . Full month name (January, February, etc.)
<B><LI>%d</B>. . . . . Day of month
<B><LI>%j</B> . . . . . Julian day of year
<B><LI>%m</B> . . . . Month number (01-12)
<B><LI>%y</B>. . . . . Year in century
<B><LI>%Y</B> . . . . Year with 4 digits
<P>
<B><LI>%H</B> . . . . Hour (00-23)
<B><LI>%I</B> . . . . . Hour (00-12)
<B><LI>%M</B> . . . . Minutes (00-59)
<B><LI>%S</B> . . . . . Seconds(00-59)
<B><LI>%p</B> . . . . . PM or AM
<P>
<B><LI>%D</B> . . . . Date as %m/%d/%y
<B><LI>%r</B>. . . . . Time as %I:%M:%S %p
<B><LI>%R</B> . . . . Time as %I:%M
<B><LI>%T</B> . . . . Time as %I:%M:%S
<B><LI>%Z</B> . . . . Time Zone Name
</UL>
<B><DT>clock scan</B> <I>dateString</I>
<DD> The <B>scan</B> subcommand converts a human readable string to a
system clock value, as would be returned by <B>clock seconds</B>
<P>
The <I>dateString</I> argument contains strings in these forms:
<DL>
<DT>time
<DD>A time of day in one of the formats shown below.  Meridian may be
AM, or PM, or a capitalization variant.  If it is not
sepcified, then the hour (hh) is interpreted as a 24 hour clock.  Zone
may be a three letter description of a time zone, EST, PDT, etc.
<UL>
<LI>hh:mm:ss ?meridian? ?zone?
<LI> hhmm ?meridian? ?zone?
</UL>
<DT>date
<DD> A date in one of the formats shown below.
<UL>
<LI> mm/dd/yy
<LI> mm/dd
<LI> monthname dd, yy
<LI> monthname dd
<LI> dd monthname yy
<LI> dd monthname
<LI> day, dd monthname yy
</UL>
</DL>
</DL>

:TEXT_END:

:LESSON_TEXT_START_LEVEL 2:
Most computer systems track the current time and day by storing the
number of seconds that have elapsed since an arbitrary date in memory.
The start date (0 seconds) is usually referred to as <B>the epoch</B>,
since that's when time starts (for that system).
When you need to know the current date and time, the computer converts
that value from seconds since the epoch into a user readable string.
<P>
In Tcl, the <B>clock</B> command provides access to the time and date functions.
Depending on the subcommands invoked, it can acquire the current
time, or convert between different representations of time and date.
<P>
<DL>
<B><DT>clock seconds </B>
<DD> The <B>clock seconds</B> command returns the time in seconds since
the epoch.  The date of the epoch varies for different operating systems,
thus this value is useful for comparison purposes, or as an input to the
<B>clock format</B> command.
<P>
<B><DT>clock format</B> <I>clockValue</I> ?<B>-gmt</B> <I>boolean</I>? ?<B>-format</B> <I>string</I>? 
<DD> The <B>format</B> subcommand formats a <I>clockvalue</I> (as returned by
<B>clock clicks</B> into a human readable string.
<P>
The <B>-gmt</B> switch takes a boolean as the second argument.  If the boolean
is <B>1</B> or <B>True</B>, then the time will be formatted as Greenwich Mean
Time, otherwise, it will be formatted as local time.
<P>
The <B>-format</B> option controls what format the return will be in.  The
contents of the <I>string</I> argument to format has similar contents as
the format statement (as discussed in lesson 19, 33 and 34).  In addition,
there are several more <B>%*</B> descriptors that can be used to describe
the output.  
<P>
These include:
<UL>
<B><LI>%a</B> . . . . Abbreviated weekday name (Mon, Tue, etc.)
<B><LI>%A</B> . . . . Full weekday name (Monday, Tuesday, etc.)
<B><LI>%b</B> . . . . Abbreviated month name (Jan, Feb, etc.)
<B><LI>%B</B> . . . . Full month name (January, February, etc.)
<B><LI>%d</B>. . . . . Day of month
<B><LI>%j</B> . . . . . Julian day of year
<B><LI>%m</B> . . . . Month number (01-12)
<B><LI>%y</B>. . . . . Year in century
<B><LI>%Y</B> . . . . Year with 4 digits
<P>
<B><LI>%H</B> . . . . Hour (00-23)
<B><LI>%I</B> . . . . . Hour (00-12)
<B><LI>%M</B> . . . . Minutes (00-59)
<B><LI>%S</B> . . . . . Seconds(00-59)
<B><LI>%p</B> . . . . . PM or AM
<P>
<B><LI>%D</B> . . . . Date as %m/%d/%y
<B><LI>%r</B>. . . . . Time as %I:%M:%S %p
<B><LI>%R</B> . . . . Time as %I:%M
<B><LI>%T</B> . . . . Time as %I:%M:%S
<B><LI>%Z</B> . . . . Time Zone Name
</UL>
<B><DT>clock scan</B> <I>dateString</I>
<DD> The <B>scan</B> subcommand converts a human readable string to a
system clock value, as would be returned by <B>clock seconds</B>
<P>
The <I>dateString</I> argument contains strings in these forms:
<DL>
<DT>time
<DD>A time of day in one of the formats shown below.  Meridian may be
AM, or PM, or a capitalization variant.  If it is not
sepcified, then the hour (hh) is interpreted as a 24 hour clock.  Zone
may be a three letter description of a time zone, EST, PDT, etc.
<UL>
<LI>hh:mm:ss ?meridian? ?zone?
<LI> hhmm ?meridian? ?zone?
</UL>
<DT>date
<DD> A date in one of the formats shown below.
<UL>
<LI> mm/dd/yy
<LI> mm/dd
<LI> monthname dd, yy
<LI> monthname dd
<LI> dd monthname yy
<LI> dd monthname
<LI> day, dd monthname yy
</UL>
</DL>
</DL>

:TEXT_END:

:CODE_START:
;# Get the time in system seconds
set systemTime [clock seconds]

;# Display that time using the hour, minute and second descriptors.
puts "The time is: [clock format $systemTime -format %H:%M:%S]"

;# Display the date using a shorthand format
puts "The date is: [clock format $systemTime -format %D]"

;# You can use complex format statements.
puts [clock format $systemTime -format {Today is: %A, the %d of %B, %Y}]

;# And, this is the default output for the time, with no -format
puts "\n the default format for the time is: [clock format $systemTime]\n"

;# The book and movie versions of 2001 had different dates for when the
;# HAL 9000 became alive.
;# We can use the scan command to figure out how many seconds they differed by

set halBirthBook "Jan 12, 1997"
set halBirthMovie "Jan 12, 1992"
set bookSeconds [clock scan $halBirthBook]
set movieSeconds [clock scan $halBirthMovie]

puts "The book and movie versions of '2001, A Space Oddysey' had a"
puts "discrepency of [expr $bookSeconds - $movieSeconds] seconds in how"
puts "soon we would have sentient computers like the HAL 9000"

:TEXT_END:

