dttm

Written as dttm(argnum flags):options in a transform expression.

Minimum arguments	0
Maximum arguments	1
Default arguments	0
Argument modes	SINGLE_PRIMITIVE

Documentation

Load current datetime (when no input arg) or a datetime from input arg to native datetime, and optionally convert to a different format or adjust with offset or change timezone.

This transform converts input datetime object or string into format specified in options. The options string supports below forms:

• load and return string representation of datetime: {in_format}||{out_format}, where either {in_format} or {out_format} or both can be blank, and the ‘||’ marker indicates to load datetime from input per in_format, and convert it to out_format as output string.

• load and return adjusted datetime: {in_format}|{+,-,@}{adjustment} where:

  • {in_format} is optional if input is in starndard formator
  • {+,-,@} are 3 supported adjustment types:

    • ‘+’ or ‘-’: adjust the input datetime forward (‘+’) or backward (‘-’) by the amount set in {adjustment}. And allowed {adjustment} can be any combination of below expressions (using comma ‘,’ as separator when multiple expressions exist):

      1. ‘{n} days’ or ‘{n} day’
      2. ‘{n} hours’ or ‘{n} hour’
      3. ‘{n} minutes’ or ‘{n} minute’
      4. ‘{n} seconds’ or ‘{n} second’
      5. ‘{n} milliseconds’ or ‘{n} millisecond’
      6. ‘{n} microseconds’ or ‘{n} microsecond’
      7. ‘{n} weeks’ or ‘{n} week’

    • ‘@’: adjust the timezone of the input datetime, to the one specified in {adjustment}, e.g. ‘America/New_York’

• load only (useful for working with other datetime transforms for e.g. comparison) and return loaded datetime:

  • blank string (‘’): loads the datetime assuming standard formats
  • {in_format}: loads the datetime using format per in_format.

Notes on semantics of blank in_format and out_format:

• blank in_format means the input datetime string will be parsed using stanrdard formats. If the input datetime is in a custom format, its format must be specified in options, otherwise input parse will fail.
• blank out_format means to use ISO8601 format (to seconds) for the output (assuming ‘||’ marker is present)

Important Notes:

• when input arg is not provided, current datetime is used as input
• when input arg is already a native datetime object (e.g. the result of a previous DatetimeFormatTransform), input_format is ignored, since no datetime parsing is required.
• when input_format is invalid and causes parsing to fail, this transform will do a rescue parse using a fallback approach to scan common formats and return the datetime if recognised.

Flags

Flag	Letter
noncaptive_input	I
arg_num_flexible	f

Examples

Load current datetime

Input args: []
Transforms: "dttm:"
Output: "2025-07-11T07:46:34Z"

Human readable standard datetime load

Input args: ["Fri Jul 11 07:46:34 UTC 2025"]
Transforms: "dttm:"
Output: "2025-07-11T07:46:34Z"

Human readable standard input datetime to ISO8601 format

Input args: ["Fri Jul 11 07:46:34 UTC 2025"]
Transforms: "dttm:||"
Output: "2025-07-11T07:46:34+00:00"

Timestamp since epoch as input to ISO8601 format

Input args: [1752219994]
Transforms: "dttm:||"
Output: "2025-07-11T07:46:34+00:00"

Standard input datetime to custom format

Input args: ["Fri Jul 11 07:46:34 UTC 2025"]
Transforms: "dttm:||%Y-%m-%d %H:%M"
Output: "2025-07-11 07:46"

Custom datetime input to custom datetime output

Input args: ["Date: 2025-07-11, Time: 07:46:34 +00:00"]
Transforms: "dttm:Date: %Y-%m-%d, Time: %H:%M:%S %z||%Y-%m-%d %H:%M"
Output: "2025-07-11 07:46"

Standard input datetime adjusted forward

Input args: ["Fri Jul 11 07:46:34 UTC 2025"]
Transforms: "dttm:|+3 days,1 hour"
Output: "2025-07-14T08:46:34Z"

Custom datetime with timezone changed

Input args: ["Date: 2025-07-11, Time: 07:46:34 +00:00"]
Transforms: "dttm:Date: %Y-%m-%d, Time: %H:%M:%S %z|@Australia/Melbourne"
Output: "2025-07-11T07:46:34+10:00"