@spec parse(String.t(), String.t() | Datix.compiled(), list()) ::
  {:ok, DateTime.t()}
  | {:error,
     Datix.FormatStringError.t()
     | Datix.ParseError.t()
     | Datix.ValidationError.t()
     | Datix.OptionError.t()}

Parses a datetime string into a DateTime according to the given format.

See the Calendar.strftime/3 documentation for how to specify a format string.

When the format string contains an offset (%z) or a timezone abbreviation (%Z), then the :time_zone option is required. See below for more information on the option.

Options

• :calendar - the calendar to build the Date, defaults to Calendar.ISO

• :preferred_date - a string for the preferred format to show dates, it can't contain the %x format and defaults to "%Y-%m-%d" if the option is not received

• :month_names - a list of the month names, if the option is not received it defaults to a list of month names in English

• :abbreviated_month_names - a list of abbreviated month names, if the option is not received it defaults to a list of abbreviated month names in English

• :day_of_week_names - a list of day names, if the option is not received it defaults to a list of day names in English

• :abbreviated_day_of_week_names - a list of abbreviated day names, if the option is not received it defaults to a list of abbreviated day names in English

• :preferred_time - a string for the preferred format to show times, it can't contain the %X format and defaults to "%H:%M:%S" if the option is not received

• :am_pm_names - a keyword list with the names of the period of the day, defaults to [am: "am", pm: "pm"].

• :pivot_year - (since v0.2.0) a 2-digit year that represents the pivot year to use when %y is used. %y represents a 2-digit year, but Datix doesn't assume anything about which century such year refers to. For this reason, the :pivot_year option is required whenever %y is present in the format string; if not present, this function returns {:error, :missing_pivot_year_option}. For example, if pivot_year: 65, then the 2-digit year 64 and lower will refer to the current century (2064 and so on at the time of writing this), while the 2-digit year 65 and higher will refer to the previous century (1965 and so on).

• :time_zone - (since v0.3.0) a function that receives the parsed datetime as NaiveDateTime, the zone abbreviation, and the offset to handle the time zone and returns an :ok tuple with the DateTime or an :error tuple with Datix.ValidationError. Defaults to a function handling only "UTC".

Examples

iex> Datix.DateTime.parse("2021/01/10 12:14:24", "%Y/%m/%d %H:%M:%S")
{:ok, ~U[2021-01-10 12:14:24Z]}

iex> format = Datix.compile!("%Y/%m/%d %H:%M:%S")
iex> Datix.DateTime.parse("2021/01/10 12:14:24", format)
{:ok, ~U[2021-01-10 12:14:24Z]}

iex> Datix.DateTime.parse("2018/06/27 11:23:55 CEST+0200", "%Y/%m/%d %H:%M:%S %Z%z")
{:error, %Datix.ValidationError{module: Datix.DateTime, reason: {:unknown_timezone_abbr, "CEST"}}}

If you need to parse non-UTC datetimes, you'll have to pass the :time_zone option.

tz_fun = fn naive_datetime, abbr, offset ->
  {:ok, naive_datetime |> DateTime.from_naive!(convert_abbr(abbr)) |> DateTime.add(-offset)}
end

Datix.DateTime.parse("2018/06/27 11:23:55 CEST+0200", "%Y/%m/%d %H:%M:%S %Z%z", time_zone: tz_fun)

@spec parse!(String.t(), String.t() | Datix.compiled(), list()) :: DateTime.t()

Parses a datetime string according to the given format, erroring out for invalid arguments.

This function is just defined for UTC datetimes.

Options

Accepts the same options as listed for parse/3.

Examples

iex> Datix.DateTime.parse!("2018/06/27 11:23:55 UTC+0000", "%Y/%m/%d %H:%M:%S %Z%z")
~U[2018-06-27 11:23:55Z]

iex> format = Datix.compile!("%Y/%m/%d %H:%M:%S %Z%z")
iex> Datix.DateTime.parse!("2018/06/27 11:23:55 UTC+0000", format)
~U[2018-06-27 11:23:55Z]

iex> Datix.DateTime.parse!("2018/06/27 11:23:55 CEST+0200", "%Y/%m/%d %H:%M:%S %Z%z")
** (Datix.ValidationError) unknown timezone abbreviation: CEST