github.com/kanishk98/terraform@v1.3.0-dev.0.20220917174235-661ca8088a6a/website/docs/language/functions/timecmp.mdx (about)

     1  ---
     2  page_title: timecmp - Functions - Configuration Language
     3  description: |-
     4    The timecmp function adds a duration to a timestamp, returning a new
     5    timestamp.
     6  ---
     7  
     8  # `timecmp` Function
     9  
    10  `timecmp` compares two timestamps and returns a number that represents the
    11  ordering of the instants those timestamps represent.
    12  
    13  ```hcl
    14  timecmp(timestamp_a, timestamp_b)
    15  ```
    16  
    17  | Condition                                          | Return Value |
    18  |----------------------------------------------------|--------------|
    19  | `timestamp_a` is before `timestamp_b`              | `-1`         |
    20  | `timestamp_a` is the same instant as `timestamp_b` | `0`          |
    21  | `timestamp_a` is after `timestamp_b`               | `1`          |
    22  
    23  When comparing the timestamps, `timecmp` takes into account the UTC offsets
    24  given in each timestamp. For example, `06:00:00+0200` and `04:00:00Z` are
    25  the same instant after taking into account the `+0200` offset on the first
    26  timestamp.
    27  
    28  In the Terraform language, timestamps are conventionally represented as
    29  strings using [RFC 3339](https://tools.ietf.org/html/rfc3339)
    30  "Date and Time format" syntax. `timecmp` requires the its two arguments to
    31  both be strings conforming to this syntax.
    32  
    33  ## Examples
    34  
    35  ```
    36  > timecmp("2017-11-22T00:00:00Z", "2017-11-22T00:00:00Z")
    37  0
    38  > timecmp("2017-11-22T00:00:00Z", "2017-11-22T01:00:00Z")
    39  -1
    40  > timecmp("2017-11-22T01:00:00Z", "2017-11-22T00:00:00Z")
    41  1
    42  > timecmp("2017-11-22T01:00:00Z", "2017-11-22T00:00:00-01:00")
    43  0
    44  ```
    45  
    46  `timecmp` can be particularly useful in defining
    47  [custom condition checks](/language/expressions/custom-conditions) that
    48  involve a specified timestamp being within a particular range. For example,
    49  the following resource postcondition would raise an error if a TLS certificate
    50  (or other expiring object) expires sooner than 30 days from the time of
    51  the "apply" step:
    52  
    53  ```hcl
    54    lifecycle {
    55      postcondition {
    56        condition     = timecmp(timestamp(), timeadd(self.expiration_timestamp, "-720h")) < 0
    57        error_message = "Certificate will expire in less than 30 days."
    58      }
    59    }
    60  ```
    61  
    62  ## Related Functions
    63  
    64  * [`timestamp`](./timestamp) returns the current timestamp when it is evaluated
    65    during the apply step.
    66  * [`timeadd`](./timeadd) can perform arithmetic on timestamps by adding or
    67    removing a specified duration.