time
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:
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:
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
The String Representations of Civil
UTC Value Manipulation
UTC vs 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.
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
.
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|Error
Converts a given Civil record to RFC 5322 format (e.g Wed, 10 Mar 2021 19:51:55 -0800 (PST)
).
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
.
Parameters
- civil Civil -
time:Civil
that needs to be converted
dateValidate
Check that days and months are within range as per Gregorian calendar rules.
Parameters
- date Date - The date to be validated
Return Type
- Error? -
()
if thedate
is valid or elsetime:Error
dayOfWeek
Get the day of week for a specified date.
Parameters
- date Date - Date value
Return Type
- DayOfWeek -
time:DayOfWeek
if thedate
is 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 decimal
Returns no of seconds from unspecified epoch. This API guarantees consistent value increase in subsequent calls with nanoseconds precision.
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.
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
Returns difference in seconds between utc1
and utc2
.
This will be positive if utc1
occurs after 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
andutc2
asSeconds
utcFromCivil
Converts a given Civil
value to an Utc
timestamp.
Parameters
- civilTime Civil -
time:Civil
time
utcFromString
Converts from RFC 3339 timestamp (e.g., 2007-12-03T10:15:30.00Z
) to Utc.
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
).
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
Converts a given time:Utc
timestamp to a time:Civil
value.
Parameters
- utc Utc -
time:Utc
timestamp
Return Type
- Civil - The corresponding
time:Civil
value
utcToEmailString
function utcToEmailString(Utc utc, UtcZoneHandling zh) returns string
Converts a given UTC to an email formatted string (e.g Mon, 3 Dec 2007 10:15:30 GMT
).
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
).
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:Civil
time
utcToCivil
Converts a given time:Utc
timestamp to a time:Civil
value based on the time zone value.
Parameters
- utc Utc -
time:Utc
timestamp
Return Type
- Civil - The corresponding
time:Civil
value
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 -
Civil
time
utcToCivil
Converts a given Utc
timestamp to a Civil
value based on the time zone value.
Parameters
- utc Utc -
Utc
timestamp
Return Type
- Civil - The corresponding
Civil
value
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.