ballerina/time package
Package overview
The ballerina/time
package provides implementations related to time, date, time zones, and durations.
The package 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 zoneId
and zoneOffset
as attributes.
Samples
Getting the current time/date
time:Time time = time:currentTime(); // Create an object 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.zoneId; // Time zone as an identifier. E.g., “America/Panama”.
int zoneoffset = time.zone.zoneOffset; // Time zone as an offset. E.g., -05:00.
// Get the current date and time upto milliseconds.
int year = time.year(); // E.g., 2018
int month = time.month(); // E.g., 3
int day = time.day(); // E.g., 1
int hour = time.hour(); // E.g., 18
int minute = time.minute(); // E.g., 56
int second = time.second(); // E.g., 23
int milliSecond = time.milliSecond(); // E.g., 555
string weekday = time.weekday(); // Day of the week. E.g., “TUESDAY”.
Creating a time/date object
// Create an object of type ‘Time’ with time zone.
time:Timezone zoneIdValue = {zoneId:"America/Panama"};
time:Time time1 = new (1498488382000, zoneIdValue);
// Create an object of type ‘Time’ with the time zone offset.
time:Timezone zoneOffsetValue = {zoneId:"-05:00"};
time:Time time2 =new (1498488382000, zoneOffsetValue);
// Create an object of type ‘Time’ without the time zone.
time:Timezone noZoneValue = {zoneId:""};
time:Time time3 = new (1498488382000, noZoneValue);
// Create an object 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 = {zoneId:"America/Panama"};
time:Time time = new (1498488382444, zoneValue);
//Format a time to a string of a given pattern.
string time1 = time.format("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_FORMAT_RFC_1123); // E.g., "Mon, 26 Jun 2017 09:46:22 -0500”
// Convert a time object to a string value.
string time3 = time.toString(); //”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(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(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 | ||
---|---|---|---|
Timezone | Ballerina Timezone represents the timezone information associated with a particular time. |
Objects Summary
Object | Description | ||
---|---|---|---|
Time | Ballerina Time represents a particular time with its associated timezone. |
Functions Summary
Return Type | Function and Description | ||
---|---|---|---|
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 timezone. |
||
Time | currentTime() Returns the current time value with the system default timezone. |
||
int | nanoTime() Returns the current system time in nano seconds. |
||
Time | parse(string data, string|RFC_1123 format) Returns the time for the given string representation based on the given format string. |
Global Variables
Name | Data Type | Description | |
---|---|---|---|
TIME_FORMAT_RFC_1123 | TimeFormat |
public type Timezone record
Ballerina Timezone represents the timezone information associated with a particular time.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
zoneId | string | Zone short ID or offset string |
|
zoneOffset | int | The offset in seconds |
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 timezone.
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 timezone.If empty the system local timezone 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 timezone.
Return Type | Description | ||
---|---|---|---|
Time | Time object containing the time and zone information |
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 format) 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 |
|
format | 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 type Time object
Ballerina Time represents a particular time with its associated timezone.
Field Name | Data Type | Default Value | Description |
---|---|---|---|
time | int | Time value as milliseconds since epoch |
|
zone | time:0.0.0:Timezone | The time zone of the time |
-
<Time> new(int time, time:0.0.0:Timezone zone)
Parameter Name Data Type Default Value Description time int zone time:0.0.0:Timezone -
<Time> toString() returns (string)
Returns ISO 8601 string representation of the given time.
Return Type Description string The ISO 8601 formatted string of the given time
-
<Time> format(string|RFC_1123 format) returns (string)
Returns formatted string representation of the given time.
Parameter Name Data Type Default Value Description format 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
-
<Time> year() returns (int)
Returns the year representation of the given time.
Return Type Description int The year representation
-
<Time> month() returns (int)
Returns the month representation of the given time.
Return Type Description int The month-of-year, from 1 (January) to 12 (December)
-
<Time> day() returns (int)
Returns the date representation of the given time.
Return Type Description int The day-of-month, from 1 to 31
-
<Time> weekday() returns (string)
Returns the weekday representation of the given time.
Return Type Description string The weekday representation from SUNDAY to SATURDAY
-
<Time> hour() returns (int)
Returns the hour representation of the given time.
Return Type Description int The hour-of-day, from 0 to 23
-
<Time> minute() returns (int)
Returns the minute representation of the given time.
Return Type Description int The minute-of-hour to represent, from 0 to 59
-
<Time> second() returns (int)
Returns the second representation of the given time.
Return Type Description int The second-of-minute, from 0 to 59
-
<Time> milliSecond() returns (int)
Returns the millisecond representation of the given time.
Return Type Description int The milli-of-second, from 0 to 999
-
<Time> getDate() returns ((int,int,int))
Returns the date representation of the given time.
Return Type Description (int,int,int) The year representation
-
<Time> getTime() returns ((int,int,int,int))
Returns the time representation of the given time.
Return Type Description (int,int,int,int) The hour-of-day, from 0 to 23
-
<Time> addDuration(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 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
-
<Time> subtractDuration(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 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
-
<Time> toTimezone(string zoneId) returns (Time)
Change the timezone of the given time.
Parameter Name Data Type Default Value Description zoneId string The new timezone id
Return Type Description Time Time object containing time and zone information after the conversion