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.

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.

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.

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.

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

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)

DayOfWeek if the date is valid or else panic

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
  • Civil time

Return Type

(Utc | Error)

The corresponding 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 Utc timestamp to a Civil value.

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

Parameters

  • utc Utc
  • Utc timestamp

Return Type

(Civil)

The corresponding 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

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