Struct binary_layout::FieldView

pub struct FieldView<S, F: FieldMetadata> { /* fields omitted */ }

A field view represents the field metadata stored in a Field plus it stores the underlying storage data it operates on, either as a reference to a slice &[u8], &mut [u8], or as an owning Vec.

Since this API remembers the underlying storage data in a view object, you don’t have to pass it in each time you’re accessing a field. If you rather prefer an API that does not do that, take a look at the Field API.

Example:

use binary_layout::prelude::*;

define_layout!(my_layout, LittleEndian, {
  field_one: u16,
  another_field: [u8; 16],
  something_else: u32,
  tail_data: [u8],
});

fn func(storage_data: &mut [u8]) {
  let mut view = my_layout::View::new(storage_data);

  // read some data
  let format_version_header: u16 = view.field_one().read();
  // equivalent: let format_version_header = u16::from_le_bytes((&storage_data[0..2]).try_into().unwrap());

  // write some data
  view.something_else_mut().write(10);
  // equivalent: data_slice[18..22].copy_from_slice(&10u32.to_le_bytes());

  // access a data region
  let tail_data: &[u8] = view.tail_data().data();
  // equivalent: let tail_data: &[u8] = &data_slice[22..];

  // and modify it
  view.tail_data_mut().data_mut()[..5].copy_from_slice(&[1, 2, 3, 4, 5]);
  // equivalent: data_slice[18..22].copy_from_slice(&[1, 2, 3, 4, 5]);
}

Implementations

impl<S, F: FieldMetadata> FieldView<S, F>

pub fn new(storage: S) -> Self

Create a new view for a field over a given storage. You probably shouldn’t call this directly but should instead call your_layout::View::new(), which is generated by the define_layout! macro for you.

impl<S: AsRef<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<i8, E, OFFSET_>>

Field type i8: This field represents a little endian integer. In this impl, we define read accessors for such integer fields. See supported primitive integer types.

pub fn read(&self) -> i8

Read the integer field from a given data region, assuming the defined layout, using the FieldView API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: i8
   //... other fields ...
});

fn func(storage_data: &[u8]) {
    let view = my_layout::View::new(storage_data);
    let read: i8 = view.some_integer_field().read();
}

impl<S: AsMut<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<i8, E, OFFSET_>>

Field type i8: This field represents a little endian integer. In this impl, we define write accessors for such integer fields. See supported primitive integer types.

pub fn write(&mut self, value: i8)

Write the integer field to a given data region, assuming the defined layout, using the Field API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: i8
   //... other fields ...
});

fn func(storage_data: &mut [u8]) {
    let mut view = my_layout::View::new(storage_data);
    view.some_integer_field_mut().write(10);
}

impl<S: AsRef<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<i16, E, OFFSET_>>

Field type i16: This field represents a little endian integer. In this impl, we define read accessors for such integer fields. See supported primitive integer types.

pub fn read(&self) -> i16

Read the integer field from a given data region, assuming the defined layout, using the FieldView API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: i16
   //... other fields ...
});

fn func(storage_data: &[u8]) {
    let view = my_layout::View::new(storage_data);
    let read: i16 = view.some_integer_field().read();
}

impl<S: AsMut<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<i16, E, OFFSET_>>

Field type i16: This field represents a little endian integer. In this impl, we define write accessors for such integer fields. See supported primitive integer types.

pub fn write(&mut self, value: i16)

Write the integer field to a given data region, assuming the defined layout, using the Field API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: i16
   //... other fields ...
});

fn func(storage_data: &mut [u8]) {
    let mut view = my_layout::View::new(storage_data);
    view.some_integer_field_mut().write(10);
}

impl<S: AsRef<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<i32, E, OFFSET_>>

Field type i32: This field represents a little endian integer. In this impl, we define read accessors for such integer fields. See supported primitive integer types.

pub fn read(&self) -> i32

Read the integer field from a given data region, assuming the defined layout, using the FieldView API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: i32
   //... other fields ...
});

fn func(storage_data: &[u8]) {
    let view = my_layout::View::new(storage_data);
    let read: i32 = view.some_integer_field().read();
}

impl<S: AsMut<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<i32, E, OFFSET_>>

Field type i32: This field represents a little endian integer. In this impl, we define write accessors for such integer fields. See supported primitive integer types.

pub fn write(&mut self, value: i32)

Write the integer field to a given data region, assuming the defined layout, using the Field API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: i32
   //... other fields ...
});

fn func(storage_data: &mut [u8]) {
    let mut view = my_layout::View::new(storage_data);
    view.some_integer_field_mut().write(10);
}

impl<S: AsRef<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<i64, E, OFFSET_>>

Field type i64: This field represents a little endian integer. In this impl, we define read accessors for such integer fields. See supported primitive integer types.

pub fn read(&self) -> i64

Read the integer field from a given data region, assuming the defined layout, using the FieldView API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: i64
   //... other fields ...
});

fn func(storage_data: &[u8]) {
    let view = my_layout::View::new(storage_data);
    let read: i64 = view.some_integer_field().read();
}

impl<S: AsMut<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<i64, E, OFFSET_>>

Field type i64: This field represents a little endian integer. In this impl, we define write accessors for such integer fields. See supported primitive integer types.

pub fn write(&mut self, value: i64)

Write the integer field to a given data region, assuming the defined layout, using the Field API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: i64
   //... other fields ...
});

fn func(storage_data: &mut [u8]) {
    let mut view = my_layout::View::new(storage_data);
    view.some_integer_field_mut().write(10);
}

impl<S: AsRef<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<u8, E, OFFSET_>>

Field type u8: This field represents a little endian integer. In this impl, we define read accessors for such integer fields. See supported primitive integer types.

pub fn read(&self) -> u8

Read the integer field from a given data region, assuming the defined layout, using the FieldView API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: u8
   //... other fields ...
});

fn func(storage_data: &[u8]) {
    let view = my_layout::View::new(storage_data);
    let read: u8 = view.some_integer_field().read();
}

impl<S: AsMut<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<u8, E, OFFSET_>>

Field type u8: This field represents a little endian integer. In this impl, we define write accessors for such integer fields. See supported primitive integer types.

pub fn write(&mut self, value: u8)

Write the integer field to a given data region, assuming the defined layout, using the Field API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: u8
   //... other fields ...
});

fn func(storage_data: &mut [u8]) {
    let mut view = my_layout::View::new(storage_data);
    view.some_integer_field_mut().write(10);
}

impl<S: AsRef<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<u16, E, OFFSET_>>

Field type u16: This field represents a little endian integer. In this impl, we define read accessors for such integer fields. See supported primitive integer types.

pub fn read(&self) -> u16

Read the integer field from a given data region, assuming the defined layout, using the FieldView API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: u16
   //... other fields ...
});

fn func(storage_data: &[u8]) {
    let view = my_layout::View::new(storage_data);
    let read: u16 = view.some_integer_field().read();
}

impl<S: AsMut<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<u16, E, OFFSET_>>

Field type u16: This field represents a little endian integer. In this impl, we define write accessors for such integer fields. See supported primitive integer types.

pub fn write(&mut self, value: u16)

Write the integer field to a given data region, assuming the defined layout, using the Field API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: u16
   //... other fields ...
});

fn func(storage_data: &mut [u8]) {
    let mut view = my_layout::View::new(storage_data);
    view.some_integer_field_mut().write(10);
}

impl<S: AsRef<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<u32, E, OFFSET_>>

Field type u32: This field represents a little endian integer. In this impl, we define read accessors for such integer fields. See supported primitive integer types.

pub fn read(&self) -> u32

Read the integer field from a given data region, assuming the defined layout, using the FieldView API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: u32
   //... other fields ...
});

fn func(storage_data: &[u8]) {
    let view = my_layout::View::new(storage_data);
    let read: u32 = view.some_integer_field().read();
}

impl<S: AsMut<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<u32, E, OFFSET_>>

Field type u32: This field represents a little endian integer. In this impl, we define write accessors for such integer fields. See supported primitive integer types.

pub fn write(&mut self, value: u32)

Write the integer field to a given data region, assuming the defined layout, using the Field API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: u32
   //... other fields ...
});

fn func(storage_data: &mut [u8]) {
    let mut view = my_layout::View::new(storage_data);
    view.some_integer_field_mut().write(10);
}

impl<S: AsRef<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<u64, E, OFFSET_>>

Field type u64: This field represents a little endian integer. In this impl, we define read accessors for such integer fields. See supported primitive integer types.

pub fn read(&self) -> u64

Read the integer field from a given data region, assuming the defined layout, using the FieldView API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: u64
   //... other fields ...
});

fn func(storage_data: &[u8]) {
    let view = my_layout::View::new(storage_data);
    let read: u64 = view.some_integer_field().read();
}

impl<S: AsMut<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<u64, E, OFFSET_>>

Field type u64: This field represents a little endian integer. In this impl, we define write accessors for such integer fields. See supported primitive integer types.

pub fn write(&mut self, value: u64)

Write the integer field to a given data region, assuming the defined layout, using the Field API.

Example:

use binary_layout::prelude::*;
                        
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_integer_field: u64
   //... other fields ...
});

fn func(storage_data: &mut [u8]) {
    let mut view = my_layout::View::new(storage_data);
    view.some_integer_field_mut().write(10);
}

impl<S: AsRef<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<[u8], E, OFFSET_>>

Field type [u8]: This field represents an open ended byte array. In this impl, we define accessors that transfer ownership of the underlying immutable package data for such fields.

pub fn data(&self) -> &[u8]

Borrow the data in the byte array with read access using the FieldView API.

Example:

use binary_layout::prelude::*;
            
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   tail_data: [u8],
});

fn func(storage_data: &[u8]) {
    let view = my_layout::View::new(storage_data);
    let tail_data: &[u8] = view.tail_data().data();
}

impl<S: AsMut<[u8]>, E: Endianness, const OFFSET_: usize> FieldView<S, Field<[u8], E, OFFSET_>>

Field type [u8]: This field represents an open ended byte array. In this impl, we define write accessors for such fields.

pub fn data_mut(&mut self) -> &mut [u8]

Borrow the data in the byte array with write access using the FieldView API.

Example:

use binary_layout::prelude::*;
            
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   tail_data: [u8],
});

fn func(storage_data: &mut [u8]) {
    let mut view = my_layout::View::new(storage_data);
    let tail_data: &mut [u8] = view.tail_data_mut().data_mut();
}

impl<'a, S: AsRef<[u8]> + ?Sized, E: Endianness, const OFFSET_: usize> FieldView<&'a S, Field<[u8], E, OFFSET_>>

Field type [u8]: This field represents an open ended byte array. In this impl, we define read accessors for such fields.

pub fn extract(self) -> &'a [u8]

Similar to FieldView::data, but this also extracts the lifetime. The reference returned by FieldView::data can only life as long as the FieldView object lives. The reference returned by this function can live for as long as the original packed_data reference that as put into the FieldView lives. However, you can only call this if you let the FieldView die, it takes the self parameter by value. Also note that this function can only be called when the FieldView was constructed with either a &[u8] or a &mut [u8] as underlying storage for the storage_data. If the FieldView was constructed based on Vec<u8> storage, then this function semantically would have to return an owning subvector, but such a thing doesn’t exist in Rust.

Example:

use binary_layout::prelude::*;
            
define_layout!(my_layout, LittleEndian, {
   another_field: u64,
   tail_data: [u8],
});

fn func(storage_data: &[u8]) -> &[u8] {
    let view = my_layout::View::new(storage_data);
    let tail_data: &[u8] = view.into_tail_data().extract();
    // Now we return tail_data. Note that the view object doesn't survive
    // this function but we can still return the `tail_data` reference.
    // This wouldn't be possible with `FieldView::data`.
    tail_data
}

impl<'a, S: AsMut<[u8]> + ?Sized, E: Endianness, const OFFSET_: usize> FieldView<&'a mut S, Field<[u8], E, OFFSET_>>

Field type [u8]: This field represents an open ended byte array. In this impl, we define accessors that transfer ownership of the underlying mutable package data for such fields.

pub fn extract(self) -> &'a mut [u8]

Similar to FieldView::data, but this also extracts the lifetime. The reference returned by FieldView::data can only life as long as the FieldView object lives. The reference returned by this function can live for as long as the original packed_data reference that as put into the FieldView lives. However, you can only call this if you let the FieldView die, it takes the self parameter by value. Also note that this function can only be called when the FieldView was constructed with either a &[u8] or a &mut [u8] as underlying storage for the storage_data. If the FieldView was constructed based on Vec<u8> storage, then this function semantically would have to return an owning subvector, but such a thing doesn’t exist in Rust.

Example:

use binary_layout::prelude::*;
            
define_layout!(my_layout, LittleEndian, {
   another_field: u64,
   tail_data: [u8],
});

fn func(storage_data: &[u8]) -> &[u8] {
    let view = my_layout::View::new(storage_data);
    let tail_data: &[u8] = view.into_tail_data().extract();
    // Now we return tail_data. Note that the view object doesn't survive
    // this function but we can still return the `tail_data` reference.
    // This wouldn't be possible with `FieldView::data`.
    tail_data
}

impl<S: AsRef<[u8]>, E: Endianness, const N: usize, const OFFSET_: usize> FieldView<S, Field<[u8; N], E, OFFSET_>>

Field type [u8; N]: This field represents a fixed size byte array. In this impl, we define read accessors for such fields.

pub fn data(&self) -> &[u8; N]

Borrow the data in the byte array with read access using the FieldView API.

Example:

use binary_layout::prelude::*;
            
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_field: [u8; 5],
   //... other fields
});

fn func(storage_data: &[u8]) {
    let view = my_layout::View::new(storage_data);
    let some_field: &[u8; 5] = view.some_field().data();
}

impl<S: AsMut<[u8]>, E: Endianness, const N: usize, const OFFSET_: usize> FieldView<S, Field<[u8; N], E, OFFSET_>>

Field type [u8; N]: This field represents a fixed size byte array. In this impl, we define write accessors for such fields.

pub fn data_mut(&mut self) -> &mut [u8; N]

Borrow the data in the byte array with write access using the FieldView API.

Example:

use binary_layout::prelude::*;
            
define_layout!(my_layout, LittleEndian, {
   //... other fields ...
   some_field: [u8; 5],
   //... other fields
});

fn func(storage_data: &mut [u8]) {
    let mut view = my_layout::View::new(storage_data);
    let some_field: &mut [u8; 5] = view.some_field_mut().data_mut();
}