Skip to main content
Last updated

Time

add-time

Use add-time to add a specified number of seconds to a given time.

Basic syntax

To add seconds to a time, use the following syntax:

(add-time time seconds)

Arguments

Use the following arguments to specify the time to which you want to add seconds using the add-time Pact function.

ArgumentTypeDescription
timetimeSpecifies the time to which you want to add seconds.
secondsdecimal or integerSpecifies the number of seconds to add to the time.

Return values

The add-time function returns the resulting time after adding the specified seconds as a time.

Examples

The following example adds 15 seconds to a specific time in the Pact REPL:

pact
pact>(add-time (time "2016-07-22T12:00:00Z") 15)"2016-07-22T12:00:15Z"
pact
pact>(add-time (time "2016-07-22T12:00:00Z") 15)"2016-07-22T12:00:15Z"

In this example, add-time returns the time "2016-07-22T12:00:15Z" after adding 15 seconds to the specified time "2016-07-22T12:00:00Z".

Usually, add-time is being used with hours and minutes as follows:

pact
pact>(add-time (time "2016-07-22T12:00:00Z") (+ (hours 1) (+ (minutes 17) 5)))2016-07-22 13:17:05 UTC```pact  ## daysUse `days` to specify a number of days `N`, which can be used with 'add-time' to add days from a given time. ### Basic syntax To specify a number of days `N`, use the following syntax: ```pact(days N)
pact
pact>(add-time (time "2016-07-22T12:00:00Z") (+ (hours 1) (+ (minutes 17) 5)))2016-07-22 13:17:05 UTC```pact  ## daysUse `days` to specify a number of days `N`, which can be used with 'add-time' to add days from a given time. ### Basic syntax To specify a number of days `N`, use the following syntax: ```pact(days N)

Arguments

Use the following argument to specify the number of days N for the days Pact function.

ArgumentTypeDescription
ndecimal or integerSpecifies the number of days to add.

Return values

The days function returns the number of seconds in the given number of days, as a decimal value.

Example

The following example demonstrates the days function in combination with add-time:

pact
(add-time (time "2016-07-22T12:00:00Z") (days 1))"2016-07-23T12:00:00Z"
pact
(add-time (time "2016-07-22T12:00:00Z") (days 1))"2016-07-23T12:00:00Z"

In this example, (days 1) is used to specify 1 day, which is then added to the time "2016-07-22T12:00:00Z" using add-time. This results in the time one day after the specified time. The days function allows for easy manipulation of time by specifying a number of days to add.

diff-time

Use diff-time to compute the difference between TIME1 and TIME2 in seconds.

Basic syntax

To compute the difference between two times TIME1 and TIME2 in seconds, use the following syntax:

(diff-time TIME1 TIME2)

Arguments

Use the following arguments to specify the times for the diff-time Pact function:

ArgumentTypeDescription
time1timeSpecifies the first time for the calculation.
time2timeSpecifies the second time for the calculation.

Return values

The diff-time function returns the difference between TIME1 and TIME2 in seconds as a decimal.

Examples

The following example demonstrates the diff-time function:

pact
pact>(diff-time (parse-time "%T" "16:00:00") (parse-time "%T" "09:30:00"))23400.0
pact
pact>(diff-time (parse-time "%T" "16:00:00") (parse-time "%T" "09:30:00"))23400.0

In this example, (diff-time (parse-time "%T" "16:00:00") (parse-time "%T" "09:30:00")) is used to compute the difference between the times "16:00:00" and "09:30:00" in seconds. The function returns the result of this computation as a decimal, representing the time difference between the two specified times.

format-time

Use format-time to format a time value using a specified format.

Basic syntax

To format a time value using a specified format, use the following syntax:

format-time format time

Arguments

Use the following arguments to specify the format and time for the format-time Pact function:

ArgumentTypeDescription
formatstringSpecifies the format string for the time.
timetimeSpecifies the time value to format.

Time formats

The parse-time and format-time functions accept format codes that derive from GNU strftime with some extensions, as follows:

%% - literal "%"

%z - RFC 822/ISO 8601:1988 style numeric time zone (e.g., "-0600" or "+0100")

%N - ISO 8601 style numeric time zone (e.g., "-06:00" or "+01:00") /EXTENSION/

%Z - timezone name

%c - The preferred calendar time representation for the current locale. As 'dateTimeFmt' locale (e.g. %a %b %e %H:%M:%S %Z %Y)

%R - same as %H:%M

%T - same as %H:%M:%S

%X - The preferred time of day representation for the current locale. As 'timeFmt' locale (e.g. %H:%M:%S)

%r - The complete calendar time using the AM/PM format of the current locale. As 'time12Fmt' locale (e.g. %I:%M:%S %p)

%P - day-half of day from ('amPm' locale), converted to lowercase, "am", "pm"

%p - day-half of day from ('amPm' locale), "AM", "PM"

%H - hour of day (24-hour), 0-padded to two chars, "00""23"

%k - hour of day (24-hour), space-padded to two chars, " 0""23"

%I - hour of day-half (12-hour), 0-padded to two chars, "01""12"

%l - hour of day-half (12-hour), space-padded to two chars, " 1""12"

%M - minute of hour, 0-padded to two chars, "00""59"

%S - second of minute (without decimal part), 0-padded to two chars, "00""60"

%v - microsecond of second, 0-padded to six chars, "000000""999999". /EXTENSION/

%Q - decimal point and fraction of second, up to 6 second decimals, without trailing zeros. For a whole number of seconds, %Q produces the empty string. /EXTENSION/

%s - number of whole seconds since the Unix epoch. For times before the Unix epoch, this is a negative number. Note that in %s.%q and %s%Q the decimals are positive, not negative. For example, 0.9 seconds before the Unix epoch is formatted as "-1.1" with %s%Q.

%D - same as %m\/%d\/%y

%F - same as %Y-%m-%d

%x - as 'dateFmt' locale (e.g. %m\/%d\/%y)

%Y - year, no padding.

%y - year of century, 0-padded to two chars, "00""99"

%C - century, no padding.

%B - month name, long form ('fst' from 'months' locale), "January""December"

%b, %h - month name, short form ('snd' from 'months' locale), "Jan""Dec"

%m - month of year, 0-padded to two chars, "01""12"

%d - day of month, 0-padded to two chars, "01""31"

%e - day of month, space-padded to two chars, " 1""31"

%j - day of year, 0-padded to three chars, "001""366"

%G - year for Week Date format, no padding.

%g - year of century for Week Date format, 0-padded to two chars, "00""99"

%f - century for Week Date format, no padding. /EXTENSION/

%V - week of year for Week Date format, 0-padded to two chars, "01""53"

%u - day of week for Week Date format, "1""7"

%a - day of week, short form ('snd' from 'wDays' locale), "Sun""Sat"

%A - day of week, long form ('fst' from 'wDays' locale), "Sunday""Saturday"

%U - week of year where weeks start on Sunday (as 'sundayStartWeek'), 0-padded to two chars, "00""53"

%w - day of week number, "0" (= Sunday) – "6" (= Saturday)

%W - week of year where weeks start on Monday (as 'Data.Thyme.Calendar.WeekdayOfMonth.mondayStartWeek'), 0-padded to two chars, "00""53"

Note: %q (picoseconds, zero-padded) does not work properly so not documented here.

Default format and JSON serialization

The default format is a UTC ISO8601 date+time format: "%Y-%m-%dT%H:%M:%SZ", as accepted by the time function. While the time object internally supports up to microsecond resolution, values returned from the Pact interpreter as JSON will be serialized with the default format. When higher resolution is desired, explicitly format times with %v and related codes.

Return values

The format-time function returns a new string with the formatted time value.

Examples

The following example demonstrates the format-time function:

pact
pact>(format-time "%F" (time "2016-07-22T12:00:00Z"))"2016-07-22"
pact
pact>(format-time "%F" (time "2016-07-22T12:00:00Z"))"2016-07-22"

In this example, "%F" is the format string specifying the format of the output. The format-time function is used to format the time value (time "2016-07-22T12:00:00Z") using the specified format. The result of this operation is a formatted string representing the date in the format YYYY-MM-DD. The format-time function is useful for converting time values to human-readable formats in Pact contracts.

hours

The hours function calculates a time duration in hours, which can be used with the add-time function to add a specific number of hours to a given time.

Syntax

The syntax for the hours function is as follows:

(hours n)

Arguments

ArgumentTypeDescription
ninteger or decimalSpecifies the number of hours as either a decimal or an integer.

Return Value

The hours function returns a decimal value representing the specified number of hours.

Examples

Adding hours to a time:

pact
(add-time (time "2016-07-22T12:00:00Z") (hours 1))
pact
(add-time (time "2016-07-22T12:00:00Z") (hours 1))

In this example, the add-time function is used to add one hour to the time represented by the string "2016-07-22T12:00:00Z".

Specifying hours as an integer:

pact
pact>(hours 3)10800.0
pact
pact>(hours 3)10800.0

In this example, the hours function specifies 3 hours as an integer value.

Specifying hours as a decimal:

pact
pact>(hours 2.5)9000.0
pact
pact>(hours 2.5)9000.0

In this example, the hours function specifies 2.5 hours as a decimal value.

The hours function is useful for performing time calculations in Pact contracts, such as adding or subtracting specific durations from timestamps.

minutes

Use minutes to represent a duration of N minutes, primarily for use with the add-time function.

Basic syntax

To represent a duration of N minutes, use the following syntax:

(minutes n)

Argument

Use the following argument to specify the number of minutes for the duration using the minutes Pact function.

ArgumentTypeDescription
ndecimal or integerSpecifies the number of minutes for the duration.

Return value

The minutes function returns the duration in decimal format.

Examples

The following example demonstrates the use of minutes in combination with add-time in the Pact REPL:

pact
pact>(add-time (time "2016-07-22T12:00:00Z") (minutes 1))2016-07-22 12:01:00 UTC
pact
pact>(add-time (time "2016-07-22T12:00:00Z") (minutes 1))2016-07-22 12:01:00 UTC

parse-time

Use parse-time to construct time from a UTC value using a specified format. See "Time Formats" docs for supported formats.

Basic syntax

To construct time from a UTC value using a specified format, use the following syntax:

(parse-time format utcval)

Arguments

Use the following arguments to specify the format and UTC value for constructing time using the parse-time Pact function.

ArgumentTypeDescription
formatstringSpecifies the format for parsing the UTC value.
utcvalstringSpecifies the UTC value to be parsed.

Return value

The parse-time function returns a time value constructed from the provided UTC value using the specified format.

Examples

The following example demonstrates the use of parse-time in the Pact REPL:

pact
pact>(parse-time "%F" "2016-09-12")2016-09-12 00:00:00 UTC
pact
pact>(parse-time "%F" "2016-09-12")2016-09-12 00:00:00 UTC

In this example, parse-time is used to construct a time value from the UTC value "2016-09-12" using the format "%F".

time

The time function constructs a time object from a UTC value using the ISO8601 format (%Y-%m-%dT%H:%M:%SZ).

Basic syntax

To construct a time object from a UTC value, use the following syntax:

(time UTC)

Arguments

Use the following argument to specify the UTC value for constructing the time object using the time Pact function.

ArgumentTypeDescription
UTCstringSpecifies the UTC value in ISO8601 format (%Y-%m-%dT%H:%M:%SZ).

Return value

The time function returns a time object constructed from the provided UTC value.

Examples

The following example demonstrates the usage of the time function within the Pact REPL. It constructs a time object from the UTC value "2016-07-22T11:26:35Z":

pact
pact>(time "2016-07-22T11:26:35Z")2016-07-22 11:26:35 UTC
pact
pact>(time "2016-07-22T11:26:35Z")2016-07-22 11:26:35 UTC

This example illustrates how to use the time function to create a time object from a UTC value using the ISO8601 format in Pact.