Getting Started

This guide targets Luna-Flow/floating 0.7.1. It shows how to select a package, install the module, construct values, choose an error model, and find the relevant reference material.

Choose A Numeric Domain

Choose the representation from the semantics your application needs, not from the spelling of its input.

Requirement	Package	Primary value	Result model
Arbitrary-precision dyadic values or IEEE binary interchange	bin_float	BinFloat	Value, or (value, BinaryFlags) with a context
IEEE arbitrary-precision decimal and decimal interchange	decimal	Decimal	Value, or (value, DecimalFlags) with a context
General Decimal Arithmetic status and traps	decimal_gda	Decimal	GdaOutcome[Decimal] with next context and raised flags
Certified real enclosure	ball_float	BallFloat / BallFloatDecorated	Enclosure, or (enclosure, BallFlags) with a context
IEEE decimal pipeline with accumulated flags	decimal_checked	DecimalChecked	Defined value plus latest and accumulated DecimalFlags
GDA pipeline with trap control	decimal_gda_checked	GdaDecimalChecked	Sticky context and GdaOutcome[Decimal]
Short-circuit binary or interval pipeline	bin_float_checked, ball_float_checked	*Result	Result[..., ArithmeticError] retained inside a wrapper
Representation-independent comparison	semantic	SemanticScalar / SemanticInterval	Exact projection, intentionally dropping metadata

Use numeric_expr and frontend/* only when building parsers or conformance tools. internal/*, consistency, doc_examples, and *_bench are maintainer infrastructure rather than application dependencies.

Install And Import

Add the current release:

moon add Luna-Flow/floating@0.7.1
moon add Luna-Flow/arithmetic

Import only the package boundaries used by the current MoonBit package:

import {
  "Luna-Flow/arithmetic"
  "Luna-Flow/floating/bin_float"
  "Luna-Flow/floating/decimal"
  "Luna-Flow/floating/decimal_gda"
  "Luna-Flow/floating/decimal_checked"
  "Luna-Flow/floating/decimal_gda_checked"
  "Luna-Flow/floating/ball_float"
}

Imports name packages, not source files. Files inside one moon.pkg are one compilation unit and do not create submodules.

Luna-Flow/arithmetic supplies the rounding-mode type used by explicit precision and conversion boundaries. It is unnecessary when every operation uses its default rounding mode, but importing it keeps those policies visible.

Construct Values

Binary coefficients are represented by BinCoeff; the sign is independent. Decimal parsing preserves the input quantum, including significant trailing zeros. Intervals are normally built from ordered binary endpoints.

let binary = @bin_float.BinFloat::make(
  @bin_float.BinCoeff::from_uint64(3UL),
  -1,
  53,
)
let decimal = @decimal.Decimal::from_string("12.3400").unwrap()
let interval = @ball_float.BallFloat::from_bounds(
  @bin_float.BinFloat::from_int(1),
  @bin_float.BinFloat::from_int(2),
)

binary is the exact dyadic value 3 × 2^-1; decimal retains exponent -4; and interval denotes every real value from 1 through 2. Call normalized() only when canonical cohort form is intended.

Select A Context Model

Use ordinary methods for unconstrained arbitrary-precision work. Use *_ctx when precision, exponent limits, rounding, tininess, clamp, or status flags are part of the result.

let binary_context = @bin_float.BinaryContext::binary64()
let (binary_sum, binary_flags) = binary.add_ctx(binary, binary_context)

let decimal_context = @decimal.DecimalContext::decimal64()
let (decimal_value, decimal_flags) =
  @decimal.Decimal::from_string_ctx("1.234567890123456789", decimal_context)

IEEE contexts are immutable inputs and flags are explicit outputs. Combine flags when a multi-step calculation needs accumulated status. GDA instead returns the updated sticky context as part of every GdaOutcome.

Select A Failure Model

The library intentionally exposes several non-equivalent failure channels:

• Option is used by simple constructors where invalid input has no additional diagnostic contract.
• Result[T, ArithmeticError] is used by checked scalar capabilities.
• BinaryFlags, DecimalFlags, and BallFlags report IEEE- or domain-style conditions without replacing the returned value.
• GdaOutcome[T] always retains the GDA-defined result, even when a configured trap fires.
• DecimalChecked accumulates IEEE flags without replacing defined NaN or infinity results; GdaDecimalChecked short-circuits traps while retaining their complete GdaOutcome.
• Entire, Empty, and NaI are interval-domain values, not generic errors.

Do not convert all of these to exceptions or one universal Result; doing so would erase observable numerical semantics.

Read Results Correctly

• Signed zero, infinity, quiet NaN, signaling NaN, and payloads may be observable on scalar representations.
• Ordinary scalar comparison is partial in the presence of NaN; total-order APIs are separate operations.
• BallFloat has containment and set relations, not a scalar total order.
• An interval result is correct when it encloses the mathematical result; tightness is a separate quality property.
• SemanticScalar compares mathematical meaning but intentionally loses precision, quantum, signed zero, NaN payloads, decorations, and flags.

Continue Reading

• Numeric semantics explains precision, rounding, status, special values, and interval enclosure.
• Architecture maps stable packages to parsing, execution, and verification infrastructure.
• Verification lists quick and authoritative gates and the exact scope of each conformance claim.
• Package api.md, tutorial.md, and design.md pages provide callable names, workflows, and implementation boundaries respectively.
• Core evidence is package-local: bin_float, decimal, decimal_gda, and ball_float.