Functions - 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 default system time-zone.
format
Returns the 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 the ISO 8601 string representation of the given time.
toTimeZone
Change the time-zone of the given time.

addDuration

(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.
  string timeText = "2020-06-26T09:46:22.444-0500";
  string timeFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSZ";
  time:Time|error originalTime = time:parse(timeText, timeFormat);
  if (originalTime is time:Time) {
      time:Time newTime = time:addDuration(originalTime, 1, 1, 1, 1, 1, 1, 1);
  }

Parameters

  • time Time
  • The Time record to add the duration

  • 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

    (Time)
  • Time object containing time and zone information after the addition

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.
  time:Time|error dateTime = time:createTime(2020, 3, 28, 23, 42, 45, 554, "America/Panama");

Parameters

  • 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

    (Time | Error)
  • Time object containing time and zone information or an time:Error if failed to create the time

currentTime

()

returns Time
Returns the current time value with the default system time-zone.
  time:Time now = time:currentTime();
  • Return Type

    (Time)
  • Time object containing the time and the zone information

format

(Time time, string timeFormat)

returns string | Error
Returns the formatted string representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  string|error timeString = time:format(time, time:TIME_FORMAT_RFC_1123);

Parameters

  • time Time
  • The Time record to be formatted

  • timeFormat string
  • The format, which is used to format the time represented by this object

  • Return Type

    (string | Error)
  • The formatted string of the given time or else a time:Error if failed to format the time

getDate

(Time time)

returns [int, int, int]
Returns the date representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  [int, int, int] date = time:getDate(time);

Parameters

  • time Time
  • The Time record to get the date representation

  • Return Type

    ([int, int, int])
  • The year representation with the month-of-year from 1 (January) to 12 (December) and the day-of-month from 1 to 31

getDay

(Time time)

returns int
Returns the date representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  int day = time:getDay(time);

Parameters

  • time Time
  • The Time record to get the date representation

  • Return Type

    (int)
  • The day-of-month from 1 to 31

getHour

(Time time)

returns int
Returns the hour representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  int hour = time:getHour(time);

Parameters

  • time Time
  • The Time record to get the hour representation

  • Return Type

    (int)
  • The hour-of-day from 0 to 23

getMilliSecond

(Time time)

returns int
Returns the millisecond representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  int milliSecond = time:getMilliSecond(time);

Parameters

  • time Time
  • The Time record to get the millisecond representation

  • Return Type

    (int)
  • The milli-of-second from 0 to 999

getMinute

(Time time)

returns int
Returns the minute representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  int minute = time:getMinute(time);

Parameters

  • time Time
  • The Time record to get the minute representation

  • Return Type

    (int)
  • The minute-of-hour to represent from 0 to 59

getMonth

(Time time)

returns int
Returns the month representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  int month = time:getMonth(time);

Parameters

  • time Time
  • The Time record to get the month representation from

  • Return Type

    (int)
  • The month-of-year from 1 (January) to 12 (December)

getSecond

(Time time)

returns int
Returns the second representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  int second = time:getSecond(time);

Parameters

  • time Time
  • The Time record to get the second representation

  • Return Type

    (int)
  • The second-of-minute from 0 to 59

getTime

(Time time)

returns [int, int, int, int]
Returns the time representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  [int, int, int, int] timeGenerated = time:getTime(time);

Parameters

  • time Time
  • The Time record

  • Return Type

    ([int, int, int, int])
  • The hour-of-day to represent from 0 to 23, the minute-of-hour to represent from 0 to 59, the second-of-minute from 0 to 59, and the milli-of-second from 0 to 999

getWeekday

(Time time)

returns string
Returns the weekday representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  string weekDay = time:getWeekday(time);

Parameters

  • time Time
  • The Time record to get the weekday representation

  • Return Type

    (string)
  • The weekday representation from SUNDAY to SATURDAY

getYear

(Time time)

returns int
Returns the year representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  int year = time:getYear(time);

Parameters

  • time Time
  • The Time record to retrieve the year representation

  • Return Type

    (int)
  • The year representation

nanoTime

()

returns int
Returns the current system time in nano seconds.
  int now = time:nanoTime();
  • Return Type

    (int)
  • Integer value of the current system time in nano seconds

parse

(string data, string timeFormat)

returns Time | Error
Returns the time for the given string representation based on the given format string.
  string timeFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSZ";
  time:Time|error time = time:parse("2020-06-26T09:46:22.444-0500", timeFormat);

Parameters

  • data string
  • The time text to parse

  • timeFormat string
  • The format, which is used to parse the given text

  • Return Type

    (Time | Error)
  • Time object containing the time and zone information or else a time:Error if failed to parse the given string

subtractDuration

(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.
  string timeText = "2020-06-26T09:46:22.444-0500";
  string timeFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSZ";
  time:Time|error originalTime = time:parse(timeText, timeFormat);
  if (originalTime is time:Time) {
      time:Time newTime = time:subtractDuration(originalTime, 1, 1, 1, 1, 1, 1, 1);
  }

Parameters

  • 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

    (Time)
  • Time object containing time and zone information after the subtraction

toString

(Time time)

returns string
Returns the ISO 8601 string representation of the given time.
  time:TimeZone zoneValue = {id: "America/Panama"};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  string timeString = time:toString(time);

Parameters

  • time Time
  • The Time record to be converted to string

  • Return Type

    (string)
  • The ISO 8601-formatted string of the given time

toTimeZone

(Time time, string zoneId)

returns Time | Error
Change the time-zone of the given time.
  string zoneId = "America/Panama";
  time:TimeZone zoneValue = {id: zoneId};
  time:Time time = {time: 1578488382444, zone: zoneValue};
  time:Time|time:Error newTime = time:toTimeZone(time, zoneId);

Parameters

  • time Time
  • The Time record of which the time-zone is to be changed

  • zoneId string
  • The new time-zone ID

  • Return Type

    (Time | Error)
  • Time object containing the time and zone information after the conversion or else a time:Error if failed to format the time