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

### 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-0310: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

Error

The error to be returned when arguments are invalid.


FormatError

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

string

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


Civil

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

civil

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

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


DayOfWeek

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


utcFromCivil

civilTime

The corresponding `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-0310: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 `Utc` timestamp to a `Civil` value.
```ballerina
time:Utc utc = time:utcNow();
time:Civil civil = time:utcToCivil(utc);
```


utcToCivil

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


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


year

month

anydata

hour

minute as an integer(0 <= minute <= 59)   

minute

second as decimal value with nanoseconds precision

second

utcOffset

ZoneOffset

the string representation of the time zone


timeAbbrev

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

day of the week(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).


readonly

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.


Record: TimeOfDay

Fields