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:

1time: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:

1decimal 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

1// Converts from RFC 3339 timestamp to UTC.
2time:Utc utc = check time:utcFromString("2007-12-0310:15:30.00Z");
3
4// Converts a given `time:Utc` time to a RFC 3339 timestamp.
5string utcString = time:utcToString(utc);

The String Representations of Civil

1// Converts from RFC 3339 timestamp to a civil record.
2time:Civil civil2 = check time:civilFromString("2007-12-03T10:15:30.00Z");
3
4// Converts a given `time:Civil` time to a RFC 3339 timestamp.
5string civilString = check time:civilToString(civil);

UTC Value Manipulation

1// Returns the UTC time that occurs seconds after the given UTC.
2time:Utc utc = time:utcAddSeconds(time:utcNow(), 20.900);
3
4// Returns the difference in seconds between two given UTC time values.
5time:Utc utc1 = time:utcNow();
6time:Utc utc2 = check time:utcFromString("2021-04-12T23:20:50.520Z");
7time:Seconds seconds = time:utcDiffSeconds(utc1, utc2);

UTC vs Civil

1// Converts a given UTC to a Civil.
2time:Civil civil = time:utcToCivil(utc);
3
4// Converts a given Civil to a UTC.
5time:Utc utc = time:utcFromCivil(civil);

Functions

[15]

civilFromEmailString

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

civilFromString

Converts a given RFC 3339 timestamp(e.g.

civilToEmailString

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

civilToString

Obtain a RFC 3339 timestamp(e.g.

dateValidate

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

dayOfWeek

Get the day of week for a specified date.

monotonicNow

Returns no of seconds from unspecified epoch.

utcAddSeconds

Returns Utc time that occurs seconds after utc.

utcDiffSeconds

Returns difference in seconds between utc1 and utc2.

utcFromCivil

Converts a given Civil value to an Utc timestamp.

utcFromString

Converts from RFC 3339 timestamp(e.g.

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

utcToCivil

Converts a given Utc timestamp to a Civil value.

utcToEmailString

Converts a given UTC to an email formatted string(e.g Mon, 3 Dec 2007 10:15:30 GMT).

utcToString

Converts a given time:Utc time to a RFC 3339 timestamp(e.g.

Records

[4]

Civil

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

Date

Date in proleptic Gregorian calendar.

TimeOfDay

Time within a day Not always duration from midnight.

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

Constants

[7]

FRIDAY

Friday represents from integer 5.

MONDAY

Monday represents from integer 1.

SATURDAY

Saturday represents from integer 6.

SUNDAY

Represents Sunday from integer 0.

THURSDAY

Thursday represents from integer 4.

TUESDAY

Tuesday represents from integer 2.

WEDNESDAY

Wednesday represents from integer 3.

Enums

[1]

HeaderZoneHandling

Indicate how to handle both zoneOffset and timeAbbrev.

Types

[5]

DayOfWeek

The day of week according to the US convention.

Seconds

Holds the seconds as a decimal value.

Utc

Point on UTC time-scale.

UtcZoneHandling

Defualt zone value represation in different formats.

ZERO_OR_ONE

Represents the type that can be either zero or one.

Variables

[1]

Z

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

Errors

[2]

Error

The generic module level error.

FormatError

The error to be returned when arguments are invalid.