This package provides implementations related to the UTC and localized time. In the world of cloud computing, the most essential type of time is UTC. Therefore, the more focus on this module is to give the most precise UTC and also handle some complex use cases such as leap seconds and daylight time-saving.
time:Utc is the tuple representation of the UTC. The UTC represents the number of seconds from a
specified epoch. Here, the epoch is the UNIX epoch of 1970-01-01T00:00:00Z.
Use the following API to get the current epoch time:
1time:Utc utc = time:utcNow();
The monotonic time represents the number of seconds from an unspecified epoch.
Use the following API to get the monotonic time from an unspecified topic:
1decimal seconds = time:monotonicNow();
The localized time represents using
time:Civil record. It includes the following details:
- timezone information
- daylight time-saving information
Parallel to the aforementioned time representations, this package includes a set of APIs to facilitate time conversions and manipulations using a set of high-level APIs. Those conversion APIs can be listed as follows.
The String Representations of UTC
1// Converts from RFC 3339 timestamp to UTC2time:Utc utc = check time:utcFromString("2007-12-0310:15:30.00Z");34// Converts a given time:Utc time to a RFC 3339 timestamp5string utcString = time:utcToString(utc);
The String Representations of Civil
1// Converts from RFC 3339 timestamp to a civil record2time:Civil civil2 = check time:civilFromString("2007-12-03T10:15:30.00Z");34// Converts a given time:Civil time to a RFC 3339 timestamp5string civilString = check time:civilToString(civil);
UTC Value Manipulation
1// Returns the UTC time that occurs seconds after the given UTC2time:Utc utc = time:utcAddSeconds(time:utcNow(), 20.900);34// Returns difference in seconds between two given UTC time values5time:Utc utc1 = time:utcNow();6time:Utc utc2 = check time:utcFromString("2021-04-12T23:20:50.520Z");7time:Seconds seconds = time:utcDiffSeconds(utc1, utc2);
UTC vs Civil
1// Converts a given UTC to a Civil2time:Civil civil = time:utcToCivil(utc);34// Converts a given Civil to an UTC5time:Utc utc = time:utcFromCivil(civil);
To learn more about these APIs, see the time example.
Converts a given RFC 5322 formatted(e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`) string to a civil record.
Converts a given RFC 3339 timestamp(e.g.
Converts a given Civil record to RFC 5322 format(e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`).
Obtain a RFC 3339 timestamp(e.g.
Check that days and months are within range as per Gregorian calendar rules.
Get the day of week for a specified date.
Returns no of seconds from unspecified epoch.
Returns Utc time that occurs seconds after `utc`.
Returns difference in seconds between utc1 and utc2.
Converts a given `Civil` value to an `Utc` timestamp.
Converts from RFC 3339 timestamp(e.g.
Returns Utc representing current time(current instant of the system clock as seconds from the epoch of 1970-01-01T00:00:00).
Converts a given `Utc` timestamp to a `Civil` value.
Converts a given UTC to an email formatted string(e.g `Mon, 3 Dec 2007 10:15:30 GMT`).
Converts a given `time:Utc` time to a RFC 3339 timestamp(e.g.
Time within some region relative to a time scale stipulated by civilian authorities.
Date in proleptic Gregorian calendar.
Time within a day Not always duration from midnight.
This is closed so it is a subtype of Delta Fields can negative if any of the three fields are > 0, then all must be >= 0 if any of the three fields are < 0, then all must be <= 0 Semantic is that durations should be left out
Friday represents from integer 5.
Monday represents from integer 1.
Saturday represents from integer 6.
Represents Sunday from integer 0.
Thursday represents from integer 4.
Tuesday represents from integer 2.
Wednesday represents from integer 3.
Indicate how to handle both `zoneOffset` and `timeAbbrev`.
The day of weel according to the US convention.
Holds the seconds as a decimal value.
Point on UTC time-scale.
Defualt zone value represation in different formats.
Represents the type that can be either zero or one.
The generic module level error.