# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
The `i24` crate provides specialized 24-bit integer types for Rust: **i24** (signed) and **u24** (unsigned). This library is particularly useful for audio processing, embedded systems, and network protocols where precise bit-width control is required. The project emerged from the [Wavers](https://crates.io/crates/wavers) project for WAV file processing.
## Development Commands
### Core Development
```bash
# Build the project
cargo build
# Run all tests
cargo test
# Run tests for a specific test name/pattern
cargo test <pattern>
# Check code without building
cargo check
# Build with strict warnings (recommended for development)
RUSTFLAGS="-Dwarnings" cargo build --all-targets
# Generate documentation
cargo doc
# Generate documentation with strict warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
```
### Python Bindings Development
```bash
# Build Python extension (requires maturin and pyo3 feature)
cargo build --features pyo3
# Install Python package locally for testing
maturin develop
```
### Feature Testing
```bash
# Test with different feature combinations
cargo test --no-default-features
cargo test --features serde
cargo test --features zerocopy
cargo test --features alloc
cargo test --all-features
```
## Code Architecture
### Core Structure
- **`src/lib.rs`**: Main library entry point with public API and compile-time macros (`i24!`, `u24!`)
- **`src/types/`**: Core integer type implementations
- `i24.rs`: 24-bit signed integer implementation
- `u24.rs`: 24-bit unsigned integer implementation
- `mod.rs`: Type exports and Python bindings re-exports
- **`src/repr.rs`**: Internal representation and memory layout utilities
### Key Types
- **`I24`/`U24`**: Main integer types with arithmetic operations
- **`I24Bytes`/`U24Bytes`**: Byte array representations (`[u8; 3]`)
- **`PyI24`/`PyU24`**: Python bindings (pyo3 feature)
### Feature Flags
- **`alloc`**: Enables bulk I/O operations and PackedStruct functionality
- **`std`**: Enables standard library features (num-traits/std)
- **`pyo3`**: Enables Python bindings (requires std)
- **`serde`**: Enables serialization support
- **`zerocopy`**: Enables zerocopy trait implementations
### Memory Safety
All types implement `bytemuck` traits (`NoUninit`, `Zeroable`, `AnyBitPattern`) for safe byte-to-value conversions. The crate uses `#[repr(packed)]` internally but provides safe abstractions.
### Wire Format Support
The `packed` module provides utilities for working with binary protocols:
- `PackedStruct` trait for custom serialization
- Helper functions for mixed native/i24 structures
- Bulk read/write operations for network protocols
## Testing Strategy
The crate uses multiple testing approaches:
- **Unit tests**: Standard Rust unit tests in each module
- **Property tests**: Using `proptest` for exhaustive value range testing
- **Integration tests**: In `examples/` directory demonstrating real-world usage
- **Cross-platform tests**: Endianness handling verification
- **Benchmark tests**: Performance comparison with native integer types
## Development Notes
### Value Ranges
- **i24**: -8,388,608 to 8,388,607 (2^23 - 1)
- **u24**: 0 to 16,777,215 (2^24 - 1)
### Overflow Behavior
Arithmetic operations match Rust's standard integer behavior. Use checked operations (`checked_add`, `saturating_mul`, etc.) for safety-critical code.
### Endianness
All types support little-endian, big-endian, and native-endian byte operations. The bulk I/O functions handle endianness conversion efficiently using `bytemuck`.
