Struct StructDeserializer 

pub struct StructDeserializer { /* private fields */ }

Deserializer for structured data extraction and type conversion

This struct provides a type-safe interface for deserializing complex structures that were created with StructSerializer. It supports both JSON and binary formats, with comprehensive error handling and flexible field access patterns.

The deserializer maintains a HashMap of field names to FieldValue instances, allowing for efficient field lookup and extraction. Fields are consumed during extraction to prevent accidental reuse and ensure proper deserialization flow.

Fields

• fields - Internal storage mapping field names to their serialized values

Thread Safety

This type is not thread-safe. Access from multiple threads requires external synchronization.

Memory Layout

The deserializer uses a HashMap for field storage, providing O(1) average field lookup time. Memory usage scales linearly with the number of fields.

Implementations

impl StructDeserializer

pub fn from_fields(fields: HashMap<String, FieldValue>) -> Self

Create a new StructDeserializer from a field map

This is the recommended way to create a StructDeserializer when you have a HashMap of fields, typically from a FieldValue::Object variant or when constructing a deserializer programmatically.

Arguments

• fields - HashMap containing field names and their serialized values

Returns

A new StructDeserializer ready for field extraction

Performance

This constructor performs no validation or conversion, making it the fastest way to create a deserializer when you already have the field data.

pub fn load_json<P: AsRef<Path>>(path: P) -> SerializationResult<Self>

Load a struct from a JSON file

Reads a JSON file from the filesystem and creates a StructDeserializer from its contents. The file is expected to contain a valid JSON object that can be parsed into field-value pairs.

Arguments

• path - Path to the JSON file to load

Returns

A StructDeserializer containing the parsed field data, or an error if the file cannot be read or parsed

Errors

Returns an error if:

• The file does not exist or cannot be opened
• The file contains invalid JSON
• The JSON structure is not a valid object
• I/O errors occur during file reading

Performance

The entire file is read into memory before parsing. For very large files, consider using streaming JSON parsing instead.

pub fn load_binary<P: AsRef<Path>>(path: P) -> SerializationResult<Self>

Load a struct from a binary file

Reads a binary file from the filesystem and creates a StructDeserializer from its contents. The file is expected to contain valid binary data that was previously serialized using the binary format.

Arguments

• path - Path to the binary file to load

Returns

A StructDeserializer containing the parsed field data, or an error if the file cannot be read or parsed

Errors

Returns an error if:

• The file does not exist or cannot be opened
• The file contains invalid binary format
• The binary data is corrupted or truncated
• I/O errors occur during file reading

Performance

The entire file is read into memory before parsing. Binary format is typically more compact and faster to parse than JSON.

pub fn field<T: FromFieldValue>(&mut self, name: &str) -> SerializationResult<T>

Extract a field with automatic type detection

Extracts a field from the deserializer and converts it to the specified type. The field is consumed (removed) from the deserializer to prevent accidental reuse and ensure proper deserialization flow.

Arguments

• name - Name of the field to extract

Returns

The converted field value, or an error if the field is missing or cannot be converted to the target type

Errors

Returns an error if:

• The field does not exist in the deserializer
• The field value cannot be converted to the target type
• Type conversion fails due to incompatible data

Performance

Field extraction is O(1) average case due to HashMap lookup. The field is removed from the deserializer to prevent memory leaks.

Examples found in repository

examples/serialization/nested_structures.rs (line 57)

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let email = deserializer.field("email")?;
        let phone = deserializer.field("phone")?;
        let address_city = deserializer.field("address_city")?;
        let address_state = deserializer.field("address_state")?;
        let social_media = deserializer.field("social_media")?;

        Ok(ContactInfo {
            email,
            phone,
            address_city,
            address_state,
            social_media,
        })
    }
}

impl ToFieldValue for ContactInfo {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for ContactInfo {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ContactInfo from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize ContactInfo from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ContactInfo, found {}",
                value.type_name()
            ),
        })
    }
}

/// Address struct
#[derive(Debug, Clone, PartialEq)]
pub struct Address {
    pub street: String,
    pub city: String,
    pub state: String,
    pub postal_code: String,
    pub country: String,
}

impl StructSerializable for Address {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("street", &self.street)
            .field("city", &self.city)
            .field("state", &self.state)
            .field("postal_code", &self.postal_code)
            .field("country", &self.country)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let street = deserializer.field("street")?;
        let city = deserializer.field("city")?;
        let state = deserializer.field("state")?;
        let postal_code = deserializer.field("postal_code")?;
        let country = deserializer.field("country")?;

        Ok(Address {
            street,
            city,
            state,
            postal_code,
            country,
        })
    }
}

impl ToFieldValue for Address {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Address {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Address from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Address from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Address, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project information struct
#[derive(Debug, Clone, PartialEq)]
pub struct Project {
    pub name: String,
    pub description: String,
    pub status: ProjectStatus,
    pub budget: f64,
    pub team_members: Vec<String>,
    pub milestones: Vec<Milestone>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for Project {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("status", &self.status)
            .field("budget", &self.budget)
            .field("team_members", &self.team_members)
            .field("milestones", &self.milestones)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let status = deserializer.field("status")?;
        let budget = deserializer.field("budget")?;
        let team_members = deserializer.field("team_members")?;
        let milestones = deserializer.field("milestones")?;
        let metadata = deserializer.field("metadata")?;

        Ok(Project {
            name,
            description,
            status,
            budget,
            team_members,
            milestones,
            metadata,
        })
    }
}

impl ToFieldValue for Project {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Project {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Project from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Project from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Project, found {}",
                value.type_name()
            ),
        })
    }
}

/// Project status enumeration
#[derive(Debug, Clone, PartialEq)]
pub enum ProjectStatus {
    Planning,
    InProgress,
    OnHold,
    Completed,
    Cancelled,
}

impl ToFieldValue for ProjectStatus {
    fn to_field_value(&self) -> FieldValue {
        let status_str = match self {
            ProjectStatus::Planning => "planning",
            ProjectStatus::InProgress => "in_progress",
            ProjectStatus::OnHold => "on_hold",
            ProjectStatus::Completed => "completed",
            ProjectStatus::Cancelled => "cancelled",
        };
        FieldValue::from_string(status_str.to_string())
    }
}

impl FromFieldValue for ProjectStatus {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        match value {
            FieldValue::String(s) => match s.as_str() {
                "planning" => Ok(ProjectStatus::Planning),
                "in_progress" => Ok(ProjectStatus::InProgress),
                "on_hold" => Ok(ProjectStatus::OnHold),
                "completed" => Ok(ProjectStatus::Completed),
                "cancelled" => Ok(ProjectStatus::Cancelled),
                _ => Err(SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Unknown project status: {}", s),
                }),
            },
            _ => Err(SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!(
                    "Expected String for ProjectStatus, found {}",
                    value.type_name()
                ),
            }),
        }
    }
}

/// Project milestone struct
#[derive(Debug, Clone, PartialEq)]
pub struct Milestone {
    pub name: String,
    pub description: String,
    pub due_date: String, // Simplified as string for this example
    pub is_completed: bool,
    pub progress_percentage: f32,
    pub dependencies: Vec<String>,
}

impl StructSerializable for Milestone {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("description", &self.description)
            .field("due_date", &self.due_date)
            .field("is_completed", &self.is_completed)
            .field("progress_percentage", &self.progress_percentage)
            .field("dependencies", &self.dependencies)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let description = deserializer.field("description")?;
        let due_date = deserializer.field("due_date")?;
        let is_completed = deserializer.field("is_completed")?;
        let progress_percentage = deserializer.field("progress_percentage")?;
        let dependencies = deserializer.field("dependencies")?;

        Ok(Milestone {
            name,
            description,
            due_date,
            is_completed,
            progress_percentage,
            dependencies,
        })
    }
}

impl ToFieldValue for Milestone {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Milestone {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Milestone from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Milestone from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Milestone, found {}",
                value.type_name()
            ),
        })
    }
}

/// Company struct with basic collections and nesting
#[derive(Debug, Clone, PartialEq)]
pub struct Company {
    pub name: String,
    pub founded_year: i32,
    pub headquarters_city: String,
    pub headquarters_state: String,
    pub employee_count: usize,
    pub department_names: Vec<String>,
    pub active_project_names: Vec<String>,
    pub company_metadata: HashMap<String, String>,
}

impl StructSerializable for Company {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("founded_year", &self.founded_year)
            .field("headquarters_city", &self.headquarters_city)
            .field("headquarters_state", &self.headquarters_state)
            .field("employee_count", &self.employee_count)
            .field("department_names", &self.department_names)
            .field("active_project_names", &self.active_project_names)
            .field("company_metadata", &self.company_metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let founded_year = deserializer.field("founded_year")?;
        let headquarters_city = deserializer.field("headquarters_city")?;
        let headquarters_state = deserializer.field("headquarters_state")?;
        let employee_count = deserializer.field("employee_count")?;
        let department_names = deserializer.field("department_names")?;
        let active_project_names = deserializer.field("active_project_names")?;
        let company_metadata = deserializer.field("company_metadata")?;

        Ok(Company {
            name,
            founded_year,
            headquarters_city,
            headquarters_state,
            employee_count,
            department_names,
            active_project_names,
            company_metadata,
        })
    }
}

impl ToFieldValue for Company {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for Company {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize Company from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize Company from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for Company, found {}",
                value.type_name()
            ),
        })
    }
}

/// Department struct
#[derive(Debug, Clone, PartialEq)]
pub struct Department {
    pub name: String,
    pub manager: String,
    pub employee_count: u32,
    pub budget: f64,
    pub office_locations: Vec<Address>,
}

impl StructSerializable for Department {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("manager", &self.manager)
            .field("employee_count", &self.employee_count)
            .field("budget", &self.budget)
            .field("office_locations", &self.office_locations)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let manager = deserializer.field("manager")?;
        let employee_count = deserializer.field("employee_count")?;
        let budget = deserializer.field("budget")?;
        let office_locations = deserializer.field("office_locations")?;

        Ok(Department {
            name,
            manager,
            employee_count,
            budget,
            office_locations,
        })
    }

examples/serialization/basic_structs.rs (line 59)

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let id = deserializer.field("id")?;
        let username = deserializer.field("username")?;
        let email = deserializer.field("email")?;
        let age = deserializer.field("age")?;
        let is_active = deserializer.field("is_active")?;
        let score = deserializer.field("score")?;

        Ok(UserProfile {
            id,
            username,
            email,
            age,
            is_active,
            score,
        })
    }
}

impl ToFieldValue for UserProfile {
    fn to_field_value(&self) -> FieldValue {
        // Convert to JSON and then parse as FieldValue for nested object handling
        match self.to_json() {
            Ok(json_str) => {
                // For examples, we'll serialize as JSON string for simplicity
                FieldValue::from_json_object(json_str)
            }
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for UserProfile {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize UserProfile from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize UserProfile from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for UserProfile, found {}",
                value.type_name()
            ),
        })
    }
}

/// Application settings struct with optional fields and collections
#[derive(Debug, Clone, PartialEq)]
pub struct AppSettings {
    pub app_name: String,
    pub version: String,
    pub debug_mode: bool,
    pub max_connections: u32,
    pub timeout_seconds: f32,
    pub features: Vec<String>,
    pub environment_vars: HashMap<String, String>,
    pub optional_database_url: Option<String>,
}

impl StructSerializable for AppSettings {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("app_name", &self.app_name)
            .field("version", &self.version)
            .field("debug_mode", &self.debug_mode)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
            .field("features", &self.features)
            .field("environment_vars", &self.environment_vars)
            .field("optional_database_url", &self.optional_database_url)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let app_name = deserializer.field("app_name")?;
        let version = deserializer.field("version")?;
        let debug_mode = deserializer.field("debug_mode")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;
        let features = deserializer.field("features")?;
        let environment_vars = deserializer.field("environment_vars")?;
        let optional_database_url = deserializer.field("optional_database_url")?;

        Ok(AppSettings {
            app_name,
            version,
            debug_mode,
            max_connections,
            timeout_seconds,
            features,
            environment_vars,
            optional_database_url,
        })
    }

examples/serialization/json_vs_binary.rs (line 59)

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let operation = deserializer.field("operation")?;
        let duration_micros = deserializer.field("duration_micros")?;
        let memory_usage_bytes = deserializer.field("memory_usage_bytes")?;
        let cpu_usage_percent = deserializer.field("cpu_usage_percent")?;
        let throughput_ops_per_sec = deserializer.field("throughput_ops_per_sec")?;
        let metadata = deserializer.field("metadata")?;

        Ok(PerformanceMetrics {
            operation,
            duration_micros,
            memory_usage_bytes,
            cpu_usage_percent,
            throughput_ops_per_sec,
            metadata,
        })
    }
}

impl ToFieldValue for PerformanceMetrics {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for PerformanceMetrics {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize PerformanceMetrics from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize PerformanceMetrics from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for PerformanceMetrics, found {}",
                value.type_name()
            ),
        })
    }
}

/// Large dataset for performance testing
#[derive(Debug, Clone, PartialEq)]
pub struct LargeDataset {
    pub name: String,
    pub values: Vec<f32>, // Changed from f64 to f32 (supported)
    pub labels: Vec<String>,
    pub feature_count: usize, // Simplified from Vec<Vec<f32>> to just a count
    pub feature_dimension: usize, // Store dimensions separately
    pub metadata: HashMap<String, String>,
    pub timestamp_count: usize, // Simplified from Vec<u64> to just count
}

impl StructSerializable for LargeDataset {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("name", &self.name)
            .field("values", &self.values)
            .field("labels", &self.labels)
            .field("feature_count", &self.feature_count)
            .field("feature_dimension", &self.feature_dimension)
            .field("metadata", &self.metadata)
            .field("timestamp_count", &self.timestamp_count)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let name = deserializer.field("name")?;
        let values = deserializer.field("values")?;
        let labels = deserializer.field("labels")?;
        let feature_count = deserializer.field("feature_count")?;
        let feature_dimension = deserializer.field("feature_dimension")?;
        let metadata = deserializer.field("metadata")?;
        let timestamp_count = deserializer.field("timestamp_count")?;

        Ok(LargeDataset {
            name,
            values,
            labels,
            feature_count,
            feature_dimension,
            metadata,
            timestamp_count,
        })
    }
}

impl ToFieldValue for LargeDataset {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for LargeDataset {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize LargeDataset from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize LargeDataset from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for LargeDataset, found {}",
                value.type_name()
            ),
        })
    }
}

/// Configuration data (typical JSON use case)
#[derive(Debug, Clone, PartialEq)]
pub struct Configuration {
    pub version: String,
    pub debug_enabled: bool,
    pub log_level: String,
    pub database_settings: HashMap<String, String>,
    pub feature_flags_enabled: bool, // Simplified from HashMap<String, bool>
    pub max_connections: f32,        // Simplified from HashMap<String, f64>
    pub timeout_seconds: f32,
}

impl StructSerializable for Configuration {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("version", &self.version)
            .field("debug_enabled", &self.debug_enabled)
            .field("log_level", &self.log_level)
            .field("database_settings", &self.database_settings)
            .field("feature_flags_enabled", &self.feature_flags_enabled)
            .field("max_connections", &self.max_connections)
            .field("timeout_seconds", &self.timeout_seconds)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let version = deserializer.field("version")?;
        let debug_enabled = deserializer.field("debug_enabled")?;
        let log_level = deserializer.field("log_level")?;
        let database_settings = deserializer.field("database_settings")?;
        let feature_flags_enabled = deserializer.field("feature_flags_enabled")?;
        let max_connections = deserializer.field("max_connections")?;
        let timeout_seconds = deserializer.field("timeout_seconds")?;

        Ok(Configuration {
            version,
            debug_enabled,
            log_level,
            database_settings,
            feature_flags_enabled,
            max_connections,
            timeout_seconds,
        })
    }

examples/serialization/error_handling.rs (line 58)

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let version = deserializer.field("version")?;
        let name = deserializer.field("name")?;
        let value = deserializer.field("value")?;

        // Handle optional fields gracefully for schema evolution
        let optional_field = deserializer.field_optional("optional_field")?;
        let new_field = deserializer.field_optional("new_field")?;

        // Validate version compatibility
        if version > 3 {
            return Err(SerializationError::ValidationFailed {
                field: "version".to_string(),
                message: format!("Unsupported version: {}. Maximum supported: 3", version),
            });
        }

        Ok(VersionedData {
            version,
            name,
            value,
            optional_field,
            new_field,
        })
    }
}

impl ToFieldValue for VersionedData {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for VersionedData {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize VersionedData from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize VersionedData from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for VersionedData, found {}",
                value.type_name()
            ),
        })
    }
}

/// Validated user input with constraints
#[derive(Debug, Clone, PartialEq)]
pub struct ValidatedUserInput {
    pub username: String,
    pub email: String,
    pub age: u16,
    pub preferences: HashMap<String, String>,
}

impl StructSerializable for ValidatedUserInput {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("username", &self.username)
            .field("email", &self.email)
            .field("age", &self.age)
            .field("preferences", &self.preferences)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let username: String = deserializer.field("username")?;
        let email: String = deserializer.field("email")?;
        let age: u16 = deserializer.field("age")?;
        let preferences: HashMap<String, String> = deserializer.field("preferences")?;

        // Validate username
        if username.is_empty() || username.len() > 50 {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message: "Username must be 1-50 characters long".to_string(),
            });
        }

        if !username
            .chars()
            .all(|c| c.is_alphanumeric() || c == '_' || c == '-')
        {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message:
                    "Username can only contain alphanumeric characters, underscores, and hyphens"
                        .to_string(),
            });
        }

        // Validate email (basic check)
        if !email.contains('@') || !email.contains('.') || email.len() < 5 {
            return Err(SerializationError::ValidationFailed {
                field: "email".to_string(),
                message: "Invalid email format".to_string(),
            });
        }

        // Validate age
        if !(13..=120).contains(&age) {
            return Err(SerializationError::ValidationFailed {
                field: "age".to_string(),
                message: "Age must be between 13 and 120".to_string(),
            });
        }

        // Validate preferences
        if preferences.len() > 20 {
            return Err(SerializationError::ValidationFailed {
                field: "preferences".to_string(),
                message: "Too many preferences (maximum 20)".to_string(),
            });
        }

        for (key, value) in &preferences {
            if key.len() > 50 || value.len() > 200 {
                return Err(SerializationError::ValidationFailed {
                    field: "preferences".to_string(),
                    message: format!("Preference key/value too long: {}", key),
                });
            }
        }

        Ok(ValidatedUserInput {
            username,
            email,
            age,
            preferences,
        })
    }
}

impl ToFieldValue for ValidatedUserInput {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for ValidatedUserInput {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ValidatedUserInput from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize ValidatedUserInput from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ValidatedUserInput, found {}",
                value.type_name()
            ),
        })
    }
}

/// Recovery helper for handling partial data
#[derive(Debug, Clone, PartialEq)]
pub struct RecoverableData {
    pub critical_field: String,
    pub important_field: Option<String>,
    pub optional_field: Option<String>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for RecoverableData {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("critical_field", &self.critical_field)
            .field("important_field", &self.important_field)
            .field("optional_field", &self.optional_field)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        // Critical field - must exist
        let critical_field = deserializer.field("critical_field")?;

        // Important field - try to recover if missing
        let important_field = deserializer.field_optional("important_field")?;

        // Optional field - graceful fallback
        let optional_field = deserializer.field_optional("optional_field")?;

        // Metadata - recover what we can
        let metadata = deserializer.field_or("metadata", HashMap::new())?;

        Ok(RecoverableData {
            critical_field,
            important_field,
            optional_field,
            metadata,
        })
    }

pub fn field_or<T: FromFieldValue>( &mut self, name: &str, default: T, ) -> SerializationResult<T>

Extract a field value with type conversion and provide a default if missing

Extracts a field from the deserializer and converts it to the specified type. If the field is missing, returns the provided default value instead of returning an error.

Arguments

• name - Name of the field to extract
• default - Default value to return if the field is missing

Returns

The converted field value, or the default value if the field is missing. Returns an error only if the field exists but cannot be converted to the target type.

Errors

Returns an error if:

• The field exists but cannot be converted to the target type
• Type conversion fails due to incompatible data

Performance

Field extraction is O(1) average case. The field is removed from the deserializer if it exists.

Examples found in repository

examples/serialization/error_handling.rs (line 280)

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        // Critical field - must exist
        let critical_field = deserializer.field("critical_field")?;

        // Important field - try to recover if missing
        let important_field = deserializer.field_optional("important_field")?;

        // Optional field - graceful fallback
        let optional_field = deserializer.field_optional("optional_field")?;

        // Metadata - recover what we can
        let metadata = deserializer.field_or("metadata", HashMap::new())?;

        Ok(RecoverableData {
            critical_field,
            important_field,
            optional_field,
            metadata,
        })
    }

pub fn field_optional<T: FromFieldValue>( &mut self, name: &str, ) -> SerializationResult<Option<T>>

Extract a field value as an optional type

Extracts a field from the deserializer and converts it to the specified type, returning Some(value) if the field exists and can be converted, or None if the field is missing.

Arguments

• name - Name of the field to extract

Returns

Some(converted_value) if the field exists and can be converted, None if the field is missing, or an error if the field exists but cannot be converted to the target type

Errors

Returns an error if:

• The field exists but cannot be converted to the target type
• Type conversion fails due to incompatible data

Performance

Field extraction is O(1) average case. The field is removed from the deserializer if it exists.

Examples found in repository

examples/serialization/error_handling.rs (line 63)

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let version = deserializer.field("version")?;
        let name = deserializer.field("name")?;
        let value = deserializer.field("value")?;

        // Handle optional fields gracefully for schema evolution
        let optional_field = deserializer.field_optional("optional_field")?;
        let new_field = deserializer.field_optional("new_field")?;

        // Validate version compatibility
        if version > 3 {
            return Err(SerializationError::ValidationFailed {
                field: "version".to_string(),
                message: format!("Unsupported version: {}. Maximum supported: 3", version),
            });
        }

        Ok(VersionedData {
            version,
            name,
            value,
            optional_field,
            new_field,
        })
    }
}

impl ToFieldValue for VersionedData {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for VersionedData {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize VersionedData from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!("Failed to deserialize VersionedData from binary: {}", e),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for VersionedData, found {}",
                value.type_name()
            ),
        })
    }
}

/// Validated user input with constraints
#[derive(Debug, Clone, PartialEq)]
pub struct ValidatedUserInput {
    pub username: String,
    pub email: String,
    pub age: u16,
    pub preferences: HashMap<String, String>,
}

impl StructSerializable for ValidatedUserInput {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("username", &self.username)
            .field("email", &self.email)
            .field("age", &self.age)
            .field("preferences", &self.preferences)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        let username: String = deserializer.field("username")?;
        let email: String = deserializer.field("email")?;
        let age: u16 = deserializer.field("age")?;
        let preferences: HashMap<String, String> = deserializer.field("preferences")?;

        // Validate username
        if username.is_empty() || username.len() > 50 {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message: "Username must be 1-50 characters long".to_string(),
            });
        }

        if !username
            .chars()
            .all(|c| c.is_alphanumeric() || c == '_' || c == '-')
        {
            return Err(SerializationError::ValidationFailed {
                field: "username".to_string(),
                message:
                    "Username can only contain alphanumeric characters, underscores, and hyphens"
                        .to_string(),
            });
        }

        // Validate email (basic check)
        if !email.contains('@') || !email.contains('.') || email.len() < 5 {
            return Err(SerializationError::ValidationFailed {
                field: "email".to_string(),
                message: "Invalid email format".to_string(),
            });
        }

        // Validate age
        if !(13..=120).contains(&age) {
            return Err(SerializationError::ValidationFailed {
                field: "age".to_string(),
                message: "Age must be between 13 and 120".to_string(),
            });
        }

        // Validate preferences
        if preferences.len() > 20 {
            return Err(SerializationError::ValidationFailed {
                field: "preferences".to_string(),
                message: "Too many preferences (maximum 20)".to_string(),
            });
        }

        for (key, value) in &preferences {
            if key.len() > 50 || value.len() > 200 {
                return Err(SerializationError::ValidationFailed {
                    field: "preferences".to_string(),
                    message: format!("Preference key/value too long: {}", key),
                });
            }
        }

        Ok(ValidatedUserInput {
            username,
            email,
            age,
            preferences,
        })
    }
}

impl ToFieldValue for ValidatedUserInput {
    fn to_field_value(&self) -> FieldValue {
        match self.to_json() {
            Ok(json_str) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for ValidatedUserInput {
    fn from_field_value(value: FieldValue, field_name: &str) -> SerializationResult<Self> {
        // Try JSON object first
        if let Ok(json_data) = value.as_json_object() {
            return Self::from_json(json_data).map_err(|e| SerializationError::ValidationFailed {
                field: field_name.to_string(),
                message: format!("Failed to deserialize ValidatedUserInput from JSON: {}", e),
            });
        }

        // Try binary object
        if let Ok(binary_data) = value.as_binary_object() {
            return Self::from_binary(binary_data).map_err(|e| {
                SerializationError::ValidationFailed {
                    field: field_name.to_string(),
                    message: format!(
                        "Failed to deserialize ValidatedUserInput from binary: {}",
                        e
                    ),
                }
            });
        }

        Err(SerializationError::ValidationFailed {
            field: field_name.to_string(),
            message: format!(
                "Expected JsonObject or BinaryObject for ValidatedUserInput, found {}",
                value.type_name()
            ),
        })
    }
}

/// Recovery helper for handling partial data
#[derive(Debug, Clone, PartialEq)]
pub struct RecoverableData {
    pub critical_field: String,
    pub important_field: Option<String>,
    pub optional_field: Option<String>,
    pub metadata: HashMap<String, String>,
}

impl StructSerializable for RecoverableData {
    fn to_serializer(&self) -> StructSerializer {
        StructSerializer::new()
            .field("critical_field", &self.critical_field)
            .field("important_field", &self.important_field)
            .field("optional_field", &self.optional_field)
            .field("metadata", &self.metadata)
    }

    fn from_deserializer(deserializer: &mut StructDeserializer) -> SerializationResult<Self> {
        // Critical field - must exist
        let critical_field = deserializer.field("critical_field")?;

        // Important field - try to recover if missing
        let important_field = deserializer.field_optional("important_field")?;

        // Optional field - graceful fallback
        let optional_field = deserializer.field_optional("optional_field")?;

        // Metadata - recover what we can
        let metadata = deserializer.field_or("metadata", HashMap::new())?;

        Ok(RecoverableData {
            critical_field,
            important_field,
            optional_field,
            metadata,
        })
    }

pub fn field_with_error<T: FromFieldValue, F>( &mut self, name: &str, error_fn: F, ) -> SerializationResult<T>

where F: FnOnce(&str, &SerializationError) -> SerializationResult<T>,

Extract a field value with custom error handling

Extracts a field from the deserializer and converts it to the specified type, using a custom error handling function to process any errors that occur during extraction or conversion.

Arguments

• name - Name of the field to extract
• error_fn - Function to handle errors during field extraction or conversion

Returns

The converted field value, or the result of the error handling function if an error occurs

Errors

The error handling function can return any error type that implements the appropriate error traits. The function is called with the field name and the original error for context.

Performance

Field extraction is O(1) average case. The error handling function is only called when an error occurs.

pub fn remaining_fields(&self) -> Vec<&str>

Get the names of all remaining fields

Returns a vector containing the names of all fields that have not yet been extracted from the deserializer. This is useful for debugging, validation, or implementing custom deserialization logic.

Returns

A vector of field names that are still available for extraction

Performance

This method performs O(n) work to collect all field names, where n is the number of remaining fields. The returned vector is a copy of the field names.

pub fn has_field(&self, name: &str) -> bool

Check if a field exists

Returns whether a field with the specified name exists in the deserializer and has not yet been extracted. This is useful for conditional field extraction or validation.

Arguments

• name - Name of the field to check

Returns

true if the field exists and has not been extracted, false otherwise

Performance

This method performs O(1) average case lookup using HashMap contains_key.

pub fn from_json(json: &str) -> SerializationResult<Self>

Create a deserializer from a JSON string

Parses a JSON string and creates a StructDeserializer from its contents. The JSON string is expected to contain a valid JSON object that can be parsed into field-value pairs.

Arguments

• json - JSON string to parse

Returns

A StructDeserializer containing the parsed field data, or an error if the JSON string cannot be parsed

Errors

Returns an error if:

• The JSON string is malformed or invalid
• The JSON structure is not a valid object
• Parsing fails due to unexpected JSON format

Performance

JSON parsing is performed in a single pass. The entire JSON string is processed to build the field map.

pub fn from_binary(data: &[u8]) -> SerializationResult<Self>

Create a deserializer from binary data

Parses binary data and creates a StructDeserializer from its contents. The binary data is expected to contain valid binary format data that was previously serialized using the binary format.

Arguments

• data - Binary data to parse

Returns

A StructDeserializer containing the parsed field data, or an error if the binary data cannot be parsed

Errors

Returns an error if:

• The binary data is malformed or corrupted
• The binary format is invalid or unsupported
• Parsing fails due to unexpected binary structure
• The data is truncated or incomplete

Performance

Binary parsing is typically faster than JSON parsing due to the more compact format and lack of string parsing overhead.

Trait Implementations

impl Debug for StructDeserializer

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

Formats the value using the given formatter.