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        match one_of_names(|| expected.field_names()) {
193            Some(one_of) => Self::custom(format_args!("unknown {el_ty} `{field_name}`, expected {one_of}")),
194            _ => Self::custom(format_args!("unknown {el_ty} `{field_name}`, there are no {el_ty}s")),
195        }
196    }
197
198    /// The `tag` does not specify a variant of the sum type.
199    fn unknown_variant_tag<'de, T: SumVisitor<'de>>(tag: u8, expected: &T) -> Self {
200        Self::custom(format_args!(
201            "unknown tag {tag:#x} for sum type {}",
202            expected.sum_name().unwrap_or("<unknown>"),
203        ))
204    }
205
206    /// The `name` is not that of a variant of the sum type.
207    fn unknown_variant_name<'de, T: VariantVisitor<'de>>(name: &str, expected: &T) -> Self {
208        match one_of_names(|| expected.variant_names().map(Some)) {
209            Some(one_of) => Self::custom(format_args!("unknown variant `{name}`, expected {one_of}",)),
210            _ => Self::custom(format_args!("unknown variant `{name}`, there are no variants")),
211        }
212    }
213}
214
215/// Turns a closure `impl Fn(&mut Formatter) -> Result` into a `Display`able object.
216pub struct FDisplay<F>(F);
217
218impl<F: Fn(&mut fmt::Formatter) -> fmt::Result> fmt::Display for FDisplay<F> {
219    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
220        (self.0)(f)
221    }
222}
223
224/// Turns a closure `F: Fn(&mut Formatter) -> Result` into a `Display`able object.
225pub fn fmt_fn<F: Fn(&mut fmt::Formatter) -> fmt::Result>(f: F) -> FDisplay<F> {
226    FDisplay(f)
227}
228
229/// Returns an error message for a `problem` with field at `index` and an optional `name`.
230fn error_on_field<'a, 'de>(
231    problem: &'static str,
232    index: usize,
233    name: Option<&'a str>,
234    prod: &impl ProductVisitor<'de>,
235) -> impl fmt::Display + 'a {
236    let field_kind = match prod.product_kind() {
237        ProductKind::Normal => "field",
238        ProductKind::ReducerArgs => "reducer argument",
239    };
240    fmt_fn(move |f| {
241        // e.g. "missing field `foo`"
242        f.write_str(problem)?;
243        f.write_str(field_kind)?;
244        if let Some(name) = name {
245            write!(f, " `{name}`")
246        } else {
247            write!(f, " (index {index})")
248        }
249    })
250}
251
252/// Returns an error message for invalid product type lengths.
253fn fmt_invalid_len<'de>(
254    expected: &impl ProductVisitor<'de>,
255) -> FDisplay<impl '_ + Fn(&mut fmt::Formatter) -> fmt::Result> {
256    fmt_fn(|f| {
257        let ty = match expected.product_kind() {
258            ProductKind::Normal => "product type",
259            ProductKind::ReducerArgs => "reducer args for",
260        };
261        let name = expected.product_name().unwrap_or("<product>");
262        let len = expected.product_len();
263
264        write!(f, "{ty} {name} with {len} elements")
265    })
266}
267
268/// A visitor walking through a [`Deserializer`] for products.
269pub trait ProductVisitor<'de> {
270    /// The resulting product.
271    type Output;
272
273    /// Returns the name of the product, if any.
274    fn product_name(&self) -> Option<&str>;
275
276    /// Returns the length of the product.
277    fn product_len(&self) -> usize;
278
279    /// Returns the kind of the product.
280    fn product_kind(&self) -> ProductKind {
281        ProductKind::Normal
282    }
283
284    /// The input contains an unnamed product.
285    fn visit_seq_product<A: SeqProductAccess<'de>>(self, prod: A) -> Result<Self::Output, A::Error>;
286
287    /// The input contains a named product.
288    fn visit_named_product<A: NamedProductAccess<'de>>(self, prod: A) -> Result<Self::Output, A::Error>;
289}
290
291/// What kind of product is this?
292#[derive(Clone, Copy)]
293pub enum ProductKind {
294    // A normal product.
295    Normal,
296    /// A product in the context of reducer arguments.
297    ReducerArgs,
298}
299
300/// Provides a [`ProductVisitor`] with access to each element of the unnamed product in the input.
301///
302/// This is a trait that a [`Deserializer`] passes to a [`ProductVisitor`] implementation.
303pub trait SeqProductAccess<'de> {
304    /// The error type that can be returned if some error occurs during deserialization.
305    type Error: Error;
306
307    /// Deserializes an `T` from the input.
308    ///
309    /// Returns `Ok(Some(value))` for the next element in the product,
310    /// or `Ok(None)` if there are no more remaining items.
311    ///
312    /// This method exists as a convenience for [`Deserialize`] implementations.
313    /// [`SeqProductAccess`] implementations should not override the default behavior.
314    fn next_element<T: Deserialize<'de>>(&mut self) -> Result<Option<T>, Self::Error> {
315        self.next_element_seed(PhantomData)
316    }
317
318    /// Statefully deserializes `T::Output` from the input provided a `seed` value.
319    ///
320    /// Returns `Ok(Some(value))` for the next element in the unnamed product,
321    /// or `Ok(None)` if there are no more remaining items.
322    ///
323    /// [`Deserialize`] implementations should typically use
324    /// [`next_element`](SeqProductAccess::next_element) instead.
325    fn next_element_seed<T: DeserializeSeed<'de>>(&mut self, seed: T) -> Result<Option<T::Output>, Self::Error>;
326}
327
328/// Provides a [`ProductVisitor`] with access to each element of the named product in the input.
329///
330/// This is a trait that a [`Deserializer`] passes to a [`ProductVisitor`] implementation.
331pub trait NamedProductAccess<'de> {
332    /// The error type that can be returned if some error occurs during deserialization.
333    type Error: Error;
334
335    /// Deserializes field name of type `V::Output`
336    /// from the input using a visitor provided by the deserializer.
337    fn get_field_ident<V: FieldNameVisitor<'de>>(&mut self, visitor: V) -> Result<Option<V::Output>, Self::Error>;
338
339    /// Deserializes field value of type `T` from the input.
340    ///
341    /// This method exists as a convenience for [`Deserialize`] implementations.
342    /// [`NamedProductAccess`] implementations should not override the default behavior.
343    fn get_field_value<T: Deserialize<'de>>(&mut self) -> Result<T, Self::Error> {
344        self.get_field_value_seed(PhantomData)
345    }
346
347    /// Statefully deserializes the field value `T::Output` from the input provided a `seed` value.
348    ///
349    /// [`Deserialize`] implementations should typically use
350    /// [`next_element`](NamedProductAccess::get_field_value) instead.
351    fn get_field_value_seed<T: DeserializeSeed<'de>>(&mut self, seed: T) -> Result<T::Output, Self::Error>;
352}
353
354/// Visitor used to deserialize the name of a field.
355pub trait FieldNameVisitor<'de> {
356    /// The resulting field name.
357    type Output;
358
359    /// The sort of product deserialized.
360    fn kind(&self) -> ProductKind {
361        ProductKind::Normal
362    }
363
364    /// Provides a list of valid field names.
365    ///
366    /// Where `None` is yielded, this indicates a nameless field.
367    fn field_names(&self) -> impl '_ + Iterator<Item = Option<&str>>;
368
369    /// Deserializes the name of a field using `name`.
370    fn visit<E: Error>(self, name: &str) -> Result<Self::Output, E>;
371
372    /// Deserializes the name of a field using `index`.
373    ///
374    /// Should only be called when `index` is already known to exist
375    /// and is expected to panic otherwise.
376    fn visit_seq(self, index: usize) -> Self::Output;
377}
378
379/// A visitor walking through a [`Deserializer`] for sums.
380///
381/// This side is provided by a [`Deserialize`] implementation
382/// when calling [`Deserializer::deserialize_sum`].
383pub trait SumVisitor<'de> {
384    /// The resulting sum.
385    type Output;
386
387    /// Returns the name of the sum, if any.
388    fn sum_name(&self) -> Option<&str>;
389
390    /// Returns whether an option is expected.
391    ///
392    /// The provided implementation does not.
393    fn is_option(&self) -> bool {
394        false
395    }
396
397    /// Drives the deserialization of a sum value.
398    ///
399    /// This method will ask the data format ([`A: SumAccess`][SumAccess])
400    /// which variant of the sum to select in terms of a variant name / tag.
401    /// `A` will use a [`VariantVisitor`], that `SumVisitor` has provided,
402    /// to translate into something that is meaningful for `visit_sum`, e.g., an index.
403    ///
404    /// The data format will also return an object ([`VariantAccess`])
405    /// that can deserialize the contents of the variant.
406    fn visit_sum<A: SumAccess<'de>>(self, data: A) -> Result<Self::Output, A::Error>;
407}
408
409/// Provides a [`SumVisitor`] access to the data of a sum in the input.
410///
411/// An `A: SumAccess` object is created by the [`D: Deserializer`]
412/// which passes `A` to a [`V: SumVisitor`] that `D` in turn was passed.
413/// `A` is then used by `V` to split tag and value input apart.
414pub trait SumAccess<'de> {
415    /// The error type that can be returned if some error occurs during deserialization.
416    type Error: Error;
417
418    /// The visitor used to deserialize the content of the sum variant.
419    type Variant: VariantAccess<'de, Error = Self::Error>;
420
421    /// Called to identify which variant to deserialize.
422    /// Returns a tuple with the result of identification (`V::Output`)
423    /// and the input to variant data deserialization.
424    ///
425    /// The `visitor` is provided by the [`Deserializer`].
426    /// This method is typically called from [`SumVisitor::visit_sum`]
427    /// which will provide the [`V: VariantVisitor`](VariantVisitor).
428    fn variant<V: VariantVisitor<'de>>(self, visitor: V) -> Result<(V::Output, Self::Variant), Self::Error>;
429}
430
431/// A visitor passed from [`SumVisitor`] to [`SumAccess::variant`]
432/// which the latter uses to decide what variant to deserialize.
433pub trait VariantVisitor<'de> {
434    /// The result of identifying a variant, e.g., some index type.
435    type Output;
436
437    /// Provides a list of variant names.
438    fn variant_names(&self) -> impl '_ + Iterator<Item = &str>;
439
440    /// Identify the variant based on `tag`.
441    fn visit_tag<E: Error>(self, tag: u8) -> Result<Self::Output, E>;
442
443    /// Identify the variant based on `name`.
444    fn visit_name<E: Error>(self, name: &str) -> Result<Self::Output, E>;
445}
446
447/// A visitor passed from [`SumAccess`] to [`SumVisitor::visit_sum`]
448/// which the latter uses to deserialize the data of a selected variant.
449pub trait VariantAccess<'de>: Sized {
450    type Error: Error;
451
452    /// Called when deserializing the contents of a sum variant.
453    ///
454    /// This method exists as a convenience for [`Deserialize`] implementations.
455    fn deserialize<T: Deserialize<'de>>(self) -> Result<T, Self::Error> {
456        self.deserialize_seed(PhantomData)
457    }
458
459    /// Called when deserializing the contents of a sum variant, and provided with a `seed` value.
460    fn deserialize_seed<T: DeserializeSeed<'de>>(self, seed: T) -> Result<T::Output, Self::Error>;
461}
462
463/// A `SliceVisitor` is provided a slice `T` of some elements by a [`Deserializer`]
464/// and is tasked with translating this slice to the `Output` type.
465pub trait SliceVisitor<'de, T: ToOwned + ?Sized>: Sized {
466    /// The output produced by this visitor.
467    type Output;
468
469    /// The input contains a slice.
470    ///
471    /// The lifetime of the slice is ephemeral
472    /// and it may be destroyed after this method returns.
473    fn visit<E: Error>(self, slice: &T) -> Result<Self::Output, E>;
474
475    /// The input contains a slice and ownership of the slice is being given to the [`SliceVisitor`].
476    fn visit_owned<E: Error>(self, buf: T::Owned) -> Result<Self::Output, E> {
477        self.visit(buf.borrow())
478    }
479
480    /// The input contains a slice that lives at least as long (`'de`) as the [`Deserializer`].
481    fn visit_borrowed<E: Error>(self, borrowed_slice: &'de T) -> Result<Self::Output, E> {
482        self.visit(borrowed_slice)
483    }
484}
485
486/// A visitor walking through a [`Deserializer`] for arrays.
487pub trait ArrayVisitor<'de, T> {
488    /// The output produced by this visitor.
489    type Output;
490
491    /// The input contains an array.
492    fn visit<A: ArrayAccess<'de, Element = T>>(self, vec: A) -> Result<Self::Output, A::Error>;
493}
494
495/// Provides an [`ArrayVisitor`] with access to each element of the array in the input.
496///
497/// This is a trait that a [`Deserializer`] passes to an [`ArrayVisitor`] implementation.
498pub trait ArrayAccess<'de> {
499    /// The element / base type of the array.
500    type Element;
501
502    /// The error type that can be returned if some error occurs during deserialization.
503    type Error: Error;
504
505    /// This returns `Ok(Some(value))` for the next element in the array,
506    /// or `Ok(None)` if there are no more remaining elements.
507    fn next_element(&mut self) -> Result<Option<Self::Element>, Self::Error>;
508
509    /// Returns the number of elements remaining in the array, if known.
510    fn size_hint(&self) -> Option<usize> {
511        None
512    }
513}
514
515/// `DeserializeSeed` is the stateful form of the [`Deserialize`] trait.
516pub trait DeserializeSeed<'de> {
517    /// The type produced by using this seed.
518    type Output;
519
520    /// Equivalent to the more common [`Deserialize::deserialize`] associated function,
521    /// except with some initial piece of data (the seed `self`) passed in.
522    fn deserialize<D: Deserializer<'de>>(self, deserializer: D) -> Result<Self::Output, D::Error>;
523}
524
525use crate::de::impls::BorrowedSliceVisitor;
526pub use spacetimedb_bindings_macro::Deserialize;
527
528/// A data structure that can be deserialized from any data format supported by the SpacetimeDB Algebraic Type System.
529///
530/// In most cases, implementations of `Deserialize` may be `#[derive(Deserialize)]`d.
531///
532/// The `Deserialize` trait in SATS performs the same function as `serde::Deserialize` in [`serde`].
533/// See the documentation of `serde::Deserialize` for more information of the data model.
534///
535/// The lifetime `'de` allows us to deserialize lifetime-generic types in a zero-copy fashion.
536///
537/// Do not manually implement this trait unless you know what you are doing.
538/// Implementations must be consistent with `Serialize for T`, `SpacetimeType for T` and `Serialize, Deserialize for AlgebraicValue`.
539/// Implementations that are inconsistent across these traits may result in data loss.
540///
541/// [`serde`]: https://crates.io/crates/serde
542pub trait Deserialize<'de>: Sized {
543    /// Deserialize this value from the given `deserializer`.
544    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>;
545
546    #[doc(hidden)]
547    /// Deserialize this value from the given the BSATN `deserializer`.
548    fn deserialize_from_bsatn<R: BufReader<'de>>(
549        deserializer: bsatn::Deserializer<'de, R>,
550    ) -> Result<Self, bsatn::DecodeError> {
551        Self::deserialize(deserializer)
552    }
553
554    /// used in the Deserialize for Vec<T> impl to allow specializing deserializing Vec<T> as bytes
555    #[doc(hidden)]
556    #[inline(always)]
557    fn __deserialize_vec<D: Deserializer<'de>>(deserializer: D) -> Result<Vec<Self>, D::Error> {
558        deserializer.deserialize_array(BasicVecVisitor)
559    }
560
561    #[doc(hidden)]
562    #[inline(always)]
563    fn __deserialize_array<D: Deserializer<'de>, const N: usize>(deserializer: D) -> Result<[Self; N], D::Error> {
564        deserializer.deserialize_array(BasicArrayVisitor)
565    }
566}
567
568/// A data structure that can be deserialized in SATS
569/// without borrowing any data from the deserializer.
570pub trait DeserializeOwned: for<'de> Deserialize<'de> {}
571impl<T: for<'de> Deserialize<'de>> DeserializeOwned for T {}
572
573impl<'de, T: Deserialize<'de>> DeserializeSeed<'de> for PhantomData<T> {
574    type Output = T;
575
576    fn deserialize<D: Deserializer<'de>>(self, deserializer: D) -> Result<Self::Output, D::Error> {
577        T::deserialize(deserializer)
578    }
579}
580
581/// A vector with two operations: `with_capacity` and `push`.
582pub trait GrowingVec<T> {
583    /// Create the collection with the given capacity.
584    fn with_capacity(cap: usize) -> Self;
585
586    /// Push to the vector the `elem`.
587    fn push(&mut self, elem: T);
588}
589
590impl<T> GrowingVec<T> for Vec<T> {
591    fn with_capacity(cap: usize) -> Self {
592        Self::with_capacity(cap)
593    }
594    fn push(&mut self, elem: T) {
595        self.push(elem)
596    }
597}
598
599impl<T, const N: usize> GrowingVec<T> for SmallVec<[T; N]> {
600    fn with_capacity(cap: usize) -> Self {
601        Self::with_capacity(cap)
602    }
603    fn push(&mut self, elem: T) {
604        self.push(elem)
605    }
606}
607
608/// A basic implementation of `ArrayVisitor::visit` using the provided size hint.
609pub fn array_visit<'de, A: ArrayAccess<'de>, V: GrowingVec<A::Element>>(mut access: A) -> Result<V, A::Error> {
610    let mut v = V::with_capacity(access.size_hint().unwrap_or(0));
611    while let Some(x) = access.next_element()? {
612        v.push(x)
613    }
614    Ok(v)
615}
616
617/// An implementation of [`ArrayVisitor<'de, T>`] where the output is a `Vec<T>`.
618pub struct BasicVecVisitor;
619
620impl<'de, T> ArrayVisitor<'de, T> for BasicVecVisitor {
621    type Output = Vec<T>;
622
623    fn visit<A: ArrayAccess<'de, Element = T>>(self, vec: A) -> Result<Self::Output, A::Error> {
624        array_visit(vec)
625    }
626}
627
628/// An implementation of [`ArrayVisitor<'de, T>`] where the output is a `SmallVec<[T; N]>`.
629pub struct BasicSmallVecVisitor<const N: usize>;
630
631impl<'de, T, const N: usize> ArrayVisitor<'de, T> for BasicSmallVecVisitor<N> {
632    type Output = SmallVec<[T; N]>;
633
634    fn visit<A: ArrayAccess<'de, Element = T>>(self, vec: A) -> Result<Self::Output, A::Error> {
635        array_visit(vec)
636    }
637}
638
639/// An implementation of [`ArrayVisitor<'de, T>`] where the output is a `[T; N]`.
640struct BasicArrayVisitor<const N: usize>;
641
642impl<'de, T, const N: usize> ArrayVisitor<'de, T> for BasicArrayVisitor<N> {
643    type Output = [T; N];
644
645    fn visit<A: ArrayAccess<'de, Element = T>>(self, mut vec: A) -> Result<Self::Output, A::Error> {
646        let mut v = arrayvec::ArrayVec::<T, N>::new();
647        while let Some(el) = vec.next_element()? {
648            v.try_push(el)
649                .map_err(|_| Error::custom("too many elements for array"))?
650        }
651        v.into_inner().map_err(|_| Error::custom("too few elements for array"))
652    }
653}
654
655/// Provided a list of names,
656/// returns a human readable list of all the names,
657/// or `None` in the case of an empty list of names.
658fn one_of_names<'a, I: Iterator<Item = Option<&'a str>>>(names: impl Fn() -> I) -> Option<impl fmt::Display> {
659    // Count how many names there are.
660    let count = names().count();
661
662    // There was at least one name; render those names.
663    (count != 0).then(move || {
664        fmt_fn(move |f| {
665            let mut anon_name = 0;
666            // An example of what happens for names "foo", "bar", and "baz":
667            //
668            // count = 1 -> "`foo`"
669            //       = 2 -> "`foo` or `bar`"
670            //       > 2 -> "one of `foo`, `bar`, or `baz`"
671            for (index, mut name) in names().enumerate() {
672                let mut name_buf: String = String::new();
673                let name = name.get_or_insert_with(|| {
674                    name_buf = format!("{anon_name}");
675                    anon_name += 1;
676                    &name_buf
677                });
678                match (count, index) {
679                    (1, _) => write!(f, "`{name}`"),
680                    (2, 1) => write!(f, "`{name}`"),
681                    (2, 2) => write!(f, "`or `{name}`"),
682                    (_, 1) => write!(f, "one of `{name}`"),
683                    (c, i) if i < c => write!(f, ", `{name}`"),
684                    (_, _) => write!(f, ", `, or {name}`"),
685                }?;
686            }
687
688            Ok(())
689        })
690    })
691}
692
693/// Deserializes `none` variant of an optional value.
694pub struct NoneAccess<E>(PhantomData<E>);
695
696impl<E: Error> NoneAccess<E> {
697    /// Returns a new [`NoneAccess`].
698    pub fn new() -> Self {
699        Self(PhantomData)
700    }
701}
702
703impl<E: Error> Default for NoneAccess<E> {
704    fn default() -> Self {
705        Self::new()
706    }
707}
708
709impl<'de, E: Error> SumAccess<'de> for NoneAccess<E> {
710    type Error = E;
711    type Variant = Self;
712
713    fn variant<V: VariantVisitor<'de>>(self, visitor: V) -> Result<(V::Output, Self::Variant), Self::Error> {
714        visitor.visit_name("none").map(|var| (var, self))
715    }
716}
717impl<'de, E: Error> VariantAccess<'de> for NoneAccess<E> {
718    type Error = E;
719    fn deserialize_seed<T: DeserializeSeed<'de>>(self, seed: T) -> Result<T::Output, Self::Error> {
720        seed.deserialize(UnitAccess::new())
721    }
722}
723
724/// Deserializes `some` variant of an optional value.
725pub struct SomeAccess<D>(D);
726
727impl<D> SomeAccess<D> {
728    /// Returns a new [`SomeAccess`] with a given deserializer for the `some` variant.
729    pub fn new(de: D) -> Self {
730        Self(de)
731    }
732}
733
734impl<'de, D: Deserializer<'de>> SumAccess<'de> for SomeAccess<D> {
735    type Error = D::Error;
736    type Variant = Self;
737
738    fn variant<V: VariantVisitor<'de>>(self, visitor: V) -> Result<(V::Output, Self::Variant), Self::Error> {
739        visitor.visit_name("some").map(|var| (var, self))
740    }
741}
742
743impl<'de, D: Deserializer<'de>> VariantAccess<'de> for SomeAccess<D> {
744    type Error = D::Error;
745    fn deserialize_seed<T: DeserializeSeed<'de>>(self, seed: T) -> Result<T::Output, Self::Error> {
746        seed.deserialize(self.0)
747    }
748}
749
750/// A `Deserializer` that represents a unit value.
751// used in the implementation of `VariantAccess for NoneAccess`
752pub struct UnitAccess<E>(PhantomData<E>);
753
754impl<E: Error> UnitAccess<E> {
755    /// Returns a new [`UnitAccess`].
756    pub fn new() -> Self {
757        Self(PhantomData)
758    }
759}
760
761impl<E: Error> Default for UnitAccess<E> {
762    fn default() -> Self {
763        Self::new()
764    }
765}
766
767impl<'de, E: Error> SeqProductAccess<'de> for UnitAccess<E> {
768    type Error = E;
769
770    fn next_element_seed<T: DeserializeSeed<'de>>(&mut self, _seed: T) -> Result<Option<T::Output>, Self::Error> {
771        Ok(None)
772    }
773}
774
775impl<'de, E: Error> NamedProductAccess<'de> for UnitAccess<E> {
776    type Error = E;
777
778    fn get_field_ident<V: FieldNameVisitor<'de>>(&mut self, _visitor: V) -> Result<Option<V::Output>, Self::Error> {
779        Ok(None)
780    }
781
782    fn get_field_value_seed<T: DeserializeSeed<'de>>(&mut self, _seed: T) -> Result<T::Output, Self::Error> {
783        unreachable!()
784    }
785}
786
787impl<'de, E: Error> Deserializer<'de> for UnitAccess<E> {
788    type Error = E;
789
790    fn deserialize_product<V: ProductVisitor<'de>>(self, visitor: V) -> Result<V::Output, Self::Error> {
791        visitor.visit_seq_product(self)
792    }
793
794    fn deserialize_sum<V: SumVisitor<'de>>(self, _visitor: V) -> Result<V::Output, Self::Error> {
795        Err(E::custom("invalid type"))
796    }
797
798    fn deserialize_bool(self) -> Result<bool, Self::Error> {
799        Err(E::custom("invalid type"))
800    }
801
802    fn deserialize_u8(self) -> Result<u8, Self::Error> {
803        Err(E::custom("invalid type"))
804    }
805
806    fn deserialize_u16(self) -> Result<u16, Self::Error> {
807        Err(E::custom("invalid type"))
808    }
809
810    fn deserialize_u32(self) -> Result<u32, Self::Error> {
811        Err(E::custom("invalid type"))
812    }
813
814    fn deserialize_u64(self) -> Result<u64, Self::Error> {
815        Err(E::custom("invalid type"))
816    }
817
818    fn deserialize_u128(self) -> Result<u128, Self::Error> {
819        Err(E::custom("invalid type"))
820    }
821
822    fn deserialize_u256(self) -> Result<u256, Self::Error> {
823        Err(E::custom("invalid type"))
824    }
825
826    fn deserialize_i8(self) -> Result<i8, Self::Error> {
827        Err(E::custom("invalid type"))
828    }
829
830    fn deserialize_i16(self) -> Result<i16, Self::Error> {
831        Err(E::custom("invalid type"))
832    }
833
834    fn deserialize_i32(self) -> Result<i32, Self::Error> {
835        Err(E::custom("invalid type"))
836    }
837
838    fn deserialize_i64(self) -> Result<i64, Self::Error> {
839        Err(E::custom("invalid type"))
840    }
841
842    fn deserialize_i128(self) -> Result<i128, Self::Error> {
843        Err(E::custom("invalid type"))
844    }
845
846    fn deserialize_i256(self) -> Result<i256, Self::Error> {
847        Err(E::custom("invalid type"))
848    }
849
850    fn deserialize_f32(self) -> Result<f32, Self::Error> {
851        Err(E::custom("invalid type"))
852    }
853
854    fn deserialize_f64(self) -> Result<f64, Self::Error> {
855        Err(E::custom("invalid type"))
856    }
857
858    fn deserialize_str<V: SliceVisitor<'de, str>>(self, _visitor: V) -> Result<V::Output, Self::Error> {
859        Err(E::custom("invalid type"))
860    }
861
862    fn deserialize_bytes<V: SliceVisitor<'de, [u8]>>(self, _visitor: V) -> Result<V::Output, Self::Error> {
863        Err(E::custom("invalid type"))
864    }
865
866    fn deserialize_array_seed<V: ArrayVisitor<'de, T::Output>, T: DeserializeSeed<'de> + Clone>(
867        self,
868        _visitor: V,
869        _seed: T,
870    ) -> Result<V::Output, Self::Error> {
871        Err(E::custom("invalid type"))
872    }
873}
spacetimedb_sats/de.rs

spacetimedb_sats/
de.rs
