Skip to main content

uni_sparse_vector/
encode.rs

1use crate::error::SparseError;
2use crate::sparse::SparseVector;
3
4/// Canonical binary form of a [`SparseVector`].
5///
6/// Layout (little-endian, variable length):
7/// ```text
8/// [count: u32] [indices: count × u32] [values: count × f32]
9/// ```
10/// Indices and values are stored in separate runs (not interleaved) to match
11/// the Arrow `Struct{indices: List<UInt32>, values: List<Float32>}` lowering
12/// and to keep each run contiguous for scoring. Weights are lossless `f32`;
13/// quantization is applied by the storage engine at the postings boundary, not
14/// here.
15pub fn encode(sv: &SparseVector) -> Vec<u8> {
16    let n = sv.len();
17    let mut buf = Vec::with_capacity(4 + n * 8);
18    buf.extend_from_slice(&(n as u32).to_le_bytes());
19    for &idx in sv.indices() {
20        buf.extend_from_slice(&idx.to_le_bytes());
21    }
22    for &val in sv.values() {
23        buf.extend_from_slice(&val.to_le_bytes());
24    }
25    buf
26}
27
28/// Decode a [`SparseVector`] from its canonical binary form, re-validating all
29/// invariants (so a corrupted or hand-built buffer cannot smuggle in unsorted
30/// indices or NaN weights).
31pub fn decode_slice(bytes: &[u8]) -> Result<SparseVector, SparseError> {
32    if bytes.len() < 4 {
33        return Err(SparseError::Truncated {
34            need: 4,
35            got: bytes.len(),
36        });
37    }
38    let count = u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]) as usize;
39    let need = 4 + count * 8;
40    if bytes.len() < need {
41        return Err(SparseError::Truncated {
42            need,
43            got: bytes.len(),
44        });
45    }
46    if bytes.len() > need {
47        return Err(SparseError::TrailingBytes {
48            trailing: bytes.len() - need,
49        });
50    }
51
52    // The payload is two contiguous runs of `count` little-endian 4-byte words:
53    // the indices first, then the values. `need` was checked above, so each run
54    // splits cleanly into 4-byte chunks.
55    let (index_bytes, value_bytes) = bytes[4..need].split_at(count * 4);
56    let indices = index_bytes
57        .as_chunks::<4>()
58        .0
59        .iter()
60        .map(|c| u32::from_le_bytes(*c))
61        .collect();
62    let values = value_bytes
63        .as_chunks::<4>()
64        .0
65        .iter()
66        .map(|c| f32::from_le_bytes(*c))
67        .collect();
68
69    SparseVector::new(indices, values)
70}
71
72#[cfg(test)]
73mod tests {
74    use super::*;
75
76    #[test]
77    fn roundtrip_basic() {
78        let original = SparseVector::new(vec![1, 7, 42], vec![0.25, -1.5, 3.0]).unwrap();
79        let bytes = encode(&original);
80        let decoded = decode_slice(&bytes).unwrap();
81        assert_eq!(original, decoded);
82    }
83
84    #[test]
85    fn roundtrip_empty() {
86        let original = SparseVector::new(vec![], vec![]).unwrap();
87        let bytes = encode(&original);
88        assert_eq!(bytes.len(), 4);
89        assert_eq!(decode_slice(&bytes).unwrap(), original);
90    }
91
92    #[test]
93    fn truncated_header_rejected() {
94        assert!(matches!(
95            decode_slice(&[0u8; 3]).unwrap_err(),
96            SparseError::Truncated { .. }
97        ));
98    }
99
100    #[test]
101    fn truncated_payload_rejected() {
102        let original = SparseVector::new(vec![1, 2], vec![1.0, 2.0]).unwrap();
103        let mut bytes = encode(&original);
104        bytes.truncate(bytes.len() - 1);
105        assert!(matches!(
106            decode_slice(&bytes).unwrap_err(),
107            SparseError::Truncated { .. }
108        ));
109    }
110
111    #[test]
112    fn trailing_bytes_rejected() {
113        let original = SparseVector::new(vec![1], vec![1.0]).unwrap();
114        let mut bytes = encode(&original);
115        bytes.push(0xFF);
116        assert!(matches!(
117            decode_slice(&bytes).unwrap_err(),
118            SparseError::TrailingBytes { .. }
119        ));
120    }
121
122    #[test]
123    fn decode_revalidates_invariants() {
124        // Hand-build a buffer with unsorted indices [5, 1]; decode must reject.
125        let mut bytes = Vec::new();
126        bytes.extend_from_slice(&2u32.to_le_bytes());
127        bytes.extend_from_slice(&5u32.to_le_bytes());
128        bytes.extend_from_slice(&1u32.to_le_bytes());
129        bytes.extend_from_slice(&1.0f32.to_le_bytes());
130        bytes.extend_from_slice(&2.0f32.to_le_bytes());
131        assert!(matches!(
132            decode_slice(&bytes).unwrap_err(),
133            SparseError::UnsortedIndices { .. }
134        ));
135    }
136}