TIMESTAMP

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

8.2.2

Introduced

See Also

CALDAT, SYSTIME, TIMESTAMPTOVALUES, TIMEGEN