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:

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 number of seconds to the specified time.

The following example adds 120 seconds to the specified time "2024-06-22T12:00:00Z" in the Pact REPL:

In most cases, you use the add-time function in combination with other functions such hours or minutes as follows:

Use days to specify a number of days. You can use this function in conjunctions with the add-time function to add days to a specified time.

To specify a number of days, use the following syntax:

Use the following argument to specify the n number of days 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 how to use the days function to return the number of seconds in one day as a decimal value:

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

In this example, (days 1) adds one day to the specified time "2024-07-22T12:00:00Z" using the add-time function, enabling straightforward manipulation of time-based information in smart contracts.

Use diff-time to compute the difference between time1 and time2 in seconds.

To compute the difference between two tinme1 and time2 in seconds, use the following syntax:

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 how to use the diff-time function to compute the difference between the times "16:00:00" and "09:30:00" in seconds:

In this example, 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. The format-time function is useful for converting time values to human-readable formats in Pact contracts.

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

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 percentage sign "%".

%z - RFC 822/ISO 8601:1988 style numeric time zone, for example, "-0600" or "+0100".

%N - ISO 8601 style numeric time zone, for example, "-06:00" or "+01:00".

%Z - Timezone name.

%c - The preferred calendar time representation for the current locale. As 'dateTimeFmt' in locale, for example, %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' in locale, for example, %H:%M:%S.

%r - The complete calendar time using the AM/PM format of the current locale. As 'time12Fmt' in locale, for example, %I:%M:%S %p.

%P - Day-half of day from 'amPm' in locale, converted to lowercase, for example, "am", "pm".

%p - Day-half of day from 'amPm' in locale, for example, "AM", "PM".

%H - Hour of day in 24-hour format, 0-padded to two characters, "00"–"23".

%k - Hour of day in 24-hour format, space-padded to two characters, " 0"–"23".

%I - Hour of day-half in 12-hour format, 0-padded to two characters, "01"–"12".

%l - Hour of day-half in 12-hour format, space-padded to two characters, " 1"–"12".

%M - Minute of the hour, 0-padded to two characterss, "00"–"59".

%S - Second of minute without decimal part, 0-padded to two characters, "00"–"60".

%v - Microsecond of second, 0-padded to six characters, "000000"–"999999".

%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.

%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 formats, 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' in locale, for example, %m\/%d\/%y.

%Y - Year, no padding.

%y - Year of century, 0-padded to two characters, "00"–"99".

%C - Century, no padding.

%B - Month name, long form 'fst' from 'months' in locale, "January"–"December".

%b, %h - Month name, short form 'snd' from 'months' in locale, "Jan"–"Dec".

%m - Month of year, 0-padded to two characters, "01"–"12".

%d - Day of month, 0-padded to two characters, "01"–"31".

%e - Day of month, space-padded to two characters, " 1"–"31".

%j - Day of year, 0-padded to three characters, "001"–"366".

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

%g - Year of century for Week Date format, 0-padded to two characters, "00"–"99".

%f - Century for Week Date format, no padding.

%V - Week of year for Week Date format, 0-padded to two characters, "01"–"53".

%u - Day of week for Week Date format, "1"–"7".

%a - Day of week, short form 'snd' from 'wDays' in locale, "Sun"–"Sat".

%A - Day of week, long form 'fst' from 'wDays' in locale, "Sunday"–"Saturday".

%U - Week of year where weeks start on Sunday (as 'sundayStartWeek'), 0-padded to two characters, "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 characters, "00"–"53".

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

The default format is a UTC ISO 8601 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 how to use the format-time function to format the time value (time "2016-07-22T12:00:00Z") using the specified format:

In this example, "%F" is the format string specifying the format of the output. The result of this operation is a formatted string representing the date in the format YYYY-MM-DD.

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.