# Numbers, ranges, and math

> Use numeric helpers, iteration, conversions, rounding, and floating-point checks.

Canonical: https://alice-lang.org/documentation/library/numbers/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

## Basic numeric operations

```alice
puts 42.gcd(30)
puts 42.to_s(16)
puts 3.14159.round(2)
puts 15.clamp(0, 10)
puts (1..5).sum
```

Expected output:

```text
6
2a
3.14
10
15
```

[Edit and run in the Alice playground](https://playground.alice-lang.org/#code=u.cHV0cyA0Mi5nY2QoMzApCnB1dHMgNDIudG9fcygxNikKcHV0cyAzLjE0MTU5LnJvdW5kKDIpCnB1dHMgMTUuY2xhbXAoMCwgMTApCnB1dHMgKDEuLjUpLnN1bQ)

`gcd` finds a greatest common divisor, `to_s(16)` formats a base-16 number, and `clamp` bounds a value. Choose numeric types deliberately: integer division and conversions can discard information.

## Helpers by purpose

| Methods                                            | Purpose                       |
| -------------------------------------------------- | ----------------------------- |
| `abs`, `clamp(lo, hi)`, `between?(lo, hi)`         | Magnitude and bounds          |
| `even?`, `odd?`, `zero?`, `positive?`, `negative?` | Predicates                    |
| `gcd`, `lcm`, `digits`, `divmod`                   | Integer arithmetic            |
| `round(n)`, `floor(n)`, `ceil(n)`, `truncate`      | Rounding and truncation       |
| `sqrt`, `cbrt`, `log`, `log2`, `log10`             | Elementary math               |
| `nan?`, `infinite?`                                | Special floating-point values |
| `to_i`, `to_f`, `to_s(base)`                       | Conversion and representation |

.NET's `Math` and `MathF` provide additional operations, such as `Math.Sin(x)` and `Math.Sqrt(x)`. Their names and numeric overloads follow .NET.

## Numeric iteration

```alice
3.times { |i| puts i }       # 0, 1, 2
2.upto(4) { |i| puts i }     # 2, 3, 4
4.downto(2) { |i| puts i }   # 4, 3, 2
```

`step(limit, by)` advances a numeric value by a stride. Ranges also provide `step`, `size`, `include?`, `cover?`, `to_a`, `sum`, and the enumerable helpers. Use a positive, meaningful stride and avoid constructing a huge array when only traversal is needed.

## Floating-point results

`Float32` and `Float64` are finite-precision binary numbers. Decimal values such as `0.1` do not generally have an exact binary representation. Test approximate results with a tolerance suited to the computation.

Alice can fuse multiply-add expressions, which rounds once, and parallel sums can change the addition order. `@[StrictMath]` prevents contraction in a method but does not by itself force every reduction to use serial order. See [performance](https://alice-lang.org/documentation/guides/performance.md#floating-point-results).

## Random values

`rand` is available as a prelude helper. .NET's `Random` gives explicit control over a generator and seed. Use a fixed seed in tests that depend on random choices, and do not use ordinary pseudo-random values as cryptographic secrets.

## Continue reading

- Previous: [Strings and formatting](https://alice-lang.org/documentation/library/strings.md)
- Next: [Regular expressions](https://alice-lang.org/documentation/library/regex.md)