Cldr.Unit.Range (Cldr Units v3.19.2)

Implements a unit range type, similar to Date.Range.

A unit range but be comprise first and last units that have the same base unit. The last unit will be converted to the unit type of the first unit.

Unit ranges are useful in at least the following cases:

To be able to enumerate a unit range.
To be able to format a unit range in a localised manner using Cldr.Number.to_range_string/2.

Summary

Types

t()

A unit range consists of two units where the last unit can be converted to the same unit type as the first unit.

Functions

new(first, last)

Returns a new Cldr.Unit.Range.

new!(first, last)

Returns a new Cldr.Unit.Range or raises an exception.

to_iolist(range)

See Cldr.Unit.Format.to_iolist/1.

to_iolist(range, options)

See Cldr.Unit.Format.to_iolist/2.

to_iolist(range, backend, options)

See Cldr.Unit.Format.to_iolist/3.

to_string(range)

See Cldr.Unit.Format.to_string/1.

to_string(range, options)

See Cldr.Unit.Format.to_string/2.

to_string(range, backend, options)

See Cldr.Unit.Format.to_string/3.

Types

t()

@type t() :: %Cldr.Unit.Range{first: Cldr.Unit.t(), last: Cldr.Unit.t()}

A unit range consists of two units where the last unit can be converted to the same unit type as the first unit.

Functions

new(first, last)

(since 3.16.0)

@spec new(Cldr.Unit.t(), Cldr.Unit.t()) ::
  {:ok, t()} | {:error, {module(), String.t()}}

Returns a new Cldr.Unit.Range.

Arguments

first is any Cldr.Unit.t/0 returned by Cldr.Unit.new/2.
last is any Cldr.Unit.t/0 returned by Cldr.Unit.new/2 that is convertible to the same unit as first and where its converted value is greater than or equal to the value of first.

Returns

{:ok, unit_range} or
{:error, {exception, reason}}.

Examples

iex> Cldr.Unit.Range.new Cldr.Unit.new!(:gram, 1), Cldr.Unit.new!(:gram, 4)
{:ok, Cldr.Unit.Range.new!(Cldr.Unit.new!(:gram, 1), Cldr.Unit.new!(:gram, 4))}

iex> Cldr.Unit.Range.new Cldr.Unit.new!(:gram, 1), Cldr.Unit.new!(:liter, 4)
{:error,
 {Cldr.Unit.InvalidRangeError,
  "Unit ranges require that the last unit can be converted to the first unit. " <>
  "Found Cldr.Unit.new!(:gram, 1) and Cldr.Unit.new!(:liter, 4)"}}

iex> Cldr.Unit.Range.new Cldr.Unit.new!(:gram, 5), Cldr.Unit.new!(:gram, 4)
{:error,
 {Cldr.Unit.InvalidRangeError,
  "Unit ranges require that the first unit be less than or equal to the last. " <>
  "Found Cldr.Unit.new!(:gram, 5) and Cldr.Unit.new!(:gram, 4)"}}

new!(first, last)

(since 3.16.0)

@spec new!(Cldr.Unit.t(), Cldr.Unit.t()) :: t() | no_return()

Returns a new Cldr.Unit.Range or raises an exception.

Arguments

first is any Cldr.Unit.t/0 returned by Cldr.Unit.new/2.
last is any Cldr.Unit.t/0 returned by Cldr.Unit.new/2 that is convertible to the same unit as first and where its converted value is greater than or equal to the value of first.

Returns

unit_range or
raises an exception.

Example

iex> Cldr.Unit.Range.new! Cldr.Unit.new!(:gram, 1), Cldr.Unit.new!(:gram, 4)
Cldr.Unit.Range.new!(Cldr.Unit.new!(:gram, 1), Cldr.Unit.new!(:gram, 4))

to_iolist(range)

See Cldr.Unit.Format.to_iolist/1.

to_iolist(range, options)

See Cldr.Unit.Format.to_iolist/2.

to_iolist(range, backend, options)

See Cldr.Unit.Format.to_iolist/3.

to_string(range)

See Cldr.Unit.Format.to_string/1.

to_string(range, options)

See Cldr.Unit.Format.to_string/2.

to_string(range, backend, options)

See Cldr.Unit.Format.to_string/3.