DOCUMENTATION:
  name: strftime
  version_added: "2.4"
  short_description: Returns date and/or time
  description:
    - Using Python's L(strftime, https://docs.python.org/3/library/datetime.html#datetime.datetime.strftime) function, take a data formatting string and a date/time to create a formatted date.
  notes:
    - This is a passthrough to Python's C(datetime.datetime.strftime), for a complete set of formatting options go to L(the Python documentation, https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes).
    - Before Ansible Core 2.21, this was based upon C(time.strftime) Python API.
  positional: _input, second, utc
  options:
    _input:
      description:
        - A formatting string following C(strftime) conventions.
        - Some additional directives are not supported by all platforms. See Python documentation for more details.
        - See L(the Python documentation, https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior) for a reference.
      type: str
      required: true
    second:
      description:
        - A datetime in seconds from C(epoch) to format.
        - If not supplied, the current time based on C(time.time()) will be used.
      type: int
    utc:
      description:
        - Whether time supplied is in UTC.
        - If C(utc) is true, the time will be in UTC, otherwise it will be in the local timezone.
        - Before Ansible Core 2.21, this was based upon C(time.strftime) Python API.
      type: bool
      default: false
      version_added: '2.14'

EXAMPLES: |
  # for a complete set of features go to https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes

  # Display year-month-day
  {{ '%Y-%m-%d' | strftime }}
  # => "2021-03-19"

  # Display hour:min:sec
  {{ '%H:%M:%S' | strftime }}
  # => "21:51:04"

  # Use ansible_date_time.epoch fact
  {{ '%Y-%m-%d %H:%M:%S' | strftime(ansible_date_time.epoch) }}
  # => "2021-03-19 21:54:09"

  # Use arbitrary epoch value
  {{ '%Y-%m-%d' | strftime(0) }}          # => 1970-01-01
  {{ '%Y-%m-%d' | strftime(seconds=1441357287, utc=true) }} # => 2015-09-04

RETURN:
  _value:
    description: A formatted date/time string.
    type: str
