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.
Argument | Type | Description |
---|---|---|
time | time | Specifies the time to which you want to add seconds . |
seconds | decimal or integer | Specifies 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>(add-time (time "2016-07-22T12:00:00Z") 15)"2016-07-22T12:00:15Z"
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>(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>(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.
Argument | Type | Description |
---|---|---|
n | decimal or integer | Specifies 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
:
(add-time (time "2016-07-22T12:00:00Z") (days 1))"2016-07-23T12:00:00Z"
(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:
Argument | Type | Description |
---|---|---|
time1 | time | Specifies the first time for the calculation. |
time2 | time | Specifies 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>(diff-time (parse-time "%T" "16:00:00") (parse-time "%T" "09:30:00"))23400.0
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:
Argument | Type | Description |
---|---|---|
format | string | Specifies the format string for the time. |
time | time | Specifies 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>(format-time "%F" (time "2016-07-22T12:00:00Z"))"2016-07-22"
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
Argument | Type | Description |
---|---|---|
n | integer or decimal | Specifies 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:
(add-time (time "2016-07-22T12:00:00Z") (hours 1))
(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>(hours 3)10800.0
pact>(hours 3)10800.0
In this example, the hours
function specifies 3 hours as an integer value.
Specifying hours as a decimal:
pact>(hours 2.5)9000.0
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.
Argument | Type | Description |
---|---|---|
n | decimal or integer | Specifies 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>(add-time (time "2016-07-22T12:00:00Z") (minutes 1))2016-07-22 12:01:00 UTC
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.
Argument | Type | Description |
---|---|---|
format | string | Specifies the format for parsing the UTC value. |
utcval | string | Specifies 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>(parse-time "%F" "2016-09-12")2016-09-12 00:00:00 UTC
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.
Argument | Type | Description |
---|---|---|
UTC | string | Specifies 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>(time "2016-07-22T11:26:35Z")2016-07-22 11:26:35 UTC
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.