planus/
lib.rs

1#![deny(missing_docs)]
2#![doc = include_str!("../README.md")]
3#![cfg_attr(not(feature = "std"), no_std)]
4mod backvec;
5mod builder;
6mod impls;
7mod slice_helpers;
8mod traits;
9
10/// Error types for serialization/deserialization
11pub mod errors;
12/// Types for interacting with vectors of unions in serialized data
13pub mod union_vectors;
14/// Types for interacting with vectors in serialized data
15pub mod vectors;
16
17#[cfg(any(
18    feature = "vtable-cache",
19    feature = "string-cache",
20    feature = "bytes-cache"
21))]
22mod builder_cache;
23
24#[doc(hidden)]
25pub extern crate alloc;
26#[doc(hidden)]
27pub mod table_reader;
28#[doc(hidden)]
29pub mod table_writer;
30
31pub use crate::{
32    builder::Builder,
33    errors::Error,
34    slice_helpers::{ArrayWithStartOffset, SliceWithStartOffset},
35    traits::*,
36    union_vectors::UnionVector,
37    vectors::Vector,
38};
39
40#[doc(hidden)]
41pub const fn check_version_compatibility(s: &str) {
42    match s.as_bytes() {
43        b"planus-1.1.1" => (),
44        _ => panic!(
45            "Your generated code is out of date, please regenerate using planus version 1.1.1"
46        ),
47    }
48}
49
50/// A type alias for [`Result`] with a Planus error
51///
52/// It is recommended to handle reading of serialized data in functions
53/// returning this result type to avoid boilerplate error handling using
54/// the ? operator.
55///
56/// [`Result`]: core::result::Result
57pub type Result<T> = core::result::Result<T, Error>;
58#[doc(hidden)]
59pub type Cursor<'a, const N: usize> = array_init_cursor::Cursor<'a, u8, N>;
60
61#[doc(hidden)]
62pub enum Void {}
63
64#[doc(hidden)]
65/// Used in the union-builders in generated code
66pub struct Uninitialized;
67
68#[doc(hidden)]
69/// Used in the union-builders in generated code
70pub struct Initialized<const N: u8, T>(pub T);
71
72#[doc(hidden)]
73/// Used in the tables-builders in generated code
74pub struct DefaultValue;
75
76impl<P: Primitive, D: ?Sized> WriteAsDefault<P, D> for DefaultValue {
77    type Prepared = Void;
78    fn prepare(&self, _builder: &mut Builder, _default: &D) -> Option<Self::Prepared> {
79        None
80    }
81}
82
83impl<P> WriteAsDefaultUnionVector<P> for DefaultValue {
84    fn prepare(&self, _builder: &mut Builder) -> Option<UnionVectorOffset<P>> {
85        None
86    }
87}
88
89impl From<Void> for crate::Error {
90    fn from(v: Void) -> Self {
91        match v {}
92    }
93}
94
95/// An offset to a serialized value of type T inside a buffer currently being built.
96pub struct Offset<T: ?Sized> {
97    offset: u32,
98    phantom: core::marker::PhantomData<T>,
99}
100impl<T: ?Sized> Copy for Offset<T> {}
101impl<T: ?Sized> Clone for Offset<T> {
102    #[inline]
103    fn clone(&self) -> Self {
104        *self
105    }
106}
107
108impl<T: ?Sized> Offset<T> {
109    #[doc(hidden)]
110    pub fn downcast(&self) -> Offset<()> {
111        Offset {
112            offset: self.offset,
113            phantom: core::marker::PhantomData,
114        }
115    }
116}
117
118/// An offset to a serialized union value of type T inside a buffer currently being built.
119pub struct UnionOffset<T: ?Sized> {
120    tag: u8,
121    offset: Offset<()>,
122    phantom: core::marker::PhantomData<T>,
123}
124impl<T: ?Sized> Copy for UnionOffset<T> {}
125impl<T: ?Sized> Clone for UnionOffset<T> {
126    #[inline]
127    fn clone(&self) -> Self {
128        *self
129    }
130}
131
132impl<T: ?Sized> UnionOffset<T> {
133    #[doc(hidden)]
134    #[inline]
135    pub fn new(tag: u8, offset: Offset<()>) -> Self {
136        Self {
137            tag,
138            offset,
139            phantom: core::marker::PhantomData,
140        }
141    }
142
143    #[doc(hidden)]
144    #[inline]
145    pub fn tag(&self) -> u8 {
146        self.tag
147    }
148
149    #[doc(hidden)]
150    #[inline]
151    pub fn offset(&self) -> Offset<()> {
152        self.offset
153    }
154}
155
156/// An offset to a serialized vector of union values of type T and vector of union tags inside a buffer currently being built
157pub struct UnionVectorOffset<T: ?Sized> {
158    tags_offset: Offset<[u8]>,
159    values_offset: Offset<[Offset<()>]>,
160    phantom: core::marker::PhantomData<T>,
161}
162impl<T: ?Sized> Copy for UnionVectorOffset<T> {}
163impl<T: ?Sized> Clone for UnionVectorOffset<T> {
164    #[inline]
165    fn clone(&self) -> Self {
166        *self
167    }
168}
169
170impl<T: ?Sized> UnionVectorOffset<T> {
171    #[doc(hidden)]
172    #[inline]
173    pub fn new(tags_offset: Offset<[u8]>, values_offset: Offset<[Offset<()>]>) -> Self {
174        Self {
175            tags_offset,
176            values_offset,
177            phantom: core::marker::PhantomData,
178        }
179    }
180
181    #[doc(hidden)]
182    #[inline]
183    pub fn tags_offset(&self) -> Offset<[u8]> {
184        self.tags_offset
185    }
186
187    #[doc(hidden)]
188    #[inline]
189    pub fn values_offset(&self) -> Offset<[Offset<()>]> {
190        self.values_offset
191    }
192}
planus/lib.rs

planus/
lib.rs
