substrate_data/schema/
format.rs

1//! [`Schema`]: a format, a type that reads, writes, encodes, packs and describes itself.
2
3use super::{Reader, Shape, read_ref_value};
4use crate::binary::{Decoder, Writer};
5use crate::frame::{Packer, Unpacker};
6use crate::model::borrowed::ValueRef;
7use crate::model::value::Value;
8
9/// A format: a type that reads, writes, encodes, packs and describes itself.
10pub trait Schema: Sized {
11    /// What the format looks like.
12    fn shape() -> Shape;
13
14    /// Reads `v`. Problems go to `cx` at its current path; `None` when the
15    /// value couldn't be read (the problem is in `cx`).
16    fn read(v: &ValueRef<'_>, cx: &mut Reader<'_>) -> Option<Self>;
17
18    /// The value, as the format writes it.
19    fn write(&self) -> Value;
20
21    /// The value of a field that isn't there — `None`: the field is required.
22    #[must_use]
23    fn absent() -> Option<Self> {
24        None
25    }
26
27    /// Whether a struct leaves this field out when writing it.
28    fn skip(&self) -> bool {
29        false
30    }
31
32    /// Writes itself in the binary form, straight — [`Schema::write`]'s
33    /// value encoded, unless the type knows better (derived ones do).
34    fn encode(&self, w: &mut Writer) {
35        w.value(&self.write());
36    }
37
38    /// Writes itself as text, straight ([`crate::text::Writer`]) —
39    /// [`Schema::write`]'s value as text, unless the type knows better
40    /// (derived ones do): no value tree is built on the way.
41    fn write_text(&self, w: &mut crate::text::Writer) {
42        w.value(&self.write());
43    }
44
45    /// Reads itself from the binary form, straight; `None` when it isn't
46    /// what [`Schema::encode`] writes — then [`read_bytes`](crate::schema::read_bytes) reads the slow
47    /// way, which says what's wrong. Through a value unless the type knows
48    /// better (derived ones do).
49    fn decode(d: &mut Decoder<'_>) -> Option<Self> {
50        let arena = bumpalo::Bump::new();
51        let v = d.value_ref(&arena).ok()?;
52        read_ref_value(&v).ok()
53    }
54
55    /// Packs itself into a frame ([`crate::frame`]): its binary form as
56    /// bytes, unless the type packs itself (derived ones and plain types do).
57    fn pack(&self, p: &mut Packer) {
58        p.put_tagged(self);
59    }
60
61    /// Reads itself out of a frame; `None` if the bytes aren't what
62    /// [`Schema::pack`] writes.
63    fn unpack(u: &mut Unpacker<'_>) -> Option<Self> {
64        u.tagged()
65    }
66
67    /// A list of these packed: a count, then each one (floats raw).
68    fn pack_list(items: &[Self], p: &mut Packer) {
69        let at = p.begin_list(items.len());
70        for item in items {
71            item.pack(p);
72        }
73        p.end(at);
74    }
75
76    /// A list of these out of a frame.
77    fn unpack_list(u: &mut Unpacker<'_>) -> Option<Vec<Self>> {
78        let (n, end) = u.list()?;
79        let mut out = Vec::with_capacity(n);
80        for _ in 0..n {
81            out.push(Self::unpack(u)?);
82        }
83        u.skip_to(end)?;
84        Some(out)
85    }
86
87    /// A list of these written straight (numbers pack theirs).
88    fn encode_list(items: &[Self], w: &mut Writer) {
89        w.list(items.len());
90        for item in items {
91            item.encode(w);
92        }
93    }
94
95    /// A list of these read straight.
96    fn decode_list(d: &mut Decoder<'_>) -> Option<Vec<Self>> {
97        let n = d.list()?;
98        let mut out = Vec::with_capacity(n);
99        for _ in 0..n {
100            out.push(Self::decode(d)?);
101        }
102        d.leave();
103        Some(out)
104    }
105}
substrate_data/schema/format.rs

substrate_data/schema/
format.rs
