Skip to content

Conversation

@AshharAhmadKhan
Copy link

Summary

This PR implements full IEEE 754 half-precision (binary16) float16 support for the Rust runtime as requested in issue #3207.

Implementation Details

Core Type (fory-core/src/float16.rs)

  • New type: #[repr(transparent)] pub struct float16(u16) - 614 lines
  • IEEE 754 compliant f32 ↔ float16 conversions with proper rounding
  • Round-to-nearest, ties-to-even rounding mode
  • Complete special value handling: NaN (payload preservation), ±Inf, ±0, subnormals
  • Overflow/underflow: Overflow → Infinity, Underflow → Subnormal/Zero
  • Policy A comparison: Bitwise Eq/Hash (usable in HashMap) + separate IEEE helpers
  • Arithmetic: Implemented via f32 round-back
  • Classification methods: is_nan, is_infinite, is_finite, is_normal, is_subnormal, is_zero, is_sign_negative
  • Operator traits: Add, Sub, Mul, Div, Neg, PartialOrd
  • Display/Debug: Format via to_f32()

Integration

  • Buffer methods (buffer.rs): write_f16() and read_f16() using little-endian
  • Serializer (serializer/number.rs): Full Serializer trait + ForyDefault implementation
  • Type system (types.rs): Added to BASIC_TYPES, PRIMITIVE_TYPES, PRIMITIVE_ARRAY_TYPES, BASIC_TYPE_NAMES, PRIMITIVE_ARRAY_TYPE_MAP, is_primitive_type_id()
  • Module export (lib.rs): Public module with Float16 alias

Testing

  • 11 comprehensive unit tests covering all edge cases (ALL PASSING)
  • Full test suite (135 tests, ALL PASSING)
  • Test coverage includes:
    • Special values (±0, ±Inf, NaN)
    • Boundary values (max 65504, min normal 2^-14, min subnormal 2^-24)
    • Overflow/underflow behavior
    • Round-to-nearest ties-to-even
    • Arithmetic operations
    • Classification methods
    • Comparison semantics (bitwise & IEEE)

Why?

Support for half-precision floats is essential for:

  • Reduced payload size and memory footprint
  • ML/graphics interoperability where float16 is common
  • Cross-language compatibility with other Fory implementations

What does this PR do?

Adds production-ready IEEE 754 binary16 support to Rust runtime matching the exact specification in #3207, including:

  • Strong type safety (no raw u16 in public API)
  • Stable Rust only (no nightly features)
  • Zero external dependencies
  • Complete IEEE 754 compliance
  • Comprehensive test coverage

Related issues

Closes #3207

Does this PR introduce any user-facing change?

  • Does this PR introduce any public API change?

    • Yes: Adds new public type float16 (exported as Float16)
    • New methods: from_bits, to_bits, from_f32, to_f32, classification methods, arithmetic methods
    • New constant values: ZERO, NEG_ZERO, INFINITY, NEG_INFINITY, NAN, MAX, MIN_POSITIVE, MIN_POSITIVE_SUBNORMAL
  • Does this PR introduce any binary protocol compatibility change?

    • Yes: Adds FLOAT16 (TypeId = 16) and FLOAT16_ARRAY (TypeId = 50) to wire format
    • Encoded as 2 bytes (little-endian u16 representing IEEE 754 binary16 bits)
    • Backward compatible: Existing code unaffected, new type opt-in only

Benchmark

Not applicable - this PR adds new functionality without modifying existing code paths. No performance impact on existing f32/f64 usage.

- Add float16 type as transparent wrapper around u16
- Implement IEEE 754 compliant f32<->float16 conversions
  - Round-to-nearest, ties-to-even rounding
  - Proper handling of NaN, Inf, ±0, subnormals
  - Overflow to infinity, underflow to subnormal/zero
- Add buffer read/write methods (write_f16, read_f16)
- Implement Serializer trait for float16
- Add float16 to all relevant type arrays and functions
- Implement arithmetic via f32 round-back
- Use Policy A (bitwise Eq/Hash, separate IEEE helpers)
- Add comprehensive unit tests (11 tests, all passing)

Resolves apache#3207
- Add #[allow(non_camel_case_types)] to float16 struct (per issue requirements)
- Add #[allow(dead_code)] to EXP_BIAS constant
- Add Apache license header to number.rs (required by CI)
- Suppress clippy::should_implement_trait warnings for explicit arithmetic methods
  (methods required by issue spec alongside trait implementations)
- Add #[allow(clippy::should_implement_trait)] to all arithmetic methods
- Restore missing float16 import in number.rs
- Fix formatting
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Rust] add float16 to rust

1 participant