# 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).

## [Unreleased]

### 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 `GuaranteesFiniteValues` 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 `GuaranteesFiniteValues`
  - 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 `GuaranteesFiniteValues` marker trait
  - `DebugValidationPolicy<StrictFinitePolicy>` now implements `GuaranteesFiniteValues` 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)
