Packages
ex_cldr_units
3.16.2
3.20.5
3.20.4
3.20.3
3.20.2
3.20.1
3.20.0
3.19.2
3.19.1
3.19.0
3.18.1
3.18.0
3.17.2
3.17.1
3.17.0
3.16.5
3.16.4
3.16.3
3.16.2
3.16.1
3.16.0
3.15.0
3.14.0
3.13.3
3.13.2
3.13.1
3.13.0
3.12.2
3.12.1
3.12.0
3.11.0
3.10.0
3.9.2
3.9.1
3.9.0
3.8.0
3.8.0-rc.2
3.8.0-rc.1
3.8.0-rc.0
3.7.1
3.7.0
3.6.0
3.5.3
3.5.2
3.5.1
3.5.0
3.5.0-rc.1
3.5.0-rc.0
3.4.0
3.4.0-rc.0
3.3.1
3.3.0
3.3.0-rc.0
3.2.1
3.2.0
3.1.2
3.1.1
3.1.0
3.0.1
3.0.0
3.0.0-rc.0
2.8.1
2.8.0
2.7.0
2.6.1
2.6.0
2.5.3
2.5.2
2.5.1
2.5.0
2.4.0
2.3.3
2.3.2
retired
2.3.1
2.3.0
2.2.0
2.1.0
2.0.0
1.3.0
1.2.2
1.2.1
1.2.0
1.1.1
1.1.0
retired
1.0.1
retired
1.0.0
retired
1.0.0-rc.0
retired
0.4.4
0.4.3
0.4.2
0.4.1
0.4.0
0.3.1
0.3.0
0.2.1
0.2.0
0.1.3
0.1.2
0.1.1
0.1.0
Unit formatting (volume, area, length, ...), conversion and arithmetic functions based upon the Common Locale Data Repository (CLDR).
Current section
Files
Jump to
Current section
Files
lib/cldr/unit_range.ex
defmodule Cldr.Unit.Range do
@moduledoc """
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:
1. To be able to enumerate a unit range.
2. To be able to format a unit range in a localised manner using
`Cldr.Number.to_range_string/2`.
"""
defstruct [:first, :last]
@typedoc """
A unit range consists of two units where the
last unit can be converted to the same unit type
as the first unit.
"""
@type t :: %{first: Cldr.Unit.t(), last: Cldr.Unit.t()}
@doc """
Returns a new Cldr.Unit.Range.
### Arguments
* `first` is any `t:Cldr.Unit.t/0` returned by `Cldr.Unit.new/2`.
* `last` is any `t: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)"}}
"""
@doc since: "3.16.0"
@spec new(Cldr.Unit.t(), Cldr.Unit.t()) ::
{:ok, t()} | {:error, {module(), String.t()}}
def new(%Cldr.Unit{} = first, %Cldr.Unit{} = last) do
case Cldr.Unit.convert(last, first.unit) do
{:ok, last} ->
if first.value <= last.value do
{:ok, %__MODULE__{first: first, last: last}}
else
{:error,
{Cldr.Unit.InvalidRangeError,
"Unit ranges require that the first unit be less than or equal to the last. Found #{inspect(first)} and #{inspect(last)}"}}
end
{:error, _} ->
{:error,
{Cldr.Unit.InvalidRangeError,
"Unit ranges require that the last unit can be converted to the first unit. Found #{inspect(first)} and #{inspect(last)}"}}
end
end
@doc """
Returns a new Cldr.Unit.Range or raises an exception.
### Arguments
* `first` is any `t:Cldr.Unit.t/0` returned by `Cldr.Unit.new/2`.
* `last` is any `t: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))
"""
@doc since: "3.16.0"
@dialyzer {:nowarn_function, {:new!, 2}}
@spec new!(Cldr.Unit.t(), Cldr.Unit.t()) :: t() | no_return()
def new!(%Cldr.Unit{} = first, %Cldr.Unit{} = last) do
case new(first, last) do
{:ok, range} -> range
{:error, {exception, reason}} -> raise exception, reason
end
end
defdelegate to_iolist(range), to: Cldr.Unit.Format
defdelegate to_iolist(range, options), to: Cldr.Unit.Format
defdelegate to_iolist(range, backend, options), to: Cldr.Unit.Format
defdelegate to_string(range), to: Cldr.Unit.Format
defdelegate to_string(range, options), to: Cldr.Unit.Format
defdelegate to_string(range, backend, options), to: Cldr.Unit.Format
end