Module time
ballerina/time Ballerina library
Package Overview
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.
UTC Time
The 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:
time:Utc utc = time:utcNow();
Monotonic Time
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:
decimal seconds = time:monotonicNow();
Civil Time
The localized time represents using time:Civil record. It includes the following details:
- date
- time
- timezone information
- daylight time-saving information
APIs
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
// Converts from RFC 3339 timestamp to UTC time:Utc utc = check time:utcFromString("2007-12-0310:15:30.00Z"); // Converts a given time:Utc time to a RFC 3339 timestamp string utcString = time:utcToString(utc);
The String Representations of Civil
// Converts from RFC 3339 timestamp to a civil record time:Civil civil2 = check time:civilFromString("2007-12-03T10:15:30.00Z"); // Converts a given time:Civil time to a RFC 3339 timestamp string civilString = check time:civilToString(civil);
UTC Value Manipulation
// Returns the UTC time that occurs seconds after the given UTC time:Utc utc = time:utcAddSeconds(time:utcNow(), 20.900); // Returns difference in seconds between two given UTC time values time:Utc utc1 = time:utcNow(); time:Utc utc2 = check time:utcFromString("2021-04-12T23:20:50.520Z"); time:Seconds seconds = time:utcDiffSeconds(utc1, utc2);
UTC vs Civil
// Converts a given UTC to a Civil time:Civil civil = time:utcToCivil(utc); // Converts a given Civil to an UTC time:Utc utc = time:utcFromCivil(civil);
To learn more about these APIs, see the time example.
Functions
civilFromEmailString
Converts a given RFC 5322 formatted(e.g Wed, 10 Mar 2021 19:51:55 -0800 (PST)) string to a civil record.
time: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
Converts a given RFC 3339 timestamp(e.g. 2007-12-03T10:15:30.00Z) to time:Civil.
time:Civil|time:Error civil1 = time:civilFromString("2021-04-12T23:20:50.520+05:30[Asia/Colombo]"); time: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:Civilvalue or an error if the givendateTimeStringis invalid
civilToEmailString
function civilToEmailString(Civil civil, HeaderZoneHandling zoneHandling) returns string|ErrorConverts a given Civil record to RFC 5322 format(e.g Wed, 10 Mar 2021 19:51:55 -0800 (PST)).
time:Civil civil = check time:civilFromString("2021-04-12T23:20:50.520+05:30[Asia/Colombo]"); string|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 specifiedtime:Civilcontains invalid parameters(e.g.month> 12)
civilToString
Obtain a RFC 3339 timestamp(e.g. 2007-12-03T10:15:30.00Z) from a given time:Civil.
time:Civil civil = check time:civilFromString("2007-12-03T10:15:30.00Z"); string|time:Error civilString = time:civilToString(civil);
Parameters
- civil Civil -
time:Civilthat needs to be converted
Return Type
- string|Error - The corresponding string value or an error if the specified
time:Civilcontains invalid parameters(e.g.month> 12)
dateValidate
function dateValidate(Date date) returns Error?Check that days and months are within range as per Gregorian calendar rules.
time:Date date = {year: 1994, month: 11, day: 7}; time:Error? isValid = time:dateValidate(date);
Parameters
- date Date - The date to be validated
Return Type
- Error? -
()if thedateis valid or elsetime:Error
dayOfWeek
Get the day of week for a specified date.
time:Date date = {year: 1994, month: 11, day: 7}; time:DayOfWeek day = time:dayOfWeek(date);
Parameters
- date Date - Date value
Return Type
- DayOfWeek -
DayOfWeekif thedateis valid or else panic
monotonicNow
function monotonicNow() returns decimalReturns no of seconds from unspecified epoch. This API guarantees consistent value increase in subsequent calls with nanoseconds precision.
decimal seconds = time:monotonicNow();
Return Type
- decimal - Number of seconds from an unspecified epoch
utcAddSeconds
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.
time: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:Utcvalue after the summation
utcDiffSeconds
Returns difference in seconds between utc1 and utc2. This will be positive if utc1 occurs after utc2
time:Utc utc1 = time:utcNow(); time:Utc utc2 = check time:utcFromString("2021-04-12T23:20:50.520Z"); time: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
utc1andutc2asSeconds
utcFromCivil
Converts a given Civil value to an Utc timestamp.
time:Civil civil = time:utcToCivil(time:utcNow()); time:Utc utc = time:utcFromCivil(civil);
Parameters
- civilTime Civil -
Civiltime
Return Type
- Utc|Error - The corresponding
Utcvalue or an error ifcivilTime.utcOffsetis missing
utcFromString
Converts from RFC 3339 timestamp(e.g. 2007-12-03T10:15:30.00Z) to Utc.
time: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:Utcor atime:Errorwhen the specified timestamp is not adhere to the RFC 3339 format(e.g.2007-12-03T10:15:30.00Z)
utcNow
Returns Utc representing current time(current instant of the system clock as seconds from the epoch of 1970-01-01T00:00:00).
Parameters
- precision int? (default ()) - Specifies number of zeros after decimal point (e.g. 3 would give millisecond precision and nil means native precision(nanosecond precision 9) of clock)
Return Type
- Utc - The
time:Utcvalue corresponding to the current UTC time
utcToCivil
Converts a given Utc timestamp to a Civil value.
time:Utc utc = time:utcNow(); time:Civil civil = time:utcToCivil(utc);
Parameters
- utc Utc -
Utctimestamp
Return Type
- Civil - The corresponding
Civilvalue
utcToEmailString
function utcToEmailString(Utc utc, UtcZoneHandling zh) returns stringConverts a given UTC to an email formatted string(e.g Mon, 3 Dec 2007 10:15:30 GMT).
time:Utc utc = time:utcNow(); string 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
Converts a given time:Utc time to a RFC 3339 timestamp(e.g. 2007-12-03T10:15:30.00Z).
string utcString = time:utcToString(time:utcNow());
Parameters
- utc Utc - Utc time as a tuple
[int, decimal]
Return Type
- string - The corresponding RFC 3339 timestamp string
Constants
time: FRIDAY
Friday represents from integer 5.
time: MONDAY
Monday represents from integer 1.
time: SATURDAY
Saturday represents from integer 6.
time: SUNDAY
Represents Sunday from integer 0.
time: THURSDAY
Thursday represents from integer 4.
time: TUESDAY
Tuesday represents from integer 2.
time: WEDNESDAY
Wednesday represents from integer 3.
Enums
time: HeaderZoneHandling
Indicate how to handle both zoneOffset and timeAbbrev.
Members
Records
time: Civil
Time within some region relative to a time scale stipulated by civilian authorities.
Fields
- Fields Included from *DateFields
- Fields Included from *TimeOfDayFields
- utcOffset ZoneOffset? - optional zone offset
- timeAbbrev string? - the string representation of the time zone
- which ZERO_OR_ONE? - if present, abbreviation for the local time (e.g. EDT, EST) in effect at the time represented by this record; this is quite the same as the name of a time zone one time zone can have two abbreviations: one for standard time and one for daylight savings time
- dayOfWeek DayOfWeek? - day of the week(SUNDAY, MONDAY, TUESDAY, ... SATURDAY)
time: Date
Date in proleptic Gregorian calendar.
Fields
- Fields Included from *DateFields
- Fields Included from *OptionalTimeOfDayFields
- utcOffset ZoneOffset? - optional zone offset
time: TimeOfDay
Time within a day Not always duration from midnight.
Fields
- Fields Included from *OptionalDateFields
- Fields Included from *TimeOfDayFields
- utcOffset ZoneOffset? - optional zone offset
time: ZoneOffset
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
Fields
- hours int -
- minutes int(default 0) -
- seconds decimal? - IETF zone files have historical zones that are offset by integer seconds; we use Seconds type so that this is a subtype of Delta
Errors
time: Error
The generic module level error.
Union types
time: DayOfWeek
DayOfWeek
The day of weel according to the US convention.
time: UtcZoneHandling
UtcZoneHandling
Defualt zone value represation in different formats.
time: ZERO_OR_ONE
ZERO_OR_ONE
Represents the type that can be either zero or one.
Intersection types
time: Utc
Utc
Point on UTC time-scale. This is represented by a tuple of length 2. The tuple is an ordered type and so the values can be compared using the Ballerina <, <=, >, >= operators. First member of tuple is int representing integral number of seconds from the epoch. Epoch is traditional Unix epoch of 1970-01-01T00:00:00Z Second member of tuple is decimal giving the fraction of a second. For times before the epoch, n is negative and f is non-negative. In other words, the UTC time represented is on or after the second specified by n. Leap seconds are handled as follows. The first member of the tuple ignores leap seconds: it assumes that every day has 86400 seconds. The second member of the tuple is >= 0. and is < 1 except during positive leaps seconds in which it is >= 1 and < 2. So given a tuple [n,f] after the epoch, n / 86400 gives the day number, and (n % 86400) + f gives the time in seconds since midnight UTC (for which the limit is 86401 on day with a positive leap second).
Decimal types
time: Seconds
Seconds
Holds the seconds as a decimal value.