@spec compile(String.t()) :: {:ok, compiled()} | {:error, Datix.FormatStringError.t()}

Compiles the given format string.

If the format string is a valid format string, then this function returns {:ok, compiled}. compiled is a term that represents a compiled format (its internal representation is private). You can pass a compiled/0 term to strptime/3 and such.

If the format string is invalid, this function returns {:error, reason}, where reason is an exception struct.

You can use this function for two reasons:

• You have the same format string that you want to compile once and then use to parse over and over

• You want to validate a format string

@spec compile!(String.t()) :: compiled()

Like compile/1, but returns the compiled struct directly or raises in case of errors.

Examples

iex> Datix.compile!("%Y-%m-%d")
Datix.compile!("%Y-%m-%d")

iex> Datix.compile!("%l")
** (Datix.FormatStringError) invalid format string because of invalid modifier: %l

@spec strptime(String.t(), String.t() | compiled(), keyword()) ::
  {:ok, t()}
  | {:error,
     Datix.ParseError.t() | Datix.FormatStringError.t() | Datix.OptionError.t()}

Parses a date-time string according to the given format.

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

format can be a format string or, since v0.2.0 of the library, a compiled format as returned by compile/1.

If parsing is successful, this function returns {:ok, datix} where datix is a map of type t/0. If you are looking for functions that return Elixir structs (such as DateTime and similar), see Datix.DateTime, Datix.Date, Datix.Time, and Datix.NaiveDateTime.

If there's an error, this function returns {:error, error} where error is an exception struct. You can raise it manually with raise/1.

Options

• :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"].

Examples

iex> Datix.strptime("2021/01/10", "%Y/%m/%d")
{:ok, %{day: 10, month: 1, year: 2021}}

iex> Datix.strptime("21/01/10", "%y/%m/%d")
{:ok, %{day: 10, month: 1, year_2_digit: 21}}

iex> Datix.strptime("13/14/15", "%H/%M/%S")
{:ok, %{hour: 13, minute: 14, second: 15}}

iex> Datix.strptime("1 PM", "%-I %p")
{:ok, %{am_pm: :pm, hour_12: 1}}

iex> Datix.strptime("Tuesday", "%A")
{:ok, %{day_of_week: 2}}

iex> Datix.strptime("Tue", "%a")
{:ok, %{day_of_week: 2}}

iex> Datix.strptime("Di", "%a",
...>   abbreviated_day_of_week_names: ~w(Mo Di Mi Do Fr Sa So))
{:ok, %{day_of_week: 2}}

iex> compiled = Datix.compile!("%Y/%m/%d")
iex> Datix.strptime("2021/01/10", compiled)
{:ok, %{day: 10, month: 1, year: 2021}}

iex> Datix.strptime("irrelevant", "%l")
{:error, %Datix.FormatStringError{reason: {:invalid_modifier, "%l"}}}

@spec strptime!(String.t(), String.t() | compiled(), keyword()) :: t()

Parses a date-time string according to the given format, erroring out for invalid arguments.