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 conjunction with the add-time function to add a specified number of 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 time1 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.

The parse-time and format-time functions accept format codes that are derived from the formatting time strftime function time templates with some extensions. You can use the following template specifiers that are introduced by using a single percentage (%) character to format time strings:

Note that two percentage characters (%%) are interpretted as a literal percentage sign (%), not a time formatting template. In addition, the template for picoseconds with zero padding (%q) doesn't work properly, so it's not included as a supported template for formatting time strings.

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 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 following example demonstrates how to replace the numeric representing the month of the year with the short name for the month:

Use the hours function to calculate a time duration in hours. You can use this function in combination 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 a specified number of minutes. You can use this function in combination with the add-time function to add a specific number of minutes to a given time.

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 a UTC formatted time string from an input time that uses the specified format.

The parse-time and format-time functions accept format codes that are derived from the formatting time strftime function time templates with some extensions. You can use the following template specifiers that are introduced by using a single percentage (%) character to format time strings:

Note that two percentage characters (%%) are interpreted as a literal percentage sign (%), not a time formatting template. In addition, the template for picoseconds with zero padding (%q) doesn't work properly, so it's not included as a supported template for formatting time strings.

To construct a UTC time string from a input time that uses a specified format, use the following syntax:

(parse-time format input)

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

The parse-time function returns a UTC formatted time constructed from the provided input value that uses the specified format.

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

In this example, the parse-time function constructs a UTC-formatted time value from the input value "2024-11-06". The input string uses the %Y-%m-%d format specified in the ISO 8601 standard and identified with the "%F" format argument.

In the following example, the input string uses the %D and %T format specifiers for date and time:

The following example parses an input string that uses the abbreviated month name (%b), the day of the month as a zero-padded string (%d), and the full year (%Y) to a UTC time:

Use the time function to construct a time object from a UTC value using the ISO 8601 standard Universal Time Coordinated (UTC) date time format:

This format is the default time format in Pact for all time-related functions. Internally, the time object supports up to microsecond resolution. However, the values returned from the Pact interpreter as JSON are be serialized using the default format. If you need higher resolution, you can explicitly format times with the %v template and related codes.

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.