C++ Native Functions: spl.time

SPL standard and specialized toolkits > spl 1.2.1 > spl.time > C++ Native Functions

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 to a timestamp (in seconds as float64).

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 to a timestamp (in nanoseconds as int64).

Parameters

ts

Start time.

diff

Difference to add.

Returns

The timestamp for ts + diff.

public timestamp createTimestamp (int64 secs, uint32 nanos)

Create a timestamp.

Parameters

secs

Number of seconds.

nanos

Number of nanoseconds.

Returns

A timestamp (sec, nanos).

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

Create a timestamp.

Parameters

secs

Number of seconds.

nanos

Number of nanoseconds.

mid

Machine id.

Returns

A timestamp (sec, nanos, mid).

public rstring ctime (timestamp time)

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

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

String representation of 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 the time, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

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

public uint32 dayOfWeek (timestamp time)

Extract the day of week from the time, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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 the time, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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 a decimal128 value to a timestamp.

Parameters

t

Time in seconds.

Returns

A timestamp that represents the same time.

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 id from a timestamp.

Parameters

t

Input timestamp.

Returns

The 'machineId' part of the timestamp.

public uint32 getNanoseconds(timestamp t)

Extract the nanoseconds from a timestamp.

Parameters

t

Input timestamp.

Returns

The 'nanoseconds' part of the timestamp.

public int64 getSeconds(timestamp t)

Extract the seconds from a timestamp.

Parameters

t

Input timestamp.

Returns

The 'seconds' part of the timestamp.

public stateful timestamp getTimestamp()

Get the current wall clock time.

Note: This function uses gettimeofday system call on Linux.

Returns

Time since the Epoch (00:00:00 UTC, January 1, 1970).

Throws

SPLRuntimeException

If unable to create timestamp. If an exception is thrown, the operator calling this function terminates.

public stateful float64 getTimestampInSecs()

Get the current wall clock time in seconds (fractional).

Note: This function uses gettimeofday system call on Linux.

Returns

Time since the Epoch (00:00:00 UTC, January 1, 1970).

Throws

SPLRuntimeException

If unable to create timestamp. If an exception is thrown, the operator calling this function terminates.

public uint32 gmday (timestamp time)

Extract the day of month from the time, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

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

public uint32 gmdayOfWeek (timestamp time)

Extract the day of week from the time, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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 the time, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

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

public uint32 gmhour (timestamp time)

Extract the hour from the time, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

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

public uint32 gmminute (timestamp time)

Extract the minute from the time, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

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

public uint32 gmmonth (timestamp time)

Extract the month from the time, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

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

public uint32 gmsecond (timestamp time)

Extract the second from the time, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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 broken-down time (Sys.tm) using UTC timezone.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

result

Output tuple (see Sys.tm) representing broken down time in UTC.

public uint32 gmyear (timestamp time)

Extract the year from the time, using the UTC timezone.

Note: This function uses the POSIX gmtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

The year component of the time.

public uint32 hour (timestamp time)

Extract the hour from the time, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

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

public uint32 minute (timestamp time)

Extract the minute from the time, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

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

public uint32 month (timestamp time)

Extract the month from the time, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

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

public uint32 second (timestamp time)

Extract the second from the time, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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 broken-down time (Sys.tm) to a date and time string.

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

Parameters

time

Broken-down time (Sys.tm) representing the desired time.

format

Date and time format string (see man page for strptime).

Returns

String representation of date and 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 broken-down time (Sys.tm).

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

Parameters

dateTime

String representation of date/time.

format

Date and time format string (see man page for strptime).

result

Broken-down time (Sys.tm) 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 broken-down time (Sys.tm), using the current timezone.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

result

Output tuple (see Sys.tm) representing 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 broken-down time (Sys.tm), using a specified timezone.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

tzone

Timezone to use for conversion.

result

Output tuple (see Sys.tm) representing broken down time in the specified timezone.

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

Converts date and time strings into a timestamp containing the time since the Epoch, 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', current locale is used for month names. If 'false', C locale is assumed. Performance of timeStringToTimestamp() is greater with useLocaleMonth == 'false'.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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

Converts date and time strings into a timestamp containing the time since the Epoch, 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

Time zone (e.g., "UTC").

useLocaleMonth

If 'true', current locale is used for month names. If 'false', C locale is assumed. Performance of timeStringToTimestamp is greater with useLocaleMonth == 'false'.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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

Converts date and time strings into a timestamp containing the time since the Epoch, 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', current locale is used for month names. If 'false', C locale is assumed. Performance of timeStringToTimestamp() is greater with useLocaleMonth == 'false'.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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

Converts date and time strings into a timestamp containing the time since the Epoch, 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

Time zone (e.g., "UTC").

useLocaleMonth

If 'true', current locale is used for month names. If 'false', C locale is assumed. Performance of timeStringToTimestamp is greater with useLocaleMonth == 'false'.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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

DEPRECATED. Please replace with timeStringToTimestamp. Converts date and time strings into a timestamp containing the time since the Epoch, using the current timezone.

Note: DEPRECATED. Please replace with timeStringToTimestamp.

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. Performance of timeStringToTimestamp is greater with useLocaleMonth == 'false'.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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

DEPRECATED. Please replace with timeStringToTimestamp. Converts date and time strings into a timestamp containing the time since the Epoch, using the specified timezone.

Note: DEPRECATED. Please replace with timeStringToTimestamp.

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

Time zone (e.g., "UTC").

useLocaleMonth

If 'true', current locale is used for month names. If 'false', C locale is assumed. Performance of timeStringToTimestamp is greater with useLocaleMonth == 'false'.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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

DEPRECATED. Please replace with timeStringToTimestamp. Converts date and time strings into a timestamp containing the time since the Epoch, using the current timezone.

Note: DEPRECATED. Please replace with timeStringToTimestamp.

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. Performance of timeStringToTimestamp is greater with useLocaleMonth == 'false'.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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

DEPRECATED. Please replace with timeStringToTimestamp. Converts date and time strings into a timestamp containing the time since the Epoch, using the specified timezone.

Note: DEPRECATED. Please replace with timeStringToTimestamp.

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

Time zone (e.g., "UTC").

useLocaleMonth

If 'true', current locale is used for month names. If 'false', C locale is assumed. Performance of timeStringToTimestamp is greater with useLocaleMonth == 'false'.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

public decimal128 toDecimal128(timestamp ts)

Convert a timestamp to a decimal128 value.

Parameters

ts

Timestamp.

Returns

Timestamp as a decimal128 value (preserve all bits).

<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 containing the time since the Epoch, using the current time zone. Supported formats:

• 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 (e.g., Sys.YYYY_MM_DD_hh_mm_ss_mmm).

str

A string with the specified format.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

<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, T tmzone)

Converts a date and time string into a timestamp containing the time since the Epoch, using the specified time zone. Supported formats:

• 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 (e.g., Sys.YYYY_MM_DD_hh_mm_ss_mmm).

str

A string with the specified format.

tmzone

A string with the timezone.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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 (Sys.tm) into a timestamp containing the time since the Epoch.

Parameters

time

Broken-down time tuple.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

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 (Sys.tm) into a timestamp containing the time since the Epoch. Additional parameter to specify using default time zone

Parameters

time

Broken-down time tuple.

defaultZone

If 'true', then use default time zone.

Returns

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

public uint32 year (timestamp time)

Extract the year from the time, using the current timezone.

Note: This function uses the POSIX localtime_r routine.

Parameters

time

Seconds since the Epoch (00:00:00 UTC, January 1, 1970).

Returns

The year component of the time.