Returns the current time in one of several different formats. Optionally, if a time is supplied in one of the supported formats, it will convert the time to another format.
Time returns the current time or a supplied time in one of several different formats.
time([option_out [,option_in [,time ]]])
- One of Normal, Long, UTC, Hours, Minutes, Seconds, Timestamp, Offset, Elapsed, Reset.
- Note that only the first character is used. Any remaining characters are ignored. This will apply even if the word is spelled incorrectly.
- One of Normal, Long, UTC, Hours, Minutes, Seconds, Timestamp.
- If this option is specified, it defines the format of the time in the following parameter.
- Time to be used as source in the format specified by option_in. If this time is omitted, option_in is ignored and the current time is used.
A string containing the current time depending on the option specified.
Where an output option only is specified the current time is converted to the that format.
If there is no option or the option is invalid, the current time is returned in the 24-hour clock format: hh:mm:ss. Midnight is returned as 00:00:00.
If an input time is specified, that time is used instead of the current time.
- The local time in the format hh:mm:ss. This is the default if no option is provided or it is invalid.
- The time in the format: hh:mm:ss.ddd where ddd is decimal fractions of a second to three decimal places (milliseconds).
- The Universal Co-ordinated Time (UTC - also known as GMT) in the format hh:mm:ss.
- The number of hours since midnight.
- The number of minutes since midnight.
- The number of seconds since midnight.
- Unix time stamp as a decimal number. This is the number of seconds since 01/01/1970 00:00:00 UTC.
The UTC offset option is used for information only and is not used as part of a time conversion.
- The number of minutes between UTC time and local time. This does not include daylight saving time. For GMT this is 0, for EST is -300 and for WET is 60.
The remaining two options are used to return the elapsed time and are not used as part of a time conversion.
- The number of seconds.microseconds since the elapsed time clock was started or reset. (See The Elapsed Time Clock below). The value is returned in the format: sssssssss.uuuuuu without leading zeros or blanks. The fractional part always has six digits.
- The number of seconds.microseconds since the elapsed time clock was started or reset (See The Elapsed Time Clock below). The value is returned in the format: sssssssss.uuuuuu without leading zeros or blanks. The fractional part always has six digits. This option resets the elapsed-time clock.
The first call to date or time in one clause causes a time stamp to be made that is then used for any further calls to date or time in that clause. This means that multiple calls to either function in a single expression or clause will be consistent with each other.
Here are some examples, assuming the time is 16:54:22 on 31 August 2008:
time() -> '16:54:22' time('H') -> '16' time('L') -> '16:54:22.123456' /* Perhaps */ time('M') -> '1014' /* 54 + 60*16 */ time('N') -> '16:54:22' time('O') -> '60' /* Minutes between UTC time and local time */ time('S') -> '60862' /* 22 + 60*(54 + 60*16) */ time('T') -> '1220201662' /* Seconds since 01/01/1970 00:00:00 GMT */ time('U') -> '15:54:22' /* Universal Co-ordinated Time (UTC or GMT) */
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'), the current system time stamp is returned. This is the number of seconds and microseconds since 01/01/1970 00:00:00 in the format ssssssssss.uuuuuu. Repeated calls to time('E') will return the current time stamp or if the counter has been reset, the current elapsed time.
Note that the actual value returned for the microseconds is system dependent and can change at less than microsecond intervals. Refer to the system documentation for the exact interval.
On the first call in a program to time('R'), the current system time stamp is returned and then the elapsed time clock is re-started. Subsequent calls to time('E') or time('R') will return the current elapsed time.
(To be implemented) The clock is saved across internal routine calls. An internal routine inherits the time clock that was started by its caller, but any timing the caller is doing is not affected, even if the clock is reset by the internal routine.
An example of the elapsed time clock in use:
time('R') → 1220201662.123450 /* The first call on 31-08-2008 */ /* 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 */
| To be implemented
|Currently there is limited support revolving around VB date serials.|
| To be implemented
|Currently there is limited support for time handling using the following Xst library functions.|