Crate use_real 

use-real

Small real-number primitives for direct, explicit Rust code.
Validated finite values, checked closed intervals, and tolerance-aware comparisons without a broader numeric framework.

Surface · When to use it · Installation · Examples · Validation · Scope

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.

Validated finite values Real turns finite-value checks into a named type rather than an ambient convention.

Closed intervals RealInterval provides checked bounds, midpoint, width, containment, and clamping.

Explicit tolerance approx_eq compares two finite values with a caller-supplied tolerance instead of a hidden epsilon policy.

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);

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)?);

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. Small real-number primitives for RustUse.

Re-exports

pub use error::RealError;

pub use real::Real;

pub use real::RealInterval;

pub use real::approx_eq;

Modules

error

prelude

real