mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-02-17 19:00:37 -05:00
2ee9589650
This is a complement to "timestamp" and "timeadd" which allows establishing the ordering of two different timestamps while taking into account their timezone offsets, which isn't otherwise possible using the existing primitives in the Terraform language.
68 lines
2.2 KiB
Plaintext
68 lines
2.2 KiB
Plaintext
---
|
|
page_title: timecmp - Functions - Configuration Language
|
|
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 Terraform 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) 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`](./timestamp) returns the current timestamp when it is evaluated
|
|
during the apply step.
|
|
* [`timeadd`](./timeadd) can perform arithmetic on timestamps by adding or
|
|
removing a specified duration.
|