Date and Time Handling Built-ins

Date and Time Handling Built-ins execute operations involving time. The format patterns are represented as a ZonedDateTime object.

Create Date Format

Constructs a SimpleDateFormat using the given pattern and the default date format symbols.

Syntax

<result DateFormat> := createDateFormat(<pattern String>)

Returns

The result of the created DateTime format.

Parameter

• pattern - The pattern describing the DateTime format

Example

stepdef "create times"
    dateFormat := createDateFormat("yyyy.MM.dd G 'at' HH:mm:ss z")
    println("created date format is " + dateFormat)
end

Date Parser

Parses any English textual DateTime description into a Unix timestamp. It accepts various expressions of time and instantiates a Date object.

Syntax

<result Date> := date(<time String>)

Returns

The result of the created DateTime format.

Parameter

• time - A Date string
  • Valid formats are listed in the StringToTime documentation

Example

stepdef "parse dates"
    now           := date("now")
    lastMonday    := date("last Monday")
    println("it is "  + now)
    println("it was " + lastMonday)
end

Now - Query the Time Based on a Given Timezone

Syntax

<result ZonedDateTime> := now(<zonedId String>)

Returns

The current time of the specified timezone as a ZonedDateTime object.

Parameter

• zoneId - The given timezone

Example

stepdef "compare times"
    localtime := now("Canada/Central")
    nonlocaltime := now("GMT")
    println(""+ nonlocaltime)
end

Note: Instances returned by the now() function cannot be called by the createDateFormat() function. However, they can be called by the formatDateTime() function .

Now With Positive Offset

Adds a specified number of time units to the time instance.

Syntax

<nowResult ZonedDateTime> := <timeInstance Object><plusTimeUnit>(<number Number>)

Returns

The new time instance.

Parameters

• timeInstance - The time instance to add to

• plusTimeUnit - The type of unit that must be added

  • May be one of: Years, Months, Weeks, Days, Hours, Minutes, Seconds or Nanos

• number - the quantity of time units defined for the plusTimeUnit.

Example

stepdef "what time is it now"
    time  := now("UTC")
    time1 := time.plusMinutes(30)
    println("it is now " + time1)

Now With Negative Offset

Subtracts a specified number of time units to the time instance.

Syntax

<nowResult ZonedDateTime> := <minusInstance Object><minusTimeUnit>(<number Number>)

Returns

The new time instance.

Parameters

• timeInstance - The time instance to subtract from

• plusTimeUnit - The type of unit that must be subtracted

  • May be one of: Years, Months, Weeks, Days, Hours, Minutes, Seconds or Nanos

• number - The quantity of time units defined for the minusTimeUnit

Example

stepdef "what time is it now"
    time  := now("UTC")
    time1 := time.minusSeconds(30)
    println("it is now " + time1)

Time Comparison

These steps are used for comparing one time before or after a specified time.

Is Before

Compares two times with each other and checks if the first occurs before the second.

Syntax

<isBefore Boolean> := <time1 ZonedDateTime>.isBefore(<time2 ZonedDateTime>)

Returns Returns true if time1 is earlier than time2, false otherwise.

Parameters

• time1 - The reference time

• time2 - The time to compare to

Example

stepdef "check times"
    time1 := now("UTC")
    time2 := time1.plusSeconds(1)
    time1.isBefore(time2)
    println("time1 is " + time1)
end

Is After

Compares two times with each other and checks if the first occurs after the second.

Syntax

<isAfter Boolean> := <time1 ZonedDateTime>.isAfter(<time2 ZonedDateTime>)

Returns

true if time1 is later than time2, false otherwise.

Parameters

• time1 - The reference time

• time2 - The time to compare to

Example

stepdef "check times"
    time1 := now("UTC")
    time2 := time1.minusHours(5)
    time2.isAfter(time1)
    println("time2 is " + time2)
end

Format Date Time

This method takes a time and a format pattern as parameters and returns the string representation of the time in that format.

Syntax

<result String> := formatDateTime(<time ZonedDateTime>, <format String>)

Returns

The string representation of the time in the specified format.

Parameters

• time - A specific date-time written as a ZonedDateTime object

  • Instances returned by the now() function can be used here

• format - Defines the format that the time will be expressed in

Example

stepdef "format the time"
    time := now("UTC")
    timeStr := formatDateTime(time, "yyyy-MM-dd HH:mm:ss")
    println("old format was " + time)
    println("new format looks like " + timeStr)
end

Parse Date Time

This method gets a ZonedDateTime that can be used for Date/Time calculations.

Syntax

<result ZonedDateTime>
    := parseDateTime(<dateTime String>, <format String>,<timeZoneId String>)

Returns

The ZonedDateTime object with the specified date and time.

Parameters

• format - The specified output format of the DateTime being used

  • For example, "yyyy-MM-dd HH:mm:ss" or "YYMMDD HH:MM"

• timeZoneID - The given timezone

Example

stepdef "parsedate"
    parsed := parseDateTime("2015-02-03 11:49:00", "yyyy-MM-dd HH:mm:ss", "Europe/Vienna")
    println("parsed date is " + parsed)
end

Note: If the parsedDateTime() uses a different time format than the given dateTime parameter, intaQt Studio will create an error message.