Time-related data types

A Timespan defines the length of a duration of time, and a Timestamp defines a point in time. For example, “two hours” is a duration that can be represented as a Timespan, while “three o'clock in the afternoon UTC on 8 November, 2018” is a point in time that can be represented as a Timestamp. Both types can use nanosecond values if it is available on the platform.

The Timespan data type

A Timespan value represents a duration of time. The Timespan data type matches a specified range of durations and includes all values within the given range. The default represents a positive or negative infinite duration. A Timespan value can be specified with strings or numbers in various forms. The type takes up to two parameters.

Parameters

The full signature for Timespan is:
Timespan[ (<TIMESPAN START OR LENGTH>, (<TIMESPAN END>)) ]
Position Parameter Data type Default value Description
1 Timespan start or length String, Float, Integer, or default default (negative infinity in a span) If only one parameter is passed, it is the length of the timespan. If two parameters are passed, this is the start or from value in a time range.
2 Timespan end String, Float, Integer, or default default (positive infinity) or none if only one value passed. The end or to value in a time range.
Timespan values are interpreted depending on their format:

  • A String in the format D-HH:MM:SS represents a duration of D days, HH hours, MM minutes, and SS seconds.

  • An Integer or Float represents a duration in seconds.

A Timespan defined as a range (two parameters) matches any Timespan durations that can fit within that range. If either end of a range is defined as default (infinity), it is an open range, while any other range is a closed range. The range is inclusive.

In other words, Timespan[2] matches a duration of two seconds, but Timespan[0, 2] can match any Timespan from zero to two seconds, inclusive.

The Timespan type is not enumerable.

For information about converting values of other types to Timespan using the new function, or for converting a Timespan to a String using strftime, see the function reference documentation.

Examples:
Timespan[2]
Matches a Timespan value of 2 seconds.
Timespan[77.3]
Matches a Timespan value of 1 minute, 17 seconds, and 300 milliseconds (77.3 seconds).
Timespan['1-00:00:00', '2-00:00:00']
Matches a closed range of Timespan values between 1 and 2 days.

The Timestamp data type

A Timestamp value represents a specific point in time. The Timestamp data type can be one single point or any point within a given range, depending on the number of specified parameters. Timestamp values that include a default parameter represents an infinite range of either positive or negative Timestamps. A Timestamp value can be specified with strings or numbers in various forms.

Parameters

The full signature for Timestamp is:
Timestamp[ (<TIMESTAMP VALUE>, (<RANGE LIMIT>)) ]
The type takes up to two parameters, and defaults to an infinite range to the past and future. A Timestamp with one parameter represents a single point in time, while two parameters represent a range of Timestamps, with the first parameter being the from value and the second being the to value.
Position Parameter Data type Default value Description
1 Timestamp value String, Float, Integer, or default default (negative infinity in a range) Point in time if passed alone, or from value in a range if passed with a second parameter.
2 Range limit String, Float, Integer, or default default (positive infinity), or none if only one value is passed The to value in a range.
A Timestamp that is defined as a single point in time (one parameter) matches exactly that point.

A Timestamp that is defined as a range (two parameters) matches any point in time within that range. If either end of a range is defined as default (infinity), it is an open range, while any other range is a closed range. The range is inclusive.

So, Timestamp['2000-01-01T00:00:00.000'] matches 0:00 UTC on 1 January, 2000, while Timestamp['2000-01-01T00:00:00.000', '2001-01-01T00:00:00.000] matches Timestamp values from that point in time to a point in time one year later, inclusive.

Timestamp values are interpreted depending on their format.

For information about converting values of other types to Timestamp using the new function, or for converting a Timespan to a String using the strftime function, see the function reference documentation.

Examples:
Timestamp['2000-01-01T00:00:00.000', default]
Matches an open range of Timestamps from the start of the 21st century to an infinite point in the future.
Timestamp['2012-10-10']
Matches the exact Timestamp 2012-10-10T00:00:00.0 UTC.
Timestamp[default, 1433116800]
Matches an open range of Timestamps from an infinite point in the past to 2015-06-01T00:00:00 UTC, here expressed as seconds since the Unix epoch.
Timestamp['2010-01-01', '2015-12-31T23:59:59.999999999']
Matches a closed range of Timestamps between the start of 2010 and the end of 2015.