Time

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

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

(add-time time seconds)

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

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

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

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:

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

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

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

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.

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

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

(diff-time TIME1 TIME2)

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

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

The following example demonstrates the diff-time function:

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.

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

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

format-time format time

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

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.

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.

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

The following example demonstrates the format-time function:

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.

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.

The syntax for the hours function is as follows:

(hours n)

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

Adding hours to a time:

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:

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

Specifying hours as a decimal:

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.

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

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

(minutes n)

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

The minutes function returns the duration in decimal format.

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

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

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

(parse-time format utcval)

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

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

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

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

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

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

(time UTC)

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

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

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":

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