The TIMESTAMP function returns one or more date/time strings in ISO-8601 format, when you provide a year, month, day, hour, minute, second, and offset from Coordinated Universal Time (UTC). If this function is called without keywords, it returns a string with the system time in UTC. This function is the inverse to TIMESTAMPTOVALUES.
This routine is written in the IDL language. Its source code can be found in the file timestamp.pro in the lib subdirectory of the IDL distribution.
Examples
Example 1
This
simple example uses integers for date/time keywords. The time is based
on UTC since the OFFSET keyword is not set. It returns a single
date/time string in ISO-8601 format.
timestamp_string = TIMESTAMP(YEAR = 2012, MONTH = 9, $
DAY = 4, HOUR = 11, MINUTE = 25, SECOND = 15)
PRINT, timestamp_string
Return value:
2012-09-04T11:25:15Z
See Additional Examples below for more detailed use cases.
Syntax
Result = TIMESTAMP( DAY=value, HOUR=value, MINUTE=value, MONTH=value, OFFSET=value, SECOND=value, /UTC, YEAR=value, /ZERO)
Return Value
A date/time string that conforms to the ISO-8601 standard. The string can be in any of the following formats, depending on which keywords you set:
YYYY-MM-DD
YYYY-MM-DDTHH:MM:SS.DZ
YYYY-MM-DDTHH:MM:SS:Doo:mm
Where:
- YYYY is the four-digit year
- MM is the two-digit month
- DD is the two-digit day
- T separates the date and time
- HH is the two-digit hour
- MM is the two-digit minute
- SS is the two-digit second
- D is the decimal fraction of a second with up to double-precision
- Z indicates Coordinated Universal Time (UTC)
- oo
is a two-digit offset in hours from UTC time. If the offset is
negative, a minus symbol (-) precedes the value. If it is positive, a
plus symbol (+) precedes the value.
- mm is an optional partial-hour offset (in minutes) from UTC time
If
all keywords are scalar (a single integer value), the function returns
a scalar. If some keywords are set to arrays, those arrays must contain
the same number of elements. If the inputs are a combination of scalars
and arrays, the function uses the scalar value with each element of the
arrays; the return value will be an array.
If you do not set any keywords, the function returns the system time in UTC.
Keywords
DAY (optional)
Set
this keyword to an integer or array of integers representing the day(s)
of month. The default value is the current day if you do not set this
keyword.
HOUR (optional)
Set
this keyword to an integer or array of integers representing the
hour(s). Values range from 0 (midnight) to 23 (11:00 p.m.) The default
value is 0 if you do not set this keyword. If you do not set HOUR,
MINUTE, and SECOND, the return string will consist of the date only,
and the OFFSET and UTC keywords will be ignored.
MINUTE (optional)
Set
this keyword to an integer (0 to 59) or array of integers representing
the minute(s). The default value is 0 if you do not set this keyword.
If you do not set HOUR, MINUTE, and SECOND, the return string will
consist of the date only, and the OFFSET and UTC keywords will be ignored.
MONTH (optional)
Set
this keyword to an integer or integer array representing the month(s).
The default value is the current month if you do not set this keyword.
OFFSET (optional)
Set
this keyword to a value that represents the offset in hours from
Coordinated Universal Time (UTC). Use a minus symbol (-) for negative
offsets. (For example, -4 represents U.S. Eastern Daylight Time.)
Values range from -12 to 14. The offset varies for U.S. time zones,
depending on whether standard time or daylight savings time is observed.
If you do not set this keyword, the time is assumed to be in UTC.
If
you set the MONTH, DAY, HOUR, MINUTE, and/or SECOND keywords to arrays,
the offset will apply to all elements of the returned arrays.
Set OFFSET to one of the following data types:
- Integer (scalar)
- Integer array: The array must have the same number of elements as the YEAR keyword if you set YEAR to an array.
- Floating-point
value: This indicates a partial-hour offset. For example, a value of
9.5 represents an offset of 9:30 hours from UTC.
- Floating-point
array: This indicates a partial-hour offset. The array must have the
same number of elements as the YEAR keyword if you set YEAR to an array.
See the Additional Examples below.
SECOND (optional)
Set this keyword to one of the following data types representing the second(s):
- Integer
(0 to 59) or array of integers: The return string will not contain a
decimal point followed by decimal fractions of a second.
- Floating-point
value or array of floating-point values: The return string will contain
a floating-point value for the fraction of a second.
- Double-precision
value or array of double-precision values: The return string will
contain a double-precision value for the fraction of a second.
The default value is 0 if you do not set this keyword.
If
you do not set HOUR, MINUTE, and SECOND, the return string will consist
of the date only, and the OFFSET and UTC keywords will be ignored.
UTC (optional)
Set this keyword to force the return string to UTC time, in which case it will show the letter Z.
- If you do not set the OFFSET keyword, then UTC time is already implied and you do not need to set the UTC keyword.
- If you set both the OFFSET and UTC keywords, the return string will be converted from local time to UTC using the offset.
- If
you set the OFFSET keyword and you set UTC=0, the return string will be
in local time and the hour offset from UTC will be appended to the
string instead of the letter Z. For example, the offset will be shown as -04:00 for UTC minus four hours.
See the Additional Examples below.
YEAR (optional)
Set
this keyword to an integer or integer array, representing the year(s).
The default value is the current year if you do not set this keyword.
If you set it to an array, the return value will be an array of strings.
ZERO (optional)
Set this keyword to initialize the return string(s) to all zeros (0000-00-00T00:00:00Z). All other keywords will be ignored.
Additional Examples
Example 2
This
example shows a combination of arrays and scalars for input, with a
single offset of 8 hours. The return value is a three-element array of
date/time strings in ISO-8601 format.
timestamp_string = TIMESTAMP(YEAR = [2011, 2012, 2012], MONTH = [9,9,6], DAY = 1, $
HOUR = [11,12,1], MINUTE = [30,55,0], SECOND = [0.0,1.2345,2], OFFSET = 8)
PRINT, timestamp_string
Return value:
2011-09-01T11:30:00+08:00 2012-09-01T12:55:01.2345+08:00 2012-06-01T01:00:02+08:00
Example 3
This
example sets the OFFSET keyword to an array and sets the UTC keyword to
0. The returned string shows local time. The offset in hours from UTC
is appended to each string with the minus symbol (-).
timestamp_string = TIMESTAMP(YEAR = 2012, MONTH = 9, DAY = [4,5,6], $
HOUR = [11,12,13], OFFSET = [-4,-3,-2], UTC = 0)
PRINT, timestamp_string
Return value:
2012-09-04T11:00:00-04:00 2012-09-05T12:00:00-03:00 2012-09-06T13:00:00-02:00
Example 4
This example is similar to Example 3, but it sets the UTC keyword, thus displaying the time in UTC (indicated by the letter Z).
timestamp_string = TIMESTAMP(YEAR = 2012, MONTH = 9, DAY = [4,5,6], $
HOUR = [9,12,16], OFFSET = [-4,-3,-2], /UTC)
PRINT, timestamp_string
Return value:
2012-09-04T13:00:00Z 2012-09-05T15:00:00Z 2012-09-06T18:00:00Z
Example 5
This example uses an offset of 12 hours with the returned string in UTC. The result falls back to the previous day.
timestamp_string = TIMESTAMP(YEAR = 2012, MONTH = 9, DAY = 4, $
HOUR = 11, MINUTE = 25, SECOND = 15, OFFSET = 12, /UTC)
PRINT, timestamp_string
Return value:
2012-09-03T23:25:15Z
Version History
See Also
CALDAT, SYSTIME, TIMESTAMPTOVALUES, TIMEGEN