dodecet_encoder/
lib.rs

1//! # Dodecet Encoder
2//!
3//! A revolutionary 12-bit dodecet encoding system optimized for geometric and calculus operations.
4//!
5//! ## What is a Dodecet?
6//!
7//! A **dodecet** is a 12-bit unit composed of 3 nibbles (4-bit sets):
8//!
9//! ```text
10//! ┌─────────────────────────────────────────┐
11//! │           DODECET (12 bits)             │
12//! ├─────────────────────────────────────────┤
13//! │  Nibble 2  │  Nibble 1  │  Nibble 0    │
14//! │  (4 bits)  │  (4 bits)  │  (4 bits)    │
15//! │  [11:8]    │  [7:4]     │  [3:0]       │
16//! ├─────────────────────────────────────────┤
17//! │  Example:   0xA        0xB        0xC  │
18//! │  Hex: 0xABC = 1010 1011 1100 (binary)  │
19//! └─────────────────────────────────────────┘
20//! ```
21//!
22//! ## Why 12 Bits?
23//!
24//! - **Hex-Friendly**: Each dodecet = 3 hex digits (e.g., 0xABC)
25//! - **Geometric**: 12 bits can encode 4096 values (vs 256 for 8-bit)
26//! - **Calculus-Optimized**: Natural alignment for derivatives and integrals
27//! - **Shape Encoding**: Perfect for vertices, edges, faces (3D geometry)
28//!
29//! ## Quick Start
30//!
31//! ```rust
32//! use dodecet_encoder::{Dodecet, DodecetArray};
33//!
34//! // Create a dodecet from hex
35//! let d = Dodecet::from_hex(0xABC);
36//!
37//! // Access nibbles
38//! assert_eq!(d.nibble(0).unwrap(), 0xC);
39//! assert_eq!(d.nibble(1).unwrap(), 0xB);
40//! assert_eq!(d.nibble(2).unwrap(), 0xA);
41//!
42//! // Geometric encoding: 3D point (x, y, z)
43//! let point: DodecetArray<3> = DodecetArray::from_slice(&[0x123, 0x456, 0x789]);
44//! ```
45//!
46//! ## Architecture
47//!
48//! This crate provides:
49//! - **Core Types**: `Dodecet`, `DodecetArray`, `DodecetString`
50//! - **Geometric Operations**: Vector math, transformations, rotations
51//! - **Hex Encoding**: Bidirectional hex conversion
52//! - **Performance**: SIMD-optimized operations where possible
53
54pub mod dodecet;
55pub mod array;
56pub mod string;
57pub mod geometric;
58pub mod hex;
59pub mod calculus;
60pub mod eisenstein;
61pub mod lighthouse;
62pub mod seed_discovery;
63pub mod simd;
64pub mod temporal;
65
66// WASM bindings
67#[cfg(feature = "wasm")]
68pub mod wasm;
69
70// Re-export core types
71pub use dodecet::Dodecet;
72pub use array::DodecetArray;
73pub use string::DodecetString;
74pub use geometric::{Point3D, Vector3D, Transform3D};
75
76// Re-export WASM types when feature is enabled
77#[cfg(feature = "wasm")]
78pub use wasm::{WasmDodecet, WasmPoint3D, WasmVector3D, DodecetUtils};
79
80/// Maximum value of a dodecet (12 bits = 4095)
81pub const MAX_DODECET: u16 = 0xFFF;
82
83/// Number of bits in a dodecet
84pub const DODECET_BITS: u8 = 12;
85
86/// Number of nibbles in a dodecet
87pub const NIBBLES: u8 = 3;
88
89/// Number of values a dodecet can represent
90pub const CAPACITY: u16 = 4096;
91
92/// Error type for dodecet operations
93#[derive(Debug, Clone, Copy, PartialEq, Eq)]
94pub enum DodecetError {
95    /// Value exceeds 12-bit capacity
96    Overflow,
97    /// Invalid hex string
98    InvalidHex,
99    /// Invalid nibble index
100    InvalidNibble,
101    /// Invalid geometric operation
102    InvalidGeometry,
103    /// Invalid array length for SIMD operation
104    InvalidLength,
105}
106
107impl std::fmt::Display for DodecetError {
108    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
109        match self {
110            DodecetError::Overflow => write!(f, "Value exceeds 12-bit capacity (max: 4095)"),
111            DodecetError::InvalidHex => write!(f, "Invalid hex string"),
112            DodecetError::InvalidNibble => write!(f, "Nibble index must be 0, 1, or 2"),
113            DodecetError::InvalidGeometry => write!(f, "Invalid geometric operation"),
114            DodecetError::InvalidLength => write!(f, "Invalid array length for SIMD operation"),
115        }
116    }
117}
118
119impl std::error::Error for DodecetError {}
120
121/// Result type for dodecet operations
122pub type Result<T> = std::result::Result<T, DodecetError>;
123
124#[cfg(test)]
125mod tests {
126    use super::*;
127
128    #[test]
129    fn test_constants() {
130        assert_eq!(MAX_DODECET, 4095);
131        assert_eq!(DODECET_BITS, 12);
132        assert_eq!(NIBBLES, 3);
133        assert_eq!(CAPACITY, 4096);
134    }
135}
dodecet_encoder/lib.rs

dodecet_encoder/
lib.rs
