ball_float_checked Tutorial

BallFloatResult keeps Result[BallFloat, ArithmeticError] inside a fluent pipeline. Use it when invalid bounds, non-finite exact construction, or a checked elementary proof failure should stop later interval operations.

Validate Construction Once

///|
test "checked interval construction" {
  let x = @ball_float_checked.BallFloatResult::from_bounds(
    @bin_float.BinFloat::from_int(1, precision=32),
    @bin_float.BinFloat::from_int(2, precision=32),
    precision=32,
  )
  let y = @ball_float_checked.BallFloatResult::from_int(3, precision=32)
  let result = (x + y).result().unwrap()
  inspect(result.is_empty(), content="false")
}

Later operations short-circuit the first error. Use map for an infallible interval transform and bind when a callback may construct another checked interval. flat_map is deprecated.

Distinguish Wide Success From Failure

Entire is a valid success because it still encloses the mathematical result. For example, division by an interval crossing zero may produce Entire rather than ArithmeticError. After extracting a successful interval, apply an application tightness policy with is_entire(), width(), or boundedness.

Relation observers such as contains, subset, and overlaps remain outside the wrapper. Extract the checked interval, then apply the observer; a Boolean relation has no meaningful first-error pipeline state.

Decorations And Flags Stay Explicit

BallFloatResult stores bare intervals only. It does not retain BallFloatDecorated state or BallFlags. Use raw ball_float APIs when decoration, NaI, inexact, overflow, or underflow is part of the result contract.

Recommended Practice

1. Use the wrapper to validate untrusted construction and retain first failure.
2. Treat Entire as successful enclosure, then evaluate tightness separately.
3. Extract once before set relations or decorated operations.
4. Use raw try_*_interval when structured certification detail must be handled directly.

See Design and the raw ball_float tutorial.