C++ Native Functions: spl.time

This page documents native functions that can be invoked from SPL, including the SPL interfaces that can be used to invoke each of the native functions.

Functions

public timestamp add(timestamp ts, float64 diff)

Add a time difference in seconds (as float64) to a timestamp.

Parameters

ts: Start time.
diff: Difference to add.

Returns

The timestamp for ts + diff.

public timestamp add(timestamp ts, int64 diff)

Add a time difference in nanoseconds (as int64) to a timestamp.

Parameters

ts: Start time.
diff: Difference to add.

Returns

The timestamp for ts + diff.

public timestamp createTimestamp (int64 secs, uint32 nanos)

Create a timestamp given the number of seconds and nanoseconds elapsed since the Epoch (00:00:00 UTC, January 1, 1970).

Parameters

secs: Number of seconds.
nanos: Number of nanoseconds.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public timestamp createTimestamp (int64 secs, uint32 nanos, int32 mid)

Create a timestamp given the number of seconds and nanoseconds elapsed since the Epoch (00:00:00 UTC, January 1, 1970), and a machine identifier that identifies the computer where the time measurement was taken.

Parameters

secs: Number of seconds.
nanos: Number of nanoseconds.
mid: Machine identifier.

Returns

The timestamp for the specified point in time and machine identifier.

public rstring ctime (timestamp time)

Convert a timestamp to a date and time string, using the current timezone.

Parameters

time: The input timestamp.

Returns

The string representation of the date and time in the form "Wed Jun 30 21:49:08 1993n", using the C locale.

public uint32 day (timestamp time)

Extract the day of month from a timestamp, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time: The input timestamp.

Returns

The day component of the time (in the range [1,31]).

public uint32 dayOfWeek (timestamp time)

Extract the day of week from a timestamp, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time: The input timestamp.

Returns

The day component of the time (in the range [0,6], 0 = Sunday).

public uint32 dayOfYear (timestamp time)

Extract the day of year from a timestamp, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time: The input timestamp.

Returns

The day component of the time (in the range [0,365]).

public int64 diffAsNanos(timestamp ts1, timestamp ts2)

Compute the difference between two timestamps in nanoseconds (as int64).

Note: Valid for ranges of 2^63 nanoseconds (292.47 years).

Parameters

ts1: First timestamp.
ts2: Second timestamp.

Returns

The difference ts1 - ts2 in nanoseconds.

public float64 diffAsSecs(timestamp ts1, timestamp ts2)

Compute the difference between two timestamps in seconds (as float64).

Note: Differences of less than 104.24 days retain nanosecond accuracy. Larger differences retain less accuracy.

Parameters

ts1: First timestamp.
ts2: Second timestamp.

Returns

The difference ts1 - ts2 in seconds.

public timestamp fromDecimal128(decimal128 t)

Convert to a timestamp a decimal128 value that preserves the precision of a timestamp, and represents the time as the number of seconds (including fractions) elapsed since the Epoch (00:00:00 UTC, January 1, 1970).

Parameters

t: Time in seconds since the Epoch, as a decimal128 value.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public stateful int64 getCPUCounterInNanoSeconds()

Obtain the CPU counter, which is an indication of relative time, in nanoseconds.

Note: This function cannot be used for reliable time measurements across multiple processors.


Returns: The current processor CPU counter in nanoseconds.

public int32 getMachineId(timestamp t)

Extract the machine identifier from a timestamp. The machine identifier is used to identify the computer where the time measurement was taken.

Parameters

t: The input timestamp.

Returns

The 'machine identifier' part of the timestamp.

public uint32 getNanoseconds(timestamp t)

Extract the part of a timestamp that represents the number of namoseconds elapsed since a whole number of seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Parameters

t: The input timestamp.

Returns

The 'nanoseconds' part of the timestamp.

public int64 getSeconds(timestamp t)

Extract the part of a timestamp that represents the number of whole seconds elapsed since the Epoch (00:00:00 UTC, January 1, 1970).

Parameters

t: The input timestamp.

Returns

The 'seconds' part of the timestamp.

public stateful timestamp getTimestamp()

Get the current wall clock time as a timestamp.

Note: This function uses gettimeofday system call on Linux.

Returns

The timestamp, with the machine identifier set to zero.

Throws

SPLRuntimeException: If unable to create a timestamp.

public stateful float64 getTimestampInSecs()

Get the current wall clock time as the number of seconds (including fractions) elapsed since the Epoch (00:00:00 UTC, January 1, 1970).

Note: This function uses gettimeofday system call on Linux.

Returns

Time in seconds since the Epoch, as a float64 value.

Throws

SPLRuntimeException: If unable to create a timestamp.

public uint32 gmday (timestamp time)

Extract the day of month from a timestamp, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time: The input timestamp.

Returns

The day component of the time (in the range [1,31]).

public uint32 gmdayOfWeek (timestamp time)

Extract the day of week from a timestamp, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time: The input timestamp.

Returns

The day component of the time (in the range [0,6], 0 = Sunday).

public uint32 gmdayOfYear (timestamp time)

Extract the day of year from a timestamp, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time: The input timestamp.

Returns

The day component of the time (in the range [0,365]).

public uint32 gmhour (timestamp time)

Extract the hour from a timestamp, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time: The input timestamp.

Returns

The hour component of the time (in the range [0,23]).

public uint32 gmminute (timestamp time)

Extract the minute from a timestamp, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time: The input timestamp.

Returns

The minute component of the time (in the range [0,59]).

public uint32 gmmonth (timestamp time)

Extract the month from a timestamp, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time: The input timestamp.

Returns

The month component of the time (in the range [0,11]).

public uint32 gmsecond (timestamp time)

Extract the second from a timestamp, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time: The input timestamp.

Returns

The second component of the time (in the range [0,61]).

public void gmtime (timestamp time, mutable tuple<int32 sec, int32 min, int32 hour, int32 mday, int32 mon, int32 year, int32 wday, int32 yday, int32 isdst, int32 gmtoff, rstring zone> result)

Convert a timestamp to a broken-down time (using the Sys.tm type), using the UTC timezone.

Parameters

time: The input timestamp.
result: Tuple to contain the broken-down time.

public uint32 gmyear (timestamp time)

Extract the year from a timestamp, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time: The input timestamp.

Returns

The year component of the time.

public uint32 hour (timestamp time)

Extract the hour from a timestamp, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time: The input timestamp.

Returns

The hour component of the time (in the range [0,23]).

public uint32 minute (timestamp time)

Extract the minute from a timestamp, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time: The input timestamp.

Returns

The minute component of the time (in the range [0,59]).

public uint32 month (timestamp time)

Extract the month from a timestamp, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time: The input timestamp.

Returns

The month component of the time (in the range [0,11]).

public uint32 second (timestamp time)

Extract the second from a timestamp, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time: The input timestamp.

Returns

The second component of the time (in the range [0,61]).

public rstring strftime (tuple<int32 sec, int32 min, int32 hour, int32 mday, int32 mon, int32 year, int32 wday, int32 yday, int32 isdst, int32 gmtoff, rstring zone> time, rstring format)

Convert a broken-down time (using the Sys.tm type) to a date and time string, using strftime.

Note: This function is POSIX compliant, and uses the current locale.

Parameters

time: The broken-down time.
format: Date and time format string (see the system man page for strftime).

Returns

The string representation of the broken-down time.

public void strptime (rstring dateTime, rstring format, mutable tuple<int32 sec, int32 min, int32 hour, int32 mday, int32 mon, int32 year, int32 wday, int32 yday, int32 isdst, int32 gmtoff, rstring zone> result, mutable uint32 numCharsProcessed)

Convert a date and time string to a broken-down time (using the Sys.tm type), using strptime.

Note: This function is POSIX compliant, and uses the current locale.

Parameters

dateTime: The string representation of the date and time.
format: Date and time format string (see the system man page for strptime).
result: The broken-down time corresponding to the date and time string.
numCharsProcessed: Number of characters successfully consumed from dateTime.

public void time (timestamp time, mutable tuple<int32 sec, int32 min, int32 hour, int32 mday, int32 mon, int32 year, int32 wday, int32 yday, int32 isdst, int32 gmtoff, rstring zone> result)

Convert a timestamp to a broken-down time (using the Sys.tm type), using the current timezone.

Parameters

time: The input timestamp.
result: Tuple to contain the broken-down time.

public void time (timestamp time, rstring tzone, mutable tuple<int32 sec, int32 min, int32 hour, int32 mday, int32 mon, int32 year, int32 wday, int32 yday, int32 isdst, int32 gmtoff, rstring zone> result)

Convert a timestamp to a broken-down time (using the Sys.tm type), using a specified timezone.

Parameters

time: The input timestamp.
tzone: The POSIX format timezone to use for the conversion, for example, "UTC-7".
result: Tuple to contain the broken-down time.

public timestamp timeStringToTimestamp (rstring dmy, rstring hmsmilli, boolean useLocaleMonth)

Convert date and time strings into a timestamp, using the current timezone.

Parameters

dmy: A string with a format of the form "04-OCT-2005".
hmsmilli: A string with a format of the form "14:18:19.324".
useLocaleMonth: If 'true', the current locale is used for month names. If 'false', the C locale is assumed. The performance of timeStringToTimestamp() is greater with useLocaleMonth set to 'false'.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public timestamp timeStringToTimestamp (rstring dmy, rstring hmsmilli, rstring tmzone, boolean useLocaleMonth)

Convert date and time strings into a timestamp, using the specified timezone.

Parameters

dmy: A string with a format of the form "04-OCT-2005".
hmsmilli: A string with a format of the form "14:18:19.324".
tmzone: The POSIX format timezone to use for the conversion, for example, "UTC-7".
useLocaleMonth: If 'true', the current locale is used for month names. If 'false', the C locale is assumed. The performance of timeStringToTimestamp is greater with useLocaleMonth set to 'false'.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public timestamp timeStringToTimestamp (ustring dmy, ustring hmsmilli, boolean useLocaleMonth)

Convert date and time strings into a timestamp, using the current timezone.

Parameters

dmy: A string with a format of the form "04-OCT-2005".
hmsmilli: A string with a format of the form "14:18:19.324".
useLocaleMonth: If 'true', the current locale is used for month names. If 'false', the C locale is assumed. The performance of timeStringToTimestamp() is greater with useLocaleMonth set to 'false'.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public timestamp timeStringToTimestamp (ustring dmy, ustring hmsmilli, ustring tmzone, boolean useLocaleMonth)

Convert date and time strings into a timestamp, using the specified timezone.

Parameters

dmy: A string with a format of the form "04-OCT-2005".
hmsmilli: A string with a format of the form "14:18:19.324".
tmzone: The POSIX format timezone to use for the conversion, for example, "UTC-7".
useLocaleMonth: If 'true', the current locale is used for month names. If 'false', the C locale is assumed. The performance of timeStringToTimestamp is greater with useLocaleMonth set to 'false'.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public timestamp timeStringtoTimestamp (rstring dmy, rstring hmsmilli, boolean useLocaleMonth)

DEPRECATED. Converts date and time strings into a timestamp, using the current timezone.

Note: DEPRECATED. Please use timeStringToTimestamp instead.

Parameters

dmy: A string with a format of the form "04-OCT-2005".
hmsmilli: A string with a format of the form "14:18:19.324".
useLocaleMonth: If 'true', current locale is used for month names. If 'false', C locale is assumed. The performance of timeStringToTimestamp is greater with useLocaleMonth set to 'false'.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public timestamp timeStringtoTimestamp (rstring dmy, rstring hmsmilli, rstring tmzone, boolean useLocaleMonth)

DEPRECATED. Converts date and time strings into a timestamp, using the specified timezone.

Note: DEPRECATED. Please use timeStringToTimestamp instead.

Parameters

dmy: A string with a format of the form "04-OCT-2005".
hmsmilli: A string with a format of the form "14:18:19.324".
tmzone: The POSIX format timezone to use for the conversion, for example, "UTC-7".
useLocaleMonth: If 'true', current locale is used for month names. If 'false', C locale is assumed. The performance of timeStringToTimestamp is greater with useLocaleMonth set to 'false'.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public timestamp timeStringtoTimestamp (ustring dmy, ustring hmsmilli, boolean useLocaleMonth)

DEPRECATED. Converts date and time strings into a timestamp, using the current timezone.

Note: DEPRECATED. Please use timeStringToTimestamp instead.

Parameters

dmy: A string with a format of the form "04-OCT-2005".
hmsmilli: A string with a format of the form "14:18:19.324".
useLocaleMonth: If 'true', current locale is used for month names. If 'false', C locale is assumed. The performance of timeStringToTimestamp is greater with useLocaleMonth set to 'false'.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public timestamp timeStringtoTimestamp (ustring dmy, ustring hmsmilli, ustring tmzone, boolean useLocaleMonth)

DEPRECATED. Converts date and time strings into a timestamp, using the specified timezone.

Note: DEPRECATED. Please use timeStringToTimestamp instead.

Parameters

dmy: A string with a format of the form "04-OCT-2005".
hmsmilli: A string with a format of the form "14:18:19.324".
tmzone: The POSIX format timezone to use for the conversion, for example, "UTC-7".
useLocaleMonth: If 'true', current locale is used for month names. If 'false', C locale is assumed. The performance of timeStringToTimestamp is greater with useLocaleMonth set to 'false'.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public decimal128 toDecimal128(timestamp ts)

Convert a timestamp to a decimal128 value that preserves the precision of the timestamp, and represents the time as the number of seconds (including fractions) elapsed since the Epoch (00:00:00 UTC, January 1, 1970).

Parameters

ts: Timestamp.

Returns

Time in seconds since the Epoch, as a decimal128 value.

<string T> public timestamp toTimestamp (enum {YYYYMMDDhhmmss,YYYY_MM_DD_hh_mm_ss,MM_DD_YYYY_hh_mm_ss,DD_MM_YYYY_hh_mm_ss,YYYY_MM_DD_hh_mm_ss_mmm,MM_DD_YYYY_hh_mm_ss_mmm,DD_MM_YYYY_hh_mm_ss_mmm} ftype, T str)

Converts a date and time string into a timestamp, using the current timezone.

Supported formats (where "YYYY", "MM", "DD", "hh", "mm", "ss" indicate digital values of the year, month, day, hour, minute, second, respectively):

Sys.YYYYMMDDhhmmss: "YYYYMMDDhhmmss"
Sys.YYYY_MM_DD_hh_mm_ss: "YYYY-MM-DD hh:mm:ss" (any separator can be used)
Sys.MM_DD_YYYY_hh_mm_ss: "MM-DD-YYYY hh:mm:ss" (any separator can be used)
Sys.DD_MM_YYYY_hh_mm_ss: "DD-MM-YYYY hh:mm:ss" (any separator can be used)
Sys.YYYY_MM_DD_hh_mm_ss_mmm: "YYYY-MM-DD hh:mm:ss.mmm" (any separator can be used)
Sys.MM_DD_YYYY_hh_mm_ss_mmm: "MM-DD-YYYY hh:mm:ss.mmm" (any separator can be used)
Sys.DD_MM_YYYY_hh_mm_ss_mmm: "DD-MM-YYYY hh:mm:ss.mmm" (any separator can be used)

Parameters

ftype: The format of the string (for example, Sys.YYYY_MM_DD_hh_mm_ss_mmm).
str: A string with the specified format.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

Converts a date and time string into a timestamp, using the specified timezone.

Supported formats (where "YYYY", "MM", "DD", "hh", "mm", "ss" indicate digital values of the year, month, day, hour, minute, second, respectively):

Sys.YYYYMMDDhhmmss: "YYYYMMDDhhmmss"
Sys.YYYY_MM_DD_hh_mm_ss: "YYYY-MM-DD hh:mm:ss" (any separator can be used)
Sys.MM_DD_YYYY_hh_mm_ss: "MM-DD-YYYY hh:mm:ss" (any separator can be used)
Sys.DD_MM_YYYY_hh_mm_ss: "DD-MM-YYYY hh:mm:ss" (any separator can be used)
Sys.YYYY_MM_DD_hh_mm_ss_mmm: "YYYY-MM-DD hh:mm:ss.mmm" (any separator can be used)
Sys.MM_DD_YYYY_hh_mm_ss_mmm: "MM-DD-YYYY hh:mm:ss.mmm" (any separator can be used)
Sys.DD_MM_YYYY_hh_mm_ss_mmm: "DD-MM-YYYY hh:mm:ss.mmm" (any separator can be used)

Parameters

ftype: The format of the string (for example, Sys.YYYY_MM_DD_hh_mm_ss_mmm).
str: A string with the specified format.
tmzone: The POSIX format timezone to use for the conversion, for example, "UTC-7".

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public timestamp toTimestamp (tuple<int32 sec, int32 min, int32 hour, int32 mday, int32 mon, int32 year, int32 wday, int32 yday, int32 isdst, int32 gmtoff, rstring zone> time)

Convert a broken-down time (using the Sys.tm type) into a timestamp.

Parameters

time: A tuple containing the broken-down time.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public timestamp toTimestamp (tuple<int32 sec, int32 min, int32 hour, int32 mday, int32 mon, int32 year, int32 wday, int32 yday, int32 isdst, int32 gmtoff, rstring zone> time,boolean defaultZone)

Convert a broken-down time (using the Sys.tm type) into a timestamp, using a parameter to specify whether to use the default timezone.

Parameters

time: A tuple containing the broken-down time.
defaultZone: If 'true', then use the default timezone.

Returns

The timestamp for the specified point in time, with the machine identifier set to zero.

public uint32 year (timestamp time)

Extract the year from a timestamp, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time: The input timestamp.

Returns

The year component of the time.