Module : time

Module overview

This 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

import ballerina/io;
import ballerina/time;

public function main() {
    time:Time time = time:currentTime();    // Create a record of type ‘Time’.
    io:println(time);

    int timeValue = time.time;    // Time in milliseconds since January 1, 1970, 00:00:00 GMT. E.g., 1523513039.
    io:println(timeValue);
    int nanoTime = time:nanoTime();    // Time in nanoseconds since an arbitrary origin. Therefore, it should be used only to calculate durations. E.g., 2426115697486340.
    io:println(nanoTime);
    string zoneId = time.zone.id;    // Time zone as an identifier. E.g., “America/Panama”.
    io:println(zoneId);
    int zoneoffset = time.zone.offset;    // Time zone as an offset. E.g., -05:00.
    io:println(zoneoffset);

    // Get the current date and time upto milliseconds.
    int year = time:getYear(time);    // E.g., 2018
    io:println(year);
    int month = time:getMonth(time);    // E.g., 3
    io:println(month);
    int day = time:getDay(time);    // E.g., 1
    io:println(day);
    int hour = time:getHour(time);    // E.g., 18
    io:println(hour);
    int minute = time:getMinute(time);    // E.g., 56
    io:println(minute);
    int second = time:getSecond(time);    // E.g., 23
    io:println(second);
    int milliSecond = time:getMilliSecond(time);    // E.g., 555
    io:println(milliSecond);
    string weekday = time:getWeekday(time);// Day of the week. E.g., “TUESDAY”.
    io:println(weekday);
}

Creating a time/date record

import ballerina/io;
import ballerina/time;

public function main() {
    // Create a record of type ‘Time’ with time zone.
    time:TimeZone zoneIdValue = {id: "America/Panama"};
    time:Time time1 = {time: 1498488382000, zone: zoneIdValue};
    io:println(time1);

    // Create a record of type ‘Time’ with the time zone offset.
    time:TimeZone zoneOffsetValue = {id: "-05:00"};
    time:Time time2 = {time: 1498488382000, zone: zoneOffsetValue};
    io:println(time2);

    // Create a record of type ‘Time’ without the time zone.
    time:TimeZone noZoneValue = {id: ""};
    time:Time time3 = {time: 1498488382000, zone: noZoneValue};
    io:println(time3);

    // 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");
    if (dateTime is time:Time) {
        io:println(dateTime);
    } else {
        io:println("An error occurred: ", dateTime);
    }
}

Formatting a time/date to a string

import ballerina/io;
import ballerina/time;

public function main() returns error? {
    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 = check time:format(time, "yyyy-MM-dd'T'HH:mm:ss.SSSZ");    //E.g., “2017-06-26T09:46:22.444-0500”.
    io:println(time1);

    //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”
    io:println(time2);

    // Convert a time record to a string value.
    string time3 = time:toString(time);//”2017-06-26T09:46:22.444-05:00”
    io:println(time3);
}

Parsing a string to time/date

import ballerina/io;
import ballerina/time;

public function main() returns error? {
    // 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.
    io:println(time1);

    // 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);
    io:println(time2);
}

Setting time durations

import ballerina/time;

public function main() {
    // 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;
}

Patterns for formatting and parsing

The below patterns can be used to generate the formatter string when using the format() and parse() functions.

SymbolMeaningPresentationExamples
GeratextAD; Anno Domini; A
uyearyear2004; 04
yyear-of-erayear2004; 04
Dday-of-yearnumber189
M/Lmonth-of-yearnumber/text7; 07; Jul; July; J
dday-of-monthnumber10
Q/qquarter-of-yearnumber/text3; 03; Q3; 3rd quarter
Yweek-based-yearyear1996; 96
wweek-of-week-based-yearnumber27
Wweek-of-monthnumber4
Eday-of-weektextTue; Tuesday; T
e/clocalized day-of-weeknumber/text2; 02; Tue; Tuesday; T
Fweek-of-monthnumber3
acam-pm-of-daytextPM
hclock-hour-of-am-pm (1-12)number12
Khour-of-am-pm (0-11)number0
kclock-hour-of-am-pm (1-24)number0
Hhour-of-day (0-23)number0
mminute-of-hournumber30
ssecond-of-minutenumber55
Sfraction-of-secondfraction978
Amilli-of-daynumber1234
nnano-of-secondnumber987654321
Nnano-of-daynumber1234000000
Vime-zone IDzone-idAmerica/Los_Angeles; Z; -08:30
ztime-zone namezone-namePacific Standard Time; PST
Olocalized zone-offsetoffset-OGMT+8; GMT+08:00; UTC-08:00
Xzone-offset 'Z' for zerooffset-XZ; -08; -0830; -08:30; -083015; -08:30:15
xzone-offsetoffset-x+0000; -08; -0830; -08:30; -083015; -08:30:15
Zzone-offsetoffset-Z+0000; -0800; -08:00
ppad nextpad modifier1
'escape for textdelimiter
''single quoteliteral'
[optional section start
]optional section end

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_ERROR_REASON

Error reason to specify the time error that occurs in the module

TIME_FORMAT_RFC_1123

Specifies the time format defined by the RFC-1123

Errors

Error

Represents Time module related error