Struct FeagiByteContainer 

pub struct FeagiByteContainer { /* private fields */ }

A container for serialized FEAGI data structures with efficient binary format.

FeagiByteContainer manages multiple serializable structures in a single byte array, providing methods to read, write, and validate the contained data. The container uses a header-based format with version control and structure indexing.

Format

• Global header: version (1 byte) + increment counter (2 bytes) + struct count (1 byte)
• Per-structure headers: data length (4 bytes each)
• Structure data: serialized structure bytes

Example

use feagi_serialization::FeagiByteContainer;

let mut container = FeagiByteContainer::new_empty();
assert!(container.is_valid());
assert_eq!(container.get_number_of_bytes_used(), 4); // Just the header

Implementations

impl FeagiByteContainer

pub const CURRENT_FBS_VERSION: u8 = 2

pub const GLOBAL_BYTE_HEADER_BYTE_COUNT: usize = 4

pub const STRUCTURE_LOOKUP_HEADER_BYTE_COUNT_PER_STRUCTURE: usize = 4

pub const STRUCT_HEADER_BYTE_COUNT: usize = 2

pub fn new_empty() -> Self

Creates a new empty container with default header.

The container starts with a 4-byte header containing version, zero increment counter, and zero structure count. The container is initially valid with just a 4 byte header stating 0 contained structures

Example

use feagi_serialization::FeagiByteContainer;

let container = FeagiByteContainer::new_empty();
assert!(container.is_valid());
assert_eq!(container.get_number_of_bytes_used(), 4);

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

Returns a reference to the internal byte array.

Provides direct read access to the raw bytes of the container, including headers and all serialized structure data.

Example

use feagi_serialization::FeagiByteContainer;

let container = FeagiByteContainer::new_empty();
let bytes = container.get_byte_ref();
assert_eq!(bytes.len(), 4);
assert_eq!(bytes[0], 2); // Current version

pub fn try_write_data_to_container_and_verify<F>( &mut self, byte_writer: &mut F, ) -> Result<(), FeagiDataError>

where F: FnMut(&mut Vec<u8>) -> Result<(), FeagiDataError>,

Writes data using a callback function and validates the container.

Allows external code to write directly to the byte array, then validates that the resulting data forms a valid container structure.

Example

use feagi_serialization::{FeagiByteContainer};

// NOTE: This function is just here as an example, but this specific implementation is invalid
let mut container = FeagiByteContainer::new_empty();
let result = container.try_write_data_to_container_and_verify(&mut |bytes| {
    *bytes = vec![20u8, 2u8, 3u8]; // This is an invalid byte sequence
    Ok(())
});
// This will fail validation since we're setting invalid data
assert!(result.is_err());

pub fn try_write_data_by_ownership_to_container_and_verify( &mut self, new_data: Vec<u8>, ) -> Result<(), FeagiDataError>

Writes data to the container by taking ownership of a byte vector then validates it. Resets allocation. Only use this if you have no option

Example

use feagi_serialization::{FeagiByteContainer};

// NOTE: This here as an example, but this specific implementation is invalid
let bytes = vec![20u8, 2u8, 3u8];
let mut container = FeagiByteContainer::new_empty();
let result = container.try_write_data_by_ownership_to_container_and_verify(bytes);
// This will fail validation since we're setting invalid data
assert!(result.is_err());

pub fn try_write_data_by_copy_and_verify( &mut self, new_data: &[u8], ) -> Result<(), FeagiDataError>

Writes data to the container by expanding the internal byte vector (if needed) and overwriting the internal data with the given slice. Does not free allocation.

Example

use feagi_serialization::{FeagiByteContainer};

// NOTE: This here as an example, but this specific implementation is invalid
let bytes = vec![20u8, 2u8, 3u8];
let mut container = FeagiByteContainer::new_empty();
let result = container.try_write_data_by_copy_and_verify(&bytes);
// This will fail validation since we're setting invalid data
assert!(result.is_err());

pub fn is_valid(&self) -> bool

Checks if the container has valid data structure.

Returns true if the container has been validated and contains properly formatted header and structure data.

Example

use feagi_serialization::FeagiByteContainer;

let container = FeagiByteContainer::new_empty();
assert!(container.is_valid());

pub fn try_get_number_contained_structures( &self, ) -> Result<usize, FeagiDataError>

Returns the number of structures contained in this container.

Only works if the container is valid. Returns an error if the container has not been validated or contains invalid data.

Example

use feagi_serialization::FeagiByteContainer;

let container = FeagiByteContainer::new_empty();
assert_eq!(container.try_get_number_contained_structures().unwrap(), 0);

pub fn get_number_of_bytes_used(&self) -> usize

Returns the total number of bytes currently used by the container.

This includes headers and all structure data.

Example

use feagi_serialization::FeagiByteContainer;

let container = FeagiByteContainer::new_empty();
assert_eq!(container.get_number_of_bytes_used(), 4); // Header only

pub fn get_number_of_bytes_allocated(&self) -> usize

Returns the total memory allocated for the byte array.

This may be larger than the number of bytes used due to Vec capacity.

Example

use feagi_serialization::FeagiByteContainer;

let container = FeagiByteContainer::new_empty();
assert!(container.get_number_of_bytes_allocated() >= 4);

pub fn get_increment_counter(&self) -> Result<u16, FeagiDataError>

Returns the increment counter value from the header.

The increment counter is a 16-bit value stored in bytes 1-2 of the header. Only works if the container is valid.

Example

use feagi_serialization::FeagiByteContainer;

let container = FeagiByteContainer::new_empty();
assert_eq!(container.get_increment_counter().unwrap(), 0u16);

pub fn try_create_new_struct_from_index( &self, index: u8, ) -> Result<Box<dyn FeagiSerializable>, FeagiDataError>

Creates a new structure instance from the data at the specified index.

Deserializes the structure data at the given index and returns a boxed trait object. The structure type is determined from the stored metadata.

Example

use feagi_serialization::FeagiByteContainer;

let container = FeagiByteContainer::new_empty();
// This will fail since there are no structures
assert!(container.try_create_new_struct_from_index(0).is_err());

pub fn try_create_struct_from_first_found_struct_of_type( &self, structure_type: FeagiByteStructureType, ) -> Result<Option<Box<dyn FeagiSerializable>>, FeagiDataError>

Creates a new structure from the first instance of the given type.

Searches for the first structure matching the specified type and deserializes it. Returns None if no structure of that type is found.

pub fn try_update_struct_from_index( &self, index: u8, updating_boxed_struct: &mut dyn FeagiSerializable, ) -> Result<(), FeagiDataError>

Updates an existing structure with data from the specified index.

Deserializes data at the given index and updates the provided structure.

pub fn try_update_struct_from_first_found_struct_of_type( &self, updating_boxed_struct: &mut dyn FeagiSerializable, ) -> Result<bool, FeagiDataError>

Updates a structure from the first found instance of its type.

Returns true if a matching structure was found and updated, false otherwise.

pub fn get_contained_struct_types(&self) -> Vec<FeagiByteStructureType>

Returns a list of all structure types contained in this container.

Provides a quick way to see what types of structures are available without deserializing them.

Example

use feagi_serialization::FeagiByteContainer;

let container = FeagiByteContainer::new_empty();
let types = container.get_contained_struct_types();
assert_eq!(types.len(), 0); // Empty container

pub fn overwrite_byte_data_with_multiple_struct_data( &mut self, incoming_structs: Vec<&dyn FeagiSerializable>, new_increment_value: u16, ) -> Result<(), FeagiDataError>

Overwrites the container with multiple serialized structures.

Clears existing data and serializes all provided structures into the container. Updates the increment counter to the specified value.

pub fn overwrite_byte_data_with_single_struct_data( &mut self, incoming_struct: &dyn FeagiSerializable, new_increment_value: u16, ) -> Result<(), FeagiDataError>

Overwrites the container with a single serialized structure.

Optimized version for when only one structure needs to be stored. Clears existing data and serializes the structure with the given increment value.

pub fn set_increment_counter_state( &mut self, new_increment_value: u16, ) -> Result<(), FeagiDataError>

Updates the increment counter in the header.

Modifies the 16-bit increment counter stored in bytes 1-2 of the header. The container must be valid for this operation to succeed.

Example

use feagi_serialization::FeagiByteContainer;

let mut container = FeagiByteContainer::new_empty();
_ = container.set_increment_counter_state(42);

pub fn free_unused_allocation(&mut self)

Frees any unused memory allocation in the byte vector.

Shrinks the capacity of the internal byte vector to match its length, potentially reducing memory usage.

Example

use feagi_serialization::FeagiByteContainer;

let mut container = FeagiByteContainer::new_empty();
container.free_unused_allocation();
assert_eq!(container.get_number_of_bytes_allocated(), container.get_number_of_bytes_used());

Trait Implementations

impl Clone for FeagiByteContainer

fn clone(&self) -> FeagiByteContainer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FeagiByteContainer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for FeagiByteContainer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.