Functions

civilFromEmailString	I Converts a given RFC 5322 formatted (e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`) string to a civil record.
civilFromString	I Converts a given RFC 3339 timestamp(e.g., `2007-12-03T10:15:30.00Z`) to `time:Civil`.
civilToEmailString	I Converts a given Civil record to RFC 5322 format (e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`).
civilToString	I Obtain a RFC 3339 timestamp (e.g., `2007-12-03T10:15:30.00Z`) from a given `time:Civil`.
dateValidate	I Check that days and months are within range as per Gregorian calendar rules.
dayOfWeek	I Get the day of week for a specified date.
getZone	I Return the time zone object of a given zone ID.
loadSystemZone	I Load the default time zone of the system.
monotonicNow	I Returns no of seconds from unspecified epoch.
utcAddSeconds	I Returns UTC time that occurs seconds after `utc`.
utcDiffSeconds	I Returns difference in seconds between `utc1` and `utc2`.
utcFromCivil	I Converts a given `Civil` value to an `Utc` timestamp.
utcFromString	I Converts from RFC 3339 timestamp (e.g., `2007-12-03T10:15:30.00Z`) to Utc.
utcNow	I Returns the UTC representing the current time (current instant of the system clock in seconds from the epoch of `1970-01-01T00:00:00`).
utcToCivil	I Converts a given `time:Utc` timestamp to a `time:Civil` value.
utcToEmailString	I Converts a given UTC to an email formatted string (e.g `Mon, 3 Dec 2007 10:15:30 GMT`).
utcToString	I Converts a given `time:Utc` time to a RFC 3339 timestamp (e.g., `2007-12-03T10:15:30.00Z`).

civilFromEmailString

function civilFromEmailString(string dateTimeString) returns Civil | Error

Isolated Function

Converts a given RFC 5322 formatted (e.g Wed, 10 Mar 2021 19:51:55 -0800 (PST)) string to a civil record.


1time:Civil|time:Error emailDateTime = time:civilFromEmailString("Wed, 10 Mar 2021 19:51:55 -0820");

Parameters

dateTimeString string

RFC 5322 formatted (e.g Wed, 10 Mar 2021 19:51:55 -0800 (PST)) string to be converted

Return Type

(Civil | Error)

The corresponding civil record or an error if the given string is incorrectly formatted.

civilFromString

function civilFromString(string dateTimeString) returns Civil | Error

Isolated Function

Converts a given RFC 3339 timestamp(e.g., 2007-12-03T10:15:30.00Z) to time:Civil.


1time:Civil|time:Error civil1 = time:civilFromString("2021-04-12T23:20:50.520+05:30[Asia/Colombo]");
2time:Civil|time:Error civil2 = time:civilFromString("2007-12-03T10:15:30.00Z");

Parameters

dateTimeString string

RFC 3339 timestamp (e.g., 2007-12-03T10:15:30.00Z) as a string

Return Type

(Civil | Error)

The corresponding time:Civil value or an error if the given dateTimeString is invalid

civilToEmailString

function civilToEmailString(Civil civil, HeaderZoneHandling zoneHandling) returns string | Error

Isolated Function

Converts a given Civil record to RFC 5322 format (e.g Wed, 10 Mar 2021 19:51:55 -0800 (PST)).


1time:Civil civil = check time:civilFromString("2021-04-12T23:20:50.520+05:30[Asia/Colombo]");
2string|time:Error emailDateTime = time:civilToEmailString(civil, time:PREFER_ZONE_OFFSET);

Parameters

civil Civil

The civil record to be converted

zoneHandling HeaderZoneHandling

Indicate how to handle the zone by specifying the preference whether to give preference to zone offset or time abbreviation. Also, this can configure to use zone offset to the execution and use time abbreviation as a comment.

Return Type

(string | Error)

RFC 5322 formatted (e.g Wed, 10 Mar 2021 19:51:55 -0800 (PST)) string or an error if the specified time:Civil contains invalid parameters (e.g., month > 12)

civilToString

function civilToString(Civil civil) returns string | Error

Isolated Function

Obtain a RFC 3339 timestamp (e.g., 2007-12-03T10:15:30.00Z) from a given time:Civil.


1time:Civil civil = check time:civilFromString("2007-12-03T10:15:30.00Z");
2string|time:Error civilString = time:civilToString(civil);

Parameters

civil Civil

time:Civil that needs to be converted

Return Type

(string | Error)

The corresponding string value or an error if the specified time:Civil contains invalid parameters (e.g., month > 12)

dateValidate

function dateValidate(Date date) returns Error?

Isolated Function

Check that days and months are within range as per Gregorian calendar rules.


1time:Date date = {year: 1994, month: 11, day: 7};
2time:Error? isValid = time:dateValidate(date);

Parameters

date Date

The date to be validated

Return Type

(Error?)

() if the date is valid or else time:Error

dayOfWeek

function dayOfWeek(Date date) returns DayOfWeek

Isolated Function

Get the day of week for a specified date.


1time:Date date = {year: 1994, month: 11, day: 7};
2time:DayOfWeek day = time:dayOfWeek(date);

Parameters

date Date

Date value

Return Type

(DayOfWeek)

time:DayOfWeek if the date is valid or else panic

getZone

function getZone(string id) returns Zone?

Isolated Function

Return the time zone object of a given zone ID.

Parameters

id string

Time zone ID (e.g., "Continent/City")

Return Type

(Zone?)

Corresponding ime zone object or null

loadSystemZone

function loadSystemZone() returns Zone | Error

Isolated Function

Load the default time zone of the system.

Return Type

(Zone | Error)

Zone value or error when the zone ID of the system is in invalid format.

monotonicNow

function monotonicNow() returns decimal

Isolated Function

Returns no of seconds from unspecified epoch. This API guarantees consistent value increase in subsequent calls with nanoseconds precision.


1decimal seconds = time:monotonicNow();

Return Type

(decimal)

Number of seconds from an unspecified epoch

utcAddSeconds

function utcAddSeconds(Utc utc, Seconds seconds) returns Utc

Isolated Function

Returns UTC time that occurs seconds after utc. This assumes that all days have 86400 seconds except when utc represents a time during a positive leap second, in which case the corresponding day will be assumed to have 86401 seconds.


1time:Utc utc = time:utcAddSeconds(time:utcNow(), 20.900);

Parameters

utc Utc

Utc time as a tuple [int, decimal]

seconds Seconds

Number of seconds to be added

Return Type

(Utc)

The resulted time:Utc value after the summation

utcDiffSeconds

function utcDiffSeconds(Utc utc1, Utc utc2) returns Seconds

Isolated Function

Returns difference in seconds between utc1 and utc2. This will be positive if utc1 occurs after utc2


1time:Utc utc1 = time:utcNow();
2time:Utc utc2 = check time:utcFromString("2021-04-12T23:20:50.520Z");
3time:Seconds seconds = time:utcDiffSeconds(utc1, utc2);

Parameters

utc1 Utc

1st Utc time as a tuple [int, decimal]

utc2 Utc

2nd Utc time as a tuple [int, decimal]

Return Type

(Seconds)

The difference between utc1 and utc2 as Seconds

utcFromCivil

function utcFromCivil(Civil civilTime) returns Utc | Error

Isolated Function

Converts a given Civil value to an Utc timestamp.


1time:Civil civil = time:utcToCivil(time:utcNow());
2time:Utc utc = time:utcFromCivil(civil);

Parameters

civilTime Civil

time:Civil time

Return Type

(Utc | Error)

The corresponding time:Utc value or an error if civilTime.utcOffset is missing

utcFromString

function utcFromString(string timestamp) returns Utc | Error

Isolated Function

Converts from RFC 3339 timestamp (e.g., 2007-12-03T10:15:30.00Z) to Utc.


1time:Utc|time:Error utc = time:utcFromString("2007-12-0310:15:30.00Z");

Parameters

timestamp string

RFC 3339 timestamp (e.g., 2007-12-03T10:15:30.00Z) value as a string

Return Type

(Utc | Error)

The corresponding time:Utc or a time:Error when the specified timestamp is not adhere to the RFC 3339 format (e.g., 2007-12-03T10:15:30.00Z)

utcNow

function utcNow(int? precision) returns Utc

Isolated Function

Returns the UTC representing the current time (current instant of the system clock in seconds from the epoch of 1970-01-01T00:00:00).


1time:Utc utc = time:utcNow();

Parameters

precision int? (default ())

Specifies the number of zeros after the decimal point (e.g., 3 would give the millisecond precision and nil means native precision (nanosecond precision 9) of the clock)

Return Type

(Utc)

The time:Utc value corresponding to the current UTC time

utcToCivil

function utcToCivil(Utc utc) returns Civil

Isolated Function

Converts a given time:Utc timestamp to a time:Civil value.


1time:Utc utc = time:utcNow();
2time:Civil civil = time:utcToCivil(utc);

Parameters

utc Utc

time:Utc timestamp

Return Type

(Civil)

The corresponding time:Civil value

utcToEmailString

function utcToEmailString(Utc utc, UtcZoneHandling zh) returns string

Isolated Function

Converts a given UTC to an email formatted string (e.g Mon, 3 Dec 2007 10:15:30 GMT).


1time:Utc utc = time:utcNow();
2string emailFormattedString = time:utcToEmailString(utc);

Parameters

utc Utc

The UTC value to be formatted

zh UtcZoneHandling (default "0")

Type of the zone value to be added

Return Type

(string)

The corresponding formatted string

utcToString

function utcToString(Utc utc) returns string

Isolated Function

Converts a given time:Utc time to a RFC 3339 timestamp (e.g., 2007-12-03T10:15:30.00Z).


1string utcString = time:utcToString(time:utcNow());

Parameters

utc Utc

Utc time as a tuple [int, decimal]

Return Type

(string)

The corresponding RFC 3339 timestamp string