Module : time

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:

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;

Records

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

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.

Constants

TIME_FORMAT_RFC_1123