Skip to content

CEP-0013: Explicit Numeric Arithmetic Modes

Draft

Draft proposal for wrapping, checked-overflow, and saturating arithmetic APIs or operators. V1 accepts the base arithmetic operator contracts; explicit arithmetic modes remain deferred.

Summary

Catalyst should eventually add explicit arithmetic modes for operations where overflow behavior matters: wrapping, checked overflow, and saturating arithmetic.

V1 keeps base arithmetic operations small and explicit. Potentially lossy or representation-changing conversions use named methods, and overflow-mode APIs are deferred.

Example

Possible future shape:

const wrapped = counter.wrapping_add(1)
const saturated = gain.saturating_mul(2)
const checked = bytes.checked_add(header_len)

The proposal must decide whether these are primitive methods, extension methods, free functions, operators, or contract-backed APIs.

Alternative: New Operators

An alternative to the method-based API is a small family of dedicated arithmetic-mode operators. This would keep call sites compact while making the selected overflow mode visible in the operator spelling:

const wrapped = counter +% 1
const saturated = gain *| 2
const checked = bytes +? header_len

The exact spellings above are illustrative. A future accepted design would need to choose operator tokens for wrapping, saturating, and checked-overflow arithmetic, decide which primitive operations receive mode-specific forms, and define the result shape for checked operators.

Operator spellings would also need parser and readability review. They should not create ambiguous mixes with existing arithmetic, range, equality, ordering, boolean, error-return, or assignment operators, and they should remain separate from general user-defined operator overloading.

Motivation

Numeric APIs are sharp tools. DSP, systems code, and codecs often need precise overflow behavior, but implicit mode changes make code hard to audit.

Explicit APIs or operators let programmers choose arithmetic behavior at the call site and give diagnostics a clear vocabulary.

Proposed Direction

The future design should cover:

  • wrapping arithmetic APIs or operators;
  • checked-overflow arithmetic APIs;
  • saturating arithmetic APIs;
  • whether these are methods, free functions, operators, or contract-backed APIs;
  • interaction with debug/release safety modes;
  • lowering to target intrinsics when available;
  • naming conventions and diagnostics for mixed signedness or width.

V1 Compatibility

V1 remains unchanged. Deferred numeric arithmetic modes are unavailable until their source spelling and safety-mode behavior are accepted.