bin_float_checked Tutorial

BinFloatResult keeps Result[BinFloat, ArithmeticError] inside a fluent pipeline. Use it when the first checked construction or arithmetic failure should stop every later step. It is not an IEEE flag accumulator.

Build A Pipeline

///|
test "checked binary pipeline" {
  let value =
    @bin_float_checked.BinFloatResult::from_int(81, precision=48)
    .sqrt()
    .div(@bin_float_checked.BinFloatResult::from_int(3, precision=48))
  inspect(value.result().unwrap().to_string(), content="3p0")
}

Keep the wrapper until the application boundary. Call result() once the caller is ready to handle ArithmeticError; use is_ok, is_err, or error() for branch decisions without extracting the value.

Understand First-Error Short-Circuiting

Every transformation on an error is the identity. In a binary method, the left error wins before the right is evaluated as a numerical operand. This makes the pipeline deterministic but intentionally does not collect multiple errors.

Use map for an infallible BinFloat -> BinFloat transformation. Use bind when the callback may return another BinFloatResult. flat_map is a deprecated alias; new code should use bind.

let normalized = checked.map(value => value.normalized())
let validated = normalized.bind(value => {
  if value.is_finite() {
    @bin_float_checked.BinFloatResult::ok(value)
  } else {
    @bin_float_checked.BinFloatResult::err(application_error)
  }
})

Contextual Operations Do Not Retain Flags

Methods such as add_ctx and exp_ctx retain certification/arithmetic failure in the wrapper, but BinFloatResult stores only the resulting value or error. If IEEE BinaryFlags are part of the contract, call the underlying BinFloat::*_ctx API and carry (value, flags) explicitly.

Recommended Practice

1. Use the wrapper for first-error pipelines, not for status accumulation.
2. Keep all operands wrapped when using binary combinators.
3. Extract once at an application boundary rather than repeatedly unwrapping.
4. Use raw bin_float context APIs when rounding flags or interchange bits are required.

See Design for the state model and bin_float tutorial for contexts and flags.