Skip to main content

timecmp Function

timecmp compares two timestamps and returns a number that represents the ordering of the instants those timestamps represent.

Code Block
timecmp(timestamp_a, timestamp_b)
ConditionReturn Value
timestamp_a is before timestamp_b-1
timestamp_a is the same instant as timestamp_b0
timestamp_a is after timestamp_b1

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 "Date and Time format" syntax. timecmp requires the its two arguments to both be strings conforming to this syntax.


Code Block
> timecmp("2017-11-22T00:00:00Z", "2017-11-22T00:00:00Z")
> timecmp("2017-11-22T00:00:00Z", "2017-11-22T01:00:00Z")
> timecmp("2017-11-22T01:00:00Z", "2017-11-22T00:00:00Z")
> timecmp("2017-11-22T01:00:00Z", "2017-11-22T00:00:00-01:00")

timecmp can be particularly useful in defining custom condition checks 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:

Code Block
  lifecycle {
postcondition {
condition = timecmp(timestamp(), timeadd(self.expiration_timestamp, "-720h")) < 0
error_message = "Certificate will expire in less than 30 days."
  • timestamp returns the current timestamp when it is evaluated during the apply step.
  • timeadd can perform arithmetic on timestamps by adding or removing a specified duration.