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 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 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 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 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 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 time1 = time:parse("2017-06-26T09:46:22.444-0500", "yyyy-MM-dd'T'HH:mm:ss.SSSZ");
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 time2 = time:parse("2016-03-01T09:46:22.444-0500", "yyyy-MM-dd'T'HH:mm:ss.SSSZ");
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.
int diffInMillis = time1.time - time2.time;
Type Definitions
Type | Values | Description | |
---|---|---|---|
TimeFormat | 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 | 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 | 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 | 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 | 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 | ||
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)
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 | Time object containing time and zone information |
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)
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 | The formatted string of the given time |
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)
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 | Time object containing time and zone information |
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)
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 | Time object containing time and zone information after the conversion |