The
timestamp function returns the
UNIX time, which is the number of seconds that have elapsed since January 1, 1970 in Coordinated Universal Time (UTC). This value is used by many computer programs and is thus useful for storing times as well as calculating timespans. Because the time is in UTC, it eliminates the need to worry about time zones when working with times.
The first version of the function returns a timestamp for the current time according to a device's clock. The value is as accurate as the device's clock.
The second version of the function takes a string expression,
rfc3339_string, that represents a date in
RFC 3339 format. Dates specified in
ISO 8601 format can also be used by this version. The string is parsed with the timestamp representing the string returned.
The third version returns the timestamp for a date specified using numeric expressions for the
year,
month, and
day. The
hour,
minute, and
second can also be specified. Using
named arguments, you can specify a time zone offset. If not specified, the time zone of the device is used, so to calculate a timestamp in UTC, you must specify:
utcOffset := 0.
The function returns the UNIX time as a decimal value. The integer part of this value is the number of elapsed seconds, while the decimal part contains the milliseconds. If there was an error parsing the RFC 3339 string, or the date values provided, the function returns
default.
If you wish to store a timestamp in a fixed-width numeric variable, the variable should have an integer length of 10 and a decimal length of 3 (for a total length of 13 without a decimal character, or 14 with one).
// the Olympics 2008 opening ceremony was held on:
// - August, 8, 2008, at 8:00 pm (China Standard Time)
numeric timestamp_from_rfc3339 = timestamp("2008-08-08T12:00:00+00:00");
numeric timestamp_from_date = timestamp(2008, 8, 8, 20, utcOffset := 8);