Standard library

time

Module time

civilFromEmailString
civilFromString
civilToEmailString
civilToString
dateValidate
dayOfWeek
monotonicNow
utcAddSeconds
utcDiffSeconds
utcFromCivil
utcFromString
utcNow
utcToCivil
utcToEmailString
utcToString

Civil
Date
TimeOfDay
ZoneOffset

HeaderZoneHandling

FRIDAY
MONDAY
SATURDAY
SUNDAY
THURSDAY
TUESDAY
WEDNESDAY

DayOfWeek
Seconds
Utc
UtcZoneHandling
ZERO_OR_ONE

Z

Error
FormatError

ballerina/time

2.0.0-beta.2

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:

Copy

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:

Copy

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

Copy

The String Representations of Civil

Copy

UTC Value Manipulation

Copy

UTC vs Civil

Copy

Functions

civilFromEmailString

Isolated Function
function civilFromEmailString(string dateTimeString) returns Civil|Error

Converts a given RFC 5322 formatted(e.g Wed, 10 Mar 2021 19:51:55 -0800 (PST)) string to a civil record.

Copy
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

Isolated Function
function civilFromString(string dateTimeString) returns Civil|Error

Converts a given RFC 3339 timestamp(e.g. 2007-12-03T10:15:30.00Z) to time:Civil.

Copy
Parameters
  • dateTimeString string - RFC 3339 timestamp(e.g. 2007-12-03T10:15:30.00Z) as a string
Return Type
  • Civil|Error - The corresponding time:Civil value or an error if the given dateTimeString is invalid

civilToEmailString

Isolated Function
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)).

Copy
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 specified time:Civil contains invalid parameters(e.g. month > 12)

civilToString

Isolated Function
function civilToString(Civil civil) returns string|Error

Obtain a RFC 3339 timestamp(e.g. 2007-12-03T10:15:30.00Z) from a given time:Civil.

Copy
Parameters
  • civil Civil - time:Civil that needs to be converted
Return Type
  • string|Error - The corresponding string value or an error if the specified time:Civil contains invalid parameters(e.g. month > 12)

dateValidate

Isolated Function
function dateValidate(Date date) returns Error?

Check that days and months are within range as per Gregorian calendar rules.

Copy
Parameters
  • date Date - The date to be validated
Return Type
  • Error? - () if the date is valid or else time:Error

dayOfWeek

Isolated Function
function dayOfWeek(Date date) returns DayOfWeek

Get the day of week for a specified date.

Copy
Parameters
  • date Date - Date value
Return Type
  • DayOfWeek - DayOfWeek if the date is valid or else panic

monotonicNow

Isolated Function
function monotonicNow() returns decimal

Returns no of seconds from unspecified epoch. This API guarantees consistent value increase in subsequent calls with nanoseconds precision.

Copy
Return Type
  • decimal - Number of seconds from an unspecified epoch

utcAddSeconds

Isolated Function
function utcAddSeconds(Utc utc, Seconds seconds) returns Utc

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.

Copy
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

Isolated Function
function utcDiffSeconds(Utc utc1, Utc utc2) returns Seconds

Returns difference in seconds between utc1 and utc2. This will be positive if utc1 occurs after utc2

Copy
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 and utc2 as Seconds

utcFromCivil

Isolated Function
function utcFromCivil(Civil civilTime) returns Utc|Error

Converts a given Civil value to an Utc timestamp.

Copy
Parameters
  • civilTime Civil - Civil time
Return Type
  • Utc|Error - The corresponding Utc value or an error if civilTime.utcOffset is missing

utcFromString

Isolated Function
function utcFromString(string timestamp) returns Utc|Error

Converts from RFC 3339 timestamp(e.g. 2007-12-03T10:15:30.00Z) to Utc.

Copy
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:Utc or a time:Error when the specified timestamp is not adhere to the RFC 3339 format(e.g. 2007-12-03T10:15:30.00Z)

utcNow

Isolated Function
function utcNow(int? precision) returns Utc

Returns the UTC representing the current time (current instant of the system clock in seconds from the epoch of 1970-01-01T00:00:00).

Copy
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

Isolated Function
function utcToCivil(Utc utc) returns Civil

Converts a given Utc timestamp to a Civil value.

Copy
Parameters
  • utc Utc - Utc timestamp
Return Type
  • Civil - The corresponding Civil value

utcToEmailString

Isolated Function
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).

Copy
Parameters
  • utc Utc - The UTC value to be formatted
Return Type
  • string - The corresponding formatted string

utcToString

Isolated Function
function utcToString(Utc utc) returns string

Converts a given time:Utc time to a RFC 3339 timestamp(e.g. 2007-12-03T10:15:30.00Z).

Copy
Parameters
  • utc Utc - Utc time as a tuple [int, decimal]
Return Type
  • string - The corresponding RFC 3339 timestamp string

Records

time: Civil

Time within some region relative to a time scale stipulated by civilian authorities.

Fields
  • 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

time: TimeOfDay

Time within a day Not always duration from midnight.

Fields

time: ZoneOffset

Read OnlyClosed record

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
  • 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

PREFER_TIME_ABBREV
PREFER_ZONE_OFFSET
ZONE_OFFSET_WITH_TIME_ABBREV_COMMENT

Constants

time: FRIDAY

int 5

Friday represents from integer 5.

time: MONDAY

int 1

Monday represents from integer 1.

time: SATURDAY

int 6

Saturday represents from integer 6.

time: SUNDAY

int 0

Represents Sunday from integer 0.

time: THURSDAY

int 4

Thursday represents from integer 4.

time: TUESDAY

int 2

Tuesday represents from integer 2.

time: WEDNESDAY

int 3

Wednesday represents from integer 3.

Types

time: DayOfWeek

SUNDAY|MONDAY|TUESDAY|WEDNESDAY|THURSDAY|FRIDAY|SATURDAY

The day of week according to the US convention.

time: Seconds

decimal

Holds the seconds as a decimal value.

time: Utc

readonly & [int, decimal]

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

"0"|"GMT"|"UT"|"Z"

Defualt zone value represation in different formats.

time: ZERO_OR_ONE

0|1

Represents the type that can be either zero or one.

Variables

time: Z

ZoneOffset(default {hours: 0})

Represents the Z zone, hours: 0 and minutes: 0.

Errors

time: Error

The generic module level error.

time: FormatError

Distinct
Error

The error to be returned when arguments are invalid.

Other versions

2.2.42.2.32.2.22.2.12.2.0
See more...

Terms of service

Privacy policy

Cookie policy

2023 WSO2