spacetimedb_sats/
de.rs

1// Some parts copyright Serde developers under the MIT / Apache-2.0 licenses at your option.
2// See `serde` version `v1.0.169` for the parts where MIT / Apache-2.0 applies.
3
4mod impls;
5#[cfg(any(test, feature = "serde"))]
6pub mod serde;
7
8#[doc(hidden)]
9pub use impls::{visit_named_product, visit_seq_product, WithBound};
10
11use crate::buffer::BufReader;
12use crate::{bsatn, i256, u256};
13use core::fmt;
14use core::marker::PhantomData;
15use smallvec::SmallVec;
16use std::borrow::Borrow;
17
18/// A data format that can deserialize any data structure supported by SATS.
19///
20/// The `Deserializer` trait in SATS performs the same function as `serde::Deserializer` in [`serde`].
21/// See the documentation of `serde::Deserializer` for more information of the data model.
22///
23/// Implementations of `Deserialize` map themselves into this data model
24/// by passing to the `Deserializer` a visitor that can receive the necessary types.
25/// The kind of visitor depends on the `deserialize_*` method.
26/// Unlike in Serde, there isn't a single monolithic `Visitor` trait,
27/// but rather, this functionality is split up into more targeted traits such as `SumVisitor<'de>`.
28///
29/// The lifetime `'de` allows us to deserialize lifetime-generic types in a zero-copy fashion.
30///
31/// [`serde`]: https://crates.io/crates/serde
32pub trait Deserializer<'de>: Sized {
33    /// The error type that can be returned if some error occurs during deserialization.
34    type Error: Error;
35
36    /// Deserializes a product value from the input.
37    fn deserialize_product<V: ProductVisitor<'de>>(self, visitor: V) -> Result<V::Output, Self::Error>;
38
39    /// Deserializes a sum value from the input.
40    ///
41    /// The entire process of deserializing a sum, starting from `deserialize(args...)`, is roughly:
42    ///
43    /// - [`deserialize`][Deserialize::deserialize] calls this method,
44    ///   [`deserialize_sum(sum_visitor)`](Deserializer::deserialize_sum),
45    ///   providing us with a [`sum_visitor`](SumVisitor).
46    ///
47    /// - This method calls [`sum_visitor.visit_sum(sum_access)`](SumVisitor::visit_sum),
48    ///   where [`sum_access`](SumAccess) deals with extracting the tag and the variant data,
49    ///   with the latter provided as [`VariantAccess`]).
50    ///   The `SumVisitor` will then assemble these into the representation of a sum value
51    ///   that the [`Deserialize`] implementation wants.
52    ///
53    /// - [`visit_sum`](SumVisitor::visit_sum) then calls
54    ///   [`sum_access.variant(variant_visitor)`](SumAccess::variant),
55    ///   and uses the provided `variant_visitor` to translate extracted variant names / tags
56    ///   into something that is meaningful for `visit_sum`, e.g., an index.
57    ///
58    ///   The call to `variant` will also return [`variant_access`](VariantAccess)
59    ///   that can deserialize the contents of the variant.
60    ///
61    /// - Finally, after `variant` returns,
62    ///   `visit_sum` deserializes the variant data using
63    ///   [`variant_access.deserialize_seed(seed)`](VariantAccess::deserialize_seed)
64    ///   or [`variant_access.deserialize()`](VariantAccess::deserialize).
65    ///   This part may require some conditional logic depending on the identified variant.
66    ///
67    ///
68    /// The data format will also return an object ([`VariantAccess`])
69    /// that can deserialize the contents of the variant.
70    fn deserialize_sum<V: SumVisitor<'de>>(self, visitor: V) -> Result<V::Output, Self::Error>;
71
72    /// Deserializes a `bool` value from the input.
73    fn deserialize_bool(self) -> Result<bool, Self::Error>;
74
75    /// Deserializes a `u8` value from the input.
76    fn deserialize_u8(self) -> Result<u8, Self::Error>;
77
78    /// Deserializes a `u16` value from the input.
79    fn deserialize_u16(self) -> Result<u16, Self::Error>;
80
81    /// Deserializes a `u32` value from the input.
82    fn deserialize_u32(self) -> Result<u32, Self::Error>;
83
84    /// Deserializes a `u64` value from the input.
85    fn deserialize_u64(self) -> Result<u64, Self::Error>;
86
87    /// Deserializes a `u128` value from the input.
88    fn deserialize_u128(self) -> Result<u128, Self::Error>;
89
90    /// Deserializes a `u256` value from the input.
91    fn deserialize_u256(self) -> Result<u256, Self::Error>;
92
93    /// Deserializes an `i8` value from the input.
94    fn deserialize_i8(self) -> Result<i8, Self::Error>;
95
96    /// Deserializes an `i16` value from the input.
97    fn deserialize_i16(self) -> Result<i16, Self::Error>;
98
99    /// Deserializes an `i32` value from the input.
100    fn deserialize_i32(self) -> Result<i32, Self::Error>;
101
102    /// Deserializes an `i64` value from the input.
103    fn deserialize_i64(self) -> Result<i64, Self::Error>;
104
105    /// Deserializes an `i128` value from the input.
106    fn deserialize_i128(self) -> Result<i128, Self::Error>;
107
108    /// Deserializes an `i256` value from the input.
109    fn deserialize_i256(self) -> Result<i256, Self::Error>;
110
111    /// Deserializes an `f32` value from the input.
112    fn deserialize_f32(self) -> Result<f32, Self::Error>;
113
114    /// Deserializes an `f64` value from the input.
115    fn deserialize_f64(self) -> Result<f64, Self::Error>;
116
117    /// Deserializes a string-like object the input.
118    fn deserialize_str<V: SliceVisitor<'de, str>>(self, visitor: V) -> Result<V::Output, Self::Error>;
119
120    /// Deserializes an `&str` string value.
121    fn deserialize_str_slice(self) -> Result<&'de str, Self::Error> {
122        self.deserialize_str(BorrowedSliceVisitor)
123    }
124
125    /// Deserializes a byte slice-like value.
126    fn deserialize_bytes<V: SliceVisitor<'de, [u8]>>(self, visitor: V) -> Result<V::Output, Self::Error>;
127
128    /// Deserializes an array value.
129    ///
130    /// This is typically the same as [`deserialize_array_seed`](Deserializer::deserialize_array_seed)
131    /// with an uninteresting `seed` value.
132    fn deserialize_array<V: ArrayVisitor<'de, T>, T: Deserialize<'de>>(
133        self,
134        visitor: V,
135    ) -> Result<V::Output, Self::Error> {
136        self.deserialize_array_seed(visitor, PhantomData)
137    }
138
139    /// Deserializes an array value.
140    ///
141    /// The deserialization is provided with a `seed` value.
142    fn deserialize_array_seed<V: ArrayVisitor<'de, T::Output>, T: DeserializeSeed<'de> + Clone>(
143        self,
144        visitor: V,
145        seed: T,
146    ) -> Result<V::Output, Self::Error>;
147}
148
149/// The `Error` trait allows [`Deserialize`] implementations to create descriptive error messages
150/// belonging to the [`Deserializer`] against which they are currently running.
151///
152/// Every [`Deserializer`] declares an [`Error`] type
153/// that encompasses both general-purpose deserialization errors
154/// as well as errors specific to the particular deserialization format.
155///
156/// Most deserializers should only need to provide the [`Error::custom`] method
157/// and inherit the default behavior for the other methods.
158pub trait Error: Sized {
159    /// Raised when there is general error when deserializing a type.
160    fn custom(msg: impl fmt::Display) -> Self;
161
162    /// Deserializing named products are not supported for this visitor.
163    fn named_products_not_supported() -> Self {
164        Self::custom("named products not supported")
165    }
166
167    /// The product length was not as promised.
168    fn invalid_product_length<'de, T: ProductVisitor<'de>>(len: usize, expected: &T) -> Self {
169        Self::custom(format_args!(
170            "invalid length {}, expected {}",
171            len,
172            fmt_invalid_len(expected)
173        ))
174    }
175
176    /// There was a missing field at `index`.
177    fn missing_field<'de, T: ProductVisitor<'de>>(index: usize, field_name: Option<&str>, prod: &T) -> Self {
178        Self::custom(error_on_field("missing ", index, field_name, prod))
179    }
180
181    /// A field with `index` was specified more than once.
182    fn duplicate_field<'de, T: ProductVisitor<'de>>(index: usize, field_name: Option<&str>, prod: &T) -> Self {
183        Self::custom(error_on_field("duplicate ", index, field_name, prod))
184    }
185
186    /// A field with name `field_name` does not exist.
187    fn unknown_field_name<'de, T: FieldNameVisitor<'de>>(field_name: &str, expected: &T) -> Self {
188        let el_ty = match expected.kind() {
189            ProductKind::Normal => "field",
190            ProductKind::ReducerArgs => "reducer argument",
191        };
192        if let Some(one_of) = one_of_names(|| expected.field_names()) {
193            Self::custom(format_args!("unknown {el_ty} `{field_name}`, expected {one_of}"))
194        } else {
195            Self::custom(format_args!("unknown {el_ty} `{field_name}`, there are no {el_ty}s"))
196        }
197    }
198
199    /// The `tag` does not specify a variant of the sum type.
200    fn unknown_variant_tag<'de, T: SumVisitor<'de>>(tag: u8, expected: &T) -> Self {
201        Self::custom(format_args!(
202            "unknown tag {tag:#x} for sum type {}",
203            expected.sum_name().unwrap_or("<unknown>"),
204        ))
205    }
206
207    /// The `name` is not that of a variant of the sum type.
208    fn unknown_variant_name<'de, T: VariantVisitor<'de>>(name: &str, expected: &T) -> Self {
209        if let Some(one_of) = one_of_names(|| expected.variant_names().map(Some)) {
210            Self::custom(format_args!("unknown variant `{name}`, expected {one_of}",))
211        } else {
212            Self::custom(format_args!("unknown variant `{name}`, there are no variants"))
213        }
214    }
215}
216
217/// Turns a closure `impl Fn(&mut Formatter) -> Result` into a `Display`able object.
218pub struct FDisplay<F>(F);
219
220impl<F: Fn(&mut fmt::Formatter) -> fmt::Result> fmt::Display for FDisplay<F> {
221    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
222        (self.0)(f)
223    }
224}
225
226/// Turns a closure `F: Fn(&mut Formatter) -> Result` into a `Display`able object.
227pub fn fmt_fn<F: Fn(&mut fmt::Formatter) -> fmt::Result>(f: F) -> FDisplay<F> {
228    FDisplay(f)
229}
230
231/// Returns an error message for a `problem` with field at `index` and an optional `name`.
232fn error_on_field<'a, 'de>(
233    problem: &'static str,
234    index: usize,
235    name: Option<&'a str>,
236    prod: &impl ProductVisitor<'de>,
237) -> impl fmt::Display + 'a {
238    let field_kind = match prod.product_kind() {
239        ProductKind::Normal => "field",
240        ProductKind::ReducerArgs => "reducer argument",
241    };
242    fmt_fn(move |f| {
243        // e.g. "missing field `foo`"
244        f.write_str(problem)?;
245        f.write_str(field_kind)?;
246        if let Some(name) = name {
247            write!(f, " `{name}`")
248        } else {
249            write!(f, " (index {index})")
250        }
251    })
252}
253
254/// Returns an error message for invalid product type lengths.
255fn fmt_invalid_len<'de>(
256    expected: &impl ProductVisitor<'de>,
257) -> FDisplay<impl '_ + Fn(&mut fmt::Formatter) -> fmt::Result> {
258    fmt_fn(|f| {
259        let ty = match expected.product_kind() {
260            ProductKind::Normal => "product type",
261            ProductKind::ReducerArgs => "reducer args for",
262        };
263        let name = expected.product_name().unwrap_or("<product>");
264        let len = expected.product_len();
265
266        write!(f, "{ty} {name} with {len} elements")
267    })
268}
269
270/// A visitor walking through a [`Deserializer`] for products.
271pub trait ProductVisitor<'de> {
272    /// The resulting product.
273    type Output;
274
275    /// Returns the name of the product, if any.
276    fn product_name(&self) -> Option<&str>;
277
278    /// Returns the length of the product.
279    fn product_len(&self) -> usize;
280
281    /// Returns the kind of the product.
282    fn product_kind(&self) -> ProductKind {
283        ProductKind::Normal
284    }
285
286    /// The input contains an unnamed product.
287    fn visit_seq_product<A: SeqProductAccess<'de>>(self, prod: A) -> Result<Self::Output, A::Error>;
288
289    /// The input contains a named product.
290    fn visit_named_product<A: NamedProductAccess<'de>>(self, prod: A) -> Result<Self::Output, A::Error>;
291}
292
293/// What kind of product is this?
294#[derive(Clone, Copy)]
295pub enum ProductKind {
296    // A normal product.
297    Normal,
298    /// A product in the context of reducer arguments.
299    ReducerArgs,
300}
301
302/// Provides a [`ProductVisitor`] with access to each element of the unnamed product in the input.
303///
304/// This is a trait that a [`Deserializer`] passes to a [`ProductVisitor`] implementation.
305pub trait SeqProductAccess<'de> {
306    /// The error type that can be returned if some error occurs during deserialization.
307    type Error: Error;
308
309    /// Deserializes an `T` from the input.
310    ///
311    /// Returns `Ok(Some(value))` for the next element in the product,
312    /// or `Ok(None)` if there are no more remaining items.
313    ///
314    /// This method exists as a convenience for [`Deserialize`] implementations.
315    /// [`SeqProductAccess`] implementations should not override the default behavior.
316    fn next_element<T: Deserialize<'de>>(&mut self) -> Result<Option<T>, Self::Error> {
317        self.next_element_seed(PhantomData)
318    }
319
320    /// Statefully deserializes `T::Output` from the input provided a `seed` value.
321    ///
322    /// Returns `Ok(Some(value))` for the next element in the unnamed product,
323    /// or `Ok(None)` if there are no more remaining items.
324    ///
325    /// [`Deserialize`] implementations should typically use
326    /// [`next_element`](SeqProductAccess::next_element) instead.
327    fn next_element_seed<T: DeserializeSeed<'de>>(&mut self, seed: T) -> Result<Option<T::Output>, Self::Error>;
328}
329
330/// Provides a [`ProductVisitor`] with access to each element of the named product in the input.
331///
332/// This is a trait that a [`Deserializer`] passes to a [`ProductVisitor`] implementation.
333pub trait NamedProductAccess<'de> {
334    /// The error type that can be returned if some error occurs during deserialization.
335    type Error: Error;
336
337    /// Deserializes field name of type `V::Output`
338    /// from the input using a visitor provided by the deserializer.
339    fn get_field_ident<V: FieldNameVisitor<'de>>(&mut self, visitor: V) -> Result<Option<V::Output>, Self::Error>;
340
341    /// Deserializes field value of type `T` from the input.
342    ///
343    /// This method exists as a convenience for [`Deserialize`] implementations.
344    /// [`NamedProductAccess`] implementations should not override the default behavior.
345    fn get_field_value<T: Deserialize<'de>>(&mut self) -> Result<T, Self::Error> {
346        self.get_field_value_seed(PhantomData)
347    }
348
349    /// Statefully deserializes the field value `T::Output` from the input provided a `seed` value.
350    ///
351    /// [`Deserialize`] implementations should typically use
352    /// [`next_element`](NamedProductAccess::get_field_value) instead.
353    fn get_field_value_seed<T: DeserializeSeed<'de>>(&mut self, seed: T) -> Result<T::Output, Self::Error>;
354}
355
356/// Visitor used to deserialize the name of a field.
357pub trait FieldNameVisitor<'de> {
358    /// The resulting field name.
359    type Output;
360
361    /// The sort of product deserialized.
362    fn kind(&self) -> ProductKind {
363        ProductKind::Normal
364    }
365
366    /// Provides a list of valid field names.
367    ///
368    /// Where `None` is yielded, this indicates a nameless field.
369    fn field_names(&self) -> impl '_ + Iterator<Item = Option<&str>>;
370
371    /// Deserializes the name of a field using `name`.
372    fn visit<E: Error>(self, name: &str) -> Result<Self::Output, E>;
373
374    /// Deserializes the name of a field using `index`.
375    ///
376    /// Should only be called when `index` is already known to exist
377    /// and is expected to panic otherwise.
378    fn visit_seq(self, index: usize) -> Self::Output;
379}
380
381/// A visitor walking through a [`Deserializer`] for sums.
382///
383/// This side is provided by a [`Deserialize`] implementation
384/// when calling [`Deserializer::deserialize_sum`].
385pub trait SumVisitor<'de> {
386    /// The resulting sum.
387    type Output;
388
389    /// Returns the name of the sum, if any.
390    fn sum_name(&self) -> Option<&str>;
391
392    /// Returns whether an option is expected.
393    ///
394    /// The provided implementation does not.
395    fn is_option(&self) -> bool {
396        false
397    }
398
399    /// Drives the deserialization of a sum value.
400    ///
401    /// This method will ask the data format ([`A: SumAccess`][SumAccess])
402    /// which variant of the sum to select in terms of a variant name / tag.
403    /// `A` will use a [`VariantVisitor`], that `SumVisitor` has provided,
404    /// to translate into something that is meaningful for `visit_sum`, e.g., an index.
405    ///
406    /// The data format will also return an object ([`VariantAccess`])
407    /// that can deserialize the contents of the variant.
408    fn visit_sum<A: SumAccess<'de>>(self, data: A) -> Result<Self::Output, A::Error>;
409}
410
411/// Provides a [`SumVisitor`] access to the data of a sum in the input.
412///
413/// An `A: SumAccess` object is created by the [`D: Deserializer`]
414/// which passes `A` to a [`V: SumVisitor`] that `D` in turn was passed.
415/// `A` is then used by `V` to split tag and value input apart.
416pub trait SumAccess<'de> {
417    /// The error type that can be returned if some error occurs during deserialization.
418    type Error: Error;
419
420    /// The visitor used to deserialize the content of the sum variant.
421    type Variant: VariantAccess<'de, Error = Self::Error>;
422
423    /// Called to identify which variant to deserialize.
424    /// Returns a tuple with the result of identification (`V::Output`)
425    /// and the input to variant data deserialization.
426    ///
427    /// The `visitor` is provided by the [`Deserializer`].
428    /// This method is typically called from [`SumVisitor::visit_sum`]
429    /// which will provide the [`V: VariantVisitor`](VariantVisitor).
430    fn variant<V: VariantVisitor<'de>>(self, visitor: V) -> Result<(V::Output, Self::Variant), Self::Error>;
431}
432
433/// A visitor passed from [`SumVisitor`] to [`SumAccess::variant`]
434/// which the latter uses to decide what variant to deserialize.
435pub trait VariantVisitor<'de> {
436    /// The result of identifying a variant, e.g., some index type.
437    type Output;
438
439    /// Provides a list of variant names.
440    fn variant_names(&self) -> impl '_ + Iterator<Item = &str>;
441
442    /// Identify the variant based on `tag`.
443    fn visit_tag<E: Error>(self, tag: u8) -> Result<Self::Output, E>;
444
445    /// Identify the variant based on `name`.
446    fn visit_name<E: Error>(self, name: &str) -> Result<Self::Output, E>;
447}
448
449/// A visitor passed from [`SumAccess`] to [`SumVisitor::visit_sum`]
450/// which the latter uses to deserialize the data of a selected variant.
451pub trait VariantAccess<'de>: Sized {
452    type Error: Error;
453
454    /// Called when deserializing the contents of a sum variant.
455    ///
456    /// This method exists as a convenience for [`Deserialize`] implementations.
457    fn deserialize<T: Deserialize<'de>>(self) -> Result<T, Self::Error> {
458        self.deserialize_seed(PhantomData)
459    }
460
461    /// Called when deserializing the contents of a sum variant, and provided with a `seed` value.
462    fn deserialize_seed<T: DeserializeSeed<'de>>(self, seed: T) -> Result<T::Output, Self::Error>;
463}
464
465/// A `SliceVisitor` is provided a slice `T` of some elements by a [`Deserializer`]
466/// and is tasked with translating this slice to the `Output` type.
467pub trait SliceVisitor<'de, T: ToOwned + ?Sized>: Sized {
468    /// The output produced by this visitor.
469    type Output;
470
471    /// The input contains a slice.
472    ///
473    /// The lifetime of the slice is ephemeral
474    /// and it may be destroyed after this method returns.
475    fn visit<E: Error>(self, slice: &T) -> Result<Self::Output, E>;
476
477    /// The input contains a slice and ownership of the slice is being given to the [`SliceVisitor`].
478    fn visit_owned<E: Error>(self, buf: T::Owned) -> Result<Self::Output, E> {
479        self.visit(buf.borrow())
480    }
481
482    /// The input contains a slice that lives at least as long (`'de`) as the [`Deserializer`].
483    fn visit_borrowed<E: Error>(self, borrowed_slice: &'de T) -> Result<Self::Output, E> {
484        self.visit(borrowed_slice)
485    }
486}
487
488/// A visitor walking through a [`Deserializer`] for arrays.
489pub trait ArrayVisitor<'de, T> {
490    /// The output produced by this visitor.
491    type Output;
492
493    /// The input contains an array.
494    fn visit<A: ArrayAccess<'de, Element = T>>(self, vec: A) -> Result<Self::Output, A::Error>;
495}
496
497/// Provides an [`ArrayVisitor`] with access to each element of the array in the input.
498///
499/// This is a trait that a [`Deserializer`] passes to an [`ArrayVisitor`] implementation.
500pub trait ArrayAccess<'de> {
501    /// The element / base type of the array.
502    type Element;
503
504    /// The error type that can be returned if some error occurs during deserialization.
505    type Error: Error;
506
507    /// This returns `Ok(Some(value))` for the next element in the array,
508    /// or `Ok(None)` if there are no more remaining elements.
509    fn next_element(&mut self) -> Result<Option<Self::Element>, Self::Error>;
510
511    /// Returns the number of elements remaining in the array, if known.
512    fn size_hint(&self) -> Option<usize> {
513        None
514    }
515}
516
517/// `DeserializeSeed` is the stateful form of the [`Deserialize`] trait.
518pub trait DeserializeSeed<'de> {
519    /// The type produced by using this seed.
520    type Output;
521
522    /// Equivalent to the more common [`Deserialize::deserialize`] associated function,
523    /// except with some initial piece of data (the seed `self`) passed in.
524    fn deserialize<D: Deserializer<'de>>(self, deserializer: D) -> Result<Self::Output, D::Error>;
525}
526
527use crate::de::impls::BorrowedSliceVisitor;
528pub use spacetimedb_bindings_macro::Deserialize;
529
530/// A data structure that can be deserialized from any data format supported by the SpacetimeDB Algebraic Type System.
531///
532/// In most cases, implementations of `Deserialize` may be `#[derive(Deserialize)]`d.
533///
534/// The `Deserialize` trait in SATS performs the same function as `serde::Deserialize` in [`serde`].
535/// See the documentation of `serde::Deserialize` for more information of the data model.
536///
537/// The lifetime `'de` allows us to deserialize lifetime-generic types in a zero-copy fashion.
538///
539/// Do not manually implement this trait unless you know what you are doing.
540/// Implementations must be consistent with `Serialize for T`, `SpacetimeType for T` and `Serialize, Deserialize for AlgebraicValue`.
541/// Implementations that are inconsistent across these traits may result in data loss.
542///
543/// [`serde`]: https://crates.io/crates/serde
544pub trait Deserialize<'de>: Sized {
545    /// Deserialize this value from the given `deserializer`.
546    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>;
547
548    #[doc(hidden)]
549    /// Deserialize this value from the given the BSATN `deserializer`.
550    fn deserialize_from_bsatn<R: BufReader<'de>>(
551        deserializer: bsatn::Deserializer<'de, R>,
552    ) -> Result<Self, bsatn::DecodeError> {
553        Self::deserialize(deserializer)
554    }
555
556    /// used in the Deserialize for Vec<T> impl to allow specializing deserializing Vec<T> as bytes
557    #[doc(hidden)]
558    #[inline(always)]
559    fn __deserialize_vec<D: Deserializer<'de>>(deserializer: D) -> Result<Vec<Self>, D::Error> {
560        deserializer.deserialize_array(BasicVecVisitor)
561    }
562
563    #[doc(hidden)]
564    #[inline(always)]
565    fn __deserialize_array<D: Deserializer<'de>, const N: usize>(deserializer: D) -> Result<[Self; N], D::Error> {
566        deserializer.deserialize_array(BasicArrayVisitor)
567    }
568}
569
570/// A data structure that can be deserialized in SATS
571/// without borrowing any data from the deserializer.
572pub trait DeserializeOwned: for<'de> Deserialize<'de> {}
573impl<T: for<'de> Deserialize<'de>> DeserializeOwned for T {}
574
575impl<'de, T: Deserialize<'de>> DeserializeSeed<'de> for PhantomData<T> {
576    type Output = T;
577
578    fn deserialize<D: Deserializer<'de>>(self, deserializer: D) -> Result<Self::Output, D::Error> {
579        T::deserialize(deserializer)
580    }
581}
582
583/// A vector with two operations: `with_capacity` and `push`.
584pub trait GrowingVec<T> {
585    /// Create the collection with the given capacity.
586    fn with_capacity(cap: usize) -> Self;
587
588    /// Push to the vector the `elem`.
589    fn push(&mut self, elem: T);
590}
591
592impl<T> GrowingVec<T> for Vec<T> {
593    fn with_capacity(cap: usize) -> Self {
594        Self::with_capacity(cap)
595    }
596    fn push(&mut self, elem: T) {
597        self.push(elem)
598    }
599}
600
601impl<T, const N: usize> GrowingVec<T> for SmallVec<[T; N]> {
602    fn with_capacity(cap: usize) -> Self {
603        Self::with_capacity(cap)
604    }
605    fn push(&mut self, elem: T) {
606        self.push(elem)
607    }
608}
609
610/// A basic implementation of `ArrayVisitor::visit` using the provided size hint.
611pub fn array_visit<'de, A: ArrayAccess<'de>, V: GrowingVec<A::Element>>(mut access: A) -> Result<V, A::Error> {
612    let mut v = V::with_capacity(access.size_hint().unwrap_or(0));
613    while let Some(x) = access.next_element()? {
614        v.push(x)
615    }
616    Ok(v)
617}
618
619/// An implementation of [`ArrayVisitor<'de, T>`] where the output is a `Vec<T>`.
620pub struct BasicVecVisitor;
621
622impl<'de, T> ArrayVisitor<'de, T> for BasicVecVisitor {
623    type Output = Vec<T>;
624
625    fn visit<A: ArrayAccess<'de, Element = T>>(self, vec: A) -> Result<Self::Output, A::Error> {
626        array_visit(vec)
627    }
628}
629
630/// An implementation of [`ArrayVisitor<'de, T>`] where the output is a `SmallVec<[T; N]>`.
631pub struct BasicSmallVecVisitor<const N: usize>;
632
633impl<'de, T, const N: usize> ArrayVisitor<'de, T> for BasicSmallVecVisitor<N> {
634    type Output = SmallVec<[T; N]>;
635
636    fn visit<A: ArrayAccess<'de, Element = T>>(self, vec: A) -> Result<Self::Output, A::Error> {
637        array_visit(vec)
638    }
639}
640
641/// An implementation of [`ArrayVisitor<'de, T>`] where the output is a `[T; N]`.
642struct BasicArrayVisitor<const N: usize>;
643
644impl<'de, T, const N: usize> ArrayVisitor<'de, T> for BasicArrayVisitor<N> {
645    type Output = [T; N];
646
647    fn visit<A: ArrayAccess<'de, Element = T>>(self, mut vec: A) -> Result<Self::Output, A::Error> {
648        let mut v = arrayvec::ArrayVec::<T, N>::new();
649        while let Some(el) = vec.next_element()? {
650            v.try_push(el)
651                .map_err(|_| Error::custom("too many elements for array"))?
652        }
653        v.into_inner().map_err(|_| Error::custom("too few elements for array"))
654    }
655}
656
657/// Provided a list of names,
658/// returns a human readable list of all the names,
659/// or `None` in the case of an empty list of names.
660fn one_of_names<'a, I: Iterator<Item = Option<&'a str>>>(names: impl Fn() -> I) -> Option<impl fmt::Display> {
661    // Count how many names there are.
662    let count = names().count();
663
664    // There was at least one name; render those names.
665    (count != 0).then(move || {
666        fmt_fn(move |f| {
667            let mut anon_name = 0;
668            // An example of what happens for names "foo", "bar", and "baz":
669            //
670            // count = 1 -> "`foo`"
671            //       = 2 -> "`foo` or `bar`"
672            //       > 2 -> "one of `foo`, `bar`, or `baz`"
673            for (index, mut name) in names().enumerate() {
674                let mut name_buf: String = String::new();
675                let name = name.get_or_insert_with(|| {
676                    name_buf = format!("{anon_name}");
677                    anon_name += 1;
678                    &name_buf
679                });
680                match (count, index) {
681                    (1, _) => write!(f, "`{name}`"),
682                    (2, 1) => write!(f, "`{name}`"),
683                    (2, 2) => write!(f, "`or `{name}`"),
684                    (_, 1) => write!(f, "one of `{name}`"),
685                    (c, i) if i < c => write!(f, ", `{name}`"),
686                    (_, _) => write!(f, ", `, or {name}`"),
687                }?;
688            }
689
690            Ok(())
691        })
692    })
693}
694
695/// Deserializes `none` variant of an optional value.
696pub struct NoneAccess<E>(PhantomData<E>);
697
698impl<E: Error> NoneAccess<E> {
699    /// Returns a new [`NoneAccess`].
700    pub fn new() -> Self {
701        Self(PhantomData)
702    }
703}
704
705impl<E: Error> Default for NoneAccess<E> {
706    fn default() -> Self {
707        Self::new()
708    }
709}
710
711impl<'de, E: Error> SumAccess<'de> for NoneAccess<E> {
712    type Error = E;
713    type Variant = Self;
714
715    fn variant<V: VariantVisitor<'de>>(self, visitor: V) -> Result<(V::Output, Self::Variant), Self::Error> {
716        visitor.visit_name("none").map(|var| (var, self))
717    }
718}
719impl<'de, E: Error> VariantAccess<'de> for NoneAccess<E> {
720    type Error = E;
721    fn deserialize_seed<T: DeserializeSeed<'de>>(self, seed: T) -> Result<T::Output, Self::Error> {
722        seed.deserialize(UnitAccess::new())
723    }
724}
725
726/// Deserializes `some` variant of an optional value.
727pub struct SomeAccess<D>(D);
728
729impl<D> SomeAccess<D> {
730    /// Returns a new [`SomeAccess`] with a given deserializer for the `some` variant.
731    pub fn new(de: D) -> Self {
732        Self(de)
733    }
734}
735
736impl<'de, D: Deserializer<'de>> SumAccess<'de> for SomeAccess<D> {
737    type Error = D::Error;
738    type Variant = Self;
739
740    fn variant<V: VariantVisitor<'de>>(self, visitor: V) -> Result<(V::Output, Self::Variant), Self::Error> {
741        visitor.visit_name("some").map(|var| (var, self))
742    }
743}
744
745impl<'de, D: Deserializer<'de>> VariantAccess<'de> for SomeAccess<D> {
746    type Error = D::Error;
747    fn deserialize_seed<T: DeserializeSeed<'de>>(self, seed: T) -> Result<T::Output, Self::Error> {
748        seed.deserialize(self.0)
749    }
750}
751
752/// A `Deserializer` that represents a unit value.
753// used in the implementation of `VariantAccess for NoneAccess`
754pub struct UnitAccess<E>(PhantomData<E>);
755
756impl<E: Error> UnitAccess<E> {
757    /// Returns a new [`UnitAccess`].
758    pub fn new() -> Self {
759        Self(PhantomData)
760    }
761}
762
763impl<E: Error> Default for UnitAccess<E> {
764    fn default() -> Self {
765        Self::new()
766    }
767}
768
769impl<'de, E: Error> SeqProductAccess<'de> for UnitAccess<E> {
770    type Error = E;
771
772    fn next_element_seed<T: DeserializeSeed<'de>>(&mut self, _seed: T) -> Result<Option<T::Output>, Self::Error> {
773        Ok(None)
774    }
775}
776
777impl<'de, E: Error> NamedProductAccess<'de> for UnitAccess<E> {
778    type Error = E;
779
780    fn get_field_ident<V: FieldNameVisitor<'de>>(&mut self, _visitor: V) -> Result<Option<V::Output>, Self::Error> {
781        Ok(None)
782    }
783
784    fn get_field_value_seed<T: DeserializeSeed<'de>>(&mut self, _seed: T) -> Result<T::Output, Self::Error> {
785        unreachable!()
786    }
787}
788
789impl<'de, E: Error> Deserializer<'de> for UnitAccess<E> {
790    type Error = E;
791
792    fn deserialize_product<V: ProductVisitor<'de>>(self, visitor: V) -> Result<V::Output, Self::Error> {
793        visitor.visit_seq_product(self)
794    }
795
796    fn deserialize_sum<V: SumVisitor<'de>>(self, _visitor: V) -> Result<V::Output, Self::Error> {
797        Err(E::custom("invalid type"))
798    }
799
800    fn deserialize_bool(self) -> Result<bool, Self::Error> {
801        Err(E::custom("invalid type"))
802    }
803
804    fn deserialize_u8(self) -> Result<u8, Self::Error> {
805        Err(E::custom("invalid type"))
806    }
807
808    fn deserialize_u16(self) -> Result<u16, Self::Error> {
809        Err(E::custom("invalid type"))
810    }
811
812    fn deserialize_u32(self) -> Result<u32, Self::Error> {
813        Err(E::custom("invalid type"))
814    }
815
816    fn deserialize_u64(self) -> Result<u64, Self::Error> {
817        Err(E::custom("invalid type"))
818    }
819
820    fn deserialize_u128(self) -> Result<u128, Self::Error> {
821        Err(E::custom("invalid type"))
822    }
823
824    fn deserialize_u256(self) -> Result<u256, Self::Error> {
825        Err(E::custom("invalid type"))
826    }
827
828    fn deserialize_i8(self) -> Result<i8, Self::Error> {
829        Err(E::custom("invalid type"))
830    }
831
832    fn deserialize_i16(self) -> Result<i16, Self::Error> {
833        Err(E::custom("invalid type"))
834    }
835
836    fn deserialize_i32(self) -> Result<i32, Self::Error> {
837        Err(E::custom("invalid type"))
838    }
839
840    fn deserialize_i64(self) -> Result<i64, Self::Error> {
841        Err(E::custom("invalid type"))
842    }
843
844    fn deserialize_i128(self) -> Result<i128, Self::Error> {
845        Err(E::custom("invalid type"))
846    }
847
848    fn deserialize_i256(self) -> Result<i256, Self::Error> {
849        Err(E::custom("invalid type"))
850    }
851
852    fn deserialize_f32(self) -> Result<f32, Self::Error> {
853        Err(E::custom("invalid type"))
854    }
855
856    fn deserialize_f64(self) -> Result<f64, Self::Error> {
857        Err(E::custom("invalid type"))
858    }
859
860    fn deserialize_str<V: SliceVisitor<'de, str>>(self, _visitor: V) -> Result<V::Output, Self::Error> {
861        Err(E::custom("invalid type"))
862    }
863
864    fn deserialize_bytes<V: SliceVisitor<'de, [u8]>>(self, _visitor: V) -> Result<V::Output, Self::Error> {
865        Err(E::custom("invalid type"))
866    }
867
868    fn deserialize_array_seed<V: ArrayVisitor<'de, T::Output>, T: DeserializeSeed<'de> + Clone>(
869        self,
870        _visitor: V,
871        _seed: T,
872    ) -> Result<V::Output, Self::Error> {
873        Err(E::custom("invalid type"))
874    }
875}
spacetimedb_sats/de.rs

spacetimedb_sats/
de.rs
