Module time
ballerina/time
Overview
This module provides a set of APIs that have the capabilities to generate and manipulate UTC and localized time.
In cloud computing, the most essential type of time is UTC. Coordinated Universal Time (UTC) is the primary time standard on which the world agreed.
UTC is independent of daylight saving time and provides a unique time value for the entire world.
The definition of UTC started from the epoc 1970-01-01T00:00:00Z. Initially, humans divided a day into 86400 seconds.
However, the Earth rotation does not adhere to this time duration as the Earth is slowing down and the day is getting longer.
As a result, a solar day in 2012 is longer than 86400 SI seconds.
To correct this incompatibility, additional seconds have been added to the UTC scale, which is known as leap-seconds.
The focus of this module is to give the most precise UTC with nanoseconds precision 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 the time:Civil record. It includes the following details:
- date
- time
- timezone information
- daylight time-saving information
APIs
Parallel to the aforementioned time representations, this module 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-03T10: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 the 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 a UTC. time:Utc utc = time:utcFromCivil(civil);
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
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
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.
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
dateValidate
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 -
time:DayOfWeekif thedateis valid or else panic
getZone
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
Load the default time zone of the system.
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 -
time:Civiltime
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
utcNow
Returns the UTC representing the current time (current instant of the system clock in seconds from the epoch of 1970-01-01T00:00:00).
time: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:Utcvalue corresponding to the current UTC time
utcToCivil
Converts a given time:Utc timestamp to a time:Civil value.
time:Utc utc = time:utcNow(); time:Civil civil = time:utcToCivil(utc);
Parameters
- utc Utc -
time:Utctimestamp
Return Type
- Civil - The corresponding
time: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
Classes
time: TimeZone
Localized time zone implementation to handle time zones.
Constructor
Initialize a TimeZone class using a zone ID.
init (string? zoneId)- zoneId string? () - Zone ID as a string or nil to initialize a TimeZone object with the system default time zone
fixedOffset
function fixedOffset() returns ZoneOffset?If always at a fixed offset from Utc, then this function returns it; otherwise nil.
Return Type
- ZoneOffset? - The fixed zone offset or nil
utcFromCivil
Converts a given time:Civil value to an time:Utc timestamp based on the time zone value.
Parameters
- civil Civil -
time:Civiltime
utcToCivil
Converts a given time:Utc timestamp to a time:Civil value based on the time zone value.
Parameters
- utc Utc -
time:Utctimestamp
Return Type
- Civil - The corresponding
time:Civilvalue
Fields
- Fields Included from * & readonly
- readonly
Object types
time: Zone
Abstract object representation to handle time zones.
fixedOffset
function fixedOffset() returns ZoneOffset?If always at a fixed offset from Utc, then this function returns it; otherwise nil.
Return Type
- ZoneOffset? - The fixed zone offset or nil
utcFromCivil
Converts a given Civil value to an Utc timestamp based on the time zone value.
Parameters
- civil Civil -
Civiltime
utcToCivil
Converts a given Utc timestamp to a Civil value based on the time zone value.
Parameters
- utc Utc -
Utctimestamp
Return Type
- Civil - The corresponding
Civilvalue
Records
time: Civil
Time within some region relative to a time scale stipulated by civilian authorities.
Fields
- year int - Year as an integer
- month int - Month as an integer (1 <= month <= 12)
- day int - Day as an integer (1 <= day <= 31)
- anydata... -
- hour int - Hour as an integer(0 <= hour <= 23)
- minute int - Minute as an integer(0 <= minute <= 59)
- second Seconds - Second as decimal value with nanoseconds precision
- anydata... -
- utcOffset ZoneOffset? - An 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 (e.g., SUNDAY, MONDAY, TUESDAY, ... SATURDAY)
time: Date
Date in proleptic Gregorian calendar.
Fields
- year int - Year as an integer
- month int - Month as an integer (1 <= month <= 12)
- day int - Day as an integer (1 <= day <= 31)
- anydata... -
- hour int - Hour as an integer(0 <= hour <= 23)
- minute int - Minute as an integer(0 <= minute <= 59)
- second Seconds - Second as decimal value with nanoseconds precision
- anydata... -
- utcOffset ZoneOffset? - Optional zone offset
time: TimeOfDay
Time within a day Not always duration from midnight.
Fields
- year int - Year as an integer
- month int - Month as an integer(1 <= month <= 12)
- day int - Day as an integer (1 <= day <= 31)
- anydata... -
- hour int - Hour as an integer(0 <= hour <= 23)
- minute int - Minute as an integer(0 <= minute <= 59)
- second Seconds - Second as decimal value with nanoseconds precision
- anydata... -
- 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
Enums
time: HeaderZoneHandling
Indicate how to handle both zoneOffset and timeAbbrev.
Members
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.
Types
time: DayOfWeek
The day of week according to the US convention.
time: Seconds
Holds the seconds as a decimal value.
time: 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.
The first member of the tuple is int representing an integral number of
seconds from the epoch.
Epoch is the traditional UNIX epoch of 1970-01-01T00:00:00Z.
The second member of the tuple is a 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).
time: UtcZoneHandling
Defualt zone value represation in different formats.
time: ZERO_OR_ONE
Represents the type that can be either zero or one.
Variables
time: Z
Represents the Z zone, hours: 0 and minutes: 0.
Errors
time: Error
The generic module level error.
time: FormatError
The error to be returned when arguments are invalid.