syntree/
flavor.rs

1//! Trait for defining the flavor of a syntree.
2
3use core::ops::DerefMut;
4
5use crate::index::{Index, Length, TreeIndex};
6use crate::pointer::{Pointer, Width};
7
8/// Storage being used in a tree.
9pub trait Storage<T>
10where
11    Self: Sized + DerefMut<Target = [T]>,
12{
13    /// A storage error.
14    type Error: 'static;
15
16    /// Empty storage.
17    const EMPTY: Self;
18
19    /// Constructstorage with the given capacity.
20    fn with_capacity(capacity: usize) -> Result<Self, Self::Error>;
21
22    /// Get the capacity of the underlying storage.
23    fn capacity(&self) -> usize;
24
25    /// Push an item into storage.
26    fn push(&mut self, item: T) -> Result<(), Self::Error>;
27}
28
29#[cfg(feature = "alloc")]
30impl<T> Storage<T> for alloc::vec::Vec<T> {
31    type Error = core::convert::Infallible;
32
33    const EMPTY: Self = alloc::vec::Vec::new();
34
35    #[inline]
36    fn with_capacity(capacity: usize) -> Result<Self, Self::Error> {
37        Ok(alloc::vec::Vec::with_capacity(capacity))
38    }
39
40    #[inline]
41    fn capacity(&self) -> usize {
42        alloc::vec::Vec::capacity(self)
43    }
44
45    #[inline]
46    fn push(&mut self, item: T) -> Result<(), Self::Error> {
47        alloc::vec::Vec::push(self, item);
48        Ok(())
49    }
50}
51
52/// Declare a new flavor.
53///
54/// The available type parameters are:
55/// * `type Index` which declares the index to use.
56/// * `type Width` which declares the width to use, defaults to `usize`.
57///
58/// # Examples
59///
60/// ```
61/// use syntree::{Empty, EmptyVec, TreeIndex};
62///
63/// syntree::flavor! {
64///     struct FlavorEmpty {
65///         type Index = Empty;
66///         type Indexes = EmptyVec<TreeIndex<Self>>;
67///     }
68/// }
69///
70/// syntree::flavor! {
71///     struct FlavorU32 {
72///         type Index = u32;
73///         type Width = u32;
74///     }
75/// }
76/// ```
77#[macro_export]
78macro_rules! flavor {
79    (
80        $(#[doc = $doc:literal])*
81        $vis:vis struct $ty:ident {
82            type Index = $index:ty;
83            $(type Width = $width:ty;)?
84            $(type Storage = $storage:ty;)?
85            $(type Indexes = $indexes:ty;)?
86        }
87    ) => {
88        $(#[doc = $doc])*
89        #[non_exhaustive]
90        $vis struct $ty;
91
92        impl $crate::Flavor for $ty {
93            type Error = core::convert::Infallible;
94            type Index = $index;
95            type Length = <$index as $crate::Index>::Length;
96            type Width = $crate::flavor!(@width $($width)*);
97            type Pointer = $crate::flavor!(@pointer $($width)*);
98            type Storage<T> = $crate::macro_support::Vec<T>;
99            type Indexes = $crate::flavor!(@indexes $($indexes)*);
100        }
101    };
102
103    (@width $ty:ty) => { $ty };
104    (@width) => { usize };
105    (@pointer $ty:ty) => { <$ty as $crate::pointer::Width>::Pointer };
106    (@pointer) => { <usize as $crate::pointer::Width>::Pointer };
107    (@indexes $ty:ty) => { $ty };
108    (@indexes) => { $crate::macro_support::DefaultIndexes<Self> };
109}
110
111flavor! {
112    /// The default flavor of a tree.
113    ///
114    /// This corresponds to a `u32` index with a `usize` width.
115    pub struct FlavorDefault {
116        type Index = u32;
117        type Width = usize;
118    }
119}
120
121/// The flavor of a tree.
122///
123/// This should not be implemented directly, instead see the [flavor!] macro.
124///
125/// The Index associated type is constrained by the [Index] trait, and
126/// determines the numerical bounds of [spans] the tree.
127///
128/// The `Width` associated type determines the bounds of pointers in the tree
129/// through the [Width] trait, this decides how many elements that can be stored
130/// in the tree.
131///
132/// [spans]: crate::Span
133pub trait Flavor {
134    /// The error raised by the type of the tree.
135    type Error;
136    /// The type of an index used by a tree.
137    type Index: Index<Length = Self::Length>;
138    /// The length used in the flavor.
139    type Length: Length;
140    /// The width used in the flavor.
141    type Width: Width<Pointer = Self::Pointer>;
142    /// The pointer in use.
143    type Pointer: Pointer;
144    /// The storage type used in the tree.
145    type Storage<T>: Storage<T, Error = Self::Error>;
146    /// How indexes are stored in the tree.
147    type Indexes: Storage<TreeIndex<Self>, Error = Self::Error>;
148}
syntree/flavor.rs

syntree/
flavor.rs
