use-real

use-real provides a deliberately small real-number surface. The crate prefers explicit wrappers over loose f64 conventions: Real keeps finite-value validation attached to the value itself, RealInterval encodes closed intervals with checked ordering, and tolerance-aware comparisons require a caller-provided non-negative tolerance. use-real now composes the generic interval ownership in use-interval while keeping RealInterval focused on finite, ordered, closed bounds over validated Real values.

What this crate provides

Area	Root exports	Best fit
Finite values	`Real`, `RealError`	Explicit finite-value validation instead of raw `f64` assumptions
Closed intervals	`RealInterval`	Range checks, clamping, width, and midpoint helpers
Tolerance checks	`approx_eq`	Approximate comparisons where tolerance must stay visible

If you need to...	Start here
Validate one finite floating-point value	`Real::try_new(...)`
Model a closed interval with checked ordering	`RealInterval::try_new(...)`
Clamp or test membership in an interval	`RealInterval`
Compare values with an explicit tolerance	`approx_eq(...)`

When to use it directly

Choose use-real directly when finite-value validation and real-number helpers are the only math surface you need, or when you want floating-point assumptions to stay local instead of spreading through a broader crate.

Scenario	Use `use-real` directly?	Why
You need finite-value wrappers and checked intervals	Yes	The crate stays narrow and explicit
You want tolerance-aware comparisons with caller-owned policy	Yes	The tolerance is required at the call site
You need open, half-open, or unbounded interval semantics	Usually no	Those belong in `use-interval`
You need geometry-specific tolerance rules	Usually no	Those stay better attached to geometry types
You need complex analysis or calculus helpers	No	Those belong in adjacent focused crates

Installation

[dependencies]
use-real = "0.0.5"

Quick examples

Work with finite values and checked intervals

use use_real::{Real, RealInterval};

let value = Real::try_new(-3.5)?;
let interval = RealInterval::try_new(-2.0, 6.0)?;

assert_eq!(value.abs(), Real::try_new(3.5)?);
assert!(interval.contains(Real::try_new(1.5)?));
assert_eq!(interval.clamp(value.abs()), Real::try_new(3.5)?);
assert!((interval.midpoint().value() - 2.0).abs() < 1.0e-12);
# Ok::<(), use_real::RealError>(())

Keep tolerance choices explicit

use use_real::{Real, approx_eq};

let left = Real::try_new(1.0)?;
let right = Real::try_new(1.0 + 1.0e-10)?;

assert!(approx_eq(left, right, 1.0e-9)?);
assert!(!approx_eq(left, right, 1.0e-12)?);
# Ok::<(), use_real::RealError>(())

Validation model

Use try_new when values, bounds, or tolerances may come from user input, files, or network payloads. Use infallible constructors like Real::new(...) and RealInterval::new(...) only when finiteness and ordering are already guaranteed by the surrounding code.

When you need to hand a checked real interval to adjacent crates, use RealInterval::interval() to recover the underlying closed use_interval::Interval<Real>.

[!IMPORTANT] This crate does not define a global epsilon policy. Approximate comparison requires a caller-provided non-negative tolerance every time.

Scope

Small real-number APIs are preferred over broad trait-heavy abstractions.
The initial concrete surface focuses on finite-value validation, closed intervals built on use-interval, and explicit tolerance checks.
Symbolic algebra, arbitrary precision, and domain-specific tolerance policies are intentionally out of scope for this first slice.
Geometry-specific and calculus-specific interpretation rules belong in adjacent focused crates.

Status

use-real is a concrete pre-1.0 crate in the RustUse docs surface. The API remains intentionally small while the broader real-number roadmap is still being designed.

use-real 0.0.6