Error

The error to be returned when arguments are invalid.


FormatError

Localized time zone implementation to handle time zones.  


readonly

Zone

Initialize a TimeZone class using a zone ID.



init

Zone ID as a string or nil to initialize a TimeZone object with the system default time zone


zoneId

string

If always at a fixed offset from Utc, then this function returns it; otherwise nil.



fixedOffset

ZoneOffset

Converts a given `time:Civil` value to an `time:Utc` timestamp based on the time zone value.



utcFromCivil

civil

Civil

The corresponding `time:Utc` value or an error if `civil.timeAbbrev` is missing


Converts a given `time:Utc` timestamp to a `time:Civil` value based on the time zone value.



utcToCivil

TimeZone

FRIDAY

MONDAY

SATURDAY

SUNDAY

THURSDAY

TUESDAY

WEDNESDAY

## 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:
```ballerina
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:
```ballerina
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

### Time zone
The time zone can be obtained using a given zone ID or load the system time zone.
```ballerina
// Obtain the time zone corresponding to a given time zone ID.
time:Zone? zone = time:getZone("Asia/Colombo");

// Obtain the system time zone.
time:Zone zone = check time:loadSystemZone();
```

### 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
```ballerina
// 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
```ballerina
// 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
```ballerina
// 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
```ballerina
// 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);
```



Indicate how to handle both `zoneOffset` and `timeAbbrev`.


PREFER_TIME_ABBREV

PREFER_ZONE_OFFSET

ZONE_OFFSET_WITH_TIME_ABBREV_COMMENT

HeaderZoneHandling

Converts a given RFC 5322 formatted (e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`) string to a civil record.
```ballerina
time:Civil|time:Error emailDateTime = time:civilFromEmailString("Wed, 10 Mar 2021 19:51:55 -0820");
```


civilFromEmailString

RFC 5322 formatted (e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`) string to be converted


dateTimeString

The corresponding civil record or an error if the given string is incorrectly formatted.


Converts a given RFC 3339 timestamp(e.g., `2007-12-03T10:15:30.00Z`) to `time:Civil`.
```ballerina
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");
```


civilFromString

RFC 3339 timestamp (e.g., `2007-12-03T10:15:30.00Z`) as a string


The corresponding `time:Civil` value or an error if the given `dateTimeString` is invalid


Converts a given Civil record to RFC 5322 format (e.g `Wed, 10 Mar 2021 19:51:55 -0800 (PST)`).
```ballerina
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);
```


civilToEmailString

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.


zoneHandling

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)


Obtain a RFC 3339 timestamp (e.g., `2007-12-03T10:15:30.00Z`) from a given `time:Civil`.
```ballerina
time:Civil civil = check time:civilFromString("2007-12-03T10:15:30.00Z");
string|time:Error civilString = time:civilToString(civil);
```


civilToString

The corresponding string value or an error if the specified `time:Civil` contains invalid parameters (e.g., `month` > 12)


Check that days and months are within range as per Gregorian calendar rules.
```ballerina
time:Date date = {year: 1994, month: 11, day: 7};
time:Error? isValid = time:dateValidate(date);
```


dateValidate

date

Date

`()` if the `date` is valid or else `time:Error`


Get the day of week for a specified date.
```ballerina
time:Date date = {year: 1994, month: 11, day: 7};
time:DayOfWeek day = time:dayOfWeek(date);
```


dayOfWeek

`time:DayOfWeek` if the `date` is valid or else panic


DayOfWeek

Return the time zone object of a given zone ID.
```ballerina
time:Zone? zone = time:getZone("Asia/Colombo");
```


getZone

Time zone ID in the format of ("Continent/City")


Load the default time zone of the system.
```ballerina
time:Zone|time:Error zone = time:loadSystemZone();
```


loadSystemZone

Zone value or error when the zone ID of the system is in invalid format. 


Returns no of seconds from unspecified epoch.
This API guarantees consistent value increase in subsequent calls with nanoseconds precision.
```ballerina
decimal seconds = time:monotonicNow();
```


monotonicNow

Number of seconds from an unspecified epoch


decimal

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.
```ballerina
time:Utc utc = time:utcAddSeconds(time:utcNow(), 20.900);
```


utcAddSeconds

seconds

Seconds

The resulted `time:Utc` value after the summation


Returns difference in seconds between `utc1` and `utc2`.
This will be positive if `utc1` occurs after `utc2`
```ballerina
time:Utc utc1 = time:utcNow();
time:Utc utc2 = check time:utcFromString("2021-04-12T23:20:50.520Z");
time:Seconds seconds = time:utcDiffSeconds(utc1, utc2);
```


utcDiffSeconds

1st Utc time as a tuple `[int, decimal]`


utc1

2nd Utc time as a tuple `[int, decimal]`


utc2

The difference between `utc1` and `utc2` as `Seconds`


Converts a given `Civil` value to an `Utc` timestamp.
```ballerina
time:Civil civil = time:utcToCivil(time:utcNow());
time:Utc utc = time:utcFromCivil(civil);
```


civilTime

The corresponding `time:Utc` value or an error if `civilTime.utcOffset` is missing


Converts from RFC 3339 timestamp (e.g., `2007-12-03T10:15:30.00Z`) to Utc.
```ballerina
time:Utc|time:Error utc = time:utcFromString("2007-12-03T10:15:30.00Z");
```


utcFromString

RFC 3339 timestamp (e.g., `2007-12-03T10:15:30.00Z`) value as a string


timestamp

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


Returns the UTC representing the current time (current instant of the system clock in seconds from the epoch of `1970-01-01T00:00:00`).
```ballerina
time:Utc utc = time:utcNow();
```


utcNow

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)


precision

The `time:Utc` value corresponding to the current UTC time


Converts a given `time:Utc` timestamp to a `time:Civil` value.
```ballerina
time:Utc utc = time:utcNow();
time:Civil civil = time:utcToCivil(utc);
```


Converts a given UTC to an email formatted string (e.g `Mon, 3 Dec 2007 10:15:30 GMT`).
```ballerina
time:Utc utc = time:utcNow();
string emailFormattedString = time:utcToEmailString(utc);
```


utcToEmailString

UtcZoneHandling

Converts a given `time:Utc` time to a RFC 3339 timestamp (e.g., `2007-12-03T10:15:30.00Z`).
```ballerina
string utcString = time:utcToString(time:utcNow());
```


utcToString

The corresponding RFC 3339 timestamp string


Abstract object representation to handle time zones.  


Converts a given `Civil` value to an `Utc` timestamp based on the time zone value.



The corresponding `Utc` value or an error if `civil.timeAbbrev` is missing


Converts a given `Utc` timestamp to a `Civil` value based on the time zone value.



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


year

month

anydata

hour

minute

Second as decimal value with nanoseconds precision

second

utcOffset

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


timeAbbrev

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


which

ZERO_OR_ONE

Day of the week (e.g., SUNDAY, MONDAY, TUESDAY, ... SATURDAY)


Time within a day
Not always duration from midnight.



TimeOfDay

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


hours

minutes

IETF zone files have historical zones that are offset by
integer seconds; we use Seconds type so that this is a subtype
of Delta


This module provides a set of APIs that have the capabilities to generate and manipulate UTC and localized time.


The day of week according to the US convention.


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


Defualt zone value represation in different formats.


"GMT"

"UT"

Represents the type that can be either zero or one.


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


Errors