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;

Module Detail

Records

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

Function Description
addDuration

Add specified durations to the given time value.

createTime

Returns the Time object correspoding to the given time components and time-zone.

currentTime

Returns the current time value with the system default time-zone.

format

Returns formatted string representation of the given time.

getDate

Returns the date representation of the given time.

getDay

Returns the date representation of the given time.

getHour

Returns the hour representation of the given time.

getMilliSecond

Returns the millisecond representation of the given time.

getMinute

Returns the minute representation of the given time.

getMonth

Returns the month representation of the given time.

getSecond

Returns the second representation of the given time.

getTime

Returns the time representation of the given time.

getWeekday

Returns the weekday representation of the given time.

getYear

Returns the year representation of the given time.

nanoTime

Returns the current system time in nano seconds.

parse

Returns the time for the given string representation based on the given format string.

subtractDuration

Subtract specified durations from the given time value.

toString

Returns ISO 8601 string representation of the given time.

toTimeZone

Change the time-zone of the given time.

Type Definitions

Type Values Description
TimeFormat RFC_1123

The time format defined by the RFC-1123.

public type Time

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

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 error if failed to create the time

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 error if failed to format the 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|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 error if failed to parse the given string

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 error if failed to format the time