Icu.RelativeTime (icu v0.4.0)

High-level API for ICU4X-powered relative time formatting.

Use format/4 to generate localized relative phrases like “in 3 days”, or build reusable formatter structs with formatter/2 for repeated usage.

Summary

Types

format()

Controls the overall style of the relative time output.

format_error()
formatter()

Opaque reference to an ICU4X relative time formatter.

numeric()

Controls whether relative phrases can be non-numeric.

options()

Map form of the supported options.

options_input()
options_list()

Keyword form of the supported options.

unit()

Supported relative time units.

Functions

format(formatter, value, unit)

Formats a relative value using an existing formatter.

format(value, unit, locale, options \\ [])

Convenience helper that creates a formatter and formats in one step.

format!(formatter, value, unit)

Formats and raises on error.

format!(value, unit, locale, options \\ [])

Convenience helper that raises on error.

format_to_parts(formatter, value, unit)

Formats to parts using an existing formatter.

format_to_parts(value, unit, locale, options \\ [])

Convenience helper that formats to parts in one step.

format_to_parts!(formatter, value, unit)

Formats to parts and raises on error.

format_to_parts!(value, unit, locale, options \\ [])

Convenience helper that formats to parts and raises on error.

formatter(locale, options \\ [])

Builds a reusable formatter for the given locale and options.

formatter!(locale, options \\ [])

Builds a reusable formatter and raises on error.

Types

format()

@type format() :: :wide | :short | :narrow

Controls the overall style of the relative time output.

format_error()

@type format_error() ::
  :invalid_formatter
  | :invalid_locale
  | :invalid_options
  | :invalid_unit
  | :unsupported_fraction

formatter()

@type formatter() :: Icu.RelativeTime.Formatter.t()

Opaque reference to an ICU4X relative time formatter.

numeric()

@type numeric() :: :always | :auto

Controls whether relative phrases can be non-numeric.

options()

@type options() :: %{
  optional(:format) => format(),
  optional(:numeric) => numeric(),
  optional(:locale) => Icu.LanguageTag.t() | nil
}

Map form of the supported options.

options_input()

@type options_input() :: options() | options_list() | nil

options_list()

@type options_list() :: [
  format: format(),
  numeric: numeric(),
  locale: Icu.LanguageTag.t() | nil
]

Keyword form of the supported options.

unit()

@type unit() :: :second | :minute | :hour | :day | :week | :month | :quarter | :year

Supported relative time units.

Functions

format(formatter, value, unit)

@spec format(formatter(), number(), unit()) ::
  {:ok, String.t()} | {:error, format_error()}

Formats a relative value using an existing formatter.

format(value, unit, locale, options \\ [])

@spec format(number(), unit(), Icu.LanguageTag.t() | String.t(), options_input()) ::
  {:ok, String.t()} | {:error, format_error()}

Convenience helper that creates a formatter and formats in one step.

format!(formatter, value, unit)

@spec format!(formatter(), number(), unit()) :: String.t()

Formats and raises on error.

format!(value, unit, locale, options \\ [])

@spec format!(number(), unit(), Icu.LanguageTag.t() | String.t(), options_input()) ::
  String.t()

Convenience helper that raises on error.

format_to_parts(formatter, value, unit)

@spec format_to_parts(formatter(), number(), unit()) ::
  {:ok, [map()]} | {:error, format_error()}

Formats to parts using an existing formatter.

format_to_parts(value, unit, locale, options \\ [])

@spec format_to_parts(
  number(),
  unit(),
  Icu.LanguageTag.t() | String.t(),
  options_input()
) ::
  {:ok, [map()]} | {:error, format_error()}

Convenience helper that formats to parts in one step.

format_to_parts!(formatter, value, unit)

@spec format_to_parts!(formatter(), number(), unit()) :: [map()]

Formats to parts and raises on error.

format_to_parts!(value, unit, locale, options \\ [])

@spec format_to_parts!(
  number(),
  unit(),
  Icu.LanguageTag.t() | String.t(),
  options_input()
) :: [map()]

Convenience helper that formats to parts and raises on error.

formatter(locale, options \\ [])

@spec formatter(Icu.LanguageTag.t() | String.t(), options_input()) ::
  {:ok, formatter()} | {:error, format_error()}

Builds a reusable formatter for the given locale and options.

formatter!(locale, options \\ [])

@spec formatter!(Icu.LanguageTag.t() | String.t(), options_input()) :: formatter()

Builds a reusable formatter and raises on error.