# `Cldr.Unit.Range`
[🔗](https://github.com/elixir-cldr/cldr_units/blob/v3.20.3/lib/cldr/unit_range.ex#L1)

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`.

# `t`

```elixir
@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.

# `new`
*since 3.16.0* 

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

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)"}}

# `new!`
*since 3.16.0* 

```elixir
@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 `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))

# `to_iolist`

# `to_iolist`

# `to_iolist`

# `to_string`

# `to_string`

# `to_string`

---

*Consult [api-reference.md](api-reference.md) for complete listing*