
>>-TIME--(--+--------+--)--------------------------------------><
'-option-'
returns the local time in the 24-hour clock format: hh:mm:ss (hours,
minutes, and seconds) by default, for example, 04:41:37.
You can use the following
options to obtain alternative
formats, or to gain access to the elapsed-time clock. (Only the capitalized
and highlighted letter is needed; all characters following it are
ignored.)
- Civil
- returns the time in Civil format: hh:mmxx. The hours may take
the values 1 through 12, and the minutes the
values 00 through 59. The minutes are followed
immediately by the letters am or pm. This distinguishes
times in the morning (12 midnight through 11:59 a.m.—appearing
as 12:00am through 11:59am) from noon and afternoon
(12 noon through 11:59 p.m.—appearing as 12:00pm through 11:59pm). The hour has no leading zero. The minute field shows
the current minute (rather than the nearest minute) for consistency
with other TIME results.
- Elapsed
- returns sssssssss.uuuuuu, the number of seconds.microseconds
since the elapsed-time clock (described later) was started or reset.
The number has no leading zeros or blanks, and the setting of NUMERIC
DIGITS does not affect the number. The fractional part always has
six digits.
- Hours
- returns up to two characters giving the number of hours since
midnight in the format: hh (no leading zeros or blanks, except for
a result of 0).
- Long
- returns time in the format: hh:mm:ss.uuuuuu (uuuuuu is the fraction
of seconds, in microseconds). The first eight characters of the result
follow the same rules as for the Normal form, and the fractional part
is always six digits.
- Minutes
- returns up to four characters giving the number of minutes since
midnight in the format: mmmm (no leading zeros or blanks, except for
a result of 0).
- Normal
- returns the time in the default format hh:mm:ss, as described
previously. The hours can have the values 00 through 23,
and minutes and seconds, 00 through 59. All
these are always two digits. Any fractions of seconds are ignored
(times are never rounded up). This is the default.
- Reset
- returns sssssssss.uuuuuu, the number of seconds.microseconds
since the elapsed-time clock (described later) was started or reset
and also resets the elapsed-time clock to zero. The number has no
leading zeros or blanks, and the setting of NUMERIC DIGITS does not
affect the number. The fractional part always has six digits.
- Seconds
- returns up to five characters giving the number of seconds since
midnight in the format: sssss (no leading zeros or blanks, except
for a result of 0).
Here are some examples, assuming that the time is 4:54 p.m.:
TIME() -> '16:54:22'
TIME('C') -> '4:54pm'
TIME('H') -> '16'
TIME('L') -> '16:54:22.123456' /* Perhaps */
TIME('M') -> '1014' /* 54 + 60*16 */
TIME('N') -> '16:54:22'
TIME('S') -> '60862' /* 22 + 60*(54+60*16) */
- The elapsed-time clock:
You can use the TIME function to measure real (elapsed) time
intervals. On the first call in a program to TIME('E') or TIME('R'), the elapsed-time clock is started, and either call
returns 0. From then on, calls to TIME('E') and
to TIME('R') return the elapsed time since that first call
or since the last call to TIME('R').
The clock is
saved across internal routine calls, which is to say that an internal
routine inherits the time clock its caller started. Any timing the
caller is doing is not affected, even if an internal routine resets
the clock. An example of the elapsed-time clock:
time('E') -> 0 /* The first call */
/* pause of one second here */
time('E') -> 1.002345 /* or thereabouts */
/* pause of one second here */
time('R') -> 2.004690 /* or thereabouts */
/* pause of one second here */
time('R') -> 1.002345 /* or thereabouts */
Note: See the note under DATE about consistency of times within
a single clause. The elapsed-time clock is synchronized to the other
calls to TIME and DATE, so multiple calls to the elapsed-time clock
in a single clause always return the same result. For the same reason,
the interval between two usual TIME/DATE results may be calculated
exactly using the elapsed-time clock.
- Implementation maximum:
- If the number of seconds in the elapsed time exceeds nine digits
(equivalent to over 31.6 years), an error results.