protocache_core/
mutable.rs

1//! Mutable surface matching `access-ex.h`.
2
3use std::array;
4use std::borrow::Borrow;
5use std::collections::HashMap;
6use std::hash::Hash;
7use std::marker::PhantomData;
8
9use crate::access::checked_slice_end;
10use crate::serialize::serialize_map_pairs_at_mut;
11use crate::{
12    ArrayView, Buffer, FieldView, MapKey, MapView, MessageView, Scalar, StringView, Unit,
13    build_perfect_hash_index_with_positions, fold_field, serialize_array_at_mut, serialize_bool,
14    serialize_bytes, serialize_scalar, serialize_str,
15};
16
17#[derive(Debug)]
18pub enum MutableError {
19    InvalidRoot {
20        descriptor: String,
21    },
22    MissingField {
23        descriptor: String,
24        field: String,
25    },
26    TypeMismatch {
27        descriptor: String,
28        field: String,
29        expected: &'static str,
30    },
31    InvalidMapKey {
32        descriptor: String,
33        field: String,
34        key: String,
35    },
36    SerializeFailed {
37        descriptor: String,
38        field: String,
39    },
40}
41
42impl std::fmt::Display for MutableError {
43    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
44        match self {
45            Self::InvalidRoot { descriptor } => write!(f, "invalid root for {descriptor}"),
46            Self::MissingField { descriptor, field } => {
47                write!(f, "missing field {field} in {descriptor}")
48            }
49            Self::TypeMismatch {
50                descriptor,
51                field,
52                expected,
53            } => write!(
54                f,
55                "type mismatch for {descriptor}.{field}, expected {expected}"
56            ),
57            Self::InvalidMapKey {
58                descriptor,
59                field,
60                key,
61            } => write!(f, "invalid map key {key} for {descriptor}.{field}"),
62            Self::SerializeFailed { descriptor, field } => {
63                write!(f, "failed to serialize {descriptor}.{field}")
64            }
65        }
66    }
67}
68
69impl std::error::Error for MutableError {}
70
71#[derive(Clone, Copy)]
72pub enum MutableMapKeyKind {
73    String,
74    I32,
75    U32,
76    I64,
77    U64,
78}
79
80pub trait MutableField<'a>: Clone + Default {
81    fn decode(field: FieldView<'a>) -> Option<Self>;
82    fn detect(field: FieldView<'a>) -> Option<&'a [u32]>;
83    fn folds_when_present() -> bool
84    where
85        Self: Sized,
86    {
87        true
88    }
89    fn is_empty_field(&self) -> bool {
90        false
91    }
92    fn omits_default_after_encode() -> bool
93    where
94        Self: Sized,
95    {
96        true
97    }
98    fn is_dirty(&self) -> bool {
99        false
100    }
101    fn has_nested_dirty(&self) -> bool {
102        self.is_dirty()
103    }
104    fn encode(&self, buffer: &mut Buffer) -> Result<Unit, MutableError>;
105}
106
107pub trait MutableArrayElement<'a>: MutableField<'a> {
108    fn decode_array(words: &'a [u32]) -> Option<Vec<Self>>;
109    fn detect_array_words(words: &'a [u32]) -> Option<&'a [u32]> {
110        detect_array_words::<Self>(words)
111    }
112    fn detect_array_field(field: FieldView<'a>) -> Option<&'a [u32]> {
113        Self::detect_array_words(field.object_words()?)
114    }
115    fn encode_array(values: &[Self], buffer: &mut Buffer) -> Result<Unit, MutableError>;
116}
117
118pub trait MutableMapKey<'a>: Clone + Eq + Hash {
119    fn decode_key(field: FieldView<'a>) -> Option<Self>;
120    fn detect_key(field: FieldView<'a>) -> Option<&'a [u32]>;
121    fn encode_key(&self, buffer: &mut Buffer) -> Result<Unit, MutableError>;
122    fn key_kind() -> MutableMapKeyKind;
123    fn borrowed_key_bytes(&self) -> Option<&[u8]> {
124        None
125    }
126    fn write_key_bytes<'b>(&'b self, scratch: &'b mut [u8; 8]) -> &'b [u8];
127}
128
129#[derive(Clone, Copy)]
130enum KeyBytes<'a> {
131    Borrowed(&'a [u8]),
132    Inline { data: [u8; 8], len: usize },
133}
134
135impl AsRef<[u8]> for KeyBytes<'_> {
136    fn as_ref(&self) -> &[u8] {
137        match self {
138            Self::Borrowed(bytes) => bytes,
139            Self::Inline { data, len } => &data[..*len],
140        }
141    }
142}
143
144#[derive(Clone, Debug)]
145pub struct MutableArray<'a, T> {
146    values: Vec<T>,
147    dirty: bool,
148    _marker: PhantomData<&'a ()>,
149}
150
151impl<'a, T> Default for MutableArray<'a, T> {
152    fn default() -> Self {
153        Self {
154            values: Vec::new(),
155            dirty: false,
156            _marker: PhantomData,
157        }
158    }
159}
160
161impl<'a, T> MutableArray<'a, T> {
162    pub fn new() -> Self {
163        Self::default()
164    }
165
166    pub fn len(&self) -> usize {
167        self.values.len()
168    }
169
170    pub fn is_empty(&self) -> bool {
171        self.values.is_empty()
172    }
173
174    pub fn clear(&mut self) {
175        self.dirty = true;
176        self.values.clear();
177    }
178
179    pub fn reserve(&mut self, additional: usize) {
180        self.values.reserve(additional);
181    }
182
183    pub fn push(&mut self, value: T) {
184        self.dirty = true;
185        self.values.push(value);
186    }
187
188    pub fn as_slice(&self) -> &[T] {
189        &self.values
190    }
191
192    pub fn as_mut_slice(&mut self) -> &mut [T] {
193        self.dirty = true;
194        &mut self.values
195    }
196
197    pub fn iter(&self) -> impl Iterator<Item = &T> {
198        self.values.iter()
199    }
200
201    pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut T> {
202        self.dirty = true;
203        self.values.iter_mut()
204    }
205}
206
207impl<'a, T> From<Vec<T>> for MutableArray<'a, T> {
208    fn from(values: Vec<T>) -> Self {
209        Self {
210            values,
211            dirty: false,
212            _marker: PhantomData,
213        }
214    }
215}
216
217impl<'a, T> Extend<T> for MutableArray<'a, T> {
218    fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) {
219        self.dirty = true;
220        self.values.extend(iter);
221    }
222}
223
224impl<'a, T> std::iter::FromIterator<T> for MutableArray<'a, T> {
225    fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self {
226        Self {
227            values: iter.into_iter().collect(),
228            dirty: false,
229            _marker: PhantomData,
230        }
231    }
232}
233
234impl<'b, 'a, T> IntoIterator for &'b MutableArray<'a, T> {
235    type Item = &'b T;
236    type IntoIter = std::slice::Iter<'b, T>;
237
238    fn into_iter(self) -> Self::IntoIter {
239        self.values.iter()
240    }
241}
242
243impl<'b, 'a, T> IntoIterator for &'b mut MutableArray<'a, T> {
244    type Item = &'b mut T;
245    type IntoIter = std::slice::IterMut<'b, T>;
246
247    fn into_iter(self) -> Self::IntoIter {
248        self.dirty = true;
249        self.values.iter_mut()
250    }
251}
252
253impl<'a, T> std::ops::Index<usize> for MutableArray<'a, T> {
254    type Output = T;
255
256    fn index(&self, index: usize) -> &Self::Output {
257        &self.values[index]
258    }
259}
260
261impl<'a, T> std::ops::IndexMut<usize> for MutableArray<'a, T> {
262    fn index_mut(&mut self, index: usize) -> &mut Self::Output {
263        self.dirty = true;
264        &mut self.values[index]
265    }
266}
267
268impl<'a, T: MutableArrayElement<'a>> MutableArray<'a, T> {
269    pub fn from_words(words: &'a [u32]) -> Option<Self> {
270        Some(Self {
271            values: T::decode_array(words)?,
272            dirty: false,
273            _marker: PhantomData,
274        })
275    }
276
277    pub fn encode_to_unit(&self, buffer: &mut Buffer) -> Result<Unit, MutableError> {
278        T::encode_array(&self.values, buffer)
279    }
280}
281
282#[derive(Clone, Debug)]
283pub struct MutableMap<'a, K, V> {
284    entries: HashMap<K, V>,
285    dirty: bool,
286    _marker: PhantomData<&'a ()>,
287}
288
289impl<'a, K, V> Default for MutableMap<'a, K, V> {
290    fn default() -> Self {
291        Self {
292            entries: HashMap::new(),
293            dirty: false,
294            _marker: PhantomData,
295        }
296    }
297}
298
299impl<'a, K: Eq + Hash, V> MutableMap<'a, K, V> {
300    pub fn new() -> Self {
301        Self::default()
302    }
303
304    pub fn len(&self) -> usize {
305        self.entries.len()
306    }
307
308    pub fn is_empty(&self) -> bool {
309        self.entries.is_empty()
310    }
311
312    pub fn clear(&mut self) {
313        self.dirty = true;
314        self.entries.clear();
315    }
316
317    pub fn reserve(&mut self, additional: usize) {
318        self.entries.reserve(additional);
319    }
320
321    pub fn insert(&mut self, key: K, value: V) -> Option<V> {
322        self.dirty = true;
323        self.entries.insert(key, value)
324    }
325
326    pub fn contains_key<Q>(&self, key: &Q) -> bool
327    where
328        K: Borrow<Q>,
329        Q: Eq + Hash + ?Sized,
330    {
331        self.entries.contains_key(key)
332    }
333
334    pub fn get<Q>(&self, key: &Q) -> Option<&V>
335    where
336        K: Borrow<Q>,
337        Q: Eq + Hash + ?Sized,
338    {
339        self.entries.get(key)
340    }
341
342    pub fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut V>
343    where
344        K: Borrow<Q>,
345        Q: Eq + Hash + ?Sized,
346    {
347        self.dirty = true;
348        self.entries.get_mut(key)
349    }
350
351    pub fn remove<Q>(&mut self, key: &Q) -> Option<V>
352    where
353        K: Borrow<Q>,
354        Q: Eq + Hash + ?Sized,
355    {
356        self.dirty = true;
357        self.entries.remove(key)
358    }
359
360    pub fn iter(&self) -> impl Iterator<Item = (&K, &V)> {
361        self.entries.iter()
362    }
363}
364
365impl<'a, K, V> From<HashMap<K, V>> for MutableMap<'a, K, V> {
366    fn from(entries: HashMap<K, V>) -> Self {
367        Self {
368            entries,
369            dirty: false,
370            _marker: PhantomData,
371        }
372    }
373}
374
375impl<'a, K: Eq + Hash, V> Extend<(K, V)> for MutableMap<'a, K, V> {
376    fn extend<I: IntoIterator<Item = (K, V)>>(&mut self, iter: I) {
377        self.dirty = true;
378        self.entries.extend(iter);
379    }
380}
381
382impl<'a, K: Eq + Hash, V> std::iter::FromIterator<(K, V)> for MutableMap<'a, K, V> {
383    fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self {
384        Self {
385            entries: iter.into_iter().collect(),
386            dirty: false,
387            _marker: PhantomData,
388        }
389    }
390}
391
392impl<'b, 'a, K, V> IntoIterator for &'b MutableMap<'a, K, V> {
393    type Item = (&'b K, &'b V);
394    type IntoIter = std::collections::hash_map::Iter<'b, K, V>;
395
396    fn into_iter(self) -> Self::IntoIter {
397        self.entries.iter()
398    }
399}
400
401impl<'b, 'a, K, V> IntoIterator for &'b mut MutableMap<'a, K, V> {
402    type Item = (&'b K, &'b mut V);
403    type IntoIter = std::collections::hash_map::IterMut<'b, K, V>;
404
405    fn into_iter(self) -> Self::IntoIter {
406        self.dirty = true;
407        self.entries.iter_mut()
408    }
409}
410
411impl<'a, K: MutableMapKey<'a>, V: MutableField<'a>> MutableMap<'a, K, V> {
412    pub fn from_words(words: &'a [u32]) -> Option<Self> {
413        let map = MapView::new(words)?;
414        let mut entries = HashMap::with_capacity(map.len());
415        for pair in map.iter() {
416            entries.insert(K::decode_key(pair.key())?, V::decode(pair.value())?);
417        }
418        Some(Self {
419            entries,
420            dirty: false,
421            _marker: PhantomData,
422        })
423    }
424
425    pub fn encode_to_unit(&self, buffer: &mut Buffer) -> Result<Unit, MutableError> {
426        let last = buffer.len();
427        let mut memo = Vec::with_capacity(self.entries.len());
428        let mut key_bytes = Vec::with_capacity(self.entries.len());
429        match K::key_kind() {
430            MutableMapKeyKind::String => {
431                for pair in self.entries.iter() {
432                    key_bytes.push(KeyBytes::Borrowed(
433                        pair.0
434                            .borrowed_key_bytes()
435                            .expect("string keys should expose borrowed bytes"),
436                    ));
437                    memo.push(pair);
438                }
439            }
440            _ => {
441                for pair in self.entries.iter() {
442                    let mut scratch = [0u8; 8];
443                    let len = {
444                        let bytes = pair.0.write_key_bytes(&mut scratch);
445                        bytes.len()
446                    };
447                    key_bytes.push(KeyBytes::Inline { data: scratch, len });
448                    memo.push(pair);
449                }
450            }
451        }
452        let (index, positions) = build_perfect_hash_index_with_positions(&key_bytes).ok_or(
453            MutableError::SerializeFailed {
454                descriptor: "<map>".to_owned(),
455                field: "<index>".to_owned(),
456            },
457        )?;
458
459        let mut book = vec![memo[0]; memo.len()];
460        for (idx, position) in positions.into_iter().enumerate() {
461            book[position] = memo[idx];
462        }
463
464        let mut pairs = vec![(Unit::empty(), Unit::empty()); book.len()];
465        for i in (0..book.len()).rev() {
466            let (key, value) = book[i];
467            pairs[i].1 = value.encode(buffer)?;
468            pairs[i].0 = key.encode_key(buffer)?;
469        }
470
471        serialize_map_pairs_at_mut(&index, &mut pairs, buffer, last).ok_or_else(|| {
472            MutableError::SerializeFailed {
473                descriptor: "<map>".to_owned(),
474                field: "<encode>".to_owned(),
475            }
476        })
477    }
478}
479
480#[inline(always)]
481fn detect_array_words<'a, T: MutableField<'a>>(words: &'a [u32]) -> Option<&'a [u32]> {
482    let array = ArrayView::new(words)?;
483    let end = array.total_words();
484    for index in (0..array.len()).rev() {
485        let detected = T::detect(array.expect_field(index))?;
486        let detected_end = checked_slice_end(words, detected)?;
487        if detected_end > end {
488            return words.get(..detected_end);
489        }
490    }
491    words.get(..end)
492}
493
494#[inline(always)]
495fn detect_map_words<'a, K: MutableMapKey<'a>, V: MutableField<'a>>(
496    words: &'a [u32],
497) -> Option<&'a [u32]> {
498    let map = MapView::new(words)?;
499    let end = map.total_words();
500    for index in (0..map.len()).rev() {
501        let pair = map.expect_pair(index);
502        let detected = V::detect(pair.value())?;
503        let detected_end = checked_slice_end(words, detected)?;
504        if detected_end > end {
505            return words.get(..detected_end);
506        }
507
508        let detected = K::detect_key(pair.key())?;
509        let detected_end = checked_slice_end(words, detected)?;
510        if detected_end > end {
511            return words.get(..detected_end);
512        }
513    }
514    words.get(..end)
515}
516
517#[derive(Clone, Debug)]
518pub struct MutableMessage<'a, const N: usize, const WORDS: usize> {
519    words: Option<&'a [u32]>,
520    accessed: [u64; WORDS],
521}
522
523impl<'a, const N: usize, const WORDS: usize> Default for MutableMessage<'a, N, WORDS> {
524    fn default() -> Self {
525        Self {
526            words: None,
527            accessed: [0; WORDS],
528        }
529    }
530}
531
532impl<'a, const N: usize, const WORDS: usize> MutableMessage<'a, N, WORDS> {
533    pub fn new() -> Self {
534        debug_assert_eq!(WORDS, N.div_ceil(64));
535        Self::default()
536    }
537
538    pub fn from_words(words: &'a [u32]) -> Option<Self> {
539        MessageView::layout(words)?;
540        debug_assert_eq!(WORDS, N.div_ceil(64));
541        Some(Self {
542            words: Some(words),
543            accessed: [0; WORDS],
544        })
545    }
546
547    #[inline(always)]
548    fn field(&self, id: usize) -> Option<FieldView<'a>> {
549        let words = self.words?;
550        let layout = MessageView::layout(words)?;
551        MessageView::field_in(words, &layout, id)
552    }
553
554    #[inline(always)]
555    pub fn has_field(&self, id: usize) -> bool {
556        self.field(id).is_some()
557    }
558
559    #[inline(always)]
560    pub fn was_accessed(&self, id: usize) -> bool {
561        let word = id / 64;
562        let bit = id % 64;
563        (self.accessed[word] & (1u64 << bit)) != 0
564    }
565
566    pub fn has_any_accessed(&self) -> bool {
567        self.accessed.iter().any(|&word| word != 0)
568    }
569
570    pub fn clean_words(&self) -> Option<&[u32]> {
571        if self.has_any_accessed() {
572            None
573        } else {
574            self.words
575        }
576    }
577
578    pub fn get_field<'b, T: MutableField<'a>>(&mut self, id: usize, slot: &'b mut T) -> &'b mut T {
579        if !self.was_accessed(id) {
580            let word = id / 64;
581            let bit = id % 64;
582            self.accessed[word] |= 1u64 << bit;
583            *slot = self.field(id).and_then(T::decode).unwrap_or_default();
584        }
585        slot
586    }
587
588    #[inline(always)]
589    pub fn serialize_field<T: MutableField<'a>>(
590        &self,
591        id: usize,
592        field: &T,
593        buffer: &mut Buffer,
594        unit: &mut Unit,
595    ) -> Result<(), MutableError> {
596        if !self.was_accessed(id) {
597            *unit = self
598                .field(id)
599                .and_then(T::detect)
600                .map(|words| copy_words(words, buffer, true))
601                .unwrap_or_else(Unit::empty);
602            return Ok(());
603        }
604
605        if field.is_empty_field() {
606            *unit = Unit::empty();
607            return Ok(());
608        }
609
610        *unit = field.encode(buffer)?;
611        if T::omits_default_after_encode() && should_omit_message_unit(unit) {
612            drop_present_unit(buffer, unit);
613        } else if T::folds_when_present() {
614            fold_field(buffer, unit);
615        } else {
616            debug_assert!(!T::omits_default_after_encode());
617            debug_assert!(!unit.is_segment());
618        }
619        Ok(())
620    }
621}
622
623fn should_omit_message_unit(unit: &Unit) -> bool {
624    unit.size() == 1
625}
626
627fn drop_present_unit(buffer: &mut Buffer, unit: &mut Unit) {
628    if unit.is_segment() {
629        let seg = unit.segment_info();
630        debug_assert_eq!(seg.pos, buffer.len());
631        buffer.shrink(seg.len);
632    }
633    *unit = Unit::empty();
634}
635
636#[inline(always)]
637pub fn copy_words(words: &[u32], buffer: &mut Buffer, fold: bool) -> Unit {
638    if fold && words.len() < 4 {
639        return Unit::inline(words);
640    }
641    let last = buffer.len();
642    buffer.put_words(words);
643    Unit::segment(last, buffer.len())
644}
645
646macro_rules! impl_scalar_field {
647    ($ty:ty) => {
648        impl<'a> MutableField<'a> for $ty {
649            fn decode(field: FieldView<'a>) -> Option<Self> {
650                field.scalar::<$ty>()
651            }
652
653            fn detect(field: FieldView<'a>) -> Option<&'a [u32]> {
654                field.detect_scalar()
655            }
656
657            fn folds_when_present() -> bool
658            where
659                Self: Sized,
660            {
661                false
662            }
663
664            fn is_empty_field(&self) -> bool {
665                *self == 0 as $ty
666            }
667
668            fn omits_default_after_encode() -> bool
669            where
670                Self: Sized,
671            {
672                false
673            }
674
675            fn encode(&self, _buffer: &mut Buffer) -> Result<Unit, MutableError> {
676                Ok(serialize_scalar::<$ty>(*self))
677            }
678        }
679
680        impl<'a> MutableArrayElement<'a> for $ty {
681            fn decode_array(words: &'a [u32]) -> Option<Vec<Self>> {
682                Some(
683                    ArrayView::new(words)?
684                        .scalars::<$ty>()?
685                        .iter()
686                        .collect::<Vec<_>>(),
687                )
688            }
689
690            fn encode_array(values: &[Self], buffer: &mut Buffer) -> Result<Unit, MutableError> {
691                let width = <$ty as Scalar>::WIDTH as u32;
692                if values.is_empty() {
693                    return Ok(Unit::inline(&[width]));
694                }
695                let last = buffer.len();
696                for value in values.iter().rev() {
697                    value
698                        .write_words(buffer.expand(<$ty as Scalar>::WIDTH))
699                        .expect("scalar width must match");
700                }
701                buffer.put(((values.len() as u32) << 2) | width);
702                Ok(Unit::segment(last, buffer.len()))
703            }
704        }
705    };
706}
707
708macro_rules! impl_scalar_map_key {
709    ($ty:ty, $map_kind:ident) => {
710        impl<'a> MutableMapKey<'a> for $ty {
711            fn decode_key(field: FieldView<'a>) -> Option<Self> {
712                field.scalar::<$ty>()
713            }
714
715            fn detect_key(field: FieldView<'a>) -> Option<&'a [u32]> {
716                field.detect_scalar()
717            }
718
719            fn encode_key(&self, _buffer: &mut Buffer) -> Result<Unit, MutableError> {
720                Ok(serialize_scalar::<$ty>(*self))
721            }
722
723            fn key_kind() -> MutableMapKeyKind {
724                MutableMapKeyKind::$map_kind
725            }
726
727            fn write_key_bytes<'b>(&'b self, scratch: &'b mut [u8; 8]) -> &'b [u8] {
728                let bytes = MapKey::as_key_bytes(self);
729                let len = bytes.len();
730                scratch[..len].copy_from_slice(&bytes);
731                &scratch[..len]
732            }
733        }
734    };
735}
736
737impl<'a> MutableField<'a> for bool {
738    fn decode(field: FieldView<'a>) -> Option<Self> {
739        field.scalar::<bool>()
740    }
741
742    fn detect(field: FieldView<'a>) -> Option<&'a [u32]> {
743        field.detect_scalar()
744    }
745
746    fn folds_when_present() -> bool
747    where
748        Self: Sized,
749    {
750        false
751    }
752
753    fn is_empty_field(&self) -> bool {
754        !*self
755    }
756
757    fn omits_default_after_encode() -> bool
758    where
759        Self: Sized,
760    {
761        false
762    }
763
764    fn encode(&self, _buffer: &mut Buffer) -> Result<Unit, MutableError> {
765        Ok(serialize_bool(*self))
766    }
767}
768
769impl<'a> MutableArrayElement<'a> for bool {
770    fn decode_array(words: &'a [u32]) -> Option<Vec<Self>> {
771        Some(StringView::new(words)?.as_bool_array().iter().collect())
772    }
773
774    fn detect_array_field(field: FieldView<'a>) -> Option<&'a [u32]> {
775        field.detect_string()
776    }
777
778    fn detect_array_words(words: &'a [u32]) -> Option<&'a [u32]> {
779        StringView::detect(words)
780    }
781
782    fn encode_array(values: &[Self], buffer: &mut Buffer) -> Result<Unit, MutableError> {
783        let bytes = values
784            .iter()
785            .map(|value| u8::from(*value))
786            .collect::<Vec<_>>();
787        serialize_bytes(&bytes, buffer).ok_or_else(|| MutableError::SerializeFailed {
788            descriptor: "<array>".to_owned(),
789            field: "<bool-array>".to_owned(),
790        })
791    }
792}
793
794impl_scalar_field!(i32);
795impl_scalar_field!(u32);
796impl_scalar_field!(i64);
797impl_scalar_field!(u64);
798impl_scalar_field!(f32);
799impl_scalar_field!(f64);
800impl_scalar_map_key!(i32, I32);
801impl_scalar_map_key!(u32, U32);
802impl_scalar_map_key!(i64, I64);
803impl_scalar_map_key!(u64, U64);
804
805impl<'a> MutableField<'a> for String {
806    fn decode(field: FieldView<'a>) -> Option<Self> {
807        Some(field.string()?.as_str()?.to_owned())
808    }
809
810    fn detect(field: FieldView<'a>) -> Option<&'a [u32]> {
811        field.detect_string()
812    }
813
814    fn is_empty_field(&self) -> bool {
815        self.is_empty()
816    }
817
818    fn omits_default_after_encode() -> bool
819    where
820        Self: Sized,
821    {
822        false
823    }
824
825    fn encode(&self, buffer: &mut Buffer) -> Result<Unit, MutableError> {
826        serialize_str(self, buffer).ok_or_else(|| MutableError::SerializeFailed {
827            descriptor: "<string>".to_owned(),
828            field: "<encode>".to_owned(),
829        })
830    }
831}
832
833impl<'a> MutableArrayElement<'a> for String {
834    fn decode_array(words: &'a [u32]) -> Option<Vec<Self>> {
835        let array = ArrayView::new(words)?;
836        let mut values = Vec::with_capacity(array.len());
837        for item in array.iter() {
838            values.push(Self::decode(item)?);
839        }
840        Some(values)
841    }
842
843    fn encode_array(values: &[Self], buffer: &mut Buffer) -> Result<Unit, MutableError> {
844        encode_object_array(values, buffer)
845    }
846}
847
848impl<'a> MutableMapKey<'a> for String {
849    fn decode_key(field: FieldView<'a>) -> Option<Self> {
850        Some(field.string()?.as_str()?.to_owned())
851    }
852
853    fn detect_key(field: FieldView<'a>) -> Option<&'a [u32]> {
854        field.detect_string()
855    }
856
857    fn encode_key(&self, buffer: &mut Buffer) -> Result<Unit, MutableError> {
858        serialize_str(self, buffer).ok_or_else(|| MutableError::SerializeFailed {
859            descriptor: "<map>".to_owned(),
860            field: "<string-key>".to_owned(),
861        })
862    }
863
864    fn key_kind() -> MutableMapKeyKind {
865        MutableMapKeyKind::String
866    }
867
868    fn borrowed_key_bytes(&self) -> Option<&[u8]> {
869        Some(self.as_bytes())
870    }
871
872    fn write_key_bytes<'b>(&'b self, _scratch: &'b mut [u8; 8]) -> &'b [u8] {
873        self.as_bytes()
874    }
875}
876
877impl<'a> MutableField<'a> for Vec<u8> {
878    fn decode(field: FieldView<'a>) -> Option<Self> {
879        Some(field.string()?.as_bytes().to_vec())
880    }
881
882    fn detect(field: FieldView<'a>) -> Option<&'a [u32]> {
883        field.detect_string()
884    }
885
886    fn is_empty_field(&self) -> bool {
887        self.is_empty()
888    }
889
890    fn omits_default_after_encode() -> bool
891    where
892        Self: Sized,
893    {
894        false
895    }
896
897    fn encode(&self, buffer: &mut Buffer) -> Result<Unit, MutableError> {
898        serialize_bytes(self, buffer).ok_or_else(|| MutableError::SerializeFailed {
899            descriptor: "<bytes>".to_owned(),
900            field: "<encode>".to_owned(),
901        })
902    }
903}
904
905impl<'a> MutableArrayElement<'a> for Vec<u8> {
906    fn decode_array(words: &'a [u32]) -> Option<Vec<Self>> {
907        let array = ArrayView::new(words)?;
908        let mut values = Vec::with_capacity(array.len());
909        for item in array.iter() {
910            values.push(Self::decode(item)?);
911        }
912        Some(values)
913    }
914
915    fn encode_array(values: &[Self], buffer: &mut Buffer) -> Result<Unit, MutableError> {
916        encode_object_array(values, buffer)
917    }
918}
919
920impl<'a, T: MutableArrayElement<'a>> MutableField<'a> for MutableArray<'a, T> {
921    fn decode(field: FieldView<'a>) -> Option<Self> {
922        Self::from_words(field.object_words()?)
923    }
924
925    #[inline(always)]
926    fn detect(field: FieldView<'a>) -> Option<&'a [u32]> {
927        Self::detect_array_field(field)
928    }
929
930    fn encode(&self, buffer: &mut Buffer) -> Result<Unit, MutableError> {
931        self.encode_to_unit(buffer)
932    }
933
934    fn is_empty_field(&self) -> bool {
935        self.values.is_empty()
936    }
937
938    fn omits_default_after_encode() -> bool
939    where
940        Self: Sized,
941    {
942        false
943    }
944
945    fn is_dirty(&self) -> bool {
946        self.dirty || self.values.iter().any(MutableField::has_nested_dirty)
947    }
948
949    fn has_nested_dirty(&self) -> bool {
950        self.is_dirty()
951    }
952}
953
954impl<'a, K: MutableMapKey<'a>, V: MutableField<'a>> MutableField<'a> for MutableMap<'a, K, V> {
955    fn decode(field: FieldView<'a>) -> Option<Self> {
956        Self::from_words(field.object_words()?)
957    }
958
959    #[inline(always)]
960    fn detect(field: FieldView<'a>) -> Option<&'a [u32]> {
961        detect_map_words::<K, V>(field.object_words()?)
962    }
963
964    fn encode(&self, buffer: &mut Buffer) -> Result<Unit, MutableError> {
965        self.encode_to_unit(buffer)
966    }
967
968    fn is_empty_field(&self) -> bool {
969        self.entries.is_empty()
970    }
971
972    fn omits_default_after_encode() -> bool
973    where
974        Self: Sized,
975    {
976        false
977    }
978
979    fn is_dirty(&self) -> bool {
980        self.dirty
981            || self
982                .entries
983                .iter()
984                .any(|(_, value)| value.has_nested_dirty())
985    }
986
987    fn has_nested_dirty(&self) -> bool {
988        self.is_dirty()
989    }
990}
991
992impl<'a, T: MutableArrayElement<'a>> MutableArrayElement<'a> for MutableArray<'a, T> {
993    fn decode_array(words: &'a [u32]) -> Option<Vec<Self>> {
994        let array = ArrayView::new(words)?;
995        let mut values = Vec::with_capacity(array.len());
996        for item in array.iter() {
997            values.push(Self::from_words(item.object_words()?)?);
998        }
999        Some(values)
1000    }
1001
1002    #[inline(always)]
1003    fn detect_array_field(field: FieldView<'a>) -> Option<&'a [u32]> {
1004        field
1005            .object_words()
1006            .and_then(detect_array_words::<T>)
1007            .or_else(|| T::detect_array_field(field))
1008    }
1009
1010    fn encode_array(values: &[Self], buffer: &mut Buffer) -> Result<Unit, MutableError> {
1011        encode_object_array(values, buffer)
1012    }
1013}
1014
1015impl<'a, K: MutableMapKey<'a>, V: MutableField<'a>> MutableArrayElement<'a>
1016    for MutableMap<'a, K, V>
1017{
1018    fn decode_array(words: &'a [u32]) -> Option<Vec<Self>> {
1019        let array = ArrayView::new(words)?;
1020        let mut values = Vec::with_capacity(array.len());
1021        for item in array.iter() {
1022            values.push(Self::from_words(item.object_words()?)?);
1023        }
1024        Some(values)
1025    }
1026
1027    fn encode_array(values: &[Self], buffer: &mut Buffer) -> Result<Unit, MutableError> {
1028        encode_object_array(values, buffer)
1029    }
1030}
1031
1032impl<'a, T: MutableField<'a>> MutableField<'a> for Box<T> {
1033    fn decode(field: FieldView<'a>) -> Option<Self> {
1034        Some(Box::new(T::decode(field)?))
1035    }
1036
1037    #[inline(always)]
1038    fn detect(field: FieldView<'a>) -> Option<&'a [u32]> {
1039        T::detect(field)
1040    }
1041
1042    #[inline(always)]
1043    fn encode(&self, buffer: &mut Buffer) -> Result<Unit, MutableError> {
1044        self.as_ref().encode(buffer)
1045    }
1046
1047    #[inline(always)]
1048    fn is_dirty(&self) -> bool {
1049        self.as_ref().is_dirty()
1050    }
1051
1052    #[inline(always)]
1053    fn has_nested_dirty(&self) -> bool {
1054        self.as_ref().has_nested_dirty()
1055    }
1056}
1057
1058fn encode_object_array<'a, T: MutableField<'a>>(
1059    values: &[T],
1060    buffer: &mut Buffer,
1061) -> Result<Unit, MutableError> {
1062    const STACK_UNITS: usize = 32;
1063
1064    if values.is_empty() {
1065        return Ok(Unit::inline(&[1]));
1066    }
1067    let last = buffer.len();
1068    if values.len() <= STACK_UNITS {
1069        let mut units = array::from_fn::<_, STACK_UNITS, _>(|_| Unit::empty());
1070        for i in (0..values.len()).rev() {
1071            units[i] = values[i].encode(buffer)?;
1072        }
1073        return serialize_array_at_mut(&mut units[..values.len()], buffer, last).ok_or_else(|| {
1074            MutableError::SerializeFailed {
1075                descriptor: "<array>".to_owned(),
1076                field: "<encode>".to_owned(),
1077            }
1078        });
1079    }
1080
1081    let mut units = vec![Unit::empty(); values.len()];
1082    for i in (0..values.len()).rev() {
1083        units[i] = values[i].encode(buffer)?;
1084    }
1085    serialize_array_at_mut(&mut units, buffer, last).ok_or_else(|| MutableError::SerializeFailed {
1086        descriptor: "<array>".to_owned(),
1087        field: "<encode>".to_owned(),
1088    })
1089}
1090
1091#[cfg(test)]
1092mod tests {
1093    use super::{MutableArray, MutableMap, drop_present_unit, should_omit_message_unit};
1094    use crate::mutable::MutableField;
1095    use crate::{ArrayView, Buffer, MapView, Unit};
1096
1097    #[test]
1098    fn array_ex_iter_mut_marks_collection_dirty() {
1099        let mut array = MutableArray::from(vec![1u32, 2u32]);
1100        assert!(!array.is_dirty());
1101
1102        for value in &mut array {
1103            *value += 10;
1104        }
1105
1106        assert!(array.is_dirty());
1107        assert_eq!(array.as_slice(), &[11, 12]);
1108    }
1109
1110    #[test]
1111    fn map_ex_get_mut_marks_collection_dirty() {
1112        let mut map = MutableMap::from_iter([("alpha".to_owned(), 1u32)]);
1113        assert!(!map.is_dirty());
1114
1115        *map.get_mut("alpha").unwrap() = 7;
1116
1117        assert!(map.is_dirty());
1118        assert_eq!(map.get("alpha"), Some(&7));
1119    }
1120
1121    #[test]
1122    fn map_ex_mut_into_iter_marks_collection_dirty() {
1123        let mut map =
1124            MutableMap::from_iter([("alpha".to_owned(), 1u32), ("beta".to_owned(), 2u32)]);
1125        assert!(!map.is_dirty());
1126
1127        for (_, value) in &mut map {
1128            *value *= 2;
1129        }
1130
1131        assert!(map.is_dirty());
1132        assert_eq!(map.get("alpha"), Some(&2));
1133        assert_eq!(map.get("beta"), Some(&4));
1134    }
1135
1136    #[test]
1137    fn map_ex_supports_borrowed_string_lookup() {
1138        let mut map =
1139            MutableMap::from_iter([("alpha".to_owned(), 1u32), ("beta".to_owned(), 2u32)]);
1140
1141        assert!(map.contains_key("alpha"));
1142        assert_eq!(map.get("beta"), Some(&2));
1143        assert_eq!(map.remove("alpha"), Some(1));
1144        assert!(!map.contains_key("alpha"));
1145    }
1146
1147    #[test]
1148    fn default_present_units_are_omitted_by_shape() {
1149        assert!(should_omit_message_unit(&Unit::inline(&[0])));
1150        assert!(should_omit_message_unit(&Unit::inline(&[1])));
1151        assert!(!should_omit_message_unit(&Unit::inline(&[0, 0])));
1152        assert!(!should_omit_message_unit(&Unit::inline(&[2, 0])));
1153    }
1154
1155    #[test]
1156    fn dropping_segment_present_unit_rewinds_buffer() {
1157        let mut buffer = Buffer::new();
1158        buffer.put(0);
1159        let mut unit = Unit::segment(0, buffer.len());
1160
1161        assert!(should_omit_message_unit(&unit));
1162        drop_present_unit(&mut buffer, &mut unit);
1163
1164        assert!(buffer.is_empty());
1165        assert!(unit.is_empty());
1166    }
1167
1168    #[test]
1169    fn mutable_nested_float_arrays_roundtrip() {
1170        let mut rows = MutableArray::new();
1171        rows.push(MutableArray::new());
1172        rows.push(MutableArray::from(vec![7.0f32, 8.0, 9.0]));
1173
1174        let mut buffer = Buffer::new();
1175        let unit = rows.encode(&mut buffer).unwrap();
1176        assert!(unit.is_segment());
1177
1178        let view = ArrayView::new(buffer.view()).unwrap();
1179        assert_eq!(view.len(), 2);
1180
1181        let row0 = ArrayView::new(view.field(0).unwrap().object_words().unwrap()).unwrap();
1182        assert!(row0.scalars::<f32>().unwrap().is_empty());
1183
1184        let row1_words = view.field(1).unwrap().object_words().unwrap();
1185        let row1 = ArrayView::new(row1_words).unwrap();
1186        assert_eq!(row1.width(), 1, "row1 words: {:?}", row1_words);
1187        assert_eq!(
1188            row1.scalars::<f32>().unwrap().iter().collect::<Vec<_>>(),
1189            vec![7.0, 8.0, 9.0]
1190        );
1191    }
1192
1193    #[test]
1194    fn mutable_string_key_float_array_map_roundtrip() {
1195        let mut map = MutableMap::new();
1196        map.insert(
1197            "lv5".to_owned(),
1198            MutableArray::from(vec![51.0f32, 52.0, 53.0]),
1199        );
1200        map.insert("lv9".to_owned(), MutableArray::from(vec![91.0f32, 92.0]));
1201
1202        let mut buffer = Buffer::new();
1203        let unit = map.encode(&mut buffer).unwrap();
1204        assert!(unit.is_segment());
1205
1206        let view = MapView::new(buffer.view()).unwrap();
1207        let available = view
1208            .iter()
1209            .filter_map(|pair| {
1210                pair.key()
1211                    .string()
1212                    .and_then(|key| key.as_str().map(str::to_owned))
1213            })
1214            .collect::<Vec<_>>();
1215        let lv5 = view
1216            .find_str("lv5")
1217            .unwrap_or_else(|| panic!("available keys: {available:?}, words: {:?}", buffer.view()))
1218            .value()
1219            .array()
1220            .unwrap();
1221        assert_eq!(
1222            lv5.scalars::<f32>().unwrap().iter().collect::<Vec<_>>(),
1223            vec![51.0, 52.0, 53.0]
1224        );
1225        let lv9 = view.find_str("lv9").unwrap().value().array().unwrap();
1226        assert_eq!(
1227            lv9.scalars::<f32>().unwrap().iter().collect::<Vec<_>>(),
1228            vec![91.0, 92.0]
1229        );
1230    }
1231}
protocache_core/mutable.rs

protocache_core/
mutable.rs
