ballerina/time module
Module overview
The ballerina/time
module provides implementations related to time, date, time zones, and durations.
The module has two main types as Time and TimeZone. The type Time
represents a time associated with a given time zone. It has time
and zone
as attributes. The type TimeZone
represents the time zone associated with a given time. It has id
and offset
as attributes. An id
can be one of the following:
- If
id
equals 'Z', the result is UTC. - If
id
equals 'GMT', 'UTC' or 'UT', it is equivalent to UTC. - If
id
starts with '+' or '-', the ID is parsed as an offset. Offset can be specified in one of the following ways. +h, +hh, +hh:mm, -hh:mm, +hhmm, -hhmm, +hh:mm:ss, -hh:mm:ss, +hhmmss, -hhmmss - Also
id
can be a region-based zone ID. The format is '{area}/{city}' eg: "America/Panama". The zones are based on IANA Time Zone Database (TZDB) supplied data.
Samples
Getting the current time/date
time:Time time = time:currentTime(); // Create a record of type ‘Time’.
int timeValue = time.time; // Time in milliseconds since January 1, 1970, 00:00:00 GMT. E.g., 1523513039.
int nanoTime = time:nanoTime(); // Time in nanoseconds since an arbitrary origin. Therefore, it should be used only to calculate durations. E.g., 2426115697486340.
string zoneId = time.zone.id; // Time zone as an identifier. E.g., “America/Panama”.
int zoneoffset = time.zone.offset; // Time zone as an offset. E.g., -05:00.
// Get the current date and time upto milliseconds.
int year = time:getYear(time); // E.g., 2018
int month = time:getMonth(time); // E.g., 3
int day = time:getDay(time); // E.g., 1
int hour = time:getHour(time); // E.g., 18
int minute = time:getMinute(time); // E.g., 56
int second = time:getSecond(time); // E.g., 23
int milliSecond = time:getMilliSecond(time); // E.g., 555
string weekday = time:getWeekday(time); // Day of the week. E.g., “TUESDAY”.
Creating a time/date record
// Create a record of type ‘Time’ with time zone.
time:TimeZone zoneIdValue = { id: "America/Panama" };
time:Time time1 = { time: 1498488382000, zone: zoneIdValue };
// Create a record of type ‘Time’ with the time zone offset.
time:TimeZone zoneOffsetValue = { id: "-05:00" };
time:Time time2 = { time: 1498488382000, zone: zoneOffsetValue };
// Create a record of type ‘Time’ without the time zone.
time:TimeZone noZoneValue = { id: "" };
time:Time time3 = { time: 1498488382000, zone: noZoneValue };
// Create a record of type ‘Time’ with time and date. E.g., 2018-03-28T23:42:45.554-05:00
time:Time|error dateTime = time:createTime(2018, 3, 28, 23, 42, 45, 554, "America/Panama");
Formatting a time/date to a string
time:TimeZone zoneValue = { id: "America/Panama" };
time:Time time = { time: 1498488382444, zone: zoneValue };
//Format a time to a string of a given pattern.
string|error time1 = time:format(time, "yyyy-MM-dd'T'HH:mm:ss.SSSZ"); //E.g., “2017-06-26T09:46:22.444-0500”.
//Format a time to a string of the RFC-1123 format.
string|error time2 = time:format(time, time:TIME_FORMAT_RFC_1123); // E.g., "Mon, 26 Jun 2017 09:46:22 -0500”
// Convert a time record to a string value.
string time3 = time:toString(time); //”2017-06-26T09:46:22.444-05:00”
Parsing a string to time/date
// Parse a time string of a given format.
time:Time|error time1 = time:parse("2017-06-26T09:46:22.444-0500", "yyyy-MM-dd'T'HH:mm:ss.SSSZ"); // The ‘Z’ stands for the time zone.
// Parse a time string of the RFC-1123 format.
time:Time|error time2 = time:parse("Wed, 28 Mar 2018 11:56:23 +0530", time:TIME_FORMAT_RFC_1123);
Setting time durations
// Add a duration to a given time.
time:Time|error time1 = time:parse("2017-06-26T09:46:22.444-0500", "yyyy-MM-dd'T'HH:mm:ss.SSSZ");
if (time1 is time:Time) {
time1 = time:addDuration(time1, 1, 1, 1, 1, 1, 1, 1);
// Adds 1 year, 1 month, 1 day, 1 hour, 1 minute, 1 second, and 1 millisecond.
}
// Subtract a duration from a given time.
time:Time|error time2 = time:parse("2016-03-01T09:46:22.444-0500", "yyyy-MM-dd'T'HH:mm:ss.SSSZ");
if (time2 is time:Time) {
time2 = time:subtractDuration(time2, 1, 1, 1, 1, 1, 1, 1);
// Subtracts 1 year, 1 month, 1 day, 1 hour, 1 minute, 1 second, and 1 millisecond.
}
// Get the duration between two times.
time:Time time3 = time:currentTime();
time:Time time4 = time:currentTime();
int diffInMillis = time3.time - time4.time;
Type Definitions
Type | Values | Description | |
---|---|---|---|
TimeFormat | RFC_1123 | The time format defined by the RFC-1123. |
Records Summary
Record | Description | ||
---|---|---|---|
Time | Ballerina Time represents a particular time with its associated time-zone. | ||
TimeZone | Ballerina TimeZone represents the time-zone information associated with a particular time. |
Functions Summary
Return Type | Function and Description | ||
---|---|---|---|
Time | addDuration(time:Time time, int years, int months, int days, int hours, int minutes, int seconds, int milliSeconds) Add specified durations to the given time value. |
||
Time|error<> | createTime(int year, int month, int date, int hour, int minute, int second, int milliSecond, string zoneId) Returns the Time object correspoding to the given time components and time-zone. |
||
Time | currentTime() Returns the current time value with the system default time-zone. |
||
string|error<> | format(time:Time time, string|RFC_1123 timeFormat) Returns formatted string representation of the given time. |
||
(int,int,int) | getDate(time:Time time) Returns the date representation of the given time. |
||
int | getDay(time:Time time) Returns the date representation of the given time. |
||
int | getHour(time:Time time) Returns the hour representation of the given time. |
||
int | getMilliSecond(time:Time time) Returns the millisecond representation of the given time. |
||
int | getMinute(time:Time time) Returns the minute representation of the given time. |
||
int | getMonth(time:Time time) Returns the month representation of the given time. |
||
int | getSecond(time:Time time) Returns the second representation of the given time. |
||
(int,int,int,int) | getTime(time:Time time) Returns the time representation of the given time. |
||
string | getWeekday(time:Time time) Returns the weekday representation of the given time. |
||
int | getYear(time:Time time) Returns the year representation of the given time. |
||
int | nanoTime() Returns the current system time in nano seconds. |
||
Time|error<> | parse(string data, string|RFC_1123 timeFormat) Returns the time for the given string representation based on the given format string. |
||
Time | subtractDuration(time:Time time, int years, int months, int days, int hours, int minutes, int seconds, int milliSeconds) Subtract specified durations from the given time value. |
||
string | toString(time:Time time) Returns ISO 8601 string representation of the given time. |
||
Time|error<> | toTimeZone(time:Time time, string zoneId) Change the time-zone of the given time. |
Constants
Name | Data Type | Value | Description | |
---|---|---|---|---|
TIME_FORMAT_RFC_1123 | RFC_1123 |
public type Time record
Ballerina Time represents a particular time with its associated time-zone.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
time | int | Time value as milliseconds since epoch |
|
zone | time:TimeZone | The time zone of the time |
public type TimeZone record
Ballerina TimeZone represents the time-zone information associated with a particular time.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
id | string | Zone short ID or offset string |
|
offset | int | 0 | The offset in seconds |
public function addDuration(time:Time time, int years, int months, int days, int hours, int minutes, int seconds, int milliSeconds) returns (Time)
Add specified durations to the given time value.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to add the duration to |
|
years | int | The year representation |
|
months | int | The month-of-year to represent, from 1 (January) to 12 (December) |
|
days | int | The day-of-month to represent, from 1 to 31 |
|
hours | int | The hour-of-day to represent, from 0 to 23 |
|
minutes | int | The minute-of-hour to represent, from 0 to 59 |
|
seconds | int | The second-of-minute to represent, from 0 to 59 |
|
milliSeconds | int | The milli-of-second to represent, from 0 to 999 |
Return Type | Description | ||
---|---|---|---|
Time | Time object containing time and zone information after the addition |
public function createTime(int year, int month, int date, int hour, int minute, int second, int milliSecond, string zoneId) returns (Time|error<>)
Returns the Time object correspoding to the given time components and time-zone.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
year | int | The year representation |
|
month | int | The month-of-year to represent, from 1 (January) to 12 (December) |
|
date | int | The day-of-month to represent, from 1 to 31 |
|
hour | int | The hour-of-day to represent, from 0 to 23 |
|
minute | int | The minute-of-hour to represent, from 0 to 59 |
|
second | int | The second-of-minute to represent, from 0 to 59 |
|
milliSecond | int | The milli-of-second to represent, from 0 to 999 |
|
zoneId | string | The zone id of the required time-zone.If empty the system local time-zone will be used |
Return Type | Description | ||
---|---|---|---|
Time|error<> | Time object containing time and zone information or an |
public function currentTime() returns (Time)
Returns the current time value with the system default time-zone.
Return Type | Description | ||
---|---|---|---|
Time | Time object containing the time and zone information |
public function format(time:Time time, string|RFC_1123 timeFormat) returns (string|error<>)
Returns formatted string representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to be formatted |
|
timeFormat | string|RFC_1123 | The format which is used to format the time represented by this object |
Return Type | Description | ||
---|---|---|---|
string|error<> | The formatted string of the given time or an |
public function getDate(time:Time time) returns ((int,int,int))
Returns the date representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to get the date representation from |
Return Type | Description | ||
---|---|---|---|
(int,int,int) | The year representation. The month-of-year, from 1 (January) to 12 (December). The day-of-month, from 1 to 31. |
public function getDay(time:Time time) returns (int)
Returns the date representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to get the date representation from |
Return Type | Description | ||
---|---|---|---|
int | The day-of-month, from 1 to 31 |
public function getHour(time:Time time) returns (int)
Returns the hour representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to get the hour representation from |
Return Type | Description | ||
---|---|---|---|
int | The hour-of-day, from 0 to 23 |
public function getMilliSecond(time:Time time) returns (int)
Returns the millisecond representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to get the millisecond representation from |
Return Type | Description | ||
---|---|---|---|
int | The milli-of-second, from 0 to 999 |
public function getMinute(time:Time time) returns (int)
Returns the minute representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to get the minute representation from |
Return Type | Description | ||
---|---|---|---|
int | The minute-of-hour to represent, from 0 to 59 |
public function getMonth(time:Time time) returns (int)
Returns the month representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to get the month representation from |
Return Type | Description | ||
---|---|---|---|
int | The month-of-year, from 1 (January) to 12 (December) |
public function getSecond(time:Time time) returns (int)
Returns the second representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to get the second representation from |
Return Type | Description | ||
---|---|---|---|
int | The second-of-minute, from 0 to 59 |
public function getTime(time:Time time) returns ((int,int,int,int))
Returns the time representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record |
Return Type | Description | ||
---|---|---|---|
(int,int,int,int) | The hour-of-day, from 0 to 23. The minute-of-hour to represent, from 0 to 59. The second-of-minute, from 0 to 59. The milli-of-second, from 0 to 999. |
public function getWeekday(time:Time time) returns (string)
Returns the weekday representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to get the weekday representation from |
Return Type | Description | ||
---|---|---|---|
string | The weekday representation from SUNDAY to SATURDAY |
public function getYear(time:Time time) returns (int)
Returns the year representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to retrieve the year representation from |
Return Type | Description | ||
---|---|---|---|
int | The year representation |
public function nanoTime() returns (int)
Returns the current system time in nano seconds.
Return Type | Description | ||
---|---|---|---|
int | Int value of the current system time in nano seconds |
public function parse(string data, string|RFC_1123 timeFormat) returns (Time|error<>)
Returns the time for the given string representation based on the given format string.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
data | string | The time text to parse |
|
timeFormat | string|RFC_1123 | The format which is used to parse the given text |
Return Type | Description | ||
---|---|---|---|
Time|error<> | Time object containing time and zone information or an |
public function subtractDuration(time:Time time, int years, int months, int days, int hours, int minutes, int seconds, int milliSeconds) returns (Time)
Subtract specified durations from the given time value.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to subtract the duration from |
|
years | int | The year representation |
|
months | int | The month-of-year to represent, from 1 (January) to 12 (December) |
|
days | int | The day-of-month to represent, from 1 to 31 |
|
hours | int | The hour-of-day to represent, from 0 to 23 |
|
minutes | int | The minute-of-hour to represent, from 0 to 59 |
|
seconds | int | The second-of-minute to represent, from 0 to 59 |
|
milliSeconds | int | The milli-of-second to represent, from 0 to 999 |
Return Type | Description | ||
---|---|---|---|
Time | Time object containing time and zone information after the subtraction |
public function toString(time:Time time) returns (string)
Returns ISO 8601 string representation of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record to be converted to string |
Return Type | Description | ||
---|---|---|---|
string | The ISO 8601 formatted string of the given time |
public function toTimeZone(time:Time time, string zoneId) returns (Time|error<>)
Change the time-zone of the given time.
Parameter Name | Data Type | Default Value | Description |
---|---|---|---|
time | time:Time | The Time record of which the time-zone to be changed |
|
zoneId | string | The new time-zone id |
Return Type | Description | ||
---|---|---|---|
Time|error<> | Time object containing time and zone information after the conversion
or an |