Module time
ballerina/time Ballerina library
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., 2021-03-05T00:33:28.839564+05:30) 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.
time:Zone? zone = time:getZone("Asia/Colombo");
Parameters
- id string - Time zone ID in the format of ("Continent/City")
Return Type
- Zone? - Corresponding ime zone object or null
loadSystemZone
Load the default time zone of the system.
time:Zone|time:Error zone = time:loadSystemZone();
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-03T10: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
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
Variables
time: Z
Represents the Z zone, hours: 0 and minutes: 0.
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 - 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
- which? ZERO_OR_ONE - when the clocks are put back at the end of DST, one hour's worth of times occur twice i.e. the local time is ambiguous this says which of those two times is meant same as fold field in Python see https://www.python.org/dev/peps/pep-0495/ is_dst has similar role in struct tm, but with confusing semantics
- 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
Errors
time: Error
The generic module level error.
time: FormatError
The error to be returned when arguments are invalid.
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
Union types
time: DayOfWeek
DayOfWeek
The day of week according to the US convention.
time: ZERO_OR_ONE
ZERO_OR_ONE
Represents the type that can be either zero or one.
time: UtcZoneHandling
UtcZoneHandling
Defualt zone value represation in different formats.
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.
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).
Decimal types
time: Seconds
Seconds
Holds the seconds as a decimal value.