mirror of
https://github.com/opentffoundation/opentf.git
synced 2025-12-22 03:07:51 -05:00
a15a6c9657
Signed-off-by: Janos <86970079+janosdebugs@users.noreply.github.com> Signed-off-by: Damian Stasik <920747+damianstasik@users.noreply.github.com> Signed-off-by: Roman Grinovski <roman.grinovski@gmail.com> Co-authored-by: Damian Stasik <920747+damianstasik@users.noreply.github.com> Co-authored-by: Roman Grinovski <roman.grinovski@gmail.com>
67 lines
2.3 KiB
Plaintext
67 lines
2.3 KiB
Plaintext
---
|
|
sidebar_label: timecmp
|
|
description: |-
|
|
The timecmp function adds a duration to a timestamp, returning a new
|
|
timestamp.
|
|
---
|
|
|
|
# `timecmp` Function
|
|
|
|
`timecmp` compares two timestamps and returns a number that represents the
|
|
ordering of the instants those timestamps represent.
|
|
|
|
```hcl
|
|
timecmp(timestamp_a, timestamp_b)
|
|
```
|
|
|
|
| Condition | Return Value |
|
|
|----------------------------------------------------|--------------|
|
|
| `timestamp_a` is before `timestamp_b` | `-1` |
|
|
| `timestamp_a` is the same instant as `timestamp_b` | `0` |
|
|
| `timestamp_a` is after `timestamp_b` | `1` |
|
|
|
|
When comparing the timestamps, `timecmp` takes into account the UTC offsets
|
|
given in each timestamp. For example, `06:00:00+0200` and `04:00:00Z` are
|
|
the same instant after taking into account the `+0200` offset on the first
|
|
timestamp.
|
|
|
|
In the OpenTofu language, timestamps are conventionally represented as
|
|
strings using [RFC 3339](https://tools.ietf.org/html/rfc3339)
|
|
"Date and Time format" syntax. `timecmp` requires the its two arguments to
|
|
both be strings conforming to this syntax.
|
|
|
|
## Examples
|
|
|
|
```
|
|
> timecmp("2017-11-22T00:00:00Z", "2017-11-22T00:00:00Z")
|
|
0
|
|
> timecmp("2017-11-22T00:00:00Z", "2017-11-22T01:00:00Z")
|
|
-1
|
|
> timecmp("2017-11-22T01:00:00Z", "2017-11-22T00:00:00Z")
|
|
1
|
|
> timecmp("2017-11-22T01:00:00Z", "2017-11-22T00:00:00-01:00")
|
|
0
|
|
```
|
|
|
|
`timecmp` can be particularly useful in defining
|
|
[custom condition checks](../../language/expressions/custom-conditions.mdx) that
|
|
involve a specified timestamp being within a particular range. For example,
|
|
the following resource postcondition would raise an error if a TLS certificate
|
|
(or other expiring object) expires sooner than 30 days from the time of
|
|
the "apply" step:
|
|
|
|
```hcl
|
|
lifecycle {
|
|
postcondition {
|
|
condition = timecmp(timestamp(), timeadd(self.expiration_timestamp, "-720h")) < 0
|
|
error_message = "Certificate will expire in less than 30 days."
|
|
}
|
|
}
|
|
```
|
|
|
|
## Related Functions
|
|
|
|
* [`timestamp`](../../language/functions/timestamp.mdx) returns the current timestamp when it is evaluated
|
|
during the apply step.
|
|
* [`timeadd`](../../language/functions/timeadd.mdx) can perform arithmetic on timestamps by adding or removing a specified duration.
|