# `Feel.Analysis.Images.Number.Modulo`
[🔗](https://github.com/FeeJai/BDM/blob/feel-v0.1.0/apps/feel/lib/feel/analysis/images/number/modulo.ex#L1)

The numbers `modulo(dividend, divisor)` can give, and when it gives `null` (`Feel.Analysis.Images.Number`, D-161).

`modulo(x, y)` is `x - y * floor(x / y)`, which is in `[0..y)` for a positive divisor and in `(y..0]` for a negative one.
It is worked out on the integers behind the two numbers (`Feel.Builtin.Number`), so it is exact. For a negative divisor it
is the negative of the result for the negated dividend and divisor, so only a positive divisor is worked out below.

**The numbers.** For a divisor that is one number `y`, the numbers of an interval of dividends that is narrower than `y`
are in one stretch of `y` (the residues of its ends, in order) or in two (from the residue of the lower end to `y`, and
from `0` to the residue of the upper end); a wider interval has every residue, `[0..y)`. So `modulo(x, 7)` for `x` in
`[0..5]` is `[0..5]`, for `x` in `[-5..-1]` it is `[2..6]`, and for `x` in `[-1..1]` it is `0, 1` and `[6..7)`. For a divisor
that is an interval the result is a hull: `[0..ymax)`, where `ymax` is its upper end, and a dividend that is not below zero
and is below every divisor is its own residue.

**When it is `null`.** For a divisor of zero. And for a result that needs more than 34 digits, which Table 60 turns down:
for two numbers of one sign the result is no longer than the dividend, so it is a dividend and a divisor of opposite signs
that give it. The result, `|y|` less the rest of `|x|` over `|y|`, has the first digit of `|y|` or one below it, and the
last digit of `x` or of `y`, so it is longer than 34 digits only if the last digit of `x` is 34 places or more below the
first digit of `y`. For two single numbers the result is worked out and its digits counted. For an interval it is counted
from the finest number in it: one of 34 digits, whose last digit is 33 places below its first. So `modulo(x, 7)` for `x` in
`[-100..-1]` is not `null` (the last digit of `-1.000000000000000000000000000000001` is 33 places down, and the first digit of
7 is at 0), for `x` in `[-100..-0.5]` it is (the result of `-0.5000000000000000000000000000000001` is
`6.4999999999999999999999999999999999`, 35 digits), and for `x` in `[-100..0)` it is, with `-1E-6176`, whose result needs
6,176 digits. The run counts the digits of the number and not those of its coefficient, so `modulo(-5.000000000000000000000000000000000, 20)`
is 15 and not `null`.

# `result`

```elixir
@type result() :: {Feel.Type.NumberSet.t(), boolean()}
```

The numbers of the result, and whether a pair of numbers gives `null` for a reason other than a `null` argument.

# `image`

```elixir
@spec image(Feel.Type.NumberSet.t(), Feel.Type.NumberSet.t()) :: result()
```

The numbers `modulo(x, y)` can be for the numbers of the dividends and of the divisors, and whether it can be `null`.

    iex> alias Feel.Type.NumberSet
    iex> alias Feel.Analysis.Images.Number.Modulo
    iex> to_150 = NumberSet.interval(Decimal.new(0), Decimal.new(150))
    iex> {set, null?} = Modulo.image(to_150, NumberSet.point(Decimal.new(7)))
    iex> {NumberSet.format(set), null?}
    {"[0..7)", false}
    iex> five = NumberSet.interval(Decimal.new(0), Decimal.new(5))
    iex> {set, null?} = Modulo.image(five, NumberSet.point(Decimal.new(7)))
    iex> {NumberSet.format(set), null?}
    {"[0..5]", false}
    iex> below = NumberSet.interval(Decimal.new(-5), Decimal.new(-1))
    iex> {set, null?} = Modulo.image(below, NumberSet.point(Decimal.new(7)))
    iex> {NumberSet.format(set), null?}
    {"[2..6]", false}

---

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