Localize.DateTime.Format.AppendItems (Localize v1.4.0)

Copy Markdown View Source

TR35's append-item path for flexible date-time patterns.

A locale ships a finite set of available formats, so a skeleton may ask for a field combination CLDR does not carry. TR35 resolves this by matching the closest format that is available and then appending each requested field the match omits, using the locale's appendItems templates. English asking for :yMMMdQ matches yMMMd and appends the quarter as "Jul 6, 2024 (quarter: Q3)".

Each template is a substitution list where 0 is the matched pattern, 1 is the missing field's own pattern, and 2 is the field's localized display name. Fields are appended one at a time, each round's output becoming the next round's {0}.

Summary

Functions

augment(skeleton, locale_id, calendar_type, options \\ [])

Resolves a skeleton no available format covers by augmenting the closest subset match with append-item templates.

resolve_pattern(skeleton, locale_id, calendar_type, options \\ [])

Resolves a skeleton to a pattern, using the append-item path when no available format carries every requested field.

Functions

augment(skeleton, locale_id, calendar_type, options \\ [])

@spec augment(atom() | String.t(), Localize.locale(), atom(), Keyword.t()) ::
  {:ok, String.t()} | :error | {:error, Exception.t()}

Resolves a skeleton no available format covers by augmenting the closest subset match with append-item templates.

Arguments

  • skeleton is the requested skeleton, an atom or a string.

  • locale_id is a resolved locale identifier.

  • calendar_type is a CLDR calendar name.

  • options are the formatting options, used to resolve pattern variants.

Returns

  • {:ok, pattern} where pattern is the augmented pattern string. When no format carries any requested field, the pattern starts from the first field in CLDR's canonical order, as CLDR's reference pattern generator does.

  • :error when a field the pattern would have to append is not one TR35 names as an append item.

  • {:error, exception} if the locale's data cannot be read.

Examples

en has no format with a quarter, so the closest match takes the locale's append item for it:

iex> Localize.DateTime.Format.AppendItems.augment(:yMMMdQ, :en, :gregorian)
{:ok, "MMM d, y ('quarter': Q)"}

resolve_pattern(skeleton, locale_id, calendar_type, options \\ [])

@spec resolve_pattern(atom() | String.t(), Localize.locale(), atom(), Keyword.t()) ::
  {:ok, String.t()} | :error | {:error, Exception.t()}

Resolves a skeleton to a pattern, using the append-item path when no available format carries every requested field.

This is the whole resolution chain in one call: an exact available format, else the closest match with its field widths adjusted to the request, in the calendar's own formats and then in the Gregorian calendar's, which TR35 has most calendars inherit; else a subset match from either, augmented with append items.

Arguments

  • skeleton is the requested skeleton, an atom or a string.

  • locale_id is a resolved locale identifier.

  • calendar_type is a CLDR calendar name.

  • options are the formatting options, used to resolve pattern variants.

Returns

  • {:ok, pattern}.

  • :error when the skeleton cannot be resolved at all.

  • {:error, exception} if the locale's data cannot be read.

Examples

iex> Localize.DateTime.Format.AppendItems.resolve_pattern(:yMMMd, :en, :gregorian)
{:ok, "MMM d, y"}

iex> Localize.DateTime.Format.AppendItems.resolve_pattern(:yMMMdQ, :en, :gregorian)
{:ok, "MMM d, y ('quarter': Q)"}