oxicode 0.2.1

A modern binary serialization library - successor to bincode
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278

//! SIMD-optimized encoding and decoding for oxicode.
//!
//! This module provides hardware-accelerated encoding and decoding for numerical arrays,
//! leveraging SIMD instructions (AVX2, AVX-512, NEON, SSE4.2) when available.
//!
//! ## Features
//!
//! - **Auto-detection**: Automatically detects CPU capabilities at runtime
//! - **4-8x speedup**: Significant performance improvement for numerical data
//! - **Zero-copy alignment**: Optimized memory access patterns
//! - **Fallback**: Graceful degradation to scalar path when SIMD unavailable
//!
//! ## Example
//!
//! ```rust,ignore
//! use oxicode::simd;
//!
//! let data: Vec<f32> = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0];
//!
//! // Encode with SIMD optimization
//! let encoded = simd::encode_array(&data)?;
//!
//! // Decode with SIMD optimization
//! let decoded: Vec<f32> = simd::decode_array(&encoded)?;
//! ```

mod aligned;
mod array;
mod detect;

pub use aligned::{AlignedBuffer, AlignedVec, SIMD_ALIGNMENT};
pub use array::{
    decode_f32_array, decode_f64_array, decode_i32_array, decode_i64_array, decode_u8_array,
    encode_f32_array, encode_f64_array, encode_i32_array, encode_i64_array, encode_u8_array,
};
pub use detect::{detect_capability, is_simd_available, optimal_alignment, SimdCapability};

use crate::Result;

/// Encode a slice of primitives using SIMD-optimized path when available.
///
/// This is the main entry point for SIMD-accelerated encoding. It automatically
/// dispatches to the appropriate SIMD implementation based on detected CPU capabilities.
///
/// # Type Support
///
/// Currently supports:
/// - `f32`, `f64` - Floating point types
/// - `i32`, `i64` - Signed integers
/// - `u8` - Byte arrays
///
/// # Example
///
/// ```rust,ignore
/// use oxicode::simd::encode_simd_array;
///
/// let floats: &[f32] = &[1.0, 2.0, 3.0, 4.0];
/// let encoded = encode_simd_array(floats)?;
/// ```
#[cfg(feature = "alloc")]
pub fn encode_simd_array<T: SimdEncodable>(data: &[T]) -> Result<alloc::vec::Vec<u8>> {
    T::encode_simd(data)
}

/// Decode a byte slice into a Vec of primitives using SIMD-optimized path when available.
///
/// This is the main entry point for SIMD-accelerated decoding.
///
/// # Type Support
///
/// Currently supports:
/// - `f32`, `f64` - Floating point types
/// - `i32`, `i64` - Signed integers
/// - `u8` - Byte arrays
///
/// # Example
///
/// ```rust,ignore
/// use oxicode::simd::decode_simd_array;
///
/// let encoded: &[u8] = &[...];
/// let floats: Vec<f32> = decode_simd_array(encoded)?;
/// ```
#[cfg(feature = "alloc")]
pub fn decode_simd_array<T: SimdDecodable>(data: &[u8]) -> Result<alloc::vec::Vec<T>> {
    T::decode_simd(data)
}

/// Trait for types that can be encoded using SIMD optimization.
pub trait SimdEncodable: Sized + Copy {
    /// Encode a slice of this type using SIMD when available.
    #[cfg(feature = "alloc")]
    fn encode_simd(data: &[Self]) -> Result<alloc::vec::Vec<u8>>;

    /// Encode into an existing buffer, returning bytes written.
    fn encode_simd_into(data: &[Self], dst: &mut [u8]) -> Result<usize>;
}

/// Trait for types that can be decoded using SIMD optimization.
pub trait SimdDecodable: Sized + Copy {
    /// Decode a slice into a Vec of this type using SIMD when available.
    #[cfg(feature = "alloc")]
    fn decode_simd(data: &[u8]) -> Result<alloc::vec::Vec<Self>>;

    /// Decode into an existing buffer, returning items decoded.
    fn decode_simd_into(src: &[u8], dst: &mut [Self]) -> Result<usize>;
}

#[cfg(feature = "alloc")]
extern crate alloc;

// Implement SimdEncodable for f32
impl SimdEncodable for f32 {
    #[cfg(feature = "alloc")]
    fn encode_simd(data: &[Self]) -> Result<alloc::vec::Vec<u8>> {
        encode_f32_array(data)
    }

    fn encode_simd_into(data: &[Self], dst: &mut [u8]) -> Result<usize> {
        array::encode_f32_array_into(data, dst)
    }
}

impl SimdDecodable for f32 {
    #[cfg(feature = "alloc")]
    fn decode_simd(data: &[u8]) -> Result<alloc::vec::Vec<Self>> {
        decode_f32_array(data)
    }

    fn decode_simd_into(src: &[u8], dst: &mut [Self]) -> Result<usize> {
        array::decode_f32_array_into(src, dst)
    }
}

// Implement SimdEncodable for f64
impl SimdEncodable for f64 {
    #[cfg(feature = "alloc")]
    fn encode_simd(data: &[Self]) -> Result<alloc::vec::Vec<u8>> {
        encode_f64_array(data)
    }

    fn encode_simd_into(data: &[Self], dst: &mut [u8]) -> Result<usize> {
        array::encode_f64_array_into(data, dst)
    }
}

impl SimdDecodable for f64 {
    #[cfg(feature = "alloc")]
    fn decode_simd(data: &[u8]) -> Result<alloc::vec::Vec<Self>> {
        decode_f64_array(data)
    }

    fn decode_simd_into(src: &[u8], dst: &mut [Self]) -> Result<usize> {
        array::decode_f64_array_into(src, dst)
    }
}

// Implement SimdEncodable for i32
impl SimdEncodable for i32 {
    #[cfg(feature = "alloc")]
    fn encode_simd(data: &[Self]) -> Result<alloc::vec::Vec<u8>> {
        encode_i32_array(data)
    }

    fn encode_simd_into(data: &[Self], dst: &mut [u8]) -> Result<usize> {
        array::encode_i32_array_into(data, dst)
    }
}

impl SimdDecodable for i32 {
    #[cfg(feature = "alloc")]
    fn decode_simd(data: &[u8]) -> Result<alloc::vec::Vec<Self>> {
        decode_i32_array(data)
    }

    fn decode_simd_into(src: &[u8], dst: &mut [Self]) -> Result<usize> {
        array::decode_i32_array_into(src, dst)
    }
}

// Implement SimdEncodable for i64
impl SimdEncodable for i64 {
    #[cfg(feature = "alloc")]
    fn encode_simd(data: &[Self]) -> Result<alloc::vec::Vec<u8>> {
        encode_i64_array(data)
    }

    fn encode_simd_into(data: &[Self], dst: &mut [u8]) -> Result<usize> {
        array::encode_i64_array_into(data, dst)
    }
}

impl SimdDecodable for i64 {
    #[cfg(feature = "alloc")]
    fn decode_simd(data: &[u8]) -> Result<alloc::vec::Vec<Self>> {
        decode_i64_array(data)
    }

    fn decode_simd_into(src: &[u8], dst: &mut [Self]) -> Result<usize> {
        array::decode_i64_array_into(src, dst)
    }
}

// Implement SimdEncodable for u8
impl SimdEncodable for u8 {
    #[cfg(feature = "alloc")]
    fn encode_simd(data: &[Self]) -> Result<alloc::vec::Vec<u8>> {
        encode_u8_array(data)
    }

    fn encode_simd_into(data: &[Self], dst: &mut [u8]) -> Result<usize> {
        array::encode_u8_array_into(data, dst)
    }
}

impl SimdDecodable for u8 {
    #[cfg(feature = "alloc")]
    fn decode_simd(data: &[u8]) -> Result<alloc::vec::Vec<Self>> {
        decode_u8_array(data)
    }

    fn decode_simd_into(src: &[u8], dst: &mut [Self]) -> Result<usize> {
        array::decode_u8_array_into(src, dst)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_simd_detection() {
        let cap = detect_capability();
        // Should always succeed, even if returning Scalar
        assert!(matches!(
            cap,
            SimdCapability::Avx512
                | SimdCapability::Avx2
                | SimdCapability::Sse42
                | SimdCapability::Neon
                | SimdCapability::Scalar
        ));
    }

    #[test]
    fn test_is_simd_available() {
        // This test just ensures the function works
        let _ = is_simd_available();
    }

    #[cfg(feature = "alloc")]
    #[test]
    fn test_f32_roundtrip() {
        let data: alloc::vec::Vec<f32> = alloc::vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0];
        let encoded = encode_simd_array(&data).expect("encode failed");
        let decoded: alloc::vec::Vec<f32> = decode_simd_array(&encoded).expect("decode failed");
        assert_eq!(data, decoded);
    }

    #[cfg(feature = "alloc")]
    #[test]
    fn test_i32_roundtrip() {
        let data: alloc::vec::Vec<i32> = alloc::vec![-100, -1, 0, 1, 100, 1000, -1000, 42];
        let encoded = encode_simd_array(&data).expect("encode failed");
        let decoded: alloc::vec::Vec<i32> = decode_simd_array(&encoded).expect("decode failed");
        assert_eq!(data, decoded);
    }

    #[cfg(feature = "alloc")]
    #[test]
    fn test_large_array() {
        // Test with a larger array to ensure SIMD path is exercised
        let data: alloc::vec::Vec<f64> = (0..1024).map(|i| i as f64 * 0.5).collect();
        let encoded = encode_simd_array(&data).expect("encode failed");
        let decoded: alloc::vec::Vec<f64> = decode_simd_array(&encoded).expect("decode failed");
        assert_eq!(data, decoded);
    }
}