# `Machete.NumberMatcher`
[🔗](https://github.com/mtrudel/machete/blob/main/lib/machete/matchers/number_matcher.ex#L1)

Defines a matcher that matches number values. Comparison is done in a type-agnostic manner, for
example `1.0 ~> number(exactly: 1)` matches, as does `1 ~> number(exactly: 1.0)`.

# `opts`

```elixir
@type opts() :: [
  positive: boolean(),
  strictly_positive: boolean(),
  negative: boolean(),
  strictly_negative: boolean(),
  nonzero: boolean(),
  min: number(),
  max: number(),
  roughly: number(),
  epsilon: number() | {number(), number()},
  exactly: number()
]
```

Describes the arguments that can be passed to this matcher

# `t`

```elixir
@opaque t()
```

Describes an instance of this matcher

# `number`

```elixir
@spec number(opts()) :: t()
```

Matches against number values

Takes the following arguments:

* `exactly`: Requires the matched number be exactly equal to the specified value
* `positive`: When `true`, requires the matched number be positive or zero
* `strictly_positive`: When `true`, requires the matched number be positive and nonzero
* `negative`: When `true`, requires the matched number be negative or zero
* `strictly_negative`: When `true`, requires the matched number be negative and nonzero
* `nonzero`: When `true`, requires the matched number be nonzero
* `min`: Requires the matched number be greater than or equal to the specified value
* `max`: Requires the matched number be less than or equal to the specified value
* `roughly`: Requires the matched number be within `epsilon` of the specified value
* `epsilon`: The bound(s) to use when determining how close the matched integer needs to be to
  `roughly`. Can be specified as a single number that is used for both lower and upper bounds,
  or a tuple consisting of distinct lower and upper bounds. If not specified, and if `roughly`
  is not zero, defaults to 5% of the value

Examples:

    iex> assert 1.0 ~> number()
    true

    iex> assert 1 ~> number()
    true

    iex> assert 1 ~> number(exactly: 1.0)
    true

    iex> assert 2 ~> number(roughly: 2.1, epsilon: 0.2)
    true

    iex> assert 1.0 ~> number(positive: true)
    true

    iex> assert 1 ~> number(positive: true)
    true

    iex> assert 0.0 ~> number(positive: true)
    true

    iex> assert -1.0 ~> number(positive: false)
    true

    iex> refute 0.0 ~> number(positive: false)
    false

    iex> assert 1.0 ~> number(strictly_positive: true)
    true

    iex> refute 0.0 ~> number(strictly_positive: true)
    false

    iex> assert -1.0 ~> number(strictly_positive: false)
    true

    iex> assert 0.0 ~> number(strictly_positive: false)
    true

    iex> assert -1.0 ~> number(negative: true)
    true

    iex> assert 0.0 ~> number(negative: true)
    true

    iex> assert 1.0 ~> number(negative: false)
    true

    iex> refute 0.0 ~> number(negative: false)
    false

    iex> assert -1.0 ~> number(strictly_negative: true)
    true

    iex> refute 0.0 ~> number(strictly_negative: true)
    false

    iex> assert 1.0 ~> number(strictly_negative: false)
    true

    iex> assert 0.0 ~> number(strictly_negative: false)
    true

    iex> assert 1.0 ~> number(nonzero: true)
    true

    iex> assert 0.0 ~> number(nonzero: false)
    true

    iex> assert 2.0 ~> number(min: 2.0)
    true

    iex> assert 2 ~> number(min: 2.0)
    true

    iex> assert 2.0 ~> number(max: 2.0)
    true

    iex> assert 2 ~> number(max: 2.0)
    true

    iex> assert 95.0 ~> number(roughly: 100.0)
    true

    iex> assert -95.0 ~> number(roughly: -100.0)
    true

    iex> assert 90.0 ~> number(roughly: 100.0, epsilon: 10.0)
    true

    iex> assert -90.0 ~> number(roughly: -100.0, epsilon: 10.0)
    true

    iex> assert 105.0 ~> number(roughly: 100.0, epsilon: {10.0, 5.0})
    true

    iex> assert -110.0 ~> number(roughly: -100.0, epsilon: {10.0, 5.0})
    true

    iex> refute 94.0 ~> number(roughly: 100.0)
    false

    iex> refute 89.0 ~> number(roughly: 100.0, epsilon: 10.0)
    false

    iex> refute 106.0 ~> number(roughly: 100.0, epsilon: {10.0, 5.0})
    false

---

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