View Source Datix (datix v0.3.1)
A date-time parser using Calendar.strftime/3
format strings.
Link to this section Summary
Link to this section Types
@opaque compiled()
An opaque type representing a compiled format.
The struct representation is internal and could change in the future without notice.
@type t() :: %{ optional(:am_pm) => :am | :pm, optional(:day) => pos_integer(), optional(:day_of_week) => pos_integer(), optional(:day_of_year) => pos_integer(), optional(:hour) => pos_integer(), optional(:hour_12) => pos_integer(), optional(:microsecond) => pos_integer(), optional(:minute) => pos_integer(), optional(:month) => pos_integer(), optional(:quarter) => pos_integer(), optional(:second) => pos_integer(), optional(:year) => pos_integer(), optional(:year_2_digit) => pos_integer(), optional(:zone_abbr) => String.t(), optional(:zone_offset) => integer() }
Link to this section Functions
Like compile/1
, but returns the compiled struct directly or raises in case of errors.
examples
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 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
Parses a date-time string according to the given format
, erroring out for
invalid arguments.
@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
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
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"}}}