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

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