# Fallible operations policy
This document defines how `gemath` handles **operations that can fail** (or produce undefined/undesirable results) such as normalization, inversion, and division by zero.
## Goals
- Provide **predictable, non-panicking** behavior by default.
- Preserve fast, idiomatic operator behavior (`/`, `*`, etc.) where it is naturally IEEE-754.
- Provide **explicit checked alternatives** for users who want `Option`-based failure handling.
- Keep naming consistent across the crate.
## Policy
### Normalization
- **`normalize()`**:
- Must never panic.
- For a zero-length vector, returns the **zero vector** (`VecN::ZERO`).
- Rationale: keeps common call-sites simple and matches “normalize-or-zero” behavior.
- **`try_normalize()`**:
- Returns `Option<VecN>`.
- Returns `None` for a zero-length vector.
- Rationale: allows callers to treat “cannot normalize” as an explicit failure.
### Inversion
- **`inverse()`**:
- Returns `Option<Self>` for types where inversion can fail (e.g. matrices, quaternions).
- Returns `None` when the object is non-invertible (e.g. determinant is ~0).
- This function is the canonical API name (GL/graphics convention).
- **`try_inverse()`**:
- A naming-consistent alias for `inverse()` returning the same `Option`.
- Rationale: helps users discover fallible behavior via the `try_` prefix without breaking existing `inverse()` naming.
### Division by scalar (and similar “invalid input”)
- Operator division (e.g. `v / s`) follows IEEE-754 behavior:
- Division by zero yields `±inf`/`NaN` depending on inputs.
- Rationale: keep operators lightweight and unsurprising for numeric code.
- **Checked division helpers**:
- `checked_div_scalar(s)` returns `Option<Self>`.
- Returns `None` when the divisor is **zero** (including `-0.0`) or **non-finite** (`NaN`, `±inf`).
- Otherwise returns `Some(self / s)` (or the equivalent).
## Naming conventions summary
- Prefer `try_*` for fallible operations returning `Option<T>` / `Result<T, E>`.
- Use `checked_*` when the operation is a “guarded version” of an operator or a trivially-composable primitive (e.g. “checked divide”).