@spec new(String.t() | [field()], Keyword.t()) :: {:ok, t()} | {:error, Exception.t()}

Builds a semantic skeleton.

Arguments

• code is a string of field codes such as "YMDE" or "MDTZ", or a list of field atoms such as [:year, :month, :day].

• options is a keyword list.

Options

• :length is :short, :medium (the default) or :long. It says how much space the result has, and the locale's own date format at that length sets the widths of the year, month and day — :short is usually numeric, :long spells the month out.

• :year_style is :auto (the default), :full or :with_era. :auto takes the year as the locale's date format writes it, era and all; :full never truncates it to two digits; :with_era also shows the era.

• :zone_style is :specific (the default), :generic, :location or :offset.

• :zone_length is :auto (the default), :short or :long. :auto is TR35's rule: a zone on its own takes the long form except at short length, and a zone beside other fields the short one. :short and :long choose the form outright — z or zzzz for a specific zone, v or vvvv for a generic one, O or OOOO for an offset — which TR35 does not provide for but MessageFormat 2's timeZoneStyle needs. A location zone has one form.

• :hour_cycle is :auto (the default), :clock12, :clock24, :h11, :h12, :h23 or :h24, in TR35's vocabulary. :auto uses the locale's own cycle, which is what a semantic request usually means. :clock12 and :clock24 ask for a 12- or 24-hour clock and then take the locale's pattern as it stands, so ja renders K rather than h. The four exact cycles substitute their hour symbol into the matched pattern — :h11 K, :h12 h, :h23 H, :h24 k — which is the only way to be sure which symbol you get.

• :time_precision is :hour, :minute, :minute_optional, :second (the default) or {:fractional_second, digits} with digits from 1 to

  9. :minute_optional drops the minutes when they are zero.

• :alignment is :inline (the default) or :column, TR35's two alignments. :column is for dates and times set in a column, where equal widths line up: it pads a numeric month, day and hour to two digits, so en's short date "1/5/25" becomes "01/05/25". It never turns a number into text or back, and it acts on the pattern the skeleton resolves to, leaving the classical skeleton as it is.

Each option shapes certain fields, and TR35 makes giving one for a field set that has none of them an error: :year_style needs Y, :hour_cycle and :time_precision need T, :zone_style and :zone_length need Z, and :alignment needs Y, M, D or T. :length suits every set.

Returns

• {:ok, skeleton}.

• {:error, exception} if a field code or option value is unknown, the fields are not a set TR35 defines, or an option is given for a set without the fields it applies to.

Examples

iex> {:ok, skeleton} = Localize.DateTime.SemanticSkeleton.new("YMDE")
iex> skeleton.fields
[:year, :month, :day, :weekday]

iex> Localize.DateTime.SemanticSkeleton.new("YMDQ")
{:error, %Localize.InvalidValueError{value: "Q", expected: "one of Y, M, D, E, T, Z", context: "Localize.DateTime.SemanticSkeleton"}}

@spec semantic(String.t() | [field()], Keyword.t()) :: t()

Builds a semantic skeleton, raising on invalid input.

Intended for the :format option, where the skeleton is usually a literal and a mistake in it is a programming error rather than bad data.

Arguments

• See new/2.

Returns

• A t/0.

Raises

• Localize.InvalidValueError wherever new/2 returns an error.

Examples

iex> skeleton = Localize.DateTime.SemanticSkeleton.semantic("YMD", length: :long)
iex> {skeleton.fields, skeleton.length}
{[:year, :month, :day], :long}

@spec to_classical_skeleton(t(), Keyword.t()) ::
  {:ok, atom()} | {:error, Exception.t()}

Returns the classical skeleton a semantic skeleton resolves to.

This is TR35 §Mapping to Standard Skeletons: the year, month and day take their widths from the locale's date format at the skeleton's length, the weekday, time and zone come from a fixed table, and the time precision and year style then adjust the result. The result is an ordinary skeleton atom, resolved from there by the machinery that already handles format: :yMMMd.

Arguments

• skeleton is a t/0.

• options is a keyword list.

Options

• :locale is the locale whose date formats set the widths of the year, month and day. The default is Localize.get_locale/0.

• :calendar is a calendar module, Calendar.ISO by default. Its CLDR calendar type selects the date formats, so a year in a calendar that counts years by era carries one.

• :value is the date or time being formatted. Only :minute_optional precision consults it, dropping the minutes when they are zero; without a value the minutes are shown.

Returns

• {:ok, atom} — the classical skeleton.

• {:error, exception} if the skeleton is not one new/2 builds, as a struct made by hand may not be, or the locale or calendar is not known.

Examples

iex> skeleton = Localize.DateTime.SemanticSkeleton.semantic("YMDE", length: :short)
iex> Localize.DateTime.SemanticSkeleton.to_classical_skeleton(skeleton, locale: :en)
{:ok, :yyMdEEE}

iex> skeleton = Localize.DateTime.SemanticSkeleton.semantic("YMD")
iex> Localize.DateTime.SemanticSkeleton.to_classical_skeleton(skeleton, locale: :de)
{:ok, :yMMdd}

iex> skeleton = Localize.DateTime.SemanticSkeleton.semantic("T", time_precision: :minute)
iex> Localize.DateTime.SemanticSkeleton.to_classical_skeleton(skeleton, locale: :en)
{:ok, :jm}