Struct FeagiByteStructure 

pub struct FeagiByteStructure { /* private fields */ }

Core container for validated FEAGI bytes structure data.

FeagiByteStructure is the central type for handling serialized FEAGI data structures. It provides a validated wrapper around raw bytes data, ensuring format compliance and offering high-level operations for manipulation and extraction.

Key Features

• Format Validation: Ensures bytes data conforms to FEAGI standards
• Type Safety: Validates structure types and versions before operations
• Multi-Structure Support: Can contain and manage multiple structures in one container
• Zero-Copy Operations: Provides efficient access to internal data without unnecessary copying
• Extensible Design: Supports new formats through the trait system

Binary Format Overview

Single Structure Format

[Type=? (1)][Version (1)][Type-specific payload...]

Multi-Structure Container Format

[Type=9 (1)][Version (1)][Count (1)][Headers...][Data...]
 
Where Headers = [Start₁ (4)][Length₁ (4)][Start₂ (4)][Length₂ (4)]...
And Data = [Structure₁][Structure₂]...

Thread Safety

FeagiByteStructure is thread-safe for concurrent read operations. Write operations (like capacity management) require exclusive access.

Implementations

impl FeagiByteStructure

pub const GLOBAL_BYTE_HEADER_BYTE_SIZE_IN_BYTES: usize = 2usize

Size of the global header (type + version) in bytes.

pub const MINIMUM_LENGTH_TO_BE_CONSIDERED_VALID: usize = 4usize

Minimum bytes length required for a valid FEAGI bytes structure.

pub const MULTISTRUCT_STRUCT_COUNT_BYTE_SIZE: usize = 1usize

Size of the structure count field in multi-structure wrapped_io_data.

pub const MULTISTRUCT_PER_STRUCT_HEADER_SIZE_IN_BYTES: usize = 8usize

Size of each structure’s header entry in multi-structure wrapped_io_data (start position + length).

pub const SUPPORTED_VERSION_JSON: u8 = 1u8

Currently supported version for JSON format structures.

pub const SUPPORTED_VERSION_MULTI_STRUCT: u8 = 1u8

Currently supported version for multi-structure wrapped_io_data.

pub const SUPPORTED_VERSION_NEURON_XYZP: u8 = 1u8

Currently supported version for neuron XYZP format structures.

pub fn create_from_bytes( bytes: Vec<u8>, ) -> Result<FeagiByteStructure, FeagiDataError>

Creates a new FeagiByteStructure from raw bytes data with full validation.

This is the primary constructor that validates the provided bytes data against FEAGI format requirements. It performs comprehensive checks to ensure the data represents a valid bytes structure before creating the container.

Arguments

• bytes - Raw bytes data containing a serialized FEAGI structure

Returns

• Ok(FeagiByteStructure) - Validated bytes structure ready for use
• Err(FeagiDataError) - If validation fails due to:
  • Insufficient data length (< 4 bytes minimum)
  • Invalid structure type identifier
  • Version number of 0 (reserved/invalid)
  • Format-specific validation failures

Validation Performed

• Minimum length check (at least 4 bytes)
• Valid structure type identifier (bytes 0)
• Non-zero version number (bytes 1)
• Additional format-specific validations may be added

pub fn create_from_2_existing( a: &FeagiByteStructure, b: &FeagiByteStructure, ) -> Result<FeagiByteStructure, FeagiDataError>

Creates a multi-structure container from exactly two existing structures.

This convenience method combines two FEAGI bytes structures into a single multi-structure container. It’s optimized for the common case of combining two structures and delegates to the general multi-structure creation logic.

Arguments

• a - First structure to include in the container
• b - Second structure to include in the container

Returns

• Ok(FeagiByteStructure) - Multi-structure container with both inputs
• Err(FeagiDataError) - If container creation fails

Behavior

• If either input is already a multi-structure, it will be flattened
• The result will contain exactly the individual structures from both inputs
• No nested multi-structures are created

pub fn create_from_multiple_existing( existing: Vec<&FeagiByteStructure>, ) -> Result<FeagiByteStructure, FeagiDataError>

Creates a multi-structure container from multiple existing structures.

This method combines any number of FEAGI bytes structures into a single multi-structure container. It automatically flattens any input multi-structures to avoid nesting and enforces reasonable limits on container size.

Arguments

• existing - Vector of references to structures to combine

Returns

• Ok(FeagiByteStructure) - Multi-structure container with all inputs
• Err(FeagiDataError) - If creation fails due to:
  • Empty input vector (at least one structure required)
  • Too many structures (maximum 255 supported)
  • Memory allocation failures

Behavior

• Single Input: Returns a clone of the input (no container needed)
• Multiple Inputs: Creates a new multi-structure container
• Flattening: Any input multi-structures are flattened into individual structures
• Ordering: Output order matches input order, with multi-structure contents expanded in place

Container Limits

• Maximum of 255 individual structures in the final container
• This limit is enforced after flattening all input multi-structures

pub fn create_from_compatible( object: Box<dyn FeagiByteStructureCompatible>, ) -> Result<FeagiByteStructure, FeagiDataError>

Creates a FeagiByteStructure from any compatible object.

This convenience constructor takes any object implementing the FeagiByteStructureCompatible trait and converts it to a validated bytes structure. Useful for serializing custom types.

Arguments

• object - Boxed object implementing FeagiByteStructureCompatible

Returns

• Ok(FeagiByteStructure) - Validated bytes structure containing the serialized object
• Err(FeagiDataError) - If serialization or validation fails

pub fn try_get_structure_type( &self, ) -> Result<FeagiByteStructureType, FeagiDataError>

Returns the format type of this bytes structure.

Extracts and validates the format type identifier from the first bytes of the structure. This is used to determine how to interpret the remaining data in the structure.

Returns

• Ok(FeagiByteStructureType) - The format type of this structure
• Err(FeagiDataError) - If the structure is empty or contains an invalid type

pub fn try_get_version(&self) -> Result<u8, FeagiDataError>

Returns the format version of this bytes structure.

Extracts the version number from the second bytes of the structure. Version numbers allow for format evolution while maintaining compatibility.

Returns

• Ok(u8) - The version number of this structure’s format
• Err(FeagiDataError) - If the structure is too short to contain version information

pub fn is_multistruct(&self) -> Result<bool, FeagiDataError>

Checks if this bytes structure is a multi-structure container.

Multi-structure wrapped_io_data can hold multiple individual FEAGI structures in a single bytes stream, each with its own format type and data.

Returns

• Ok(true) - This is a multi-structure container
• Ok(false) - This is a single structure
• Err(FeagiDataError) - If the structure type cannot be determined

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

Returns the number of individual structures contained in this bytes structure.

For single structures, this always returns 1. For multi-structure wrapped_io_data, this returns the number of individual structures contained within.

Returns

• Ok(usize) - The number of contained structures (always ≥ 1)
• Err(FeagiDataError) - If structure validation fails

pub fn get_ordered_object_types( &self, ) -> Result<Vec<FeagiByteStructureType>, FeagiDataError>

pub fn copy_out_single_byte_structure_from_multistruct( &self, index: usize, ) -> Result<FeagiByteStructure, FeagiDataError>

pub fn copy_out_single_object_from_single_struct( &self, ) -> Result<Box<dyn FeagiByteStructureCompatible>, FeagiDataError>

Extracts the original object from a single (non-multi-structure) bytes structure.

This method deserializes the contained data back to its original object form using the appropriate deserialization logic based on the structure’s format type. Only works with single structures - use copy_out_single_object_from_multistruct() for multi-structure wrapped_io_data.

Returns

• Ok(Box<dyn FeagiByteStructureCompatible>) - The deserialized original object
• Err(FeagiDataError) - If:
  • This is a multi-structure container (use the multistruct variant instead)
  • Deserialization fails due to corrupted data
  • Unsupported format type

Supported Format Types

• JSON → JsonStructure
• NeuronCategoricalXYZP → CorticalMappedXYZPNeuronData

pub fn copy_out_single_object_from_multistruct( &self, index: usize, ) -> Result<Box<dyn FeagiByteStructureCompatible>, FeagiDataError>

pub fn copy_out_as_byte_vector(&self) -> Vec<u8>

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

Returns a read-only reference to the internal bytes data.

Provides direct access to the underlying bytes array for reading. Useful for efficient transmission or when you need to work with the raw bytes format directly.

Returns

Read-only slice containing the complete bytes structure data

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

Returns a mutable reference to the internal bytes data.

Provides direct write access to the underlying bytes array. Caution: Modifying the data directly can invalidate the structure and cause deserialization failures. Use with care.

Returns

Mutable slice for direct bytes manipulation

Safety

Direct modification bypasses validation. Ensure any changes maintain proper FEAGI bytes structure format compliance.

pub fn borrow_data_as_mut_vec(&mut self) -> &mut Vec<u8>

Returns a mutable reference to the internal bytes vector.

Provides full access to the underlying Vec for advanced operations like resizing or bulk modifications. Caution: Direct modifications can break format compliance.

Returns

Mutable reference to the internal bytes vector

Safety

Direct vector manipulation bypasses all validation. Only use when you understand the FEAGI bytes structure format requirements.

pub fn get_wasted_capacity_count(&self) -> usize

pub fn get_utilized_capacity_percentage(&self) -> f32

pub fn ensure_capacity_of_at_least( &mut self, size: usize, ) -> Result<(), FeagiDataError>

pub fn shed_wasted_capacity(&mut self)

pub fn reset_write_index(&mut self)

Trait Implementations

impl Clone for FeagiByteStructure

fn clone(&self) -> FeagiByteStructure

Returns a duplicate of the value.

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

Performs copy-assignment from source.