**Time and Date - clock**


!!!!!!
'''[Tcl Tutorial Lesson 40%|%Previous lesson%|%]''' | '''[Tcl Tutorial Index%|%Index%|%]''' | '''[Tcl Tutorial Lesson 42%|%Next lesson%|%]'''
!!!!!!

The `clock` 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.

The `clock` command is a platform independent method of getting
the display functionality of the unix `date` command, and provides
access to the values returned by a call to the UNIX system function `gettime()`.

   `clock seconds`:   The `clock seconds` 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 `clock format` command.

   `clock format clockValue ?-gmt boolean? ?-format string?`:   The `format` subcommand formats a `clockValue` (as returned by `clock seconds`) into a human readable string. The `-gmt` switch takes a boolean as the second argument.  If the boolean is `1` or `true`, then the time will be formatted as Greenwich Mean Time, otherwise, it will be formatted as local time, taking care of daylight saving time and timezones.

The `-format` option controls what format the return will be in.  The
contents of the `string` argument to format has similar contents as
the format statement. However, the `%*` descriptors are dedicated to dates and times:

%|Code|Meaning|%
|`%a`|Abbreviated weekday name (Mon, Tue, etc.)|
|`%A`|Full weekday name (Monday, Tuesday, etc.)|
|`%b`|Abbreviated month name (Jan, Feb, etc.)|
|`%B`|Full month name (January, February, etc.)|
|`%d`|Day of month|
|`%j`|Julian day of year|
|`%m`|Month number (01-12)|
|`%y`|Year in century|
|`%Y`|Year with 4 digits|
|`%H`|Hour (00-23)|
|`%I`|Hour (00-12)|
|`%M`|Minutes (00-59)|
|`%S`|Seconds(00-59)|
|`%p`|PM or AM|
|`%D`|Date as %m/%d/%y|
|`%r`|Time as %I:%M:%S %p|
|`%R`|Time as %I:%M|
|`%T`|Time as %I:%M:%S|
|`%Z`|Time Zone Name|

    `clock scan dateString ?-format format?`:   The `scan` subcommand converts a human readable string to a system clock value, as would be returned by `clock seconds`.

The `dateString` argument for the `clock scan` command, without the `-format format` option, may be a string in any of these forms:

   * time: 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 specified, 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.
   ** hh:mm:ss ?meridian? ?zone?
   ** hhmm ?meridian? ?zone?

   * date: A date in one of the formats shown below.
   ** mm/dd/yy
   ** mm/dd
   ** monthname dd, yy
   ** monthname dd
   ** dd monthname yy
   ** dd monthname
   ** day, dd monthname yy

This is known as "free form scanning". The `clock scan` command then uses a number of heuristic rules to determine the correct form. However, it is safer to explicitly specify a format to which the date/time string should conform. This way you can be sure that the date/time is interpreted in a controlled way.

A small example of the use of the `-format` option with `clock scan`: in German speaking countries, the date is often formatted as ''2017.01.02'', meaning the second of January, 2017. This is not in a form accepted by the free form scanning rules:

======
   % puts [clock scan "2017.01.02" -format "%Y.%m.%d"]
   1483311600
   % puts [clock format 1483311600]
   Mon Jan 02 00:00:00 CET 2017
======

Arithmetic with the `clock` command is also possible:

======
   # Calculate the date ten days and 2 hours from today
   set today [clock seconds]

   set 10daysFromNow [clock add $today 10 days 2 hours]
   puts [clock format $today]
   puts [clock format $10daysFromNow]
======

might print:

======none
Thu Jun 29 19:48:27 CEST 2017
Sun Jul 09 21:48:27 CEST 2017
======

(Note the time zone: the dates fall within the daylight saving period of the year 2017)

----

***Example***

======
set systemTime [clock seconds]

puts "The time is: [clock format $systemTime -format %H:%M:%S]"
puts "The date is: [clock format $systemTime -format %D]"
puts [clock format $systemTime -format {Today is: %A, the %d of %B, %Y}]
puts "\nThe default format for the time is: [clock format $systemTime]\n"

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 "discrepancy of [expr {$bookSeconds - $movieSeconds}] seconds in how"
puts "soon we would have sentient computers like the HAL 9000"
======

<<discussion>> Resulting output
======none
The time is: 19:51:19
The date is: 06/29/2017
Today is: Thursday, the 29 of June, 2017

The default format for the time is: Thu Jun 29 19:51:19 CEST 2017

The book and movie versions of '2001, A Space Oddysey' had a
discrepancy of 157852800 seconds in how
soon we would have sentient computers like the HAL 9000
======
<<enddiscussion>

!!!!!!
'''[Tcl Tutorial Lesson 40%|%Previous lesson%|%]''' | '''[Tcl Tutorial Index%|%Index%|%]''' | '''[Tcl Tutorial Lesson 42%|%Next lesson%|%]'''
!!!!!!