binary_layout/fields/
mod.rs

1use super::endianness::Endianness;
2
3pub mod bool;
4pub mod char;
5pub mod primitive;
6pub mod wrapped;
7
8///
9/// A field represents one of the fields in the data layout and offers accessors
10/// for it. It remembers the offset of the field in its const generic parameter
11/// and the accessors use that to access the field.
12///
13/// A field does not hold any data storage, so if you use this API directly, you have to pass in
14/// the storage pointer for each call. If you want an API object that remembers the storage,
15/// take a look at the [FieldView](crate::FieldView) based API instead.
16///
17/// By itself, [Field] only offers the things common to all fields, but there
18/// are additional traits for fields that fulfill certain properties:
19/// - [FieldCopyAccess](crate::FieldCopyAccess) for fields that read/write data by copying it to/from the storage. This includes primitive types like [i8] or [u16].
20///   This trait offers [try_read](crate::FieldCopyAccess::try_read) and [try_write](crate::FieldCopyAccess::try_write) to read or write such fields.
21///   For types whose read or write operations don't throw errors, there are also the [read](crate::FieldReadExt::read) and [write](crate::FieldWriteExt) convenience methods.
22/// - [FieldSliceAccess](crate::FieldSliceAccess) for fields that read/write data by creating sub-slices over the storage. This includes, for example, byte arrays
23///   and this trait offers [data](crate::FieldSliceAccess::data) and [data_mut](crate::FieldSliceAccess::data_mut) to access such fields.
24///
25/// # Example:
26/// ```
27/// use binary_layout::prelude::*;
28///
29/// binary_layout!(my_layout, LittleEndian, {
30///   field_one: u16,
31///   another_field: [u8; 16],
32///   something_else: u32,
33///   tail_data: [u8],
34/// });
35///
36/// fn func(storage_data: &mut [u8]) {
37///   // read some data
38///   let format_version_header: u16 = my_layout::field_one::read(storage_data);
39///   // equivalent: let format_version_header = u16::from_le_bytes((&storage_data[0..2]).try_into().unwrap());
40///
41///   // write some data
42///   my_layout::something_else::write(storage_data, 10);
43///   // equivalent: data_slice[18..22].copy_from_slice(&10u32.to_le_bytes());
44///
45///   // access a data region
46///   let tail_data: &[u8] = my_layout::tail_data::data(storage_data);
47///   // equivalent: let tail_data: &[u8] = &data_slice[22..];
48///
49///   // and modify it
50///   my_layout::tail_data::data_mut(storage_data)[..5].copy_from_slice(&[1, 2, 3, 4, 5]);
51///   // equivalent: data_slice[18..22].copy_from_slice(&[1, 2, 3, 4, 5]);
52/// }
53/// ```
54pub trait Field {
55    /// The endianness of the field. Can be [LittleEndian](crate::LittleEndian) or [BigEndian](crate::BigEndian).
56    type Endian: Endianness;
57
58    /// The offset of the field in the layout.
59    ///
60    /// # Example
61    /// ```
62    /// use binary_layout::prelude::*;
63    ///
64    /// binary_layout!(my_layout, LittleEndian, {
65    ///   field1: u16,
66    ///   field2: i32,
67    ///   field3: u8,
68    /// });
69    ///
70    /// assert_eq!(0, my_layout::field1::OFFSET);
71    /// assert_eq!(2, my_layout::field2::OFFSET);
72    /// assert_eq!(6, my_layout::field3::OFFSET);
73    /// ```
74    const OFFSET: usize;
75
76    /// The size of the field in the layout.
77    /// This can be None if it is an open ended field like a byte slice
78    ///
79    /// # Example
80    /// ```
81    /// use binary_layout::prelude::*;
82    ///
83    /// binary_layout!(my_layout, LittleEndian, {
84    ///   field1: u16,
85    ///   field2: i32,
86    ///   field3: u8,
87    ///   tail: [u8],
88    /// });
89    ///
90    /// assert_eq!(Some(2), my_layout::field1::SIZE);
91    /// assert_eq!(Some(4), my_layout::field2::SIZE);
92    /// assert_eq!(Some(1), my_layout::field3::SIZE);
93    /// assert_eq!(None, my_layout::tail::SIZE);
94    /// ```
95    const SIZE: Option<usize>;
96}
97
98#[doc(hidden)]
99pub trait StorageIntoFieldView<S>
100where
101    S: AsRef<[u8]>,
102{
103    type View;
104    fn into_view(storage: S) -> Self::View;
105}
106
107#[doc(hidden)]
108pub trait StorageToFieldView<S> {
109    type View;
110    fn view(storage: S) -> Self::View;
111}
binary_layout/fields/mod.rs

binary_layout/fields/
mod.rs
