# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [0.3.2] - 2026-01-12
### Changed
- **BREAKING: Box all `ErrorsValidationRawComplex` fields for consistency**: All error fields now use
`Box<ErrorsValidationRawReal>` instead of direct values
- `InvalidImaginaryPart.source`: `ErrorsValidationRawReal` → `Box<ErrorsValidationRawReal>`
- `InvalidBothParts.real_error`: `ErrorsValidationRawReal` → `Box<ErrorsValidationRawReal>`
- `InvalidBothParts.imag_error`: `ErrorsValidationRawReal` → `Box<ErrorsValidationRawReal>`
- Benefits: Consistent API, smaller `Result<T, E>` size, follows Rust best practices
- Added `#![feature(box_patterns)]` to enable box pattern matching
- **Migration**: Pattern matches must now use `box` patterns, e.g.:
```rust
ErrorsValidationRawComplex::InvalidImaginaryPart {
source: box ErrorsValidationRawReal::IsNaN { .. }
}
```
### Added
- **Tests for `new_unchecked()`**: Comprehensive test coverage for `RealValidated::new_unchecked()`
and `ComplexValidated::new_unchecked()` in native64 backend
- Valid finite values (positive, negative, zero, edge cases)
- Debug-mode panic tests for invalid inputs (NaN, ±infinity)
### Fixed
- **Removed invalid rug test**: Removed `arg_behavior_release()` test that incorrectly attempted
to create `StrictFinite` types with infinity values (rejected by design in `try_new()`)
### CI/CD
- Configured GitLab CI to use local Gentoo runner (`tags: [gentoo]`)
- Replaced `cargo-tarpaulin` with `cargo-llvm-cov` for code coverage
- Modernized CI configuration: migrated from `only:` to `rules:` syntax
- Auto-start `pages` job (removed `when: manual`)
## [0.3.1] - 2026-01-09
### Changed
- **Removed `associated_const_equality` nightly feature requirement**: The feature is no longer needed
for compilation after recent Rust nightly changes
- The library now only requires two nightly features: `trait_alias` and `error_generic_member_access`
- Updated documentation in `lib.rs`, `README.md`, and `.github/copilot-instructions.md`
## [0.3.0] - 2025-12-12
### Added
- **Property-based testing with proptest**: Comprehensive test suite with 49 property-based tests
- Arithmetic properties: commutativity, identity, inverse operations
- Square root: `sqrt(x)² = x`, `sqrt(ab) = sqrt(a)·sqrt(b)`
- Exponential/Logarithm: inverse relationship, `exp(a+b) = exp(a)·exp(b)`, `ln(ab) = ln(a)+ln(b)`
- Trigonometry: `sin²+cos² = 1`, odd/even symmetry, `tan = sin/cos`
- Inverse trigonometry: `sin(asin(x)) = x`, `cos(acos(x)) = x`, `tan(atan(x)) = x`
- Hyperbolic: `cosh²-sinh² = 1`, symmetry properties, `tanh = sinh/cosh`
- Power: `x¹ = x`, `x⁰ = 1`, `x² = x·x`, `x⁻¹ = 1/x`, `(xᵃ)ᵇ = xᵃᵇ`
- Reciprocal: `1/(1/x) = x`, `x·(1/x) = 1`
- Complex numbers: `|z·z̄| = |z|²`, `conj(conj(z)) = z`, `|z| ≥ 0`
- Ordering: transitivity, antisymmetry, totality
- Absolute value: `|x| ≥ 0`, `|x| = |-x|`, `|xy| = |x|·|y|`
- Serialization: JSON and f64 conversion roundtrips
- Custom strategies for generating valid f64 values (finite, non-subnormal)
- 500 random cases per test (configurable via `ProptestConfig`)
- New dev-dependency: `proptest = "1.5"`
- **`Ord` trait implementation for `RealValidated<K>`**: When the validation policy implements
`GuaranteesFiniteRealValues`, the validated real type now implements `Ord`
- Enables use in `BTreeMap`, `BTreeSet`, and sorted collections
- Total ordering guaranteed because NaN values are excluded by the policy
- `cmp()` delegates to `partial_cmp().unwrap()` since all values are comparable
- **`TryFrom<f64>` trait implementation for `RealValidated`**: Standard library trait for fallible conversion
- Complements existing `try_from_f64()` method
- Enables use with `?` operator and generic conversion contexts
- Error type is the kernel's validation error type
- **Complete documentation coverage**: Added documentation for 22 previously undocumented public items
- Enables `-D missing_docs` lint to pass
- All public traits, methods, associated types/constants, and struct fields now documented
- Files updated: `lib.rs`, `neumaier_sum.rs`, `errors.rs`, `validation.rs`, `complex.rs`,
`hyperbolic.rs`, `logarithm.rs`, `pow.rs`, `real.rs`, `trigonometric.rs`
- **Organized raw trait hierarchy**: New traits for mathematical function categories
- `RawScalarTrigonometric`: Groups trigonometric functions (`unchecked_sin`, `unchecked_cos`, etc.)
- `RawScalarHyperbolic`: Groups hyperbolic functions (`unchecked_sinh`, `unchecked_cosh`, etc.)
- `RawScalarPow`: Groups power functions (`unchecked_pow`, `unchecked_powi`, etc.)
- `RawScalarTrait` now extends `ScalarCore` for cleaner trait bounds
- **Validated Scalar Wrappers Module (`scalars`)**: New module providing constrained numeric types with compile-time and runtime validation
- `AbsoluteTolerance<T>`: Non-negative tolerance value (≥ 0) for absolute error bounds
- `RelativeTolerance<T>`: Non-negative relative tolerance with `absolute_tolerance(reference)` conversion method
- `PositiveRealScalar<T>`: Strictly positive value (> 0), rejects zero
- `NonNegativeRealScalar<T>`: Non-negative value (≥ 0), accepts zero
- All types generic over `RealScalar` trait (works with `RealNative64StrictFinite`, `RealRugStrictFinite<P>`, etc.)
- Implements `TryNew`, `New`, `IntoInner`, `AsRef`, `Clone`, `PartialEq`, `PartialOrd`, `Display`, `Debug`, `Serialize`, `Deserialize`
- Error types: `ErrorsTolerance<T>`, `ErrorsPositiveRealScalar<T>`, `ErrorsNonNegativeRealScalar<T>`
- Uses `#[repr(transparent)]` for zero-cost abstraction
- Supports backtrace capture via `backtrace` feature flag
- 51 comprehensive unit tests covering all edge cases
- **"Common Pitfalls" documentation section**: Added comprehensive section documenting 5 common mistakes:
- Forgetting `Clone` for reused values (move semantics)
- Using `from_f64` with untrusted input (panics vs error handling)
- Ignoring precision requirements with rug backend
- Validation policy mismatch (StrictFinite vs StrictFiniteInDebug)
- Ignoring `#[must_use]` warnings on `Result` values
- Added to both `README.md` and `lib.rs` (docs.rs)
- **Policy comparison table**: Added detailed comparison table for validation policies:
- Compares `RealNative64StrictFinite`, `RealNative64StrictFiniteInDebug`, and `RealRugStrictFinite<P>`
- Shows Debug vs Release build behavior
- Documents use cases and `Eq`/`Hash` implications
- Added to README.md (Architecture section) and lib.rs documentation
- **`#[must_use]` attributes on fallible methods**: All `try_*` methods in trait definitions now have `#[must_use]` attribute
- Compiler will warn if a `Result` from these methods is ignored
- Affected traits: `Sqrt`, `Exp`, `Reciprocal`, `Abs`, `Arg`, `Pow`, `Sin`, `Cos`, `Tan`, `ASin`, `ACos`, `ATan`, `ATan2`, `SinH`, `CosH`, `TanH`, `ASinH`, `ACosH`, `ATanH`, `Ln`, `Log10`, `Log2`, `RealScalar`, `ComplexScalarConstructors`
- Improves API safety by preventing silent error ignoring
- **New test cases** in `tests/readme_examples.rs`:
- `test_error_handling_propagation`: Tests error propagation pattern with `?` operator
- `test_error_handling_match_variants`: Tests matching on specific `SqrtRealErrors` variants
- **BREAKING:** Removed `New` trait implementation for validated types
- `RealValidated::new()` and `ComplexValidated::new()` are now **deprecated** (will be removed in 1.0)
- The old `New::new()` method validated only in debug builds, creating **unsafe behavior in release mode**
- **Migration options:**
1. **Recommended**: Use `try_new().unwrap()` for explicit error handling
2. **For constants**: Use `unsafe { new_unchecked() }` with compile-time known values
3. **Temporary**: Keep using deprecated `new()` (shows compiler warning)
- **Rationale**: Type-level guarantees must hold in both debug and release builds
- See migration guide in function documentation
- **Documentation Improvements**:
- README.md now lists all 4 documentation resources (API docs, Architecture, Cookbook, Migration)
- lib.rs Getting Started section updated with prominent macro usage examples
- RealScalar and ComplexScalar trait docs include macro cross-references
- Enhanced inline documentation for existing macro system in `validated.rs`
- Added comprehensive comments explaining the 4-layer validated type architecture
- Improved code navigation with better section markers
- Validated macros module now public and documented with usage examples
- **Literal macros** (`real!()` and `complex!()`): Ergonomic constructors for creating validated numeric literals
- `real!(3.14)` creates `RealNative64StrictFinite` values with concise syntax
- `complex!(1.0, 2.0)` creates `ComplexNative64StrictFinite` values from real and imaginary parts
- Full doctest coverage and comprehensive unit tests
- Panics on invalid inputs (NaN, infinity, subnormal) with clear error messages
- **Public validated type builder macros**: Composable macro helpers for creating custom validated types
- `impl_validated_binary_op!`: Low-level macro for single arithmetic operations
- `impl_arithmetic_for_validated!`: Generates all standard arithmetic ops (Add, Sub, Mul, Div)
- `impl_assign_ops_for_validated!`: Generates all assignment ops (AddAssign, SubAssign, etc.)
- Enables users to create custom validated types with their own policies
- Each macro fully self-contained (no dependencies on internal macros)
- Comprehensive documentation with 5 working doctests demonstrating usage patterns
- **Developer infrastructure for future enhancements**:
- Added `src/functions/function_docs.rs` with centralized documentation constants
- Added `templates/function_trait_template.rs` as standardized template for new functions
- Reduces development time for adding mathematical functions
- **`new_unchecked()` unsafe method** for performance-critical code
- Validates in debug builds, zero overhead in release
- Use only when value validity is guaranteed by caller
- Comprehensive safety documentation with examples
- **Documentation Suite** (Phase 1 completion):
- `docs/COOKBOOK.md` (489 lines): Practical patterns and examples for common use cases
- 10 detailed patterns with working examples (validated input, generic algorithms, high-precision constants, etc.)
- Performance tips and optimization guidelines
- Cross-references to Architecture and Migration guides
- `docs/MIGRATION.md` (556 lines): Complete guide for transitioning from raw primitives (`f64`, `Complex<f64>`)
- Side-by-side comparison of patterns (before/after)
- 3-phase migration strategy (boundaries → core algorithms → internal code)
- 5 common pitfalls with solutions
- Performance benchmarking examples
- Migration checklist
- `docs/TECHNICAL_REVIEW.md` (1003 lines): Expert analysis of library architecture and quality
- Overall rating: 4.36/5 stars
- Architecture analysis (5 excellences, 3 criticalities)
- Implementation review (Neumaier sum, MPFR optimizations, IEEE 754 handling)
- Documentation criticalities and improvement roadmap
- Cross-references added to README.md and lib.rs documentation
- **Modularized Macro System** (Macro refactoring completion):
- `src/kernels/validated_macros_modular.rs`: Refactored version of monolithic `define_validated_struct!` macro
- 7 composable macros: `define_validated_struct_type!`, `impl_validated_core_traits!`, `impl_validated_constructors!`, `impl_validated_numeric_traits!`, `impl_validated_arithmetic!`, `impl_validated_special_ops!`, `impl_validated_sum!`
- `define_validated_struct_modular!` convenience macro for backward compatibility
- ~15% compile-time improvement potential for custom types
- Enables opt-out of specific trait implementations
- Comprehensive documentation with architecture rationale and usage examples
- Better debugging: pinpoint exact macro causing compilation errors
- **Enhanced Cross-References**:
- Added `complex!()` macro reference in `ComplexScalar` trait documentation
- Linked `real!()` and `complex!()` macros in "Quick Start" sections
- Added references to COOKBOOK.md and MIGRATION.md in main documentation
### Changed
- **BREAKING: Major project restructuring to modular architecture**:
- **New `backends/` module**: Backend implementations organized by numeric type
- `backends/native64/`: Native f64 and Complex<f64> implementations
- `raw.rs`: Raw trait implementations for f64/Complex<f64>
- `validated.rs`: Validated type aliases and kernel configurations
- `backends/rug/`: Arbitrary-precision implementations (feature-gated)
- `raw.rs`: Raw trait implementations for rug::Float/Complex
- `validated.rs`: Validated type aliases and kernel configurations
- **New `core/` module**: Core abstractions and traits
- `core/traits/raw.rs`: Layer 1 raw trait contracts (`RawScalarTrait`, `RawRealTrait`, `RawComplexTrait`)
- `core/traits/validation.rs`: Validation marker traits and `FpChecks`
- `core/policies.rs`: Validation policies (`StrictFinitePolicy`, `DebugValidationPolicy`)
- `core/errors.rs`: All error types consolidated
- **Consolidated `algorithms/` module**: Numerical algorithms
- `neumaier_sum.rs`: Neumaier compensated summation algorithm
- **Migration**: Import paths have changed:
- `num_valid::backends::native64::validated::RealNative64StrictFinite` (or use re-exports)
- `num_valid::core::policies::StrictFinitePolicy`
- `num_valid::core::traits::raw::RawRealTrait`
- **Rationale**: Clearer separation of concerns, easier navigation, better extensibility
- **Removed deprecated `validated_macros` module**: The file `src/kernels/validated_macros.rs` has been deleted
- All macro functionality now in `validated_macros_modular.rs`
- Legacy macros were not validating results properly
- **BREAKING: `approx::AbsDiffEq` Epsilon type changed to `AbsoluteTolerance<Self>`**:
- `RealValidated<Native64*>`: `type Epsilon` changed from `f64` to `AbsoluteTolerance<Self>`
- `ComplexValidated<Native64*>`: `type Epsilon` changed from `f64` to `AbsoluteTolerance<RealValidated<K>>`
- `RealRugStrictFinite<P>`: `type Epsilon` changed from `Self` to `AbsoluteTolerance<Self>`
- `ComplexRugStrictFinite<P>`: `type Epsilon` changed from `RealRugStrictFinite<P>` to `AbsoluteTolerance<RealRugStrictFinite<P>>`
- **Migration**: Replace `epsilon = 1e-10` with `epsilon = AbsoluteTolerance::try_new(RealNative64StrictFinite::from_f64(1e-10)).unwrap()`
- **Rationale**: Enforces type-safe tolerance values that are guaranteed to be non-negative at the type level
- Affects `abs_diff_eq!`, `relative_eq!`, and `ulps_eq!` macros from the `approx` crate
- **Replaced monolithic macros with modular macros in `validated.rs`**:
- Removed the ~400 line `define_validated_struct!` macro and helper macros from `validated.rs`
- Now uses the modular macro system from `validated_macros_modular.rs`:
- `define_validated_struct_type!` - Struct definition with derives
- `impl_validated_core_traits!` - IntoInner, Clone, PartialEq
- `impl_validated_constructors!` - TryNewValidated, TryNew, new (deprecated), new_unchecked
- `impl_validated_numeric_traits!` - Zero, One, FpChecks
- `impl_validated_arithmetic!` - Add, Sub, Mul, Div (all variants)
- `impl_validated_special_ops!` - Neg, NegAssign, MulAddRef
- `impl_validated_sum!` - Sum with Neumaier compensated algorithm
- Fixed arithmetic macros to use fully qualified `std::ops::` paths for trait names
- This reduces code duplication and improves maintainability
- No behavioral changes - all tests continue to pass
- **Modular macros now match production behavior**: Updated `impl_validated_constructors!` macro in `validated_macros_modular.rs`
- Replaced `try_create::New` trait implementation with deprecated `new()` method (matches `validated.rs`)
- Added `new_unchecked()` unsafe method for zero-cost construction in release builds
- Both constructors now have identical behavior to the monolithic macro in `validated.rs`
- This enables future refactoring to replace monolithic macros with modular versions
- **Documentation improvements**:
- Updated `copilot-instructions.md` with clearer Naming Conventions table format
- Added Error Handling Patterns section with practical code examples
- Fixed incorrect error type name: `ErrorsTryFromf64::IncorrectPrecision` → `NonRepresentableExactly`
- Added detail about `ErrorsValidationRawReal::PrecisionMismatch` for rug backend
- README.md: Fixed section numbering (was 2,4,5,6,7 → now 1,2,3,4,5,6)
- README.md: Added new "6. Error Handling" section with two patterns (propagation with `?` and match on variants)
- README.md: Enhanced math library description to include `exp_m1` and `ln_1p`
### Deprecated
- **`validated_macros` module**: The entire `kernels::validated_macros` module is now deprecated
- Will be removed in version 1.0
- These macros (`impl_validated_binary_op!`, `impl_arithmetic_for_validated!`, `impl_assign_ops_for_validated!`)
do NOT validate operation results, which can lead to NaN/infinity propagation
- Use macros from `validated_macros_modular` instead, which properly validate results via `try_new_validated()`
- Migration table provided in module documentation
### Removed
- **BREAKING: Removed `New` trait implementation for `PositiveRealScalar` and `NonNegativeRealScalar`**:
- Only `TryNew` trait is now available for constructing these types
- **Migration**: Replace `PositiveRealScalar::new(value)` with `PositiveRealScalar::try_new(value).unwrap()`
- **Rationale**: `TryNew` provides explicit error handling, preventing silent panics on invalid input
### Fixed
- **Modular Macro System**:
- Fixed all 277 compilation errors in `src/kernels/validated_macros_modular.rs`
- Added missing helper macros (`__impl_validated_arithmetic_op!`, `__impl_validated_arithmetic_op_assign!`, `__impl_validated_arithmetic_op_and_op_assign!`) with proper `#[macro_export]` attributes
- Corrected all `$crate::` path references for proper macro hygiene
- Fixed trait import paths:
- `ValidationPolicy` → `try_create::ValidationPolicy` (external crate)
- `NegAssign` → `$crate::functions::NegAssign` (functions module)
- `NeumaierAddable` → `$crate::neumaier_compensated_sum::NeumaierAddable` (neumaier module)
- Removed clippy warning (empty line after doc comment)
- **Result**: Zero compilation errors, fully functional modular macro system
- **Benefits**:
- ~15% compile-time improvement potential for custom validated types
- Greatly improved debuggability (pinpoint exact macro causing errors)
- Enables partial trait implementation (users can opt-out of specific traits)
- 7 composable macros vs 1 monolithic 239-line macro
- **Status**: Production-ready, backward compatible with existing code via `define_validated_struct_modular!` convenience wrapper
- **Documentation Link Error**: Fixed unresolved doclink in `src/macros.rs`
- Changed `RealNative64StrictFinite::try_from_f64` to `RealScalar::try_from_f64` (trait method, not type alias)
- Documentation now compiles correctly without `rug` feature enabled
- Resolves `cargo doc --no-deps` compilation error
- **Documentation Consistency (README ↔ lib.rs)**:
- Added macro examples to `RealScalar::try_from_f64()` documentation
- Added comprehensive `ComplexScalar` trait documentation with `complex!()` macro examples
- Cross-referenced `real!()` and `complex!()` macros throughout trait documentation
- Ensures consistent presentation of literal macros across all documentation entry points
- Users now see the same recommended approach (macros first) in README, lib.rs, and trait docs
- **Documentation Consistency (README ↔ ARCHITECTURE.md)**:
- Enhanced README Contributing section with direct links to key ARCHITECTURE.md sections
- Added Quick Reference table at top of ARCHITECTURE.md for fast navigation
- Added "See Also" cross-references in ARCHITECTURE.md chapters
- Linked common contribution patterns to specific documentation sections
- Improved discoverability: contributors can quickly find relevant guides for their tasks
- **Precision Validation for rug Backend** (`try_from_f64`):
- Added minimum precision requirement of 53 bits (f64 precision) for conversions to `rug::Float`
- Conversions with target precision < 53 now properly return `ErrorsTryFromf64::NonRepresentableExactly`
- All f64 values are exactly representable at precision ≥ 53 (no silent precision loss)
- Updated tests to reflect correct behavior (precision >= 53 required)
- **Breaking change**: `RealRugStrictFinite::<P>::try_from_f64()` where P < 53 now rejects all values
- **Rationale**: Ensures no information is lost when converting from f64 to rug backend
- **Migration**: Use precision ≥ 53 for rug types, or construct directly from strings for arbitrary precision
### Improved
- **Division by Zero Documentation** (Criticità P1.2):
- Improved panic message for division operations: now explicitly mentions "likely division by zero producing infinity"
- Added comprehensive inline documentation in `src/kernels/validated.rs` explaining IEEE 754 behavior
- Documents that division by zero produces `±Inf` (IEEE 754 standard), which is rejected by `StrictFinitePolicy`
- Provides clear guidance to use `Reciprocal::try_reciprocal()` trait for explicit error handling of division by zero
- Enhanced documentation of `Reciprocal` trait implementation with practical examples
- **Result**: Zero breaking changes, clearer error messages, better developer experience
- **Macro System Simplification**:
- Removed unused `pre_check` parameter from all arithmetic operation helper macros
- Affected macros: `__impl_validated_arithmetic_op!`, `__impl_validated_arithmetic_op_assign!`, `__impl_validated_arithmetic_op_and_op_assign!`
- Applied to both `src/kernels/validated.rs` (monolithic macros) and `src/kernels/validated_macros_modular.rs` (modular macros)
- **Rationale**: The parameter was never used (always passed as empty `{}`), originally intended for debug assertions that would violate Layer 1 architectural contracts
- **Benefits**:
- Simpler macro signatures (one less parameter)
- Cleaner generated code (no dead `let _ = (&rhs);` statements)
- Better maintainability (removed 18+ lines of unused parameter declarations)
- Zero runtime overhead guaranteed (no dead code to eliminate)
- **Result**: Cleaner codebase, identical functionality, all 738 tests passing
## [0.2.5] - 2025-12-03
### Added
- **Comprehensive Architecture Guide**:
- Added `docs/ARCHITECTURE.md` - a complete 25+ page architectural deep dive (~8000 words)
- Covers all 4 layers of the design with detailed explanations, examples, and rationale
- Includes step-by-step guides for adding backends and mathematical functions
- Documents error handling architecture, performance considerations, and design patterns
- Provides checklists, templates, and best practices for contributors
- Integrated references in README.md, API documentation (lib.rs), and GitHub Copilot instructions
- **Panicking Constructor `from_f64()`**:
- Added `RealScalar::from_f64()` method for convenient construction from f64 constants
- Complements existing `try_from_f64()` for cases where values are known to be valid
- Cleaner syntax: `RealNative64StrictFinite::from_f64(PI)` vs `try_from_f64(PI).unwrap()`
- Particularly useful for mathematical constants and literal values in tests
- Implemented with comprehensive test coverage (11 tests native, 11 tests rug)
### Changed
- **Naming Convention Cleanup - Removed `kernel_` Prefix from Mathematical Functions**:
- Removed `kernel_` prefix from mathematical functions to improve API consistency and clarity
- **Breaking changes** - renamed methods:
- `kernel_clamp()` → `clamp()`
- `kernel_classify()` → `classify()`
- `kernel_exp_m1()` → `exp_m1()`
- `kernel_ln_1p()` → `ln_1p()`
- `kernel_hypot()` → `hypot()`
- **Unchanged** - kept `kernel_` prefix for primitive type operations:
- Rounding: `kernel_ceil`, `kernel_floor`, `kernel_round`, `kernel_trunc`, `kernel_fract`
- Sign: `kernel_copysign`, `kernel_signum`, `kernel_is_sign_positive`, `kernel_is_sign_negative`
- **Rationale**: `kernel_` prefix now reserved exclusively for operations that directly manipulate primitive type properties (rounding, sign). Mathematical functions follow standard naming without prefix
- All tests updated and passing (87 doctests + full test suite with rug feature)
- **Documentation Simplification - `truncate_to_usize()`**:
- Reduced verbose documentation from 130+ lines to concise summary (~15 lines) with collapsible details
- Main documentation now provides quick reference with immediate example
- Detailed behavior, edge cases, comparison table, and backend notes moved to HTML `<details>` section
- Improved scannability while keeping comprehensive information available on-demand
- Applied to both `RealScalar::truncate_to_usize()` and `RawRealTrait::truncate_to_usize()`
- **Performance Optimization - MPFR Constants (rug backend)**:
- `pi()`: Now uses `rug::float::Constant::Pi` instead of `acos(-1)` (~10x faster)
- `ln_2()`: Now uses `rug::float::Constant::Log2` instead of calculation (~10x faster)
- Derived constants (`two_pi`, `pi_div_2`, `ln_10`, `log2_e`, `log10_e`) computed from MPFR base constants for consistency
- Speedup is especially significant at high precision (100+ bits)
- No API changes - purely internal optimization using MPFR precomputed constants
- **Conditional Backtrace Capture**:
- Added `backtrace` feature flag (disabled by default) to control backtrace capture at compile time
- Added `capture_backtrace()` function that returns `Backtrace::force_capture()` when feature enabled, `Backtrace::disabled()` otherwise
- Added `is_backtrace_enabled()` helper function to check feature state at runtime
- Replaced all 49 occurrences of `Backtrace::force_capture()` with `capture_backtrace()`
- Significantly improves performance when backtraces are not needed (default case)
- Users can enable backtraces for debugging with `features = ["backtrace"]` in `Cargo.toml`
- Added 6 comprehensive tests for conditional backtrace behavior covering:
- `capture_backtrace()` status verification
- `is_backtrace_enabled()` correctness
- Error backtrace status for NaN, subnormal, +∞, and -∞ errors
- **Conditional `Copy` Implementation for Validated Types**:
- `RealValidated<K>` now implements `Copy` when `K::RawReal: Copy`
- `ComplexValidated<K>` now implements `Copy` when `K::RawComplex: Copy`
- This enables zero-cost pass-by-value semantics for `RealNative64StrictFinite`, `ComplexNative64StrictFinite`, and their `InDebug` variants
- Types backed by non-`Copy` backends (like `rug::Float`) correctly require `Clone`
- Added 11 comprehensive tests for `Copy` semantics covering:
- Compile-time `Copy` trait verification
- Copy semantics (value remains valid after assignment)
- Function call by value (original still usable)
- Loop iteration with copied values
- Arithmetic operations using copies
- Mixed real/complex expressions
- **Documentation Updates**:
- Added "Feature Flags" section to README.md and lib.rs with table of available features
- Documented `backtrace` feature flag for conditional backtrace capture
- Documented conditional `Copy` implementation in Key Features section
- Consolidated feature flag examples into a single comprehensive section
### Fixed
- **Documentation Terminology Corrections**:
- Fixed misleading use of "unsafe method" terminology in 17 locations across 3 files
- Replaced "unsafe method" with "panicking method" to avoid confusion with Rust's `unsafe` keyword
- Affected traits: `Ln`, `Log10`, `Log2`, `Sin`, `Cos`, `Tan`, `ASin`, `ACos`, `ATan`, `SinH`, `CosH`, `TanH`, `ASinH`, `ACosH`, `ATanH`
- Clarified that panicking methods are memory-safe and distinct from `unsafe` functions
- All 93 doctests remain passing after corrections
- **Documentation Completeness**:
- Added comprehensive trait-level documentation to public traits in `src/functions/real.rs`
- Documented traits: `Clamp`, `Classify`, `ExpM1`, `Hypot`, `Ln1p`, `TotalCmp`
- Includes mathematical background, usage examples, and comparison with naive implementations
- Added 6 new doctests demonstrating proper usage
- Total doctests increased from 90 to 96
## [0.2.4] - 2025-11-21
### Added
- **Complete Hash Support for Complex Numbers**:
- Added `GuaranteesFiniteComplexValues` marker trait for complex validation policies
- Implemented `Eq` and `Hash` for `ComplexValidated` types with finite value guarantees
- Complex numbers can now be used as keys in `HashMap` and `HashSet`
- Added 11 comprehensive test functions covering complex number hashing for both native64 and rug backends
- Tests cover HashMap/HashSet operations, signed zero handling, hash consistency, and precision differences
### Changed
- **Unified Hashing Architecture**:
- Moved `compute_hash()` from `RawRealTrait` to `RawScalarTrait` for unified interface across real and complex types
- Complex hash implementation delegates to `compute_hash()` on real and imaginary parts sequentially
- Ensures consistent hashing behavior across all scalar types
- **Enhanced Documentation Quality**:
- Significantly improved `ComplexScalar` trait documentation with comprehensive descriptions, usage examples, and design philosophy explanations
- Added extensive hashing support section to `RawScalarTrait` documentation
- Updated `compute_hash()` method documentation to cover both real and complex scalar types
- Enhanced documentation structure and readability across all core traits and modules
### Fixed
- **Documentation Link Corrections**:
- Fixed broken intra-doc links for mathematical function traits (`functions::Max`, `functions::Min`, `functions::Conjugate`, `functions::Arg`)
- Corrected trait references throughout the documentation to properly point to the `functions` module
- All documentation now builds without warnings or broken links
### Removed
- (Nothing yet)
## [0.2.3] - 2025-11-01
### Added
- **Bytemuck Vec Conversion Support**: Extended bytemuck integration with Vec conversion utilities
- Added `extern_crate_alloc` feature to bytemuck dependency for Vec conversion support
- 2 new tests demonstrating `try_cast_vec` for zero-copy `Vec<RealNative64StrictFinite>` to `Vec<f64>` conversions
- Documented that `Vec<f64>` to `Vec<RealNative64StrictFinite>` requires iterator-based validation (cannot use `try_cast_vec`)
- **Enhanced Test Coverage for Complex Number Operations**: Added 6 new tests for `ComplexScalar::into_parts()` method
- Tests for basic usage, zero, pure real, pure imaginary, negative values, and independence of extracted parts
- 12 total tests when including rug feature variants
- Coverage for both `ComplexNative64StrictFinite` and `ComplexRugStrictFinite` types
- **Documentation Improvements**:
- Added comprehensive documentation for `ComplexScalar::into_parts()` method
- Includes description, return values, usage examples, and cross-references to related methods
- All documentation compiles without warnings
### Changed
- **Improved Code Coverage**: Test count increased from 693 to 699 tests (+6 tests)
- All `ComplexScalar` trait methods now have comprehensive test coverage
- **Updated Dependencies**:
- `bytemuck`: Now uses `features = ["extern_crate_alloc"]` for Vec conversion utilities
### Fixed
- Fixed 124 clippy warnings in test code (removed unnecessary `.clone()` calls on `Copy` types, unnecessary references in operators, and useless `vec![]` macros)
### Removed
- (Nothing yet)
## [0.2.2] - 2025-10-20
### Added
- **Bytemuck Integration**: Added `CheckedBitPattern` and `NoUninit` implementations for `RealNative64StrictFinite` and `RealNative64StrictFiniteInDebug` types, enabling safe, zero-copy conversions between `f64` byte representations and validated types
- Safe conversion from `f64` bytes to validated types with automatic validation
- Rejects invalid bit patterns (NaN, Infinity, subnormal values) during conversion
- 19 comprehensive tests covering valid conversions, invalid value rejection, round-trip conversions, and slice operations
- **Enhanced Test Coverage for Complex Number Operations**: Added 10 new tests for `ComplexScalarConstructors`, `ComplexScalarGetParts`, and `ComplexScalarSetParts` traits
- Tests for `is_pure_real()` and `is_pure_imaginary()` predicates
- Tests for `with_real_part()` and `with_imaginary_part()` builder methods
- Tests for `new_pure_real()` and `new_pure_imaginary()` constructors
- Tests for `try_new_pure_real()` and `try_new_pure_imaginary()` with validation
- Coverage for both valid inputs and error cases (NaN, Infinity)
- **Vector Conversion Tests**: Added 13 comprehensive tests for bidirectional conversions between `Vec<f64>` and `Vec<RealNative64StrictFinite>`
- Tests for successful conversion of valid values
- Tests for rejection of invalid values (NaN, Infinity, subnormals)
- Round-trip conversion tests ensuring data integrity
- Edge case tests (empty vectors, extreme values, zeros)
- Tests for different conversion patterns (consuming, filtering, preserving order)
### Changed
- **Improved Code Coverage**: Overall library coverage increased to 96.57% (from ~96.24%)
- `functions/complex.rs`: Coverage improved from 80.36% to 97.23% (+16.87%)
- Total test count increased from 668 to 691 tests (+23 tests)
- All complex number trait methods now have comprehensive test coverage
### Fixed
- (Nothing yet)
### Removed
- (Nothing yet)
## [0.2.1] - 2025-10-03
### Added
- The trait `FpScalar` now is also a sub-trait of `serde::Serialize` and `serde::Deserialize`
### Changed
- **Enhanced Documentation Quality**:
- Significantly improved `ComplexScalar` trait documentation with comprehensive descriptions, usage examples, and design philosophy explanations
- Enhanced documentation structure and readability across all core traits and modules
- Added detailed usage examples for complex number operations including basic operations and in-place modifications
### Fixed
- **Documentation Link Corrections**:
- Fixed broken intra-doc links for mathematical function traits (`functions::Max`, `functions::Min`, `functions::Conjugate`, `functions::Arg`)
- Corrected trait references throughout the documentation to properly point to the `functions` module
- Ensured all documentation builds without warnings or broken links
### Removed
- (Nothing yet)
## [0.2.0] - 2025-09-15
### Added
- **Enhanced Type Safety with HashMap Support**:
- Added `GuaranteesFiniteRealValues` marker trait for validation policies that ensure finite values
- Implemented `Eq` trait for `RealValidated` types when using policies with finite guarantees
- Implemented `Hash` trait for `RealValidated` types, enabling use as HashMap/HashSet keys
- Added specialized `Hash` implementations for different backends:
- Native `f64`: Uses IEEE 754 bit representation via `f64::to_bits()` with proper signed zero handling
- `rug::Float`: Uses integer representation via `rug::Float::to_integer()`
- **New Type Aliases with HashMap Support**:
- `RealNative64StrictFinite` now implements `Eq` and `Hash`
- `RealNative64StrictFiniteInDebug` now implements `Eq` and `Hash`
- `RealRugStrictFinite<PRECISION>` now implements `Eq` and `Hash` (when `rug` feature enabled)
- **Comprehensive Test Suite**:
- Added extensive HashMap and HashSet usage tests for all validated types
- Added hash consistency verification tests
- Added tests for signed zero hash consistency
- Added tests for both native `f64` and `rug` backends
- **Enhanced Documentation**:
- Added extensive examples for HashMap/HashSet usage
- Added documentation for all hashing mechanisms and design decisions
- **New Methods**:
- Added `RawRealTrait::truncate_as_usize()`
- Added `RealScalar::truncate_as_usize()`
- **New Dependency**:
- Added the new dependency library `az`
### Changed
- **Documentation Improvements**:
- Updated main library documentation to highlight HashMap support and hashing capabilities
- Enhanced `validation` module documentation with detailed explanations of `GuaranteesFiniteRealValues`
- Fixed broken intra-doc links throughout the codebase
- Updated version numbers in documentation examples to 0.2.0
- Clarified design decision to not implement `Ord` trait (library uses efficient `PartialOrd` with reference-based comparison)
- Updated copyright year to 2023-2025
- Fixed trait references in function documentation (e.g., `functions::Sin` instead of `Sin`)
- Updated date references from July 2025 to September 2025
- **API Surface Extensions**:
- `StrictFinitePolicy` now implements `GuaranteesFiniteRealValues` marker trait
- `DebugValidationPolicy<StrictFinitePolicy>` now implements `GuaranteesFiniteRealValues` marker trait
- Validated types with finite guarantees automatically gain `Eq` and `Hash` implementations
- **Code Organization**:
- Simplified hash implementation to use generic trait bounds instead of separate implementations
- Improved error handling documentation with better examples
- Enhanced trait documentation with comprehensive usage examples
### Fixed
- **Documentation Corrections**:
- Fixed numerous broken intra-doc links across all modules
- Corrected trait bound references in documentation
- Fixed incomplete code examples in documentation
- Updated outdated version numbers in examples
- Fixed missing import statements in code examples
- Corrected trait and type name references to match actual implementation
### Removed
- **N/A**
## [0.1.1] - 2025-09-01
### Added
- Added the following files:
- CHANGELOG.md
- Release.toml
### Changed
- Updated the required version of the following dependencies:
- criterion: 0.6 -> 0.7
- rug: 1.27.0 -> 1.28.0
- thiserror: 2.0.12 -> 2.0.16
### Fixed
- Fixed some failing tests in the documentation.
### Removed
- N/A
## [0.1.0] - 2025-07-21
### Added
- **Initial Release**
### Changed
- N/A (Initial Release)
### Fixed
- N/A (Initial Release)
### Removed
- N/A (Initial Release)