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:
- 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;
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. |
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. |
TIME_FORMAT_RFC_1123 |