Trait StructSerializable 

pub trait StructSerializable: Sized {
    // Required methods
    fn to_serializer(&self) -> StructSerializer;
    fn from_deserializer(
        deserializer: &mut StructDeserializer,
    ) -> SerializationResult<Self>;

    // Provided methods
    fn save_json<P: AsRef<Path>>(&self, path: P) -> SerializationResult<()> { ... }
    fn save_binary<P: AsRef<Path>>(&self, path: P) -> SerializationResult<()> { ... }
    fn load_json<P: AsRef<Path>>(path: P) -> SerializationResult<Self> { ... }
    fn load_binary<P: AsRef<Path>>(path: P) -> SerializationResult<Self> { ... }
    fn to_json(&self) -> SerializationResult<String> { ... }
    fn to_binary(&self) -> SerializationResult<Vec<u8>> { ... }
    fn from_json(json: &str) -> SerializationResult<Self> { ... }
    fn from_binary(data: &[u8]) -> SerializationResult<Self> { ... }
}

Trait for structs that can be serialized and deserialized using the struct builder pattern

This trait provides a complete serialization and deserialization interface for structs, offering both manual field-by-field control and convenient file I/O operations. It serves as a zero-dependency alternative to serde’s derive macros, allowing structs to be easily serialized and deserialized with minimal boilerplate.

Purpose

The StructSerializable trait provides:

• Complete serialization workflow: From struct to multiple output formats
• File I/O operations: Direct save/load to JSON and binary files
• String/binary conversion: In-memory serialization and deserialization
• Type safety: Compile-time guarantees for struct serialization
• Error handling: Comprehensive error reporting for all operations
• Zero dependencies: Pure Rust implementation without external crates

Required Methods

• to_serializer - Convert the struct to a StructSerializer
• from_deserializer - Create the struct from a StructDeserializer

Provided Methods

• save_json - Save the struct to a JSON file
• save_binary - Save the struct to a binary file
• load_json - Load the struct from a JSON file
• load_binary - Load the struct from a binary file
• to_json - Convert the struct to a JSON string
• to_binary - Convert the struct to binary data
• from_json - Create the struct from a JSON string
• from_binary - Create the struct from binary data

Examples

The trait provides comprehensive serialization capabilities with file I/O and format conversion.

Implementors

Common types that implement this trait include:

• Configuration structs: Settings, config files, parameters
• Data models: Business logic entities, domain objects
• Serializable objects: Any struct requiring persistence
• Custom types: User-defined serializable structures

Thread Safety

Implementations should be thread-safe. The trait methods should not modify any shared state and should be safe to call concurrently.

Required Methods

fn to_serializer(&self) -> StructSerializer

Converts the struct to a StructSerializer

This method should create a StructSerializer and register all fields that should be serialized. The implementation should use the fluent interface to build the serializer with all relevant fields.

Returns

A StructSerializer containing all the struct’s serializable fields

Examples

Creates a serializer with all struct fields using the fluent interface.

fn from_deserializer( deserializer: &mut StructDeserializer, ) -> SerializationResult<Self>

Creates the struct from a StructDeserializer

This method should extract all fields from the deserializer and construct a new instance of the struct. It should handle field extraction errors gracefully and provide meaningful error messages.

Arguments

• deserializer - The deserializer containing the struct’s field data

Returns

Ok(Self) on successful struct construction Err(SerializationError) if field extraction or construction fails

Examples

Extracts fields and constructs the struct with proper error handling.

Provided Methods

fn save_json<P: AsRef<Path>>(&self, path: P) -> SerializationResult<()>

Saves the struct to a JSON file

Serializes the struct to JSON format and writes it to the specified file path. The file is created if it doesn’t exist, or truncated if it already exists.

Arguments

• path - File path where the JSON data should be written

Returns

Ok(()) on successful file write Err(SerializationError) if serialization or file I/O fails

Examples

Saves struct data to a JSON file with proper file I/O handling.

Examples found in repository

examples/neural_networks/basic_linear_layer.rs (line 98)

    pub fn save_json(&self, path: &str) -> Result<(), Box<dyn std::error::Error>> {
        // Create directory if it doesn't exist
        if let Some(parent) = std::path::Path::new(path).parent() {
            fs::create_dir_all(parent)?;
        }

        let weight_path = format!("{}_weight.json", path);
        let bias_path = format!("{}_bias.json", path);

        self.weight.save_json(&weight_path)?;
        self.bias.save_json(&bias_path)?;

        println!("Saved linear layer to {} (weight and bias)", path);
        Ok(())
    }

examples/neural_networks/feedforward_network.rs (line 214)

    pub fn save_json(&self, path: &str) -> Result<(), Box<dyn std::error::Error>> {
        if let Some(parent) = std::path::Path::new(path).parent() {
            fs::create_dir_all(parent)?;
        }

        for (i, layer) in self.layers.iter().enumerate() {
            let layer_path = format!("{}_layer_{}", path, i);
            let weight_path = format!("{}_weight.json", layer_path);
            let bias_path = format!("{}_bias.json", layer_path);

            layer.weight.save_json(&weight_path)?;
            layer.bias.save_json(&bias_path)?;
        }

        println!(
            "Saved feed-forward network to {} ({} layers)",
            path,
            self.layers.len()
        );
        Ok(())
    }

examples/serialization/basic_structs.rs (line 251)

fn demonstrate_user_profile_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- User Profile Serialization ---");

    // Create a user profile with various field types
    let user = UserProfile {
        id: 12345,
        username: "alice_cooper".to_string(),
        email: "alice@example.com".to_string(),
        age: 28,
        is_active: true,
        score: 95.7,
    };

    println!("Original user profile:");
    println!("  ID: {}", user.id);
    println!("  Username: {}", user.username);
    println!("  Email: {}", user.email);
    println!("  Age: {}", user.age);
    println!("  Active: {}", user.is_active);
    println!("  Score: {}", user.score);

    // Serialize to JSON
    let json_data = user.to_json()?;
    println!("\nSerialized to JSON:");
    println!("{}", json_data);

    // Save to JSON file
    user.save_json("temp_user_profile.json")?;
    println!("Saved to file: temp_user_profile.json");

    // Load from JSON file
    let loaded_user = UserProfile::load_json("temp_user_profile.json")?;
    println!("\nLoaded user profile:");
    println!("  ID: {}", loaded_user.id);
    println!("  Username: {}", loaded_user.username);
    println!("  Email: {}", loaded_user.email);
    println!("  Age: {}", loaded_user.age);
    println!("  Active: {}", loaded_user.is_active);
    println!("  Score: {}", loaded_user.score);

    // Verify data integrity
    assert_eq!(user, loaded_user);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate serialization with collections and optional fields
fn demonstrate_app_settings_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- App Settings Serialization ---");

    // Create app settings with collections and optional fields
    let mut env_vars = HashMap::new();
    env_vars.insert("LOG_LEVEL".to_string(), "info".to_string());
    env_vars.insert("PORT".to_string(), "8080".to_string());
    env_vars.insert("HOST".to_string(), "localhost".to_string());

    let settings = AppSettings {
        app_name: "Train Station Example".to_string(),
        version: "1.0.0".to_string(),
        debug_mode: true,
        max_connections: 100,
        timeout_seconds: 30.5,
        features: vec![
            "authentication".to_string(),
            "logging".to_string(),
            "metrics".to_string(),
        ],
        environment_vars: env_vars,
        optional_database_url: Some("postgresql://localhost:5432/mydb".to_string()),
    };

    println!("Original app settings:");
    println!("  App Name: {}", settings.app_name);
    println!("  Version: {}", settings.version);
    println!("  Debug Mode: {}", settings.debug_mode);
    println!("  Max Connections: {}", settings.max_connections);
    println!("  Timeout: {} seconds", settings.timeout_seconds);
    println!("  Features: {:?}", settings.features);
    println!("  Environment Variables: {:?}", settings.environment_vars);
    println!("  Database URL: {:?}", settings.optional_database_url);

    // Serialize to binary format for efficient storage
    let binary_data = settings.to_binary()?;
    println!("\nSerialized to binary: {} bytes", binary_data.len());

    // Save to binary file
    settings.save_binary("temp_app_settings.bin")?;
    println!("Saved to file: temp_app_settings.bin");

    // Load from binary file
    let loaded_settings = AppSettings::load_binary("temp_app_settings.bin")?;
    println!("\nLoaded app settings:");
    println!("  App Name: {}", loaded_settings.app_name);
    println!("  Version: {}", loaded_settings.version);
    println!("  Debug Mode: {}", loaded_settings.debug_mode);
    println!("  Features count: {}", loaded_settings.features.len());
    println!(
        "  Environment variables count: {}",
        loaded_settings.environment_vars.len()
    );

    // Verify data integrity
    assert_eq!(settings, loaded_settings);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison between JSON and binary
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    let user = UserProfile {
        id: 98765,
        username: "bob_builder".to_string(),
        email: "bob@construction.com".to_string(),
        age: 35,
        is_active: false,
        score: 87.2,
    };

    // Save in both formats
    user.save_json("temp_format_comparison.json")?;
    user.save_binary("temp_format_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_format_comparison.json")?.len();
    let binary_size = fs::metadata("temp_format_comparison.bin")?.len();

    println!("Format comparison for UserProfile:");
    println!("  JSON file size: {} bytes", json_size);
    println!("  Binary file size: {} bytes", binary_size);
    println!(
        "  Size ratio (JSON/Binary): {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Demonstrate readability
    let json_content = fs::read_to_string("temp_format_comparison.json")?;
    println!("\nJSON format (human-readable):");
    println!("{}", json_content);

    println!("\nBinary format (first 32 bytes as hex):");
    let binary_content = fs::read("temp_format_comparison.bin")?;
    for (i, byte) in binary_content.iter().take(32).enumerate() {
        if i % 16 == 0 && i > 0 {
            println!();
        }
        print!("{:02x} ", byte);
    }
    println!("\n... ({} total bytes)", binary_content.len());

    // Load and verify both formats produce identical results
    let json_loaded = UserProfile::load_json("temp_format_comparison.json")?;
    let binary_loaded = UserProfile::load_binary("temp_format_comparison.bin")?;

    assert_eq!(json_loaded, binary_loaded);
    println!("\nFormat consistency verification: PASSED");

    Ok(())
}

examples/getting_started/serialization_basics.rs (line 65)

fn demonstrate_tensor_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Tensor Serialization ---");

    // Create a tensor with some data
    let original_tensor = Tensor::from_slice(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0], vec![2, 3]).unwrap();
    println!(
        "Original tensor: shape {:?}, data: {:?}",
        original_tensor.shape().dims,
        original_tensor.data()
    );

    // Save tensor in JSON format
    let json_path = "temp_tensor.json";
    original_tensor.save_json(json_path)?;
    println!("Saved tensor to JSON: {}", json_path);

    // Load tensor from JSON
    let loaded_tensor_json = Tensor::load_json(json_path)?;
    println!(
        "Loaded from JSON: shape {:?}, data: {:?}",
        loaded_tensor_json.shape().dims,
        loaded_tensor_json.data()
    );

    // Verify data integrity
    assert_eq!(
        original_tensor.shape().dims,
        loaded_tensor_json.shape().dims
    );
    assert_eq!(original_tensor.data(), loaded_tensor_json.data());
    println!("JSON serialization verification: PASSED");

    // Save tensor in binary format
    let binary_path = "temp_tensor.bin";
    original_tensor.save_binary(binary_path)?;
    println!("Saved tensor to binary: {}", binary_path);

    // Load tensor from binary
    let loaded_tensor_binary = Tensor::load_binary(binary_path)?;
    println!(
        "Loaded from binary: shape {:?}, data: {:?}",
        loaded_tensor_binary.shape().dims,
        loaded_tensor_binary.data()
    );

    // Verify data integrity
    assert_eq!(
        original_tensor.shape().dims,
        loaded_tensor_binary.shape().dims
    );
    assert_eq!(original_tensor.data(), loaded_tensor_binary.data());
    println!("Binary serialization verification: PASSED");

    Ok(())
}

/// Demonstrate optimizer serialization and deserialization
fn demonstrate_optimizer_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Optimizer Serialization ---");

    // Create an optimizer with some parameters
    let mut weight = Tensor::randn(vec![2, 2], Some(42)).with_requires_grad();
    let mut bias = Tensor::randn(vec![2], Some(43)).with_requires_grad();

    let config = AdamConfig {
        learning_rate: 0.001,
        beta1: 0.9,
        beta2: 0.999,
        eps: 1e-8,
        weight_decay: 0.0,
        amsgrad: false,
    };

    let mut optimizer = Adam::with_config(config);
    optimizer.add_parameter(&weight);
    optimizer.add_parameter(&bias);

    println!(
        "Created optimizer with {} parameters",
        optimizer.parameter_count()
    );
    println!("Learning rate: {}", optimizer.learning_rate());

    // Simulate some training steps
    for _ in 0..3 {
        let mut loss = weight.sum() + bias.sum();
        loss.backward(None);
        optimizer.step(&mut [&mut weight, &mut bias]);
        optimizer.zero_grad(&mut [&mut weight, &mut bias]);
    }

    // Save optimizer state
    let optimizer_path = "temp_optimizer.json";
    optimizer.save_json(optimizer_path)?;
    println!("Saved optimizer to: {}", optimizer_path);

    // Load optimizer state
    let loaded_optimizer = Adam::load_json(optimizer_path)?;
    println!(
        "Loaded optimizer with {} parameters",
        loaded_optimizer.parameter_count()
    );
    println!("Learning rate: {}", loaded_optimizer.learning_rate());

    // Verify optimizer state
    assert_eq!(
        optimizer.parameter_count(),
        loaded_optimizer.parameter_count()
    );
    assert_eq!(optimizer.learning_rate(), loaded_optimizer.learning_rate());
    println!("Optimizer serialization verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison and performance characteristics
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    // Create a larger tensor for comparison
    let tensor = Tensor::randn(vec![10, 10], Some(44));

    // Save in both formats
    tensor.save_json("temp_comparison.json")?;
    tensor.save_binary("temp_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_comparison.json")?.len();
    let binary_size = fs::metadata("temp_comparison.bin")?.len();

    println!("JSON file size: {} bytes", json_size);
    println!("Binary file size: {} bytes", binary_size);
    println!(
        "Compression ratio: {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Load and verify both formats
    let json_tensor = Tensor::load_json("temp_comparison.json")?;
    let binary_tensor = Tensor::load_binary("temp_comparison.bin")?;

    assert_eq!(tensor.shape().dims, json_tensor.shape().dims);
    assert_eq!(tensor.shape().dims, binary_tensor.shape().dims);
    assert_eq!(tensor.data(), json_tensor.data());
    assert_eq!(tensor.data(), binary_tensor.data());

    println!("Format comparison verification: PASSED");

    Ok(())
}

/// Demonstrate a basic model checkpointing workflow
fn demonstrate_model_checkpointing() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Model Checkpointing ---");

    // Create a simple model (weights and bias)
    let mut weights = Tensor::randn(vec![2, 1], Some(45)).with_requires_grad();
    let mut bias = Tensor::randn(vec![1], Some(46)).with_requires_grad();

    // Create optimizer
    let mut optimizer = Adam::with_learning_rate(0.01);
    optimizer.add_parameter(&weights);
    optimizer.add_parameter(&bias);

    println!("Initial weights: {:?}", weights.data());
    println!("Initial bias: {:?}", bias.data());

    // Simulate training
    for epoch in 0..5 {
        let mut loss = weights.sum() + bias.sum();
        loss.backward(None);
        optimizer.step(&mut [&mut weights, &mut bias]);
        optimizer.zero_grad(&mut [&mut weights, &mut bias]);

        if epoch % 2 == 0 {
            // Save checkpoint
            let checkpoint_dir = format!("checkpoint_epoch_{}", epoch);
            fs::create_dir_all(&checkpoint_dir)?;

            weights.save_json(format!("{}/weights.json", checkpoint_dir))?;
            bias.save_json(format!("{}/bias.json", checkpoint_dir))?;
            optimizer.save_json(format!("{}/optimizer.json", checkpoint_dir))?;

            println!("Saved checkpoint for epoch {}", epoch);
        }
    }

    // Load from checkpoint
    let loaded_weights = Tensor::load_json("checkpoint_epoch_4/weights.json")?;
    let loaded_bias = Tensor::load_json("checkpoint_epoch_4/bias.json")?;
    let loaded_optimizer = Adam::load_json("checkpoint_epoch_4/optimizer.json")?;

    println!("Loaded weights: {:?}", loaded_weights.data());
    println!("Loaded bias: {:?}", loaded_bias.data());
    println!(
        "Loaded optimizer learning rate: {}",
        loaded_optimizer.learning_rate()
    );

    // Verify checkpoint integrity
    assert_eq!(weights.shape().dims, loaded_weights.shape().dims);
    assert_eq!(bias.shape().dims, loaded_bias.shape().dims);
    assert_eq!(optimizer.learning_rate(), loaded_optimizer.learning_rate());

    println!("Checkpointing verification: PASSED");

    Ok(())
}

examples/serialization/error_handling.rs (line 568)

fn demonstrate_schema_evolution() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Schema Evolution Patterns ---");

    fs::create_dir_all("temp_schema_tests")?;

    // Create data with different schema versions
    println!("Creating data with different schema versions:");

    // Version 1 data (minimal)
    let v1_json = r#"{
        "version": 1,
        "name": "legacy_data",
        "value": 123.45
    }"#;
    fs::write("temp_schema_tests/v1_data.json", v1_json)?;
    println!("  ✓ Version 1 data created (minimal fields)");

    // Version 2 data (with optional field)
    let v2_json = r#"{
        "version": 2,
        "name": "v2_data",
        "value": 678.90,
        "optional_field": "added_in_v2"
    }"#;
    fs::write("temp_schema_tests/v2_data.json", v2_json)?;
    println!("  ✓ Version 2 data created (with optional field)");

    // Version 3 data (with all fields)
    let v3_data = VersionedData {
        version: 3,
        name: "v3_data".to_string(),
        value: 999.99,
        optional_field: Some("present".to_string()),
        new_field: Some(42),
    };
    v3_data.save_json("temp_schema_tests/v3_data.json")?;
    println!("  ✓ Version 3 data created (all fields)");

    // Test backward compatibility
    println!("\nTesting backward compatibility:");

    // Load v1 data with current deserializer
    match VersionedData::load_json("temp_schema_tests/v1_data.json") {
        Ok(data) => {
            println!("  ✓ V1 data loaded successfully:");
            println!("    Name: {}", data.name);
            println!("    Value: {}", data.value);
            println!("    Optional field: {:?}", data.optional_field);
            println!("    New field: {:?}", data.new_field);
        }
        Err(e) => println!("  ✗ Failed to load V1 data: {}", e),
    }

    // Load v2 data with current deserializer
    match VersionedData::load_json("temp_schema_tests/v2_data.json") {
        Ok(data) => {
            println!("  ✓ V2 data loaded successfully:");
            println!("    Name: {}", data.name);
            println!("    Value: {}", data.value);
            println!("    Optional field: {:?}", data.optional_field);
            println!("    New field: {:?}", data.new_field);
        }
        Err(e) => println!("  ✗ Failed to load V2 data: {}", e),
    }

    // Test future version rejection
    println!("\nTesting future version handling:");
    let future_version_json = r#"{
        "version": 99,
        "name": "future_data",
        "value": 123.45,
        "unknown_field": "should_be_ignored"
    }"#;
    fs::write("temp_schema_tests/future_data.json", future_version_json)?;

    match VersionedData::load_json("temp_schema_tests/future_data.json") {
        Ok(_) => println!("  ✗ Unexpected: Future version was accepted"),
        Err(e) => println!("  ✓ Expected rejection of future version: {}", e),
    }

    // Demonstrate migration strategy
    println!("\nDemonstrating migration strategy:");
    println!("  Strategy: Load old format, upgrade to new format, save");

    // Simulate migrating v1 data to v3 format
    let v1_loaded = VersionedData::load_json("temp_schema_tests/v1_data.json")?;
    let v1_upgraded = VersionedData {
        version: 3,
        name: v1_loaded.name,
        value: v1_loaded.value,
        optional_field: Some("migrated_default".to_string()),
        new_field: Some(0),
    };

    v1_upgraded.save_json("temp_schema_tests/v1_migrated.json")?;
    println!("  ✓ V1 data migrated to V3 format");

    Ok(())
}

/// Demonstrate recovery strategies
fn demonstrate_recovery_strategies() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Recovery Strategies ---");

    fs::create_dir_all("temp_recovery_tests")?;

    // Strategy 1: Graceful degradation
    println!("1. Graceful Degradation Strategy:");

    // Create complete data
    let complete_data = RecoverableData {
        critical_field: "essential_info".to_string(),
        important_field: Some("important_info".to_string()),
        optional_field: Some("nice_to_have".to_string()),
        metadata: {
            let mut map = HashMap::new();
            map.insert("key1".to_string(), "value1".to_string());
            map.insert("key2".to_string(), "value2".to_string());
            map
        },
    };

    // Save complete data
    complete_data.save_json("temp_recovery_tests/complete.json")?;

    // Create partial data (missing some fields)
    let partial_json = r#"{
        "critical_field": "essential_info",
        "optional_field": "nice_to_have"
    }"#;
    fs::write("temp_recovery_tests/partial.json", partial_json)?;

    // Load partial data and demonstrate recovery
    match RecoverableData::load_json("temp_recovery_tests/partial.json") {
        Ok(recovered) => {
            println!("  ✓ Partial data recovered successfully:");
            println!("    Critical field: {}", recovered.critical_field);
            println!(
                "    Important field: {:?} (missing, set to None)",
                recovered.important_field
            );
            println!("    Optional field: {:?}", recovered.optional_field);
            println!(
                "    Metadata: {} entries (defaulted to empty)",
                recovered.metadata.len()
            );
        }
        Err(e) => println!("  ✗ Recovery failed: {}", e),
    }

    // Strategy 2: Error context preservation
    println!("\n2. Error Context Preservation:");

    let malformed_json = r#"{
        "critical_field": "essential_info",
        "important_field": 12345,
        "metadata": "not_a_map"
    }"#;
    fs::write("temp_recovery_tests/malformed.json", malformed_json)?;

    match RecoverableData::load_json("temp_recovery_tests/malformed.json") {
        Ok(_) => println!("  ✗ Unexpected: Malformed data was accepted"),
        Err(e) => {
            println!("  ✓ Error context preserved:");
            println!("    Error: {}", e);
            println!("    Error type: {:?}", std::mem::discriminant(&e));
        }
    }

    // Strategy 3: Fallback data sources
    println!("\n3. Fallback Data Sources:");

    // Primary source (corrupted)
    let corrupted_primary = "corrupted data";
    fs::write("temp_recovery_tests/primary.json", corrupted_primary)?;

    // Backup source (valid)
    let backup_data = RecoverableData {
        critical_field: "backup_critical".to_string(),
        important_field: Some("backup_important".to_string()),
        optional_field: None,
        metadata: HashMap::new(),
    };
    backup_data.save_json("temp_recovery_tests/backup.json")?;

    // Default fallback
    let default_data = RecoverableData {
        critical_field: "default_critical".to_string(),
        important_field: None,
        optional_field: None,
        metadata: HashMap::new(),
    };

    println!("  Attempting to load data with fallback chain:");

    // Try primary source
    let loaded_data = match RecoverableData::load_json("temp_recovery_tests/primary.json") {
        Ok(data) => {
            println!("    ✓ Loaded from primary source");
            data
        }
        Err(_) => {
            println!("    ✗ Primary source failed, trying backup");

            // Try backup source
            match RecoverableData::load_json("temp_recovery_tests/backup.json") {
                Ok(data) => {
                    println!("    ✓ Loaded from backup source");
                    data
                }
                Err(_) => {
                    println!("    ✗ Backup source failed, using default");
                    default_data
                }
            }
        }
    };

    println!("  Final loaded data:");
    println!("    Critical field: {}", loaded_data.critical_field);

    Ok(())
}

/// Demonstrate production-ready error handling
fn demonstrate_production_error_handling() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Production Error Handling ---");

    fs::create_dir_all("temp_production_tests")?;

    // Error logging and monitoring
    println!("1. Error Logging and Monitoring:");

    let test_data = VersionedData {
        version: 2,
        name: "production_test".to_string(),
        value: 42.0,
        optional_field: Some("test".to_string()),
        new_field: None,
    };

    // Create error log for demonstration
    let mut error_log = fs::OpenOptions::new()
        .create(true)
        .append(true)
        .open("temp_production_tests/error.log")?;

    // Function to log errors in production format
    let mut log_error =
        |error: &SerializationError, context: &str| -> Result<(), Box<dyn std::error::Error>> {
            let timestamp = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)?
                .as_secs();

            writeln!(error_log, "[{}] ERROR in {}: {}", timestamp, context, error)?;
            Ok(())
        };

    // Simulate various error scenarios with logging
    let error_scenarios = vec![
        ("corrupted_file.json", "invalid json content"),
        ("missing_fields.json", r#"{"version": 1}"#),
        (
            "type_error.json",
            r#"{"version": "not_number", "name": "test", "value": 42.0}"#,
        ),
    ];

    for (filename, content) in error_scenarios {
        let filepath = format!("temp_production_tests/{}", filename);
        fs::write(&filepath, content)?;

        match VersionedData::load_json(&filepath) {
            Ok(_) => println!("  ✗ Unexpected success for {}", filename),
            Err(e) => {
                log_error(&e, &format!("load_config({})", filename))?;
                println!("  ✓ Error logged for {}: {}", filename, e);
            }
        }
    }

    // Health check pattern
    println!("\n2. Health Check Pattern:");

    let health_check = || -> Result<bool, SerializationError> {
        // Check if we can serialize/deserialize basic data
        let test_data = VersionedData {
            version: 1,
            name: "health_check".to_string(),
            value: 1.0,
            optional_field: None,
            new_field: None,
        };

        let serialized = test_data.to_json()?;
        let _deserialized = VersionedData::from_json(&serialized)?;
        Ok(true)
    };

    match health_check() {
        Ok(_) => println!("  ✓ Serialization system health check passed"),
        Err(e) => {
            log_error(&e, "health_check")?;
            println!("  ✗ Serialization system health check failed: {}", e);
        }
    }

    // Circuit breaker pattern simulation
    println!("\n3. Circuit Breaker Pattern:");

    struct CircuitBreaker {
        failure_count: u32,
        failure_threshold: u32,
        is_open: bool,
    }

    impl CircuitBreaker {
        fn new(threshold: u32) -> Self {
            Self {
                failure_count: 0,
                failure_threshold: threshold,
                is_open: false,
            }
        }

        fn call<F, T>(&mut self, operation: F) -> Result<T, String>
        where
            F: FnOnce() -> Result<T, SerializationError>,
        {
            if self.is_open {
                return Err("Circuit breaker is open".to_string());
            }

            match operation() {
                Ok(result) => {
                    self.failure_count = 0; // Reset on success
                    Ok(result)
                }
                Err(e) => {
                    self.failure_count += 1;
                    if self.failure_count >= self.failure_threshold {
                        self.is_open = true;
                        println!(
                            "    Circuit breaker opened after {} failures",
                            self.failure_count
                        );
                    }
                    Err(e.to_string())
                }
            }
        }
    }

    let mut circuit_breaker = CircuitBreaker::new(3);

    // Simulate operations that fail
    for i in 1..=5 {
        let result = circuit_breaker
            .call(|| VersionedData::load_json("temp_production_tests/corrupted_file.json"));

        match result {
            Ok(_) => println!("  Operation {} succeeded", i),
            Err(e) => println!("  Operation {} failed: {}", i, e),
        }
    }

    // Retry mechanism
    println!("\n4. Retry Mechanism:");

    let retry_operation = |max_attempts: u32| -> Result<VersionedData, String> {
        for attempt in 1..=max_attempts {
            println!("    Attempt {}/{}", attempt, max_attempts);

            // Try different sources in order
            let sources = vec![
                "temp_production_tests/corrupted_file.json",
                "temp_production_tests/missing_fields.json",
                "temp_production_tests/backup_valid.json",
            ];

            if attempt == max_attempts {
                // On final attempt, create valid backup
                test_data
                    .save_json("temp_production_tests/backup_valid.json")
                    .map_err(|e| format!("Failed to create backup: {}", e))?;
            }

            for source in &sources {
                match VersionedData::load_json(source) {
                    Ok(data) => {
                        println!("    ✓ Succeeded loading from {}", source);
                        return Ok(data);
                    }
                    Err(_) => {
                        println!("    ✗ Failed to load from {}", source);
                        continue;
                    }
                }
            }

            if attempt < max_attempts {
                println!("    Waiting before retry...");
                // In real code, would sleep here
            }
        }

        Err("All retry attempts exhausted".to_string())
    };

    match retry_operation(3) {
        Ok(data) => println!("  ✓ Retry succeeded: {}", data.name),
        Err(e) => println!("  ✗ Retry failed: {}", e),
    }

    Ok(())
}

examples/serialization/json_vs_binary.rs (line 710)

fn demonstrate_use_case_recommendations() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Use Case Recommendations ---");

    println!("JSON Format - Recommended for:");
    println!("  ✓ Configuration files (human-editable)");
    println!("  ✓ API responses (web compatibility)");
    println!("  ✓ Debugging and development (readability)");
    println!("  ✓ Small data structures (minimal overhead)");
    println!("  ✓ Cross-language interoperability");
    println!("  ✓ Schema evolution (self-describing)");
    println!("  ✓ Text-heavy data with few numbers");

    println!("\nBinary Format - Recommended for:");
    println!("  ✓ Large datasets (memory/storage efficiency)");
    println!("  ✓ High-performance applications (speed critical)");
    println!("  ✓ Numeric-heavy data (ML models, matrices)");
    println!("  ✓ Network transmission (bandwidth limited)");
    println!("  ✓ Embedded systems (resource constrained)");
    println!("  ✓ Long-term storage (space efficiency)");
    println!("  ✓ Frequent serialization/deserialization");

    // Demonstrate decision matrix
    println!("\nDecision Matrix Example:");

    let scenarios = vec![
        (
            "Web API Configuration",
            "JSON",
            "Human readable, web standard, small size",
        ),
        (
            "ML Model Weights",
            "Binary",
            "Large numeric data, performance critical",
        ),
        (
            "User Preferences",
            "JSON",
            "Human editable, self-documenting",
        ),
        (
            "Real-time Telemetry",
            "Binary",
            "High frequency, bandwidth limited",
        ),
        (
            "Application Settings",
            "JSON",
            "Developer accessible, version control friendly",
        ),
        (
            "Scientific Dataset",
            "Binary",
            "Large arrays, storage efficiency critical",
        ),
    ];

    for (scenario, recommendation, reason) in scenarios {
        println!("  {} -> {} ({})", scenario, recommendation, reason);
    }

    // Create examples for common scenarios
    println!("\nPractical Examples:");

    // Configuration file example (JSON)
    let config = Configuration {
        version: "2.1.0".to_string(),
        debug_enabled: false,
        log_level: "info".to_string(),
        database_settings: {
            let mut map = HashMap::new();
            map.insert("url".to_string(), "postgresql://localhost/app".to_string());
            map.insert("pool_size".to_string(), "10".to_string());
            map
        },
        feature_flags_enabled: true,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    config.save_json("temp_config_example.json")?;
    let config_content = fs::read_to_string("temp_config_example.json")?;

    println!("\nConfiguration File (JSON) - Human readable:");
    for line in config_content.lines().take(5) {
        println!("  {}", line);
    }
    println!("  ... (easily editable by developers)");

    // Data export example (Binary)
    let export_data = LargeDataset {
        name: "Training Export".to_string(),
        values: (0..1000).map(|i| (i as f32).sin()).collect(),
        labels: (0..1000).map(|i| format!("sample_{:04}", i)).collect(),
        feature_count: 50,
        feature_dimension: 20,
        timestamp_count: 1000,
        metadata: HashMap::new(),
    };

    export_data.save_binary("temp_export_example.bin")?;
    let export_size = fs::metadata("temp_export_example.bin")?.len();

    println!("\nData Export (Binary) - Efficient storage:");
    println!(
        "  File size: {} bytes ({:.1} KB)",
        export_size,
        export_size as f64 / 1024.0
    );
    println!("  1000 numeric values + 50x20 matrix + metadata");
    println!("  Compact encoding saves significant space vs JSON");

    Ok(())
}

/// Demonstrate debugging capabilities
fn demonstrate_debugging_capabilities() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Debugging Capabilities ---");

    let mut metadata = HashMap::new();
    metadata.insert("debug_session".to_string(), "session_123".to_string());
    metadata.insert("error_code".to_string(), "E001".to_string());

    let debug_metrics = PerformanceMetrics {
        operation: "debug_test".to_string(),
        duration_micros: 5432,
        memory_usage_bytes: 16384,
        cpu_usage_percent: 42.7,
        throughput_ops_per_sec: 750.0,
        metadata,
    };

    println!("Debugging Comparison:");

    // JSON debugging advantages
    let json_data = debug_metrics.to_json()?;
    println!("\nJSON Format - Debugging Advantages:");
    println!("  ✓ Human readable without tools");
    println!("  ✓ Can inspect values directly");
    println!("  ✓ Text editors show structure");
    println!("  ✓ Diff tools work naturally");
    println!("  ✓ Version control friendly");

    println!("\n  Sample JSON output for debugging:");
    for (i, line) in json_data.lines().enumerate() {
        if i < 5 {
            println!("    {}", line);
        }
    }

    // Binary debugging limitations
    let binary_data = debug_metrics.to_binary()?;
    println!("\nBinary Format - Debugging Limitations:");
    println!("  ✗ Requires special tools to inspect");
    println!("  ✗ Not human readable");
    println!("  ✗ Difficult to debug data corruption");
    println!("  ✗ Version control shows as binary diff");

    println!("\n  Binary data (hex dump for debugging):");
    print!("    ");
    for (i, byte) in binary_data.iter().take(40).enumerate() {
        if i > 0 && i % 16 == 0 {
            println!();
            print!("    ");
        }
        print!("{:02x} ", byte);
    }
    println!("\n    (requires hex editor or custom tools)");

    // Development workflow comparison
    println!("\nDevelopment Workflow Impact:");

    println!("\nJSON Workflow:");
    println!("  1. Save data to JSON file");
    println!("  2. Open in any text editor");
    println!("  3. Inspect values directly");
    println!("  4. Make manual edits if needed");
    println!("  5. Version control tracks changes");

    println!("\nBinary Workflow:");
    println!("  1. Save data to binary file");
    println!("  2. Write debugging code to load and print");
    println!("  3. Use hex editor for low-level inspection");
    println!("  4. Cannot make manual edits easily");
    println!("  5. Version control shows binary changes only");

    // Hybrid approach recommendation
    println!("\nHybrid Approach for Development:");
    println!("  - Use JSON during development/debugging");
    println!("  - Switch to binary for production deployment");
    println!("  - Provide debugging tools that export binary to JSON");
    println!("  - Include format conversion utilities");

    // Demonstrate debugging scenario
    println!("\nDebugging Scenario Example:");
    println!("  Problem: Performance metrics show unexpected values");

    // Save both formats for comparison
    debug_metrics.save_json("temp_debug_metrics.json")?;
    debug_metrics.save_binary("temp_debug_metrics.bin")?;

    println!("  JSON approach: Open temp_debug_metrics.json in editor");
    println!("    -> Immediately see cpu_usage_percent: 42.7");
    println!("    -> Compare with expected range");
    println!("    -> Check metadata for debug_session: 'session_123'");

    println!("  Binary approach: Write debugging code");
    println!("    -> Load binary file programmatically");
    println!("    -> Print values to console");
    println!("    -> Additional development time required");

    Ok(())
}

Additional examples can be found in:

• examples/serialization/nested_structures.rs

fn save_binary<P: AsRef<Path>>(&self, path: P) -> SerializationResult<()>

Saves the struct to a binary file

Serializes the struct to binary format and writes it to the specified file path. The file is created if it doesn’t exist, or truncated if it already exists.

Arguments

• path - File path where the binary data should be written

Returns

Ok(()) on successful file write Err(SerializationError) if serialization or file I/O fails

Examples

Saves struct data to a binary file with proper file I/O handling.

Examples found in repository

examples/getting_started/serialization_basics.rs (line 86)

fn demonstrate_tensor_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Tensor Serialization ---");

    // Create a tensor with some data
    let original_tensor = Tensor::from_slice(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0], vec![2, 3]).unwrap();
    println!(
        "Original tensor: shape {:?}, data: {:?}",
        original_tensor.shape().dims,
        original_tensor.data()
    );

    // Save tensor in JSON format
    let json_path = "temp_tensor.json";
    original_tensor.save_json(json_path)?;
    println!("Saved tensor to JSON: {}", json_path);

    // Load tensor from JSON
    let loaded_tensor_json = Tensor::load_json(json_path)?;
    println!(
        "Loaded from JSON: shape {:?}, data: {:?}",
        loaded_tensor_json.shape().dims,
        loaded_tensor_json.data()
    );

    // Verify data integrity
    assert_eq!(
        original_tensor.shape().dims,
        loaded_tensor_json.shape().dims
    );
    assert_eq!(original_tensor.data(), loaded_tensor_json.data());
    println!("JSON serialization verification: PASSED");

    // Save tensor in binary format
    let binary_path = "temp_tensor.bin";
    original_tensor.save_binary(binary_path)?;
    println!("Saved tensor to binary: {}", binary_path);

    // Load tensor from binary
    let loaded_tensor_binary = Tensor::load_binary(binary_path)?;
    println!(
        "Loaded from binary: shape {:?}, data: {:?}",
        loaded_tensor_binary.shape().dims,
        loaded_tensor_binary.data()
    );

    // Verify data integrity
    assert_eq!(
        original_tensor.shape().dims,
        loaded_tensor_binary.shape().dims
    );
    assert_eq!(original_tensor.data(), loaded_tensor_binary.data());
    println!("Binary serialization verification: PASSED");

    Ok(())
}

/// Demonstrate optimizer serialization and deserialization
fn demonstrate_optimizer_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Optimizer Serialization ---");

    // Create an optimizer with some parameters
    let mut weight = Tensor::randn(vec![2, 2], Some(42)).with_requires_grad();
    let mut bias = Tensor::randn(vec![2], Some(43)).with_requires_grad();

    let config = AdamConfig {
        learning_rate: 0.001,
        beta1: 0.9,
        beta2: 0.999,
        eps: 1e-8,
        weight_decay: 0.0,
        amsgrad: false,
    };

    let mut optimizer = Adam::with_config(config);
    optimizer.add_parameter(&weight);
    optimizer.add_parameter(&bias);

    println!(
        "Created optimizer with {} parameters",
        optimizer.parameter_count()
    );
    println!("Learning rate: {}", optimizer.learning_rate());

    // Simulate some training steps
    for _ in 0..3 {
        let mut loss = weight.sum() + bias.sum();
        loss.backward(None);
        optimizer.step(&mut [&mut weight, &mut bias]);
        optimizer.zero_grad(&mut [&mut weight, &mut bias]);
    }

    // Save optimizer state
    let optimizer_path = "temp_optimizer.json";
    optimizer.save_json(optimizer_path)?;
    println!("Saved optimizer to: {}", optimizer_path);

    // Load optimizer state
    let loaded_optimizer = Adam::load_json(optimizer_path)?;
    println!(
        "Loaded optimizer with {} parameters",
        loaded_optimizer.parameter_count()
    );
    println!("Learning rate: {}", loaded_optimizer.learning_rate());

    // Verify optimizer state
    assert_eq!(
        optimizer.parameter_count(),
        loaded_optimizer.parameter_count()
    );
    assert_eq!(optimizer.learning_rate(), loaded_optimizer.learning_rate());
    println!("Optimizer serialization verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison and performance characteristics
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    // Create a larger tensor for comparison
    let tensor = Tensor::randn(vec![10, 10], Some(44));

    // Save in both formats
    tensor.save_json("temp_comparison.json")?;
    tensor.save_binary("temp_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_comparison.json")?.len();
    let binary_size = fs::metadata("temp_comparison.bin")?.len();

    println!("JSON file size: {} bytes", json_size);
    println!("Binary file size: {} bytes", binary_size);
    println!(
        "Compression ratio: {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Load and verify both formats
    let json_tensor = Tensor::load_json("temp_comparison.json")?;
    let binary_tensor = Tensor::load_binary("temp_comparison.bin")?;

    assert_eq!(tensor.shape().dims, json_tensor.shape().dims);
    assert_eq!(tensor.shape().dims, binary_tensor.shape().dims);
    assert_eq!(tensor.data(), json_tensor.data());
    assert_eq!(tensor.data(), binary_tensor.data());

    println!("Format comparison verification: PASSED");

    Ok(())
}

/// Demonstrate a basic model checkpointing workflow
fn demonstrate_model_checkpointing() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Model Checkpointing ---");

    // Create a simple model (weights and bias)
    let mut weights = Tensor::randn(vec![2, 1], Some(45)).with_requires_grad();
    let mut bias = Tensor::randn(vec![1], Some(46)).with_requires_grad();

    // Create optimizer
    let mut optimizer = Adam::with_learning_rate(0.01);
    optimizer.add_parameter(&weights);
    optimizer.add_parameter(&bias);

    println!("Initial weights: {:?}", weights.data());
    println!("Initial bias: {:?}", bias.data());

    // Simulate training
    for epoch in 0..5 {
        let mut loss = weights.sum() + bias.sum();
        loss.backward(None);
        optimizer.step(&mut [&mut weights, &mut bias]);
        optimizer.zero_grad(&mut [&mut weights, &mut bias]);

        if epoch % 2 == 0 {
            // Save checkpoint
            let checkpoint_dir = format!("checkpoint_epoch_{}", epoch);
            fs::create_dir_all(&checkpoint_dir)?;

            weights.save_json(format!("{}/weights.json", checkpoint_dir))?;
            bias.save_json(format!("{}/bias.json", checkpoint_dir))?;
            optimizer.save_json(format!("{}/optimizer.json", checkpoint_dir))?;

            println!("Saved checkpoint for epoch {}", epoch);
        }
    }

    // Load from checkpoint
    let loaded_weights = Tensor::load_json("checkpoint_epoch_4/weights.json")?;
    let loaded_bias = Tensor::load_json("checkpoint_epoch_4/bias.json")?;
    let loaded_optimizer = Adam::load_json("checkpoint_epoch_4/optimizer.json")?;

    println!("Loaded weights: {:?}", loaded_weights.data());
    println!("Loaded bias: {:?}", loaded_bias.data());
    println!(
        "Loaded optimizer learning rate: {}",
        loaded_optimizer.learning_rate()
    );

    // Verify checkpoint integrity
    assert_eq!(weights.shape().dims, loaded_weights.shape().dims);
    assert_eq!(bias.shape().dims, loaded_bias.shape().dims);
    assert_eq!(optimizer.learning_rate(), loaded_optimizer.learning_rate());

    println!("Checkpointing verification: PASSED");

    Ok(())
}

/// Demonstrate error handling for serialization operations
fn demonstrate_error_handling() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Error Handling ---");

    // Test loading non-existent file
    match Tensor::load_json("nonexistent_file.json") {
        Ok(_) => println!("Unexpected: Successfully loaded non-existent file"),
        Err(e) => println!("Expected error loading non-existent file: {}", e),
    }

    // Test loading with wrong format
    let tensor = Tensor::randn(vec![2, 2], Some(47));
    tensor.save_binary("temp_binary.bin")?;

    match Tensor::load_json("temp_binary.bin") {
        Ok(_) => println!("Unexpected: Successfully loaded binary as JSON"),
        Err(e) => println!("Expected error loading binary as JSON: {}", e),
    }

    // Test loading corrupted file
    fs::write("temp_invalid.json", "invalid json content")?;
    match Tensor::load_json("temp_invalid.json") {
        Ok(_) => println!("Unexpected: Successfully loaded invalid JSON"),
        Err(e) => println!("Expected error loading invalid JSON: {}", e),
    }

    println!("Error handling verification: PASSED");

    Ok(())
}

examples/serialization/basic_structs.rs (line 311)

fn demonstrate_app_settings_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- App Settings Serialization ---");

    // Create app settings with collections and optional fields
    let mut env_vars = HashMap::new();
    env_vars.insert("LOG_LEVEL".to_string(), "info".to_string());
    env_vars.insert("PORT".to_string(), "8080".to_string());
    env_vars.insert("HOST".to_string(), "localhost".to_string());

    let settings = AppSettings {
        app_name: "Train Station Example".to_string(),
        version: "1.0.0".to_string(),
        debug_mode: true,
        max_connections: 100,
        timeout_seconds: 30.5,
        features: vec![
            "authentication".to_string(),
            "logging".to_string(),
            "metrics".to_string(),
        ],
        environment_vars: env_vars,
        optional_database_url: Some("postgresql://localhost:5432/mydb".to_string()),
    };

    println!("Original app settings:");
    println!("  App Name: {}", settings.app_name);
    println!("  Version: {}", settings.version);
    println!("  Debug Mode: {}", settings.debug_mode);
    println!("  Max Connections: {}", settings.max_connections);
    println!("  Timeout: {} seconds", settings.timeout_seconds);
    println!("  Features: {:?}", settings.features);
    println!("  Environment Variables: {:?}", settings.environment_vars);
    println!("  Database URL: {:?}", settings.optional_database_url);

    // Serialize to binary format for efficient storage
    let binary_data = settings.to_binary()?;
    println!("\nSerialized to binary: {} bytes", binary_data.len());

    // Save to binary file
    settings.save_binary("temp_app_settings.bin")?;
    println!("Saved to file: temp_app_settings.bin");

    // Load from binary file
    let loaded_settings = AppSettings::load_binary("temp_app_settings.bin")?;
    println!("\nLoaded app settings:");
    println!("  App Name: {}", loaded_settings.app_name);
    println!("  Version: {}", loaded_settings.version);
    println!("  Debug Mode: {}", loaded_settings.debug_mode);
    println!("  Features count: {}", loaded_settings.features.len());
    println!(
        "  Environment variables count: {}",
        loaded_settings.environment_vars.len()
    );

    // Verify data integrity
    assert_eq!(settings, loaded_settings);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison between JSON and binary
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    let user = UserProfile {
        id: 98765,
        username: "bob_builder".to_string(),
        email: "bob@construction.com".to_string(),
        age: 35,
        is_active: false,
        score: 87.2,
    };

    // Save in both formats
    user.save_json("temp_format_comparison.json")?;
    user.save_binary("temp_format_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_format_comparison.json")?.len();
    let binary_size = fs::metadata("temp_format_comparison.bin")?.len();

    println!("Format comparison for UserProfile:");
    println!("  JSON file size: {} bytes", json_size);
    println!("  Binary file size: {} bytes", binary_size);
    println!(
        "  Size ratio (JSON/Binary): {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Demonstrate readability
    let json_content = fs::read_to_string("temp_format_comparison.json")?;
    println!("\nJSON format (human-readable):");
    println!("{}", json_content);

    println!("\nBinary format (first 32 bytes as hex):");
    let binary_content = fs::read("temp_format_comparison.bin")?;
    for (i, byte) in binary_content.iter().take(32).enumerate() {
        if i % 16 == 0 && i > 0 {
            println!();
        }
        print!("{:02x} ", byte);
    }
    println!("\n... ({} total bytes)", binary_content.len());

    // Load and verify both formats produce identical results
    let json_loaded = UserProfile::load_json("temp_format_comparison.json")?;
    let binary_loaded = UserProfile::load_binary("temp_format_comparison.bin")?;

    assert_eq!(json_loaded, binary_loaded);
    println!("\nFormat consistency verification: PASSED");

    Ok(())
}

examples/serialization/error_handling.rs (line 406)

fn demonstrate_common_error_scenarios() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Common Error Scenarios ---");

    fs::create_dir_all("temp_error_tests")?;

    // Scenario 1: Corrupted JSON file
    println!("1. Corrupted JSON File:");
    let corrupted_json = r#"{"name": "test", "value": 42, "incomplete"#;
    fs::write("temp_error_tests/corrupted.json", corrupted_json)?;

    match VersionedData::load_json("temp_error_tests/corrupted.json") {
        Ok(_) => println!("   Unexpected: Corrupted JSON was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 2: Missing required fields
    println!("\n2. Missing Required Fields:");
    let incomplete_json = r#"{"name": "test"}"#;
    fs::write("temp_error_tests/incomplete.json", incomplete_json)?;

    match VersionedData::load_json("temp_error_tests/incomplete.json") {
        Ok(_) => println!("   Unexpected: Incomplete JSON was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 3: Type mismatches
    println!("\n3. Type Mismatch:");
    let type_mismatch_json = r#"{"version": "not_a_number", "name": "test", "value": 42.0}"#;
    fs::write("temp_error_tests/type_mismatch.json", type_mismatch_json)?;

    match VersionedData::load_json("temp_error_tests/type_mismatch.json") {
        Ok(_) => println!("   Unexpected: Type mismatch was handled gracefully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 4: File not found
    println!("\n4. File Not Found:");
    match VersionedData::load_json("temp_error_tests/nonexistent.json") {
        Ok(_) => println!("   Unexpected: Non-existent file was loaded"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 5: Binary format mismatch
    println!("\n5. Binary Format Mismatch:");
    let invalid_binary = vec![0xFF, 0xFF, 0xFF, 0xFF]; // Invalid binary data
    fs::write("temp_error_tests/invalid.bin", invalid_binary)?;

    match VersionedData::load_binary("temp_error_tests/invalid.bin") {
        Ok(_) => println!("   Unexpected: Invalid binary was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 6: Wrong format loading
    println!("\n6. Wrong Format Loading:");
    let valid_data = VersionedData {
        version: 1,
        name: "test".to_string(),
        value: 42.0,
        optional_field: None,
        new_field: None,
    };
    valid_data.save_binary("temp_error_tests/valid.bin")?;

    // Try to load binary file as JSON
    match VersionedData::load_json("temp_error_tests/valid.bin") {
        Ok(_) => println!("   Unexpected: Binary file was loaded as JSON"),
        Err(e) => println!("   Expected error: {}", e),
    }

    Ok(())
}

examples/serialization/json_vs_binary.rs (line 730)

fn demonstrate_use_case_recommendations() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Use Case Recommendations ---");

    println!("JSON Format - Recommended for:");
    println!("  ✓ Configuration files (human-editable)");
    println!("  ✓ API responses (web compatibility)");
    println!("  ✓ Debugging and development (readability)");
    println!("  ✓ Small data structures (minimal overhead)");
    println!("  ✓ Cross-language interoperability");
    println!("  ✓ Schema evolution (self-describing)");
    println!("  ✓ Text-heavy data with few numbers");

    println!("\nBinary Format - Recommended for:");
    println!("  ✓ Large datasets (memory/storage efficiency)");
    println!("  ✓ High-performance applications (speed critical)");
    println!("  ✓ Numeric-heavy data (ML models, matrices)");
    println!("  ✓ Network transmission (bandwidth limited)");
    println!("  ✓ Embedded systems (resource constrained)");
    println!("  ✓ Long-term storage (space efficiency)");
    println!("  ✓ Frequent serialization/deserialization");

    // Demonstrate decision matrix
    println!("\nDecision Matrix Example:");

    let scenarios = vec![
        (
            "Web API Configuration",
            "JSON",
            "Human readable, web standard, small size",
        ),
        (
            "ML Model Weights",
            "Binary",
            "Large numeric data, performance critical",
        ),
        (
            "User Preferences",
            "JSON",
            "Human editable, self-documenting",
        ),
        (
            "Real-time Telemetry",
            "Binary",
            "High frequency, bandwidth limited",
        ),
        (
            "Application Settings",
            "JSON",
            "Developer accessible, version control friendly",
        ),
        (
            "Scientific Dataset",
            "Binary",
            "Large arrays, storage efficiency critical",
        ),
    ];

    for (scenario, recommendation, reason) in scenarios {
        println!("  {} -> {} ({})", scenario, recommendation, reason);
    }

    // Create examples for common scenarios
    println!("\nPractical Examples:");

    // Configuration file example (JSON)
    let config = Configuration {
        version: "2.1.0".to_string(),
        debug_enabled: false,
        log_level: "info".to_string(),
        database_settings: {
            let mut map = HashMap::new();
            map.insert("url".to_string(), "postgresql://localhost/app".to_string());
            map.insert("pool_size".to_string(), "10".to_string());
            map
        },
        feature_flags_enabled: true,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    config.save_json("temp_config_example.json")?;
    let config_content = fs::read_to_string("temp_config_example.json")?;

    println!("\nConfiguration File (JSON) - Human readable:");
    for line in config_content.lines().take(5) {
        println!("  {}", line);
    }
    println!("  ... (easily editable by developers)");

    // Data export example (Binary)
    let export_data = LargeDataset {
        name: "Training Export".to_string(),
        values: (0..1000).map(|i| (i as f32).sin()).collect(),
        labels: (0..1000).map(|i| format!("sample_{:04}", i)).collect(),
        feature_count: 50,
        feature_dimension: 20,
        timestamp_count: 1000,
        metadata: HashMap::new(),
    };

    export_data.save_binary("temp_export_example.bin")?;
    let export_size = fs::metadata("temp_export_example.bin")?.len();

    println!("\nData Export (Binary) - Efficient storage:");
    println!(
        "  File size: {} bytes ({:.1} KB)",
        export_size,
        export_size as f64 / 1024.0
    );
    println!("  1000 numeric values + 50x20 matrix + metadata");
    println!("  Compact encoding saves significant space vs JSON");

    Ok(())
}

/// Demonstrate debugging capabilities
fn demonstrate_debugging_capabilities() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Debugging Capabilities ---");

    let mut metadata = HashMap::new();
    metadata.insert("debug_session".to_string(), "session_123".to_string());
    metadata.insert("error_code".to_string(), "E001".to_string());

    let debug_metrics = PerformanceMetrics {
        operation: "debug_test".to_string(),
        duration_micros: 5432,
        memory_usage_bytes: 16384,
        cpu_usage_percent: 42.7,
        throughput_ops_per_sec: 750.0,
        metadata,
    };

    println!("Debugging Comparison:");

    // JSON debugging advantages
    let json_data = debug_metrics.to_json()?;
    println!("\nJSON Format - Debugging Advantages:");
    println!("  ✓ Human readable without tools");
    println!("  ✓ Can inspect values directly");
    println!("  ✓ Text editors show structure");
    println!("  ✓ Diff tools work naturally");
    println!("  ✓ Version control friendly");

    println!("\n  Sample JSON output for debugging:");
    for (i, line) in json_data.lines().enumerate() {
        if i < 5 {
            println!("    {}", line);
        }
    }

    // Binary debugging limitations
    let binary_data = debug_metrics.to_binary()?;
    println!("\nBinary Format - Debugging Limitations:");
    println!("  ✗ Requires special tools to inspect");
    println!("  ✗ Not human readable");
    println!("  ✗ Difficult to debug data corruption");
    println!("  ✗ Version control shows as binary diff");

    println!("\n  Binary data (hex dump for debugging):");
    print!("    ");
    for (i, byte) in binary_data.iter().take(40).enumerate() {
        if i > 0 && i % 16 == 0 {
            println!();
            print!("    ");
        }
        print!("{:02x} ", byte);
    }
    println!("\n    (requires hex editor or custom tools)");

    // Development workflow comparison
    println!("\nDevelopment Workflow Impact:");

    println!("\nJSON Workflow:");
    println!("  1. Save data to JSON file");
    println!("  2. Open in any text editor");
    println!("  3. Inspect values directly");
    println!("  4. Make manual edits if needed");
    println!("  5. Version control tracks changes");

    println!("\nBinary Workflow:");
    println!("  1. Save data to binary file");
    println!("  2. Write debugging code to load and print");
    println!("  3. Use hex editor for low-level inspection");
    println!("  4. Cannot make manual edits easily");
    println!("  5. Version control shows binary changes only");

    // Hybrid approach recommendation
    println!("\nHybrid Approach for Development:");
    println!("  - Use JSON during development/debugging");
    println!("  - Switch to binary for production deployment");
    println!("  - Provide debugging tools that export binary to JSON");
    println!("  - Include format conversion utilities");

    // Demonstrate debugging scenario
    println!("\nDebugging Scenario Example:");
    println!("  Problem: Performance metrics show unexpected values");

    // Save both formats for comparison
    debug_metrics.save_json("temp_debug_metrics.json")?;
    debug_metrics.save_binary("temp_debug_metrics.bin")?;

    println!("  JSON approach: Open temp_debug_metrics.json in editor");
    println!("    -> Immediately see cpu_usage_percent: 42.7");
    println!("    -> Compare with expected range");
    println!("    -> Check metadata for debug_session: 'session_123'");

    println!("  Binary approach: Write debugging code");
    println!("    -> Load binary file programmatically");
    println!("    -> Print values to console");
    println!("    -> Additional development time required");

    Ok(())
}

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

Loads the struct from a JSON file

Reads JSON data from the specified file path and deserializes it into a new instance of the struct.

Arguments

• path - File path containing the JSON data to read

Returns

Ok(Self) on successful deserialization Err(SerializationError) if file I/O or deserialization fails

Examples

Loads struct data from a JSON file with proper error handling.

Examples found in repository

examples/neural_networks/basic_linear_layer.rs (line 114)

    pub fn load_json(
        path: &str,
        input_size: usize,
        output_size: usize,
    ) -> Result<Self, Box<dyn std::error::Error>> {
        let weight_path = format!("{}_weight.json", path);
        let bias_path = format!("{}_bias.json", path);

        let weight = Tensor::load_json(&weight_path)?.with_requires_grad();
        let bias = Tensor::load_json(&bias_path)?.with_requires_grad();

        Ok(Self {
            weight,
            bias,
            input_size,
            output_size,
        })
    }

examples/serialization/basic_structs.rs (line 255)

fn demonstrate_user_profile_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- User Profile Serialization ---");

    // Create a user profile with various field types
    let user = UserProfile {
        id: 12345,
        username: "alice_cooper".to_string(),
        email: "alice@example.com".to_string(),
        age: 28,
        is_active: true,
        score: 95.7,
    };

    println!("Original user profile:");
    println!("  ID: {}", user.id);
    println!("  Username: {}", user.username);
    println!("  Email: {}", user.email);
    println!("  Age: {}", user.age);
    println!("  Active: {}", user.is_active);
    println!("  Score: {}", user.score);

    // Serialize to JSON
    let json_data = user.to_json()?;
    println!("\nSerialized to JSON:");
    println!("{}", json_data);

    // Save to JSON file
    user.save_json("temp_user_profile.json")?;
    println!("Saved to file: temp_user_profile.json");

    // Load from JSON file
    let loaded_user = UserProfile::load_json("temp_user_profile.json")?;
    println!("\nLoaded user profile:");
    println!("  ID: {}", loaded_user.id);
    println!("  Username: {}", loaded_user.username);
    println!("  Email: {}", loaded_user.email);
    println!("  Age: {}", loaded_user.age);
    println!("  Active: {}", loaded_user.is_active);
    println!("  Score: {}", loaded_user.score);

    // Verify data integrity
    assert_eq!(user, loaded_user);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate serialization with collections and optional fields
fn demonstrate_app_settings_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- App Settings Serialization ---");

    // Create app settings with collections and optional fields
    let mut env_vars = HashMap::new();
    env_vars.insert("LOG_LEVEL".to_string(), "info".to_string());
    env_vars.insert("PORT".to_string(), "8080".to_string());
    env_vars.insert("HOST".to_string(), "localhost".to_string());

    let settings = AppSettings {
        app_name: "Train Station Example".to_string(),
        version: "1.0.0".to_string(),
        debug_mode: true,
        max_connections: 100,
        timeout_seconds: 30.5,
        features: vec![
            "authentication".to_string(),
            "logging".to_string(),
            "metrics".to_string(),
        ],
        environment_vars: env_vars,
        optional_database_url: Some("postgresql://localhost:5432/mydb".to_string()),
    };

    println!("Original app settings:");
    println!("  App Name: {}", settings.app_name);
    println!("  Version: {}", settings.version);
    println!("  Debug Mode: {}", settings.debug_mode);
    println!("  Max Connections: {}", settings.max_connections);
    println!("  Timeout: {} seconds", settings.timeout_seconds);
    println!("  Features: {:?}", settings.features);
    println!("  Environment Variables: {:?}", settings.environment_vars);
    println!("  Database URL: {:?}", settings.optional_database_url);

    // Serialize to binary format for efficient storage
    let binary_data = settings.to_binary()?;
    println!("\nSerialized to binary: {} bytes", binary_data.len());

    // Save to binary file
    settings.save_binary("temp_app_settings.bin")?;
    println!("Saved to file: temp_app_settings.bin");

    // Load from binary file
    let loaded_settings = AppSettings::load_binary("temp_app_settings.bin")?;
    println!("\nLoaded app settings:");
    println!("  App Name: {}", loaded_settings.app_name);
    println!("  Version: {}", loaded_settings.version);
    println!("  Debug Mode: {}", loaded_settings.debug_mode);
    println!("  Features count: {}", loaded_settings.features.len());
    println!(
        "  Environment variables count: {}",
        loaded_settings.environment_vars.len()
    );

    // Verify data integrity
    assert_eq!(settings, loaded_settings);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison between JSON and binary
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    let user = UserProfile {
        id: 98765,
        username: "bob_builder".to_string(),
        email: "bob@construction.com".to_string(),
        age: 35,
        is_active: false,
        score: 87.2,
    };

    // Save in both formats
    user.save_json("temp_format_comparison.json")?;
    user.save_binary("temp_format_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_format_comparison.json")?.len();
    let binary_size = fs::metadata("temp_format_comparison.bin")?.len();

    println!("Format comparison for UserProfile:");
    println!("  JSON file size: {} bytes", json_size);
    println!("  Binary file size: {} bytes", binary_size);
    println!(
        "  Size ratio (JSON/Binary): {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Demonstrate readability
    let json_content = fs::read_to_string("temp_format_comparison.json")?;
    println!("\nJSON format (human-readable):");
    println!("{}", json_content);

    println!("\nBinary format (first 32 bytes as hex):");
    let binary_content = fs::read("temp_format_comparison.bin")?;
    for (i, byte) in binary_content.iter().take(32).enumerate() {
        if i % 16 == 0 && i > 0 {
            println!();
        }
        print!("{:02x} ", byte);
    }
    println!("\n... ({} total bytes)", binary_content.len());

    // Load and verify both formats produce identical results
    let json_loaded = UserProfile::load_json("temp_format_comparison.json")?;
    let binary_loaded = UserProfile::load_binary("temp_format_comparison.bin")?;

    assert_eq!(json_loaded, binary_loaded);
    println!("\nFormat consistency verification: PASSED");

    Ok(())
}

examples/neural_networks/feedforward_network.rs (line 241)

    pub fn load_json(
        path: &str,
        config: FeedForwardConfig,
    ) -> Result<Self, Box<dyn std::error::Error>> {
        let mut layers = Vec::new();
        let mut current_size = config.input_size;
        let mut layer_idx = 0;

        // Load hidden layers
        for &hidden_size in &config.hidden_sizes {
            let layer_path = format!("{}_layer_{}", path, layer_idx);
            let weight_path = format!("{}_weight.json", layer_path);
            let bias_path = format!("{}_bias.json", layer_path);

            let weight = Tensor::load_json(&weight_path)?.with_requires_grad();
            let bias = Tensor::load_json(&bias_path)?.with_requires_grad();

            layers.push(LinearLayer {
                weight,
                bias,
                input_size: current_size,
                output_size: hidden_size,
            });

            current_size = hidden_size;
            layer_idx += 1;
        }

        // Load output layer
        let layer_path = format!("{}_layer_{}", path, layer_idx);
        let weight_path = format!("{}_weight.json", layer_path);
        let bias_path = format!("{}_bias.json", layer_path);

        let weight = Tensor::load_json(&weight_path)?.with_requires_grad();
        let bias = Tensor::load_json(&bias_path)?.with_requires_grad();

        layers.push(LinearLayer {
            weight,
            bias,
            input_size: current_size,
            output_size: config.output_size,
        });

        Ok(Self { layers, config })
    }

examples/getting_started/serialization_basics.rs (line 69)

fn demonstrate_tensor_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Tensor Serialization ---");

    // Create a tensor with some data
    let original_tensor = Tensor::from_slice(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0], vec![2, 3]).unwrap();
    println!(
        "Original tensor: shape {:?}, data: {:?}",
        original_tensor.shape().dims,
        original_tensor.data()
    );

    // Save tensor in JSON format
    let json_path = "temp_tensor.json";
    original_tensor.save_json(json_path)?;
    println!("Saved tensor to JSON: {}", json_path);

    // Load tensor from JSON
    let loaded_tensor_json = Tensor::load_json(json_path)?;
    println!(
        "Loaded from JSON: shape {:?}, data: {:?}",
        loaded_tensor_json.shape().dims,
        loaded_tensor_json.data()
    );

    // Verify data integrity
    assert_eq!(
        original_tensor.shape().dims,
        loaded_tensor_json.shape().dims
    );
    assert_eq!(original_tensor.data(), loaded_tensor_json.data());
    println!("JSON serialization verification: PASSED");

    // Save tensor in binary format
    let binary_path = "temp_tensor.bin";
    original_tensor.save_binary(binary_path)?;
    println!("Saved tensor to binary: {}", binary_path);

    // Load tensor from binary
    let loaded_tensor_binary = Tensor::load_binary(binary_path)?;
    println!(
        "Loaded from binary: shape {:?}, data: {:?}",
        loaded_tensor_binary.shape().dims,
        loaded_tensor_binary.data()
    );

    // Verify data integrity
    assert_eq!(
        original_tensor.shape().dims,
        loaded_tensor_binary.shape().dims
    );
    assert_eq!(original_tensor.data(), loaded_tensor_binary.data());
    println!("Binary serialization verification: PASSED");

    Ok(())
}

/// Demonstrate optimizer serialization and deserialization
fn demonstrate_optimizer_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Optimizer Serialization ---");

    // Create an optimizer with some parameters
    let mut weight = Tensor::randn(vec![2, 2], Some(42)).with_requires_grad();
    let mut bias = Tensor::randn(vec![2], Some(43)).with_requires_grad();

    let config = AdamConfig {
        learning_rate: 0.001,
        beta1: 0.9,
        beta2: 0.999,
        eps: 1e-8,
        weight_decay: 0.0,
        amsgrad: false,
    };

    let mut optimizer = Adam::with_config(config);
    optimizer.add_parameter(&weight);
    optimizer.add_parameter(&bias);

    println!(
        "Created optimizer with {} parameters",
        optimizer.parameter_count()
    );
    println!("Learning rate: {}", optimizer.learning_rate());

    // Simulate some training steps
    for _ in 0..3 {
        let mut loss = weight.sum() + bias.sum();
        loss.backward(None);
        optimizer.step(&mut [&mut weight, &mut bias]);
        optimizer.zero_grad(&mut [&mut weight, &mut bias]);
    }

    // Save optimizer state
    let optimizer_path = "temp_optimizer.json";
    optimizer.save_json(optimizer_path)?;
    println!("Saved optimizer to: {}", optimizer_path);

    // Load optimizer state
    let loaded_optimizer = Adam::load_json(optimizer_path)?;
    println!(
        "Loaded optimizer with {} parameters",
        loaded_optimizer.parameter_count()
    );
    println!("Learning rate: {}", loaded_optimizer.learning_rate());

    // Verify optimizer state
    assert_eq!(
        optimizer.parameter_count(),
        loaded_optimizer.parameter_count()
    );
    assert_eq!(optimizer.learning_rate(), loaded_optimizer.learning_rate());
    println!("Optimizer serialization verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison and performance characteristics
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    // Create a larger tensor for comparison
    let tensor = Tensor::randn(vec![10, 10], Some(44));

    // Save in both formats
    tensor.save_json("temp_comparison.json")?;
    tensor.save_binary("temp_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_comparison.json")?.len();
    let binary_size = fs::metadata("temp_comparison.bin")?.len();

    println!("JSON file size: {} bytes", json_size);
    println!("Binary file size: {} bytes", binary_size);
    println!(
        "Compression ratio: {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Load and verify both formats
    let json_tensor = Tensor::load_json("temp_comparison.json")?;
    let binary_tensor = Tensor::load_binary("temp_comparison.bin")?;

    assert_eq!(tensor.shape().dims, json_tensor.shape().dims);
    assert_eq!(tensor.shape().dims, binary_tensor.shape().dims);
    assert_eq!(tensor.data(), json_tensor.data());
    assert_eq!(tensor.data(), binary_tensor.data());

    println!("Format comparison verification: PASSED");

    Ok(())
}

/// Demonstrate a basic model checkpointing workflow
fn demonstrate_model_checkpointing() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Model Checkpointing ---");

    // Create a simple model (weights and bias)
    let mut weights = Tensor::randn(vec![2, 1], Some(45)).with_requires_grad();
    let mut bias = Tensor::randn(vec![1], Some(46)).with_requires_grad();

    // Create optimizer
    let mut optimizer = Adam::with_learning_rate(0.01);
    optimizer.add_parameter(&weights);
    optimizer.add_parameter(&bias);

    println!("Initial weights: {:?}", weights.data());
    println!("Initial bias: {:?}", bias.data());

    // Simulate training
    for epoch in 0..5 {
        let mut loss = weights.sum() + bias.sum();
        loss.backward(None);
        optimizer.step(&mut [&mut weights, &mut bias]);
        optimizer.zero_grad(&mut [&mut weights, &mut bias]);

        if epoch % 2 == 0 {
            // Save checkpoint
            let checkpoint_dir = format!("checkpoint_epoch_{}", epoch);
            fs::create_dir_all(&checkpoint_dir)?;

            weights.save_json(format!("{}/weights.json", checkpoint_dir))?;
            bias.save_json(format!("{}/bias.json", checkpoint_dir))?;
            optimizer.save_json(format!("{}/optimizer.json", checkpoint_dir))?;

            println!("Saved checkpoint for epoch {}", epoch);
        }
    }

    // Load from checkpoint
    let loaded_weights = Tensor::load_json("checkpoint_epoch_4/weights.json")?;
    let loaded_bias = Tensor::load_json("checkpoint_epoch_4/bias.json")?;
    let loaded_optimizer = Adam::load_json("checkpoint_epoch_4/optimizer.json")?;

    println!("Loaded weights: {:?}", loaded_weights.data());
    println!("Loaded bias: {:?}", loaded_bias.data());
    println!(
        "Loaded optimizer learning rate: {}",
        loaded_optimizer.learning_rate()
    );

    // Verify checkpoint integrity
    assert_eq!(weights.shape().dims, loaded_weights.shape().dims);
    assert_eq!(bias.shape().dims, loaded_bias.shape().dims);
    assert_eq!(optimizer.learning_rate(), loaded_optimizer.learning_rate());

    println!("Checkpointing verification: PASSED");

    Ok(())
}

/// Demonstrate error handling for serialization operations
fn demonstrate_error_handling() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Error Handling ---");

    // Test loading non-existent file
    match Tensor::load_json("nonexistent_file.json") {
        Ok(_) => println!("Unexpected: Successfully loaded non-existent file"),
        Err(e) => println!("Expected error loading non-existent file: {}", e),
    }

    // Test loading with wrong format
    let tensor = Tensor::randn(vec![2, 2], Some(47));
    tensor.save_binary("temp_binary.bin")?;

    match Tensor::load_json("temp_binary.bin") {
        Ok(_) => println!("Unexpected: Successfully loaded binary as JSON"),
        Err(e) => println!("Expected error loading binary as JSON: {}", e),
    }

    // Test loading corrupted file
    fs::write("temp_invalid.json", "invalid json content")?;
    match Tensor::load_json("temp_invalid.json") {
        Ok(_) => println!("Unexpected: Successfully loaded invalid JSON"),
        Err(e) => println!("Expected error loading invalid JSON: {}", e),
    }

    println!("Error handling verification: PASSED");

    Ok(())
}

examples/serialization/error_handling.rs (line 355)

fn demonstrate_common_error_scenarios() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Common Error Scenarios ---");

    fs::create_dir_all("temp_error_tests")?;

    // Scenario 1: Corrupted JSON file
    println!("1. Corrupted JSON File:");
    let corrupted_json = r#"{"name": "test", "value": 42, "incomplete"#;
    fs::write("temp_error_tests/corrupted.json", corrupted_json)?;

    match VersionedData::load_json("temp_error_tests/corrupted.json") {
        Ok(_) => println!("   Unexpected: Corrupted JSON was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 2: Missing required fields
    println!("\n2. Missing Required Fields:");
    let incomplete_json = r#"{"name": "test"}"#;
    fs::write("temp_error_tests/incomplete.json", incomplete_json)?;

    match VersionedData::load_json("temp_error_tests/incomplete.json") {
        Ok(_) => println!("   Unexpected: Incomplete JSON was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 3: Type mismatches
    println!("\n3. Type Mismatch:");
    let type_mismatch_json = r#"{"version": "not_a_number", "name": "test", "value": 42.0}"#;
    fs::write("temp_error_tests/type_mismatch.json", type_mismatch_json)?;

    match VersionedData::load_json("temp_error_tests/type_mismatch.json") {
        Ok(_) => println!("   Unexpected: Type mismatch was handled gracefully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 4: File not found
    println!("\n4. File Not Found:");
    match VersionedData::load_json("temp_error_tests/nonexistent.json") {
        Ok(_) => println!("   Unexpected: Non-existent file was loaded"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 5: Binary format mismatch
    println!("\n5. Binary Format Mismatch:");
    let invalid_binary = vec![0xFF, 0xFF, 0xFF, 0xFF]; // Invalid binary data
    fs::write("temp_error_tests/invalid.bin", invalid_binary)?;

    match VersionedData::load_binary("temp_error_tests/invalid.bin") {
        Ok(_) => println!("   Unexpected: Invalid binary was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 6: Wrong format loading
    println!("\n6. Wrong Format Loading:");
    let valid_data = VersionedData {
        version: 1,
        name: "test".to_string(),
        value: 42.0,
        optional_field: None,
        new_field: None,
    };
    valid_data.save_binary("temp_error_tests/valid.bin")?;

    // Try to load binary file as JSON
    match VersionedData::load_json("temp_error_tests/valid.bin") {
        Ok(_) => println!("   Unexpected: Binary file was loaded as JSON"),
        Err(e) => println!("   Expected error: {}", e),
    }

    Ok(())
}

/// Demonstrate validation patterns
fn demonstrate_validation_patterns() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Validation Patterns ---");

    println!("Testing input validation with various scenarios:");

    // Valid input
    println!("\n1. Valid Input:");
    let mut valid_preferences = HashMap::new();
    valid_preferences.insert("theme".to_string(), "dark".to_string());
    valid_preferences.insert("language".to_string(), "en".to_string());

    let valid_input = ValidatedUserInput {
        username: "john_doe".to_string(),
        email: "john@example.com".to_string(),
        age: 25,
        preferences: valid_preferences,
    };

    match valid_input.to_json() {
        Ok(json) => {
            println!("   ✓ Valid input serialized successfully");
            match ValidatedUserInput::from_json(&json) {
                Ok(_) => println!("   ✓ Valid input deserialized successfully"),
                Err(e) => println!("   ✗ Deserialization failed: {}", e),
            }
        }
        Err(e) => println!("   ✗ Serialization failed: {}", e),
    }

    // Test validation errors
    let validation_tests = vec![
        (
            "Empty username",
            ValidatedUserInput {
                username: "".to_string(),
                email: "test@example.com".to_string(),
                age: 25,
                preferences: HashMap::new(),
            },
        ),
        (
            "Invalid username characters",
            ValidatedUserInput {
                username: "user@name!".to_string(),
                email: "test@example.com".to_string(),
                age: 25,
                preferences: HashMap::new(),
            },
        ),
        (
            "Invalid email",
            ValidatedUserInput {
                username: "username".to_string(),
                email: "invalid_email".to_string(),
                age: 25,
                preferences: HashMap::new(),
            },
        ),
        (
            "Age too low",
            ValidatedUserInput {
                username: "username".to_string(),
                email: "test@example.com".to_string(),
                age: 10,
                preferences: HashMap::new(),
            },
        ),
        (
            "Age too high",
            ValidatedUserInput {
                username: "username".to_string(),
                email: "test@example.com".to_string(),
                age: 150,
                preferences: HashMap::new(),
            },
        ),
    ];

    for (description, invalid_input) in validation_tests {
        println!("\n2. {}:", description);
        match invalid_input.to_json() {
            Ok(json) => match ValidatedUserInput::from_json(&json) {
                Ok(_) => println!("   ✗ Unexpected: Invalid input was accepted"),
                Err(e) => println!("   ✓ Expected validation error: {}", e),
            },
            Err(e) => println!("   ✗ Serialization error: {}", e),
        }
    }

    // Test preferences validation
    println!("\n3. Preferences Validation:");
    let mut too_many_preferences = HashMap::new();
    for i in 0..25 {
        too_many_preferences.insert(format!("pref_{}", i), "value".to_string());
    }

    let invalid_prefs_input = ValidatedUserInput {
        username: "username".to_string(),
        email: "test@example.com".to_string(),
        age: 25,
        preferences: too_many_preferences,
    };

    match invalid_prefs_input.to_json() {
        Ok(json) => match ValidatedUserInput::from_json(&json) {
            Ok(_) => println!("   ✗ Unexpected: Too many preferences were accepted"),
            Err(e) => println!("   ✓ Expected validation error: {}", e),
        },
        Err(e) => println!("   ✗ Serialization error: {}", e),
    }

    Ok(())
}

/// Demonstrate schema evolution patterns
fn demonstrate_schema_evolution() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Schema Evolution Patterns ---");

    fs::create_dir_all("temp_schema_tests")?;

    // Create data with different schema versions
    println!("Creating data with different schema versions:");

    // Version 1 data (minimal)
    let v1_json = r#"{
        "version": 1,
        "name": "legacy_data",
        "value": 123.45
    }"#;
    fs::write("temp_schema_tests/v1_data.json", v1_json)?;
    println!("  ✓ Version 1 data created (minimal fields)");

    // Version 2 data (with optional field)
    let v2_json = r#"{
        "version": 2,
        "name": "v2_data",
        "value": 678.90,
        "optional_field": "added_in_v2"
    }"#;
    fs::write("temp_schema_tests/v2_data.json", v2_json)?;
    println!("  ✓ Version 2 data created (with optional field)");

    // Version 3 data (with all fields)
    let v3_data = VersionedData {
        version: 3,
        name: "v3_data".to_string(),
        value: 999.99,
        optional_field: Some("present".to_string()),
        new_field: Some(42),
    };
    v3_data.save_json("temp_schema_tests/v3_data.json")?;
    println!("  ✓ Version 3 data created (all fields)");

    // Test backward compatibility
    println!("\nTesting backward compatibility:");

    // Load v1 data with current deserializer
    match VersionedData::load_json("temp_schema_tests/v1_data.json") {
        Ok(data) => {
            println!("  ✓ V1 data loaded successfully:");
            println!("    Name: {}", data.name);
            println!("    Value: {}", data.value);
            println!("    Optional field: {:?}", data.optional_field);
            println!("    New field: {:?}", data.new_field);
        }
        Err(e) => println!("  ✗ Failed to load V1 data: {}", e),
    }

    // Load v2 data with current deserializer
    match VersionedData::load_json("temp_schema_tests/v2_data.json") {
        Ok(data) => {
            println!("  ✓ V2 data loaded successfully:");
            println!("    Name: {}", data.name);
            println!("    Value: {}", data.value);
            println!("    Optional field: {:?}", data.optional_field);
            println!("    New field: {:?}", data.new_field);
        }
        Err(e) => println!("  ✗ Failed to load V2 data: {}", e),
    }

    // Test future version rejection
    println!("\nTesting future version handling:");
    let future_version_json = r#"{
        "version": 99,
        "name": "future_data",
        "value": 123.45,
        "unknown_field": "should_be_ignored"
    }"#;
    fs::write("temp_schema_tests/future_data.json", future_version_json)?;

    match VersionedData::load_json("temp_schema_tests/future_data.json") {
        Ok(_) => println!("  ✗ Unexpected: Future version was accepted"),
        Err(e) => println!("  ✓ Expected rejection of future version: {}", e),
    }

    // Demonstrate migration strategy
    println!("\nDemonstrating migration strategy:");
    println!("  Strategy: Load old format, upgrade to new format, save");

    // Simulate migrating v1 data to v3 format
    let v1_loaded = VersionedData::load_json("temp_schema_tests/v1_data.json")?;
    let v1_upgraded = VersionedData {
        version: 3,
        name: v1_loaded.name,
        value: v1_loaded.value,
        optional_field: Some("migrated_default".to_string()),
        new_field: Some(0),
    };

    v1_upgraded.save_json("temp_schema_tests/v1_migrated.json")?;
    println!("  ✓ V1 data migrated to V3 format");

    Ok(())
}

/// Demonstrate recovery strategies
fn demonstrate_recovery_strategies() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Recovery Strategies ---");

    fs::create_dir_all("temp_recovery_tests")?;

    // Strategy 1: Graceful degradation
    println!("1. Graceful Degradation Strategy:");

    // Create complete data
    let complete_data = RecoverableData {
        critical_field: "essential_info".to_string(),
        important_field: Some("important_info".to_string()),
        optional_field: Some("nice_to_have".to_string()),
        metadata: {
            let mut map = HashMap::new();
            map.insert("key1".to_string(), "value1".to_string());
            map.insert("key2".to_string(), "value2".to_string());
            map
        },
    };

    // Save complete data
    complete_data.save_json("temp_recovery_tests/complete.json")?;

    // Create partial data (missing some fields)
    let partial_json = r#"{
        "critical_field": "essential_info",
        "optional_field": "nice_to_have"
    }"#;
    fs::write("temp_recovery_tests/partial.json", partial_json)?;

    // Load partial data and demonstrate recovery
    match RecoverableData::load_json("temp_recovery_tests/partial.json") {
        Ok(recovered) => {
            println!("  ✓ Partial data recovered successfully:");
            println!("    Critical field: {}", recovered.critical_field);
            println!(
                "    Important field: {:?} (missing, set to None)",
                recovered.important_field
            );
            println!("    Optional field: {:?}", recovered.optional_field);
            println!(
                "    Metadata: {} entries (defaulted to empty)",
                recovered.metadata.len()
            );
        }
        Err(e) => println!("  ✗ Recovery failed: {}", e),
    }

    // Strategy 2: Error context preservation
    println!("\n2. Error Context Preservation:");

    let malformed_json = r#"{
        "critical_field": "essential_info",
        "important_field": 12345,
        "metadata": "not_a_map"
    }"#;
    fs::write("temp_recovery_tests/malformed.json", malformed_json)?;

    match RecoverableData::load_json("temp_recovery_tests/malformed.json") {
        Ok(_) => println!("  ✗ Unexpected: Malformed data was accepted"),
        Err(e) => {
            println!("  ✓ Error context preserved:");
            println!("    Error: {}", e);
            println!("    Error type: {:?}", std::mem::discriminant(&e));
        }
    }

    // Strategy 3: Fallback data sources
    println!("\n3. Fallback Data Sources:");

    // Primary source (corrupted)
    let corrupted_primary = "corrupted data";
    fs::write("temp_recovery_tests/primary.json", corrupted_primary)?;

    // Backup source (valid)
    let backup_data = RecoverableData {
        critical_field: "backup_critical".to_string(),
        important_field: Some("backup_important".to_string()),
        optional_field: None,
        metadata: HashMap::new(),
    };
    backup_data.save_json("temp_recovery_tests/backup.json")?;

    // Default fallback
    let default_data = RecoverableData {
        critical_field: "default_critical".to_string(),
        important_field: None,
        optional_field: None,
        metadata: HashMap::new(),
    };

    println!("  Attempting to load data with fallback chain:");

    // Try primary source
    let loaded_data = match RecoverableData::load_json("temp_recovery_tests/primary.json") {
        Ok(data) => {
            println!("    ✓ Loaded from primary source");
            data
        }
        Err(_) => {
            println!("    ✗ Primary source failed, trying backup");

            // Try backup source
            match RecoverableData::load_json("temp_recovery_tests/backup.json") {
                Ok(data) => {
                    println!("    ✓ Loaded from backup source");
                    data
                }
                Err(_) => {
                    println!("    ✗ Backup source failed, using default");
                    default_data
                }
            }
        }
    };

    println!("  Final loaded data:");
    println!("    Critical field: {}", loaded_data.critical_field);

    Ok(())
}

/// Demonstrate production-ready error handling
fn demonstrate_production_error_handling() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Production Error Handling ---");

    fs::create_dir_all("temp_production_tests")?;

    // Error logging and monitoring
    println!("1. Error Logging and Monitoring:");

    let test_data = VersionedData {
        version: 2,
        name: "production_test".to_string(),
        value: 42.0,
        optional_field: Some("test".to_string()),
        new_field: None,
    };

    // Create error log for demonstration
    let mut error_log = fs::OpenOptions::new()
        .create(true)
        .append(true)
        .open("temp_production_tests/error.log")?;

    // Function to log errors in production format
    let mut log_error =
        |error: &SerializationError, context: &str| -> Result<(), Box<dyn std::error::Error>> {
            let timestamp = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)?
                .as_secs();

            writeln!(error_log, "[{}] ERROR in {}: {}", timestamp, context, error)?;
            Ok(())
        };

    // Simulate various error scenarios with logging
    let error_scenarios = vec![
        ("corrupted_file.json", "invalid json content"),
        ("missing_fields.json", r#"{"version": 1}"#),
        (
            "type_error.json",
            r#"{"version": "not_number", "name": "test", "value": 42.0}"#,
        ),
    ];

    for (filename, content) in error_scenarios {
        let filepath = format!("temp_production_tests/{}", filename);
        fs::write(&filepath, content)?;

        match VersionedData::load_json(&filepath) {
            Ok(_) => println!("  ✗ Unexpected success for {}", filename),
            Err(e) => {
                log_error(&e, &format!("load_config({})", filename))?;
                println!("  ✓ Error logged for {}: {}", filename, e);
            }
        }
    }

    // Health check pattern
    println!("\n2. Health Check Pattern:");

    let health_check = || -> Result<bool, SerializationError> {
        // Check if we can serialize/deserialize basic data
        let test_data = VersionedData {
            version: 1,
            name: "health_check".to_string(),
            value: 1.0,
            optional_field: None,
            new_field: None,
        };

        let serialized = test_data.to_json()?;
        let _deserialized = VersionedData::from_json(&serialized)?;
        Ok(true)
    };

    match health_check() {
        Ok(_) => println!("  ✓ Serialization system health check passed"),
        Err(e) => {
            log_error(&e, "health_check")?;
            println!("  ✗ Serialization system health check failed: {}", e);
        }
    }

    // Circuit breaker pattern simulation
    println!("\n3. Circuit Breaker Pattern:");

    struct CircuitBreaker {
        failure_count: u32,
        failure_threshold: u32,
        is_open: bool,
    }

    impl CircuitBreaker {
        fn new(threshold: u32) -> Self {
            Self {
                failure_count: 0,
                failure_threshold: threshold,
                is_open: false,
            }
        }

        fn call<F, T>(&mut self, operation: F) -> Result<T, String>
        where
            F: FnOnce() -> Result<T, SerializationError>,
        {
            if self.is_open {
                return Err("Circuit breaker is open".to_string());
            }

            match operation() {
                Ok(result) => {
                    self.failure_count = 0; // Reset on success
                    Ok(result)
                }
                Err(e) => {
                    self.failure_count += 1;
                    if self.failure_count >= self.failure_threshold {
                        self.is_open = true;
                        println!(
                            "    Circuit breaker opened after {} failures",
                            self.failure_count
                        );
                    }
                    Err(e.to_string())
                }
            }
        }
    }

    let mut circuit_breaker = CircuitBreaker::new(3);

    // Simulate operations that fail
    for i in 1..=5 {
        let result = circuit_breaker
            .call(|| VersionedData::load_json("temp_production_tests/corrupted_file.json"));

        match result {
            Ok(_) => println!("  Operation {} succeeded", i),
            Err(e) => println!("  Operation {} failed: {}", i, e),
        }
    }

    // Retry mechanism
    println!("\n4. Retry Mechanism:");

    let retry_operation = |max_attempts: u32| -> Result<VersionedData, String> {
        for attempt in 1..=max_attempts {
            println!("    Attempt {}/{}", attempt, max_attempts);

            // Try different sources in order
            let sources = vec![
                "temp_production_tests/corrupted_file.json",
                "temp_production_tests/missing_fields.json",
                "temp_production_tests/backup_valid.json",
            ];

            if attempt == max_attempts {
                // On final attempt, create valid backup
                test_data
                    .save_json("temp_production_tests/backup_valid.json")
                    .map_err(|e| format!("Failed to create backup: {}", e))?;
            }

            for source in &sources {
                match VersionedData::load_json(source) {
                    Ok(data) => {
                        println!("    ✓ Succeeded loading from {}", source);
                        return Ok(data);
                    }
                    Err(_) => {
                        println!("    ✗ Failed to load from {}", source);
                        continue;
                    }
                }
            }

            if attempt < max_attempts {
                println!("    Waiting before retry...");
                // In real code, would sleep here
            }
        }

        Err("All retry attempts exhausted".to_string())
    };

    match retry_operation(3) {
        Ok(data) => println!("  ✓ Retry succeeded: {}", data.name),
        Err(e) => println!("  ✗ Retry failed: {}", e),
    }

    Ok(())
}

examples/serialization/nested_structures.rs (line 699)

fn demonstrate_nested_struct_creation() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Nested Structure Creation ---");

    // Create nested address and contact info
    let headquarters = Address {
        street: "123 Innovation Drive".to_string(),
        city: "Tech City".to_string(),
        state: "CA".to_string(),
        postal_code: "94000".to_string(),
        country: "USA".to_string(),
    };

    let mut social_media = HashMap::new();
    social_media.insert("twitter".to_string(), "@techcorp".to_string());
    social_media.insert("linkedin".to_string(), "techcorp-inc".to_string());

    let contact_info = ContactInfo {
        email: "info@techcorp.com".to_string(),
        phone: Some("+1-555-0123".to_string()),
        address_city: headquarters.city.clone(),
        address_state: headquarters.state.clone(),
        social_media,
    };

    // Create departments with nested office locations
    let engineering_office = Address {
        street: "456 Developer Lane".to_string(),
        city: "Code City".to_string(),
        state: "CA".to_string(),
        postal_code: "94001".to_string(),
        country: "USA".to_string(),
    };

    let departments = [
        Department {
            name: "Engineering".to_string(),
            manager: "Alice Johnson".to_string(),
            employee_count: 50,
            budget: 2500000.0,
            office_locations: vec![engineering_office, headquarters.clone()],
        },
        Department {
            name: "Marketing".to_string(),
            manager: "Bob Smith".to_string(),
            employee_count: 15,
            budget: 800000.0,
            office_locations: vec![headquarters.clone()],
        },
    ];

    // Create projects with milestones
    let milestones = vec![
        Milestone {
            name: "Requirements Analysis".to_string(),
            description: "Complete system requirements documentation".to_string(),
            due_date: "2024-03-15".to_string(),
            is_completed: true,
            progress_percentage: 100.0,
            dependencies: vec![],
        },
        Milestone {
            name: "Architecture Design".to_string(),
            description: "Define system architecture and components".to_string(),
            due_date: "2024-04-01".to_string(),
            is_completed: false,
            progress_percentage: 75.0,
            dependencies: vec!["Requirements Analysis".to_string()],
        },
    ];

    let mut project_metadata = HashMap::new();
    project_metadata.insert("priority".to_string(), "high".to_string());
    project_metadata.insert("client".to_string(), "internal".to_string());

    let projects = [Project {
        name: "Train Station ML Platform".to_string(),
        description: "Next-generation machine learning infrastructure".to_string(),
        status: ProjectStatus::InProgress,
        budget: 1500000.0,
        team_members: vec![
            "Alice Johnson".to_string(),
            "Charlie Brown".to_string(),
            "Diana Prince".to_string(),
        ],
        milestones: milestones.clone(),
        metadata: project_metadata,
    }];

    // Create the complete company structure
    let mut company_metadata = HashMap::new();
    company_metadata.insert("industry".to_string(), "technology".to_string());
    company_metadata.insert("stock_symbol".to_string(), "TECH".to_string());

    let company = Company {
        name: "TechCorp Inc.".to_string(),
        founded_year: 2015,
        headquarters_city: headquarters.city.clone(),
        headquarters_state: headquarters.state.clone(),
        employee_count: 250,
        department_names: departments.iter().map(|d| d.name.clone()).collect(),
        active_project_names: projects.iter().map(|p| p.name.clone()).collect(),
        company_metadata,
    };

    println!("Created complex company structure:");
    println!("  Company: {}", company.name);
    println!("  Founded: {}", company.founded_year);
    println!(
        "  Headquarters: {}, {}",
        company.headquarters_city, company.headquarters_state
    );
    println!("  Employee Count: {}", company.employee_count);
    println!("  Departments: {}", company.department_names.len());
    println!("  Active Projects: {}", company.active_project_names.len());

    // Save the complete structure
    company.save_json("temp_nested_company.json")?;
    println!("Saved nested structure to: temp_nested_company.json");

    // Verify loading preserves all nested data
    let loaded_company = Company::load_json("temp_nested_company.json")?;
    assert_eq!(company, loaded_company);
    println!("Successfully verified Company roundtrip serialization");

    // Also demonstrate individual component serialization
    let address_json = headquarters.to_json()?;
    let loaded_address = Address::from_json(&address_json)?;
    assert_eq!(headquarters, loaded_address);
    println!("Successfully serialized/deserialized Address component");

    let contact_json = contact_info.to_json()?;
    let loaded_contact = ContactInfo::from_json(&contact_json)?;
    assert_eq!(contact_info, loaded_contact);
    println!("Successfully serialized/deserialized ContactInfo component");
    println!("Nested structure integrity: VERIFIED");

    Ok(())
}

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

Loads the struct from a binary file

Reads binary data from the specified file path and deserializes it into a new instance of the struct.

Arguments

• path - File path containing the binary data to read

Returns

Ok(Self) on successful deserialization Err(SerializationError) if file I/O or deserialization fails

Examples

Loads struct data from a binary file with proper error handling.

Examples found in repository

examples/getting_started/serialization_basics.rs (line 90)

fn demonstrate_tensor_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Tensor Serialization ---");

    // Create a tensor with some data
    let original_tensor = Tensor::from_slice(&[1.0, 2.0, 3.0, 4.0, 5.0, 6.0], vec![2, 3]).unwrap();
    println!(
        "Original tensor: shape {:?}, data: {:?}",
        original_tensor.shape().dims,
        original_tensor.data()
    );

    // Save tensor in JSON format
    let json_path = "temp_tensor.json";
    original_tensor.save_json(json_path)?;
    println!("Saved tensor to JSON: {}", json_path);

    // Load tensor from JSON
    let loaded_tensor_json = Tensor::load_json(json_path)?;
    println!(
        "Loaded from JSON: shape {:?}, data: {:?}",
        loaded_tensor_json.shape().dims,
        loaded_tensor_json.data()
    );

    // Verify data integrity
    assert_eq!(
        original_tensor.shape().dims,
        loaded_tensor_json.shape().dims
    );
    assert_eq!(original_tensor.data(), loaded_tensor_json.data());
    println!("JSON serialization verification: PASSED");

    // Save tensor in binary format
    let binary_path = "temp_tensor.bin";
    original_tensor.save_binary(binary_path)?;
    println!("Saved tensor to binary: {}", binary_path);

    // Load tensor from binary
    let loaded_tensor_binary = Tensor::load_binary(binary_path)?;
    println!(
        "Loaded from binary: shape {:?}, data: {:?}",
        loaded_tensor_binary.shape().dims,
        loaded_tensor_binary.data()
    );

    // Verify data integrity
    assert_eq!(
        original_tensor.shape().dims,
        loaded_tensor_binary.shape().dims
    );
    assert_eq!(original_tensor.data(), loaded_tensor_binary.data());
    println!("Binary serialization verification: PASSED");

    Ok(())
}

/// Demonstrate optimizer serialization and deserialization
fn demonstrate_optimizer_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Optimizer Serialization ---");

    // Create an optimizer with some parameters
    let mut weight = Tensor::randn(vec![2, 2], Some(42)).with_requires_grad();
    let mut bias = Tensor::randn(vec![2], Some(43)).with_requires_grad();

    let config = AdamConfig {
        learning_rate: 0.001,
        beta1: 0.9,
        beta2: 0.999,
        eps: 1e-8,
        weight_decay: 0.0,
        amsgrad: false,
    };

    let mut optimizer = Adam::with_config(config);
    optimizer.add_parameter(&weight);
    optimizer.add_parameter(&bias);

    println!(
        "Created optimizer with {} parameters",
        optimizer.parameter_count()
    );
    println!("Learning rate: {}", optimizer.learning_rate());

    // Simulate some training steps
    for _ in 0..3 {
        let mut loss = weight.sum() + bias.sum();
        loss.backward(None);
        optimizer.step(&mut [&mut weight, &mut bias]);
        optimizer.zero_grad(&mut [&mut weight, &mut bias]);
    }

    // Save optimizer state
    let optimizer_path = "temp_optimizer.json";
    optimizer.save_json(optimizer_path)?;
    println!("Saved optimizer to: {}", optimizer_path);

    // Load optimizer state
    let loaded_optimizer = Adam::load_json(optimizer_path)?;
    println!(
        "Loaded optimizer with {} parameters",
        loaded_optimizer.parameter_count()
    );
    println!("Learning rate: {}", loaded_optimizer.learning_rate());

    // Verify optimizer state
    assert_eq!(
        optimizer.parameter_count(),
        loaded_optimizer.parameter_count()
    );
    assert_eq!(optimizer.learning_rate(), loaded_optimizer.learning_rate());
    println!("Optimizer serialization verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison and performance characteristics
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    // Create a larger tensor for comparison
    let tensor = Tensor::randn(vec![10, 10], Some(44));

    // Save in both formats
    tensor.save_json("temp_comparison.json")?;
    tensor.save_binary("temp_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_comparison.json")?.len();
    let binary_size = fs::metadata("temp_comparison.bin")?.len();

    println!("JSON file size: {} bytes", json_size);
    println!("Binary file size: {} bytes", binary_size);
    println!(
        "Compression ratio: {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Load and verify both formats
    let json_tensor = Tensor::load_json("temp_comparison.json")?;
    let binary_tensor = Tensor::load_binary("temp_comparison.bin")?;

    assert_eq!(tensor.shape().dims, json_tensor.shape().dims);
    assert_eq!(tensor.shape().dims, binary_tensor.shape().dims);
    assert_eq!(tensor.data(), json_tensor.data());
    assert_eq!(tensor.data(), binary_tensor.data());

    println!("Format comparison verification: PASSED");

    Ok(())
}

examples/serialization/basic_structs.rs (line 315)

fn demonstrate_app_settings_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- App Settings Serialization ---");

    // Create app settings with collections and optional fields
    let mut env_vars = HashMap::new();
    env_vars.insert("LOG_LEVEL".to_string(), "info".to_string());
    env_vars.insert("PORT".to_string(), "8080".to_string());
    env_vars.insert("HOST".to_string(), "localhost".to_string());

    let settings = AppSettings {
        app_name: "Train Station Example".to_string(),
        version: "1.0.0".to_string(),
        debug_mode: true,
        max_connections: 100,
        timeout_seconds: 30.5,
        features: vec![
            "authentication".to_string(),
            "logging".to_string(),
            "metrics".to_string(),
        ],
        environment_vars: env_vars,
        optional_database_url: Some("postgresql://localhost:5432/mydb".to_string()),
    };

    println!("Original app settings:");
    println!("  App Name: {}", settings.app_name);
    println!("  Version: {}", settings.version);
    println!("  Debug Mode: {}", settings.debug_mode);
    println!("  Max Connections: {}", settings.max_connections);
    println!("  Timeout: {} seconds", settings.timeout_seconds);
    println!("  Features: {:?}", settings.features);
    println!("  Environment Variables: {:?}", settings.environment_vars);
    println!("  Database URL: {:?}", settings.optional_database_url);

    // Serialize to binary format for efficient storage
    let binary_data = settings.to_binary()?;
    println!("\nSerialized to binary: {} bytes", binary_data.len());

    // Save to binary file
    settings.save_binary("temp_app_settings.bin")?;
    println!("Saved to file: temp_app_settings.bin");

    // Load from binary file
    let loaded_settings = AppSettings::load_binary("temp_app_settings.bin")?;
    println!("\nLoaded app settings:");
    println!("  App Name: {}", loaded_settings.app_name);
    println!("  Version: {}", loaded_settings.version);
    println!("  Debug Mode: {}", loaded_settings.debug_mode);
    println!("  Features count: {}", loaded_settings.features.len());
    println!(
        "  Environment variables count: {}",
        loaded_settings.environment_vars.len()
    );

    // Verify data integrity
    assert_eq!(settings, loaded_settings);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison between JSON and binary
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    let user = UserProfile {
        id: 98765,
        username: "bob_builder".to_string(),
        email: "bob@construction.com".to_string(),
        age: 35,
        is_active: false,
        score: 87.2,
    };

    // Save in both formats
    user.save_json("temp_format_comparison.json")?;
    user.save_binary("temp_format_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_format_comparison.json")?.len();
    let binary_size = fs::metadata("temp_format_comparison.bin")?.len();

    println!("Format comparison for UserProfile:");
    println!("  JSON file size: {} bytes", json_size);
    println!("  Binary file size: {} bytes", binary_size);
    println!(
        "  Size ratio (JSON/Binary): {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Demonstrate readability
    let json_content = fs::read_to_string("temp_format_comparison.json")?;
    println!("\nJSON format (human-readable):");
    println!("{}", json_content);

    println!("\nBinary format (first 32 bytes as hex):");
    let binary_content = fs::read("temp_format_comparison.bin")?;
    for (i, byte) in binary_content.iter().take(32).enumerate() {
        if i % 16 == 0 && i > 0 {
            println!();
        }
        print!("{:02x} ", byte);
    }
    println!("\n... ({} total bytes)", binary_content.len());

    // Load and verify both formats produce identical results
    let json_loaded = UserProfile::load_json("temp_format_comparison.json")?;
    let binary_loaded = UserProfile::load_binary("temp_format_comparison.bin")?;

    assert_eq!(json_loaded, binary_loaded);
    println!("\nFormat consistency verification: PASSED");

    Ok(())
}

examples/serialization/error_handling.rs (line 392)

fn demonstrate_common_error_scenarios() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Common Error Scenarios ---");

    fs::create_dir_all("temp_error_tests")?;

    // Scenario 1: Corrupted JSON file
    println!("1. Corrupted JSON File:");
    let corrupted_json = r#"{"name": "test", "value": 42, "incomplete"#;
    fs::write("temp_error_tests/corrupted.json", corrupted_json)?;

    match VersionedData::load_json("temp_error_tests/corrupted.json") {
        Ok(_) => println!("   Unexpected: Corrupted JSON was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 2: Missing required fields
    println!("\n2. Missing Required Fields:");
    let incomplete_json = r#"{"name": "test"}"#;
    fs::write("temp_error_tests/incomplete.json", incomplete_json)?;

    match VersionedData::load_json("temp_error_tests/incomplete.json") {
        Ok(_) => println!("   Unexpected: Incomplete JSON was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 3: Type mismatches
    println!("\n3. Type Mismatch:");
    let type_mismatch_json = r#"{"version": "not_a_number", "name": "test", "value": 42.0}"#;
    fs::write("temp_error_tests/type_mismatch.json", type_mismatch_json)?;

    match VersionedData::load_json("temp_error_tests/type_mismatch.json") {
        Ok(_) => println!("   Unexpected: Type mismatch was handled gracefully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 4: File not found
    println!("\n4. File Not Found:");
    match VersionedData::load_json("temp_error_tests/nonexistent.json") {
        Ok(_) => println!("   Unexpected: Non-existent file was loaded"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 5: Binary format mismatch
    println!("\n5. Binary Format Mismatch:");
    let invalid_binary = vec![0xFF, 0xFF, 0xFF, 0xFF]; // Invalid binary data
    fs::write("temp_error_tests/invalid.bin", invalid_binary)?;

    match VersionedData::load_binary("temp_error_tests/invalid.bin") {
        Ok(_) => println!("   Unexpected: Invalid binary was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 6: Wrong format loading
    println!("\n6. Wrong Format Loading:");
    let valid_data = VersionedData {
        version: 1,
        name: "test".to_string(),
        value: 42.0,
        optional_field: None,
        new_field: None,
    };
    valid_data.save_binary("temp_error_tests/valid.bin")?;

    // Try to load binary file as JSON
    match VersionedData::load_json("temp_error_tests/valid.bin") {
        Ok(_) => println!("   Unexpected: Binary file was loaded as JSON"),
        Err(e) => println!("   Expected error: {}", e),
    }

    Ok(())
}

fn to_json(&self) -> SerializationResult<String>

Converts the struct to a JSON string

Serializes the struct to a human-readable JSON string format. The JSON output maintains field order and includes proper escaping.

Returns

Ok(String) containing the JSON representation on success Err(SerializationError) if serialization fails

Examples

Converts struct to JSON string with proper escaping and formatting.

Examples found in repository

examples/serialization/error_handling.rs (line 86)

    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,
        })
    }
}

impl ToFieldValue for RecoverableData {
    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 RecoverableData {
    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 RecoverableData 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 RecoverableData from binary: {}", e),
                }
            });
        }

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Error Handling and Validation Example ===\n");

    demonstrate_common_error_scenarios()?;
    demonstrate_validation_patterns()?;
    demonstrate_schema_evolution()?;
    demonstrate_recovery_strategies()?;
    demonstrate_production_error_handling()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate common serialization error scenarios
fn demonstrate_common_error_scenarios() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Common Error Scenarios ---");

    fs::create_dir_all("temp_error_tests")?;

    // Scenario 1: Corrupted JSON file
    println!("1. Corrupted JSON File:");
    let corrupted_json = r#"{"name": "test", "value": 42, "incomplete"#;
    fs::write("temp_error_tests/corrupted.json", corrupted_json)?;

    match VersionedData::load_json("temp_error_tests/corrupted.json") {
        Ok(_) => println!("   Unexpected: Corrupted JSON was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 2: Missing required fields
    println!("\n2. Missing Required Fields:");
    let incomplete_json = r#"{"name": "test"}"#;
    fs::write("temp_error_tests/incomplete.json", incomplete_json)?;

    match VersionedData::load_json("temp_error_tests/incomplete.json") {
        Ok(_) => println!("   Unexpected: Incomplete JSON was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 3: Type mismatches
    println!("\n3. Type Mismatch:");
    let type_mismatch_json = r#"{"version": "not_a_number", "name": "test", "value": 42.0}"#;
    fs::write("temp_error_tests/type_mismatch.json", type_mismatch_json)?;

    match VersionedData::load_json("temp_error_tests/type_mismatch.json") {
        Ok(_) => println!("   Unexpected: Type mismatch was handled gracefully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 4: File not found
    println!("\n4. File Not Found:");
    match VersionedData::load_json("temp_error_tests/nonexistent.json") {
        Ok(_) => println!("   Unexpected: Non-existent file was loaded"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 5: Binary format mismatch
    println!("\n5. Binary Format Mismatch:");
    let invalid_binary = vec![0xFF, 0xFF, 0xFF, 0xFF]; // Invalid binary data
    fs::write("temp_error_tests/invalid.bin", invalid_binary)?;

    match VersionedData::load_binary("temp_error_tests/invalid.bin") {
        Ok(_) => println!("   Unexpected: Invalid binary was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 6: Wrong format loading
    println!("\n6. Wrong Format Loading:");
    let valid_data = VersionedData {
        version: 1,
        name: "test".to_string(),
        value: 42.0,
        optional_field: None,
        new_field: None,
    };
    valid_data.save_binary("temp_error_tests/valid.bin")?;

    // Try to load binary file as JSON
    match VersionedData::load_json("temp_error_tests/valid.bin") {
        Ok(_) => println!("   Unexpected: Binary file was loaded as JSON"),
        Err(e) => println!("   Expected error: {}", e),
    }

    Ok(())
}

/// Demonstrate validation patterns
fn demonstrate_validation_patterns() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Validation Patterns ---");

    println!("Testing input validation with various scenarios:");

    // Valid input
    println!("\n1. Valid Input:");
    let mut valid_preferences = HashMap::new();
    valid_preferences.insert("theme".to_string(), "dark".to_string());
    valid_preferences.insert("language".to_string(), "en".to_string());

    let valid_input = ValidatedUserInput {
        username: "john_doe".to_string(),
        email: "john@example.com".to_string(),
        age: 25,
        preferences: valid_preferences,
    };

    match valid_input.to_json() {
        Ok(json) => {
            println!("   ✓ Valid input serialized successfully");
            match ValidatedUserInput::from_json(&json) {
                Ok(_) => println!("   ✓ Valid input deserialized successfully"),
                Err(e) => println!("   ✗ Deserialization failed: {}", e),
            }
        }
        Err(e) => println!("   ✗ Serialization failed: {}", e),
    }

    // Test validation errors
    let validation_tests = vec![
        (
            "Empty username",
            ValidatedUserInput {
                username: "".to_string(),
                email: "test@example.com".to_string(),
                age: 25,
                preferences: HashMap::new(),
            },
        ),
        (
            "Invalid username characters",
            ValidatedUserInput {
                username: "user@name!".to_string(),
                email: "test@example.com".to_string(),
                age: 25,
                preferences: HashMap::new(),
            },
        ),
        (
            "Invalid email",
            ValidatedUserInput {
                username: "username".to_string(),
                email: "invalid_email".to_string(),
                age: 25,
                preferences: HashMap::new(),
            },
        ),
        (
            "Age too low",
            ValidatedUserInput {
                username: "username".to_string(),
                email: "test@example.com".to_string(),
                age: 10,
                preferences: HashMap::new(),
            },
        ),
        (
            "Age too high",
            ValidatedUserInput {
                username: "username".to_string(),
                email: "test@example.com".to_string(),
                age: 150,
                preferences: HashMap::new(),
            },
        ),
    ];

    for (description, invalid_input) in validation_tests {
        println!("\n2. {}:", description);
        match invalid_input.to_json() {
            Ok(json) => match ValidatedUserInput::from_json(&json) {
                Ok(_) => println!("   ✗ Unexpected: Invalid input was accepted"),
                Err(e) => println!("   ✓ Expected validation error: {}", e),
            },
            Err(e) => println!("   ✗ Serialization error: {}", e),
        }
    }

    // Test preferences validation
    println!("\n3. Preferences Validation:");
    let mut too_many_preferences = HashMap::new();
    for i in 0..25 {
        too_many_preferences.insert(format!("pref_{}", i), "value".to_string());
    }

    let invalid_prefs_input = ValidatedUserInput {
        username: "username".to_string(),
        email: "test@example.com".to_string(),
        age: 25,
        preferences: too_many_preferences,
    };

    match invalid_prefs_input.to_json() {
        Ok(json) => match ValidatedUserInput::from_json(&json) {
            Ok(_) => println!("   ✗ Unexpected: Too many preferences were accepted"),
            Err(e) => println!("   ✓ Expected validation error: {}", e),
        },
        Err(e) => println!("   ✗ Serialization error: {}", e),
    }

    Ok(())
}

/// Demonstrate schema evolution patterns
fn demonstrate_schema_evolution() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Schema Evolution Patterns ---");

    fs::create_dir_all("temp_schema_tests")?;

    // Create data with different schema versions
    println!("Creating data with different schema versions:");

    // Version 1 data (minimal)
    let v1_json = r#"{
        "version": 1,
        "name": "legacy_data",
        "value": 123.45
    }"#;
    fs::write("temp_schema_tests/v1_data.json", v1_json)?;
    println!("  ✓ Version 1 data created (minimal fields)");

    // Version 2 data (with optional field)
    let v2_json = r#"{
        "version": 2,
        "name": "v2_data",
        "value": 678.90,
        "optional_field": "added_in_v2"
    }"#;
    fs::write("temp_schema_tests/v2_data.json", v2_json)?;
    println!("  ✓ Version 2 data created (with optional field)");

    // Version 3 data (with all fields)
    let v3_data = VersionedData {
        version: 3,
        name: "v3_data".to_string(),
        value: 999.99,
        optional_field: Some("present".to_string()),
        new_field: Some(42),
    };
    v3_data.save_json("temp_schema_tests/v3_data.json")?;
    println!("  ✓ Version 3 data created (all fields)");

    // Test backward compatibility
    println!("\nTesting backward compatibility:");

    // Load v1 data with current deserializer
    match VersionedData::load_json("temp_schema_tests/v1_data.json") {
        Ok(data) => {
            println!("  ✓ V1 data loaded successfully:");
            println!("    Name: {}", data.name);
            println!("    Value: {}", data.value);
            println!("    Optional field: {:?}", data.optional_field);
            println!("    New field: {:?}", data.new_field);
        }
        Err(e) => println!("  ✗ Failed to load V1 data: {}", e),
    }

    // Load v2 data with current deserializer
    match VersionedData::load_json("temp_schema_tests/v2_data.json") {
        Ok(data) => {
            println!("  ✓ V2 data loaded successfully:");
            println!("    Name: {}", data.name);
            println!("    Value: {}", data.value);
            println!("    Optional field: {:?}", data.optional_field);
            println!("    New field: {:?}", data.new_field);
        }
        Err(e) => println!("  ✗ Failed to load V2 data: {}", e),
    }

    // Test future version rejection
    println!("\nTesting future version handling:");
    let future_version_json = r#"{
        "version": 99,
        "name": "future_data",
        "value": 123.45,
        "unknown_field": "should_be_ignored"
    }"#;
    fs::write("temp_schema_tests/future_data.json", future_version_json)?;

    match VersionedData::load_json("temp_schema_tests/future_data.json") {
        Ok(_) => println!("  ✗ Unexpected: Future version was accepted"),
        Err(e) => println!("  ✓ Expected rejection of future version: {}", e),
    }

    // Demonstrate migration strategy
    println!("\nDemonstrating migration strategy:");
    println!("  Strategy: Load old format, upgrade to new format, save");

    // Simulate migrating v1 data to v3 format
    let v1_loaded = VersionedData::load_json("temp_schema_tests/v1_data.json")?;
    let v1_upgraded = VersionedData {
        version: 3,
        name: v1_loaded.name,
        value: v1_loaded.value,
        optional_field: Some("migrated_default".to_string()),
        new_field: Some(0),
    };

    v1_upgraded.save_json("temp_schema_tests/v1_migrated.json")?;
    println!("  ✓ V1 data migrated to V3 format");

    Ok(())
}

/// Demonstrate recovery strategies
fn demonstrate_recovery_strategies() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Recovery Strategies ---");

    fs::create_dir_all("temp_recovery_tests")?;

    // Strategy 1: Graceful degradation
    println!("1. Graceful Degradation Strategy:");

    // Create complete data
    let complete_data = RecoverableData {
        critical_field: "essential_info".to_string(),
        important_field: Some("important_info".to_string()),
        optional_field: Some("nice_to_have".to_string()),
        metadata: {
            let mut map = HashMap::new();
            map.insert("key1".to_string(), "value1".to_string());
            map.insert("key2".to_string(), "value2".to_string());
            map
        },
    };

    // Save complete data
    complete_data.save_json("temp_recovery_tests/complete.json")?;

    // Create partial data (missing some fields)
    let partial_json = r#"{
        "critical_field": "essential_info",
        "optional_field": "nice_to_have"
    }"#;
    fs::write("temp_recovery_tests/partial.json", partial_json)?;

    // Load partial data and demonstrate recovery
    match RecoverableData::load_json("temp_recovery_tests/partial.json") {
        Ok(recovered) => {
            println!("  ✓ Partial data recovered successfully:");
            println!("    Critical field: {}", recovered.critical_field);
            println!(
                "    Important field: {:?} (missing, set to None)",
                recovered.important_field
            );
            println!("    Optional field: {:?}", recovered.optional_field);
            println!(
                "    Metadata: {} entries (defaulted to empty)",
                recovered.metadata.len()
            );
        }
        Err(e) => println!("  ✗ Recovery failed: {}", e),
    }

    // Strategy 2: Error context preservation
    println!("\n2. Error Context Preservation:");

    let malformed_json = r#"{
        "critical_field": "essential_info",
        "important_field": 12345,
        "metadata": "not_a_map"
    }"#;
    fs::write("temp_recovery_tests/malformed.json", malformed_json)?;

    match RecoverableData::load_json("temp_recovery_tests/malformed.json") {
        Ok(_) => println!("  ✗ Unexpected: Malformed data was accepted"),
        Err(e) => {
            println!("  ✓ Error context preserved:");
            println!("    Error: {}", e);
            println!("    Error type: {:?}", std::mem::discriminant(&e));
        }
    }

    // Strategy 3: Fallback data sources
    println!("\n3. Fallback Data Sources:");

    // Primary source (corrupted)
    let corrupted_primary = "corrupted data";
    fs::write("temp_recovery_tests/primary.json", corrupted_primary)?;

    // Backup source (valid)
    let backup_data = RecoverableData {
        critical_field: "backup_critical".to_string(),
        important_field: Some("backup_important".to_string()),
        optional_field: None,
        metadata: HashMap::new(),
    };
    backup_data.save_json("temp_recovery_tests/backup.json")?;

    // Default fallback
    let default_data = RecoverableData {
        critical_field: "default_critical".to_string(),
        important_field: None,
        optional_field: None,
        metadata: HashMap::new(),
    };

    println!("  Attempting to load data with fallback chain:");

    // Try primary source
    let loaded_data = match RecoverableData::load_json("temp_recovery_tests/primary.json") {
        Ok(data) => {
            println!("    ✓ Loaded from primary source");
            data
        }
        Err(_) => {
            println!("    ✗ Primary source failed, trying backup");

            // Try backup source
            match RecoverableData::load_json("temp_recovery_tests/backup.json") {
                Ok(data) => {
                    println!("    ✓ Loaded from backup source");
                    data
                }
                Err(_) => {
                    println!("    ✗ Backup source failed, using default");
                    default_data
                }
            }
        }
    };

    println!("  Final loaded data:");
    println!("    Critical field: {}", loaded_data.critical_field);

    Ok(())
}

/// Demonstrate production-ready error handling
fn demonstrate_production_error_handling() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Production Error Handling ---");

    fs::create_dir_all("temp_production_tests")?;

    // Error logging and monitoring
    println!("1. Error Logging and Monitoring:");

    let test_data = VersionedData {
        version: 2,
        name: "production_test".to_string(),
        value: 42.0,
        optional_field: Some("test".to_string()),
        new_field: None,
    };

    // Create error log for demonstration
    let mut error_log = fs::OpenOptions::new()
        .create(true)
        .append(true)
        .open("temp_production_tests/error.log")?;

    // Function to log errors in production format
    let mut log_error =
        |error: &SerializationError, context: &str| -> Result<(), Box<dyn std::error::Error>> {
            let timestamp = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)?
                .as_secs();

            writeln!(error_log, "[{}] ERROR in {}: {}", timestamp, context, error)?;
            Ok(())
        };

    // Simulate various error scenarios with logging
    let error_scenarios = vec![
        ("corrupted_file.json", "invalid json content"),
        ("missing_fields.json", r#"{"version": 1}"#),
        (
            "type_error.json",
            r#"{"version": "not_number", "name": "test", "value": 42.0}"#,
        ),
    ];

    for (filename, content) in error_scenarios {
        let filepath = format!("temp_production_tests/{}", filename);
        fs::write(&filepath, content)?;

        match VersionedData::load_json(&filepath) {
            Ok(_) => println!("  ✗ Unexpected success for {}", filename),
            Err(e) => {
                log_error(&e, &format!("load_config({})", filename))?;
                println!("  ✓ Error logged for {}: {}", filename, e);
            }
        }
    }

    // Health check pattern
    println!("\n2. Health Check Pattern:");

    let health_check = || -> Result<bool, SerializationError> {
        // Check if we can serialize/deserialize basic data
        let test_data = VersionedData {
            version: 1,
            name: "health_check".to_string(),
            value: 1.0,
            optional_field: None,
            new_field: None,
        };

        let serialized = test_data.to_json()?;
        let _deserialized = VersionedData::from_json(&serialized)?;
        Ok(true)
    };

    match health_check() {
        Ok(_) => println!("  ✓ Serialization system health check passed"),
        Err(e) => {
            log_error(&e, "health_check")?;
            println!("  ✗ Serialization system health check failed: {}", e);
        }
    }

    // Circuit breaker pattern simulation
    println!("\n3. Circuit Breaker Pattern:");

    struct CircuitBreaker {
        failure_count: u32,
        failure_threshold: u32,
        is_open: bool,
    }

    impl CircuitBreaker {
        fn new(threshold: u32) -> Self {
            Self {
                failure_count: 0,
                failure_threshold: threshold,
                is_open: false,
            }
        }

        fn call<F, T>(&mut self, operation: F) -> Result<T, String>
        where
            F: FnOnce() -> Result<T, SerializationError>,
        {
            if self.is_open {
                return Err("Circuit breaker is open".to_string());
            }

            match operation() {
                Ok(result) => {
                    self.failure_count = 0; // Reset on success
                    Ok(result)
                }
                Err(e) => {
                    self.failure_count += 1;
                    if self.failure_count >= self.failure_threshold {
                        self.is_open = true;
                        println!(
                            "    Circuit breaker opened after {} failures",
                            self.failure_count
                        );
                    }
                    Err(e.to_string())
                }
            }
        }
    }

    let mut circuit_breaker = CircuitBreaker::new(3);

    // Simulate operations that fail
    for i in 1..=5 {
        let result = circuit_breaker
            .call(|| VersionedData::load_json("temp_production_tests/corrupted_file.json"));

        match result {
            Ok(_) => println!("  Operation {} succeeded", i),
            Err(e) => println!("  Operation {} failed: {}", i, e),
        }
    }

    // Retry mechanism
    println!("\n4. Retry Mechanism:");

    let retry_operation = |max_attempts: u32| -> Result<VersionedData, String> {
        for attempt in 1..=max_attempts {
            println!("    Attempt {}/{}", attempt, max_attempts);

            // Try different sources in order
            let sources = vec![
                "temp_production_tests/corrupted_file.json",
                "temp_production_tests/missing_fields.json",
                "temp_production_tests/backup_valid.json",
            ];

            if attempt == max_attempts {
                // On final attempt, create valid backup
                test_data
                    .save_json("temp_production_tests/backup_valid.json")
                    .map_err(|e| format!("Failed to create backup: {}", e))?;
            }

            for source in &sources {
                match VersionedData::load_json(source) {
                    Ok(data) => {
                        println!("    ✓ Succeeded loading from {}", source);
                        return Ok(data);
                    }
                    Err(_) => {
                        println!("    ✗ Failed to load from {}", source);
                        continue;
                    }
                }
            }

            if attempt < max_attempts {
                println!("    Waiting before retry...");
                // In real code, would sleep here
            }
        }

        Err("All retry attempts exhausted".to_string())
    };

    match retry_operation(3) {
        Ok(data) => println!("  ✓ Retry succeeded: {}", data.name),
        Err(e) => println!("  ✗ Retry failed: {}", e),
    }

    Ok(())
}

examples/serialization/json_vs_binary.rs (line 79)

    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,
        })
    }
}

impl ToFieldValue for Configuration {
    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 Configuration {
    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 Configuration 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 Configuration from binary: {}", e),
                }
            });
        }

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

/// Format comparison results
#[derive(Debug)]
pub struct FormatComparison {
    pub data_type: String,
    pub json_size_bytes: u64,
    pub binary_size_bytes: u64,
    pub json_serialize_micros: u64,
    pub binary_serialize_micros: u64,
    pub json_deserialize_micros: u64,
    pub binary_deserialize_micros: u64,
    pub size_ratio: f64,
    pub serialize_speed_ratio: f64,
    pub deserialize_speed_ratio: f64,
}

impl FormatComparison {
    fn new(data_type: String) -> Self {
        Self {
            data_type,
            json_size_bytes: 0,
            binary_size_bytes: 0,
            json_serialize_micros: 0,
            binary_serialize_micros: 0,
            json_deserialize_micros: 0,
            binary_deserialize_micros: 0,
            size_ratio: 0.0,
            serialize_speed_ratio: 0.0,
            deserialize_speed_ratio: 0.0,
        }
    }

    fn calculate_ratios(&mut self) {
        self.size_ratio = self.json_size_bytes as f64 / self.binary_size_bytes as f64;
        self.serialize_speed_ratio =
            self.binary_serialize_micros as f64 / self.json_serialize_micros as f64;
        self.deserialize_speed_ratio =
            self.binary_deserialize_micros as f64 / self.json_deserialize_micros as f64;
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== JSON vs Binary Format Comparison Example ===\n");

    demonstrate_format_characteristics()?;
    demonstrate_size_comparisons()?;
    demonstrate_performance_benchmarks()?;
    demonstrate_use_case_recommendations()?;
    demonstrate_debugging_capabilities()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate basic format characteristics
fn demonstrate_format_characteristics() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Format Characteristics ---");

    // Create sample data structures
    let mut metadata = HashMap::new();
    metadata.insert("operation_type".to_string(), "benchmark".to_string());
    metadata.insert("system".to_string(), "train_station".to_string());

    let metrics = PerformanceMetrics {
        operation: "tensor_multiplication".to_string(),
        duration_micros: 1234,
        memory_usage_bytes: 8192,
        cpu_usage_percent: 75.5,
        throughput_ops_per_sec: 1000.0,
        metadata,
    };

    println!("Format characteristics analysis:");

    // JSON characteristics
    let json_data = metrics.to_json()?;
    let json_lines = json_data.lines().count();
    let json_chars = json_data.chars().count();

    println!("\nJSON Format:");
    println!("  Size: {} bytes", json_data.len());
    println!("  Characters: {}", json_chars);
    println!("  Lines: {}", json_lines);
    println!("  Human readable: Yes");
    println!("  Self-describing: Yes");
    println!("  Cross-platform: Yes");
    println!("  Compression ratio: Variable (depends on content)");

    // Show sample JSON output
    println!("  Sample output:");
    for line in json_data.lines().take(3) {
        println!("    {}", line);
    }
    if json_lines > 3 {
        println!("    ... ({} more lines)", json_lines - 3);
    }

    // Binary characteristics
    let binary_data = metrics.to_binary()?;

    println!("\nBinary Format:");
    println!("  Size: {} bytes", binary_data.len());
    println!("  Human readable: No");
    println!("  Self-describing: No (requires schema)");
    println!("  Cross-platform: Yes (with proper endianness handling)");
    println!("  Compression ratio: High (efficient encoding)");

    // Show sample binary output (hex)
    println!("  Sample output (first 32 bytes as hex):");
    print!("    ");
    for (i, byte) in binary_data.iter().take(32).enumerate() {
        if i > 0 && i % 16 == 0 {
            println!();
            print!("    ");
        }
        print!("{:02x} ", byte);
    }
    if binary_data.len() > 32 {
        println!("\n    ... ({} more bytes)", binary_data.len() - 32);
    } else {
        println!();
    }

    // Verify roundtrip for both formats
    let json_parsed = PerformanceMetrics::from_json(&json_data)?;
    let binary_parsed = PerformanceMetrics::from_binary(&binary_data)?;

    assert_eq!(metrics, json_parsed);
    assert_eq!(metrics, binary_parsed);
    println!("\nRoundtrip verification: PASSED");

    Ok(())
}

/// Demonstrate size comparisons across different data types
fn demonstrate_size_comparisons() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Size Comparison Analysis ---");

    // Test 1: Small configuration data (typical JSON use case)
    let mut db_settings = HashMap::new();
    db_settings.insert("host".to_string(), "localhost".to_string());
    db_settings.insert("port".to_string(), "5432".to_string());
    db_settings.insert("database".to_string(), "myapp".to_string());

    let config = Configuration {
        version: "1.2.3".to_string(),
        debug_enabled: true,
        log_level: "info".to_string(),
        database_settings: db_settings,
        feature_flags_enabled: true,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    // Test 2: Large numeric dataset (typical binary use case)
    let large_dataset = LargeDataset {
        name: "ML Training Data".to_string(),
        values: (0..1000).map(|i| i as f32 * 0.1).collect(),
        labels: (0..1000).map(|i| format!("label_{}", i)).collect(),
        feature_count: 100,
        feature_dimension: 50,
        timestamp_count: 1000,
        metadata: HashMap::new(),
    };

    println!("Size comparison results:");

    // Configuration comparison
    let config_json = config.to_json()?;
    let config_binary = config.to_binary()?;

    println!("\nConfiguration Data (small, text-heavy):");
    println!("  JSON: {} bytes", config_json.len());
    println!("  Binary: {} bytes", config_binary.len());
    println!(
        "  Ratio (JSON/Binary): {:.2}x",
        config_json.len() as f64 / config_binary.len() as f64
    );
    println!("  Recommendation: JSON (human readable, small size difference)");

    // Large dataset comparison
    let dataset_json = large_dataset.to_json()?;
    let dataset_binary = large_dataset.to_binary()?;

    println!("\nLarge Numeric Dataset (1000 values, 100x50 matrix):");
    println!(
        "  JSON: {} bytes ({:.1} KB)",
        dataset_json.len(),
        dataset_json.len() as f64 / 1024.0
    );
    println!(
        "  Binary: {} bytes ({:.1} KB)",
        dataset_binary.len(),
        dataset_binary.len() as f64 / 1024.0
    );
    println!(
        "  Ratio (JSON/Binary): {:.2}x",
        dataset_json.len() as f64 / dataset_binary.len() as f64
    );
    if dataset_json.len() > dataset_binary.len() {
        println!(
            "  Space saved with binary: {} bytes ({:.1} KB)",
            dataset_json.len() - dataset_binary.len(),
            (dataset_json.len() - dataset_binary.len()) as f64 / 1024.0
        );
        println!("  Recommendation: Binary (significant size reduction)");
    } else {
        println!(
            "  Binary overhead: {} bytes ({:.1} KB)",
            dataset_binary.len() - dataset_json.len(),
            (dataset_binary.len() - dataset_json.len()) as f64 / 1024.0
        );
        println!("  Recommendation: JSON (binary overhead not justified for this size)");
    }

    // Content analysis
    println!("\nContent Type Analysis:");

    // Analyze JSON content patterns
    let json_numbers = dataset_json.matches(char::is_numeric).count();
    let json_brackets = dataset_json.matches('[').count() + dataset_json.matches(']').count();
    let json_quotes = dataset_json.matches('"').count();

    println!("  JSON overhead sources:");
    println!("    Numeric characters: ~{}", json_numbers);
    println!("    Brackets and commas: ~{}", json_brackets);
    println!("    Quote marks: {}", json_quotes);
    println!("    Formatting/whitespace: Varies");

    println!("  Binary advantages:");
    println!("    Direct numeric encoding: 4-8 bytes per number");
    println!("    No formatting overhead: Zero bytes");
    println!("    Efficient length encoding: Minimal bytes");

    Ok(())
}

/// Demonstrate performance benchmarks
fn demonstrate_performance_benchmarks() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Performance Benchmark Analysis ---");

    // Create test data of varying sizes
    let small_config = Configuration {
        version: "1.0.0".to_string(),
        debug_enabled: false,
        log_level: "warn".to_string(),
        database_settings: HashMap::new(),
        feature_flags_enabled: false,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    let large_dataset = LargeDataset {
        name: "Large Dataset".to_string(),
        values: (0..5000).map(|i| i as f32 * 0.001).collect(),
        labels: (0..5000).map(|i| format!("large_item_{}", i)).collect(),
        feature_count: 200,
        feature_dimension: 25,
        timestamp_count: 5000,
        metadata: HashMap::new(),
    };

    println!("Performance benchmark results:");

    // Benchmark each dataset (avoiding trait objects due to object safety)
    let dataset_names = ["Small Config", "Large Dataset"];

    for (i, name) in dataset_names.iter().enumerate() {
        let mut comparison = FormatComparison::new(name.to_string());

        // JSON serialization benchmark
        let start = Instant::now();
        let json_data = match i {
            0 => small_config.to_json()?,
            _ => large_dataset.to_json()?,
        };
        comparison.json_serialize_micros = start.elapsed().as_micros() as u64;
        comparison.json_size_bytes = json_data.len() as u64;

        // JSON deserialization benchmark (using PerformanceMetrics as example)
        if *name == "Small Config" {
            let start = Instant::now();
            let _parsed = Configuration::from_json(&json_data)?;
            comparison.json_deserialize_micros = start.elapsed().as_micros() as u64;
        } else {
            let start = Instant::now();
            let _parsed = LargeDataset::from_json(&json_data)?;
            comparison.json_deserialize_micros = start.elapsed().as_micros() as u64;
        }

        // Binary serialization benchmark
        let start = Instant::now();
        let binary_data = match i {
            0 => small_config.to_binary()?,
            _ => large_dataset.to_binary()?,
        };
        comparison.binary_serialize_micros = start.elapsed().as_micros() as u64;
        comparison.binary_size_bytes = binary_data.len() as u64;

        // Binary deserialization benchmark
        if *name == "Small Config" {
            let start = Instant::now();
            let _parsed = Configuration::from_binary(&binary_data)?;
            comparison.binary_deserialize_micros = start.elapsed().as_micros() as u64;
        } else {
            let start = Instant::now();
            let _parsed = LargeDataset::from_binary(&binary_data)?;
            comparison.binary_deserialize_micros = start.elapsed().as_micros() as u64;
        }

        // Calculate ratios
        comparison.calculate_ratios();

        // Display results
        println!("\n{}:", name);
        println!(
            "  Size - JSON: {} bytes, Binary: {} bytes (ratio: {:.2}x)",
            comparison.json_size_bytes, comparison.binary_size_bytes, comparison.size_ratio
        );
        println!(
            "  Serialize - JSON: {}μs, Binary: {}μs (binary relative speed: {:.2}x)",
            comparison.json_serialize_micros,
            comparison.binary_serialize_micros,
            comparison.serialize_speed_ratio
        );
        println!(
            "  Deserialize - JSON: {}μs, Binary: {}μs (binary relative speed: {:.2}x)",
            comparison.json_deserialize_micros,
            comparison.binary_deserialize_micros,
            comparison.deserialize_speed_ratio
        );
    }

    println!("\nPerformance Summary:");
    println!("  - Binary format consistently uses less storage space");
    println!("  - Performance differences vary by data type and size");
    println!("  - Larger datasets show more significant binary advantages");
    println!("  - JSON parsing overhead increases with structure complexity");

    Ok(())
}

/// Demonstrate use case recommendations
fn demonstrate_use_case_recommendations() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Use Case Recommendations ---");

    println!("JSON Format - Recommended for:");
    println!("  ✓ Configuration files (human-editable)");
    println!("  ✓ API responses (web compatibility)");
    println!("  ✓ Debugging and development (readability)");
    println!("  ✓ Small data structures (minimal overhead)");
    println!("  ✓ Cross-language interoperability");
    println!("  ✓ Schema evolution (self-describing)");
    println!("  ✓ Text-heavy data with few numbers");

    println!("\nBinary Format - Recommended for:");
    println!("  ✓ Large datasets (memory/storage efficiency)");
    println!("  ✓ High-performance applications (speed critical)");
    println!("  ✓ Numeric-heavy data (ML models, matrices)");
    println!("  ✓ Network transmission (bandwidth limited)");
    println!("  ✓ Embedded systems (resource constrained)");
    println!("  ✓ Long-term storage (space efficiency)");
    println!("  ✓ Frequent serialization/deserialization");

    // Demonstrate decision matrix
    println!("\nDecision Matrix Example:");

    let scenarios = vec![
        (
            "Web API Configuration",
            "JSON",
            "Human readable, web standard, small size",
        ),
        (
            "ML Model Weights",
            "Binary",
            "Large numeric data, performance critical",
        ),
        (
            "User Preferences",
            "JSON",
            "Human editable, self-documenting",
        ),
        (
            "Real-time Telemetry",
            "Binary",
            "High frequency, bandwidth limited",
        ),
        (
            "Application Settings",
            "JSON",
            "Developer accessible, version control friendly",
        ),
        (
            "Scientific Dataset",
            "Binary",
            "Large arrays, storage efficiency critical",
        ),
    ];

    for (scenario, recommendation, reason) in scenarios {
        println!("  {} -> {} ({})", scenario, recommendation, reason);
    }

    // Create examples for common scenarios
    println!("\nPractical Examples:");

    // Configuration file example (JSON)
    let config = Configuration {
        version: "2.1.0".to_string(),
        debug_enabled: false,
        log_level: "info".to_string(),
        database_settings: {
            let mut map = HashMap::new();
            map.insert("url".to_string(), "postgresql://localhost/app".to_string());
            map.insert("pool_size".to_string(), "10".to_string());
            map
        },
        feature_flags_enabled: true,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    config.save_json("temp_config_example.json")?;
    let config_content = fs::read_to_string("temp_config_example.json")?;

    println!("\nConfiguration File (JSON) - Human readable:");
    for line in config_content.lines().take(5) {
        println!("  {}", line);
    }
    println!("  ... (easily editable by developers)");

    // Data export example (Binary)
    let export_data = LargeDataset {
        name: "Training Export".to_string(),
        values: (0..1000).map(|i| (i as f32).sin()).collect(),
        labels: (0..1000).map(|i| format!("sample_{:04}", i)).collect(),
        feature_count: 50,
        feature_dimension: 20,
        timestamp_count: 1000,
        metadata: HashMap::new(),
    };

    export_data.save_binary("temp_export_example.bin")?;
    let export_size = fs::metadata("temp_export_example.bin")?.len();

    println!("\nData Export (Binary) - Efficient storage:");
    println!(
        "  File size: {} bytes ({:.1} KB)",
        export_size,
        export_size as f64 / 1024.0
    );
    println!("  1000 numeric values + 50x20 matrix + metadata");
    println!("  Compact encoding saves significant space vs JSON");

    Ok(())
}

/// Demonstrate debugging capabilities
fn demonstrate_debugging_capabilities() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Debugging Capabilities ---");

    let mut metadata = HashMap::new();
    metadata.insert("debug_session".to_string(), "session_123".to_string());
    metadata.insert("error_code".to_string(), "E001".to_string());

    let debug_metrics = PerformanceMetrics {
        operation: "debug_test".to_string(),
        duration_micros: 5432,
        memory_usage_bytes: 16384,
        cpu_usage_percent: 42.7,
        throughput_ops_per_sec: 750.0,
        metadata,
    };

    println!("Debugging Comparison:");

    // JSON debugging advantages
    let json_data = debug_metrics.to_json()?;
    println!("\nJSON Format - Debugging Advantages:");
    println!("  ✓ Human readable without tools");
    println!("  ✓ Can inspect values directly");
    println!("  ✓ Text editors show structure");
    println!("  ✓ Diff tools work naturally");
    println!("  ✓ Version control friendly");

    println!("\n  Sample JSON output for debugging:");
    for (i, line) in json_data.lines().enumerate() {
        if i < 5 {
            println!("    {}", line);
        }
    }

    // Binary debugging limitations
    let binary_data = debug_metrics.to_binary()?;
    println!("\nBinary Format - Debugging Limitations:");
    println!("  ✗ Requires special tools to inspect");
    println!("  ✗ Not human readable");
    println!("  ✗ Difficult to debug data corruption");
    println!("  ✗ Version control shows as binary diff");

    println!("\n  Binary data (hex dump for debugging):");
    print!("    ");
    for (i, byte) in binary_data.iter().take(40).enumerate() {
        if i > 0 && i % 16 == 0 {
            println!();
            print!("    ");
        }
        print!("{:02x} ", byte);
    }
    println!("\n    (requires hex editor or custom tools)");

    // Development workflow comparison
    println!("\nDevelopment Workflow Impact:");

    println!("\nJSON Workflow:");
    println!("  1. Save data to JSON file");
    println!("  2. Open in any text editor");
    println!("  3. Inspect values directly");
    println!("  4. Make manual edits if needed");
    println!("  5. Version control tracks changes");

    println!("\nBinary Workflow:");
    println!("  1. Save data to binary file");
    println!("  2. Write debugging code to load and print");
    println!("  3. Use hex editor for low-level inspection");
    println!("  4. Cannot make manual edits easily");
    println!("  5. Version control shows binary changes only");

    // Hybrid approach recommendation
    println!("\nHybrid Approach for Development:");
    println!("  - Use JSON during development/debugging");
    println!("  - Switch to binary for production deployment");
    println!("  - Provide debugging tools that export binary to JSON");
    println!("  - Include format conversion utilities");

    // Demonstrate debugging scenario
    println!("\nDebugging Scenario Example:");
    println!("  Problem: Performance metrics show unexpected values");

    // Save both formats for comparison
    debug_metrics.save_json("temp_debug_metrics.json")?;
    debug_metrics.save_binary("temp_debug_metrics.bin")?;

    println!("  JSON approach: Open temp_debug_metrics.json in editor");
    println!("    -> Immediately see cpu_usage_percent: 42.7");
    println!("    -> Compare with expected range");
    println!("    -> Check metadata for debug_session: 'session_123'");

    println!("  Binary approach: Write debugging code");
    println!("    -> Load binary file programmatically");
    println!("    -> Print values to console");
    println!("    -> Additional development time required");

    Ok(())
}

examples/serialization/nested_structures.rs (line 75)

    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,
        })
    }
}

impl ToFieldValue for Department {
    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 Department {
    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 Department 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 Department from binary: {}", e),
                }
            });
        }

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Nested Structures Serialization Example ===\n");

    demonstrate_nested_struct_creation()?;
    demonstrate_deep_serialization()?;
    demonstrate_collection_nesting()?;
    demonstrate_partial_loading()?;
    demonstrate_performance_analysis()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate creating complex nested structures
fn demonstrate_nested_struct_creation() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Nested Structure Creation ---");

    // Create nested address and contact info
    let headquarters = Address {
        street: "123 Innovation Drive".to_string(),
        city: "Tech City".to_string(),
        state: "CA".to_string(),
        postal_code: "94000".to_string(),
        country: "USA".to_string(),
    };

    let mut social_media = HashMap::new();
    social_media.insert("twitter".to_string(), "@techcorp".to_string());
    social_media.insert("linkedin".to_string(), "techcorp-inc".to_string());

    let contact_info = ContactInfo {
        email: "info@techcorp.com".to_string(),
        phone: Some("+1-555-0123".to_string()),
        address_city: headquarters.city.clone(),
        address_state: headquarters.state.clone(),
        social_media,
    };

    // Create departments with nested office locations
    let engineering_office = Address {
        street: "456 Developer Lane".to_string(),
        city: "Code City".to_string(),
        state: "CA".to_string(),
        postal_code: "94001".to_string(),
        country: "USA".to_string(),
    };

    let departments = [
        Department {
            name: "Engineering".to_string(),
            manager: "Alice Johnson".to_string(),
            employee_count: 50,
            budget: 2500000.0,
            office_locations: vec![engineering_office, headquarters.clone()],
        },
        Department {
            name: "Marketing".to_string(),
            manager: "Bob Smith".to_string(),
            employee_count: 15,
            budget: 800000.0,
            office_locations: vec![headquarters.clone()],
        },
    ];

    // Create projects with milestones
    let milestones = vec![
        Milestone {
            name: "Requirements Analysis".to_string(),
            description: "Complete system requirements documentation".to_string(),
            due_date: "2024-03-15".to_string(),
            is_completed: true,
            progress_percentage: 100.0,
            dependencies: vec![],
        },
        Milestone {
            name: "Architecture Design".to_string(),
            description: "Define system architecture and components".to_string(),
            due_date: "2024-04-01".to_string(),
            is_completed: false,
            progress_percentage: 75.0,
            dependencies: vec!["Requirements Analysis".to_string()],
        },
    ];

    let mut project_metadata = HashMap::new();
    project_metadata.insert("priority".to_string(), "high".to_string());
    project_metadata.insert("client".to_string(), "internal".to_string());

    let projects = [Project {
        name: "Train Station ML Platform".to_string(),
        description: "Next-generation machine learning infrastructure".to_string(),
        status: ProjectStatus::InProgress,
        budget: 1500000.0,
        team_members: vec![
            "Alice Johnson".to_string(),
            "Charlie Brown".to_string(),
            "Diana Prince".to_string(),
        ],
        milestones: milestones.clone(),
        metadata: project_metadata,
    }];

    // Create the complete company structure
    let mut company_metadata = HashMap::new();
    company_metadata.insert("industry".to_string(), "technology".to_string());
    company_metadata.insert("stock_symbol".to_string(), "TECH".to_string());

    let company = Company {
        name: "TechCorp Inc.".to_string(),
        founded_year: 2015,
        headquarters_city: headquarters.city.clone(),
        headquarters_state: headquarters.state.clone(),
        employee_count: 250,
        department_names: departments.iter().map(|d| d.name.clone()).collect(),
        active_project_names: projects.iter().map(|p| p.name.clone()).collect(),
        company_metadata,
    };

    println!("Created complex company structure:");
    println!("  Company: {}", company.name);
    println!("  Founded: {}", company.founded_year);
    println!(
        "  Headquarters: {}, {}",
        company.headquarters_city, company.headquarters_state
    );
    println!("  Employee Count: {}", company.employee_count);
    println!("  Departments: {}", company.department_names.len());
    println!("  Active Projects: {}", company.active_project_names.len());

    // Save the complete structure
    company.save_json("temp_nested_company.json")?;
    println!("Saved nested structure to: temp_nested_company.json");

    // Verify loading preserves all nested data
    let loaded_company = Company::load_json("temp_nested_company.json")?;
    assert_eq!(company, loaded_company);
    println!("Successfully verified Company roundtrip serialization");

    // Also demonstrate individual component serialization
    let address_json = headquarters.to_json()?;
    let loaded_address = Address::from_json(&address_json)?;
    assert_eq!(headquarters, loaded_address);
    println!("Successfully serialized/deserialized Address component");

    let contact_json = contact_info.to_json()?;
    let loaded_contact = ContactInfo::from_json(&contact_json)?;
    assert_eq!(contact_info, loaded_contact);
    println!("Successfully serialized/deserialized ContactInfo component");
    println!("Nested structure integrity: VERIFIED");

    Ok(())
}

/// Demonstrate deep serialization with complex nesting
fn demonstrate_deep_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Deep Serialization Analysis ---");

    let deep_milestone = Milestone {
        name: "Deep Milestone".to_string(),
        description: "Testing deep nesting serialization".to_string(),
        due_date: "2024-12-31".to_string(),
        is_completed: false,
        progress_percentage: 50.0,
        dependencies: vec!["Parent Task".to_string(), "Sibling Task".to_string()],
    };

    let deep_project = Project {
        name: "Deep Nesting Test".to_string(),
        description: "Project for testing serialization depth".to_string(),
        status: ProjectStatus::Planning,
        budget: 100000.0,
        team_members: vec!["Developer 1".to_string(), "Developer 2".to_string()],
        milestones: vec![deep_milestone],
        metadata: HashMap::new(),
    };

    // Analyze serialization output
    let json_output = deep_project.to_json()?;
    let binary_output = deep_project.to_binary()?;

    println!("Deep structure serialization analysis:");
    println!("  JSON size: {} bytes", json_output.len());
    println!("  Binary size: {} bytes", binary_output.len());
    println!("  Nesting levels: Address -> Project -> Milestone -> Dependencies");

    // Count nested objects in JSON (rough estimate)
    let object_count = json_output.matches('{').count();
    let array_count = json_output.matches('[').count();
    println!("  JSON objects: {}", object_count);
    println!("  JSON arrays: {}", array_count);

    // Verify deep roundtrip
    let json_parsed = Project::from_json(&json_output)?;
    let binary_parsed = Project::from_binary(&binary_output)?;

    assert_eq!(deep_project, json_parsed);
    assert_eq!(deep_project, binary_parsed);
    println!("Deep serialization roundtrip: VERIFIED");

    Ok(())
}

/// Demonstrate collection nesting patterns
fn demonstrate_collection_nesting() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Collection Nesting Patterns ---");

    // Create multiple departments with varying complexity
    let departments = vec![
        Department {
            name: "Research".to_string(),
            manager: "Dr. Science".to_string(),
            employee_count: 25,
            budget: 1200000.0,
            office_locations: vec![
                Address {
                    street: "1 Research Blvd".to_string(),
                    city: "Innovation Hub".to_string(),
                    state: "MA".to_string(),
                    postal_code: "02101".to_string(),
                    country: "USA".to_string(),
                },
                Address {
                    street: "2 Lab Street".to_string(),
                    city: "Tech Valley".to_string(),
                    state: "NY".to_string(),
                    postal_code: "12180".to_string(),
                    country: "USA".to_string(),
                },
            ],
        },
        Department {
            name: "Quality Assurance".to_string(),
            manager: "Test Master".to_string(),
            employee_count: 12,
            budget: 600000.0,
            office_locations: vec![], // Empty collection
        },
    ];

    println!("Collection nesting analysis:");
    println!("  Departments: {}", departments.len());

    let total_locations: usize = departments.iter().map(|d| d.office_locations.len()).sum();
    println!("  Total office locations: {}", total_locations);

    // Test serialization with mixed empty and populated collections
    // Note: Vec<Department> doesn't implement StructSerializable directly.
    // For this example, we'll serialize each department individually
    let department_json_strings: Result<Vec<String>, _> =
        departments.iter().map(|dept| dept.to_json()).collect();
    let department_json_strings = department_json_strings?;

    // Deserialize each department back
    let parsed_departments: Result<Vec<Department>, _> = department_json_strings
        .iter()
        .map(|json_str| Department::from_json(json_str))
        .collect();
    let parsed_departments = parsed_departments?;

    assert_eq!(departments, parsed_departments);
    println!("Collection nesting serialization: VERIFIED");

    // Analyze collection patterns
    for (i, dept) in departments.iter().enumerate() {
        println!(
            "  Department {}: {} locations",
            i + 1,
            dept.office_locations.len()
        );
    }

    Ok(())
}

/// Demonstrate partial loading and field access
fn demonstrate_partial_loading() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Partial Loading and Field Access ---");

    // Create a simple project for analysis
    let project = Project {
        name: "Sample Project".to_string(),
        description: "For testing partial loading".to_string(),
        status: ProjectStatus::InProgress,
        budget: 50000.0,
        team_members: vec!["Alice".to_string(), "Bob".to_string()],
        milestones: vec![Milestone {
            name: "Phase 1".to_string(),
            description: "Initial phase".to_string(),
            due_date: "2024-06-01".to_string(),
            is_completed: true,
            progress_percentage: 100.0,
            dependencies: vec![],
        }],
        metadata: HashMap::new(),
    };

    // Convert to JSON and analyze structure
    println!("Project JSON structure analysis:");

    // Parse to examine available fields by inspecting JSON structure
    let json_data = project.to_json()?;
    let field_count = json_data.matches(':').count();
    println!("  Estimated fields: {}", field_count);

    // Show top-level structure
    let lines: Vec<&str> = json_data.lines().take(10).collect();
    println!("  JSON structure preview:");
    for line in lines.iter().take(5) {
        if let Some(colon_pos) = line.find(':') {
            let field_name = line[..colon_pos].trim().trim_matches('"').trim();
            if !field_name.is_empty() {
                println!("    - {}", field_name);
            }
        }
    }

    // Demonstrate field type analysis
    println!("\nField type analysis:");
    println!("  name: String");
    println!("  status: Enum -> String");
    println!("  budget: f64 -> Number");
    println!("  team_members: Vec<String> -> Array");
    println!("  milestones: Vec<Milestone> -> Array of Objects");

    Ok(())
}

/// Demonstrate performance analysis for nested structures
fn demonstrate_performance_analysis() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Performance Analysis ---");

    // Create structures of varying complexity
    let simple_address = Address {
        street: "123 Main St".to_string(),
        city: "Anytown".to_string(),
        state: "ST".to_string(),
        postal_code: "12345".to_string(),
        country: "USA".to_string(),
    };

    let complex_department = Department {
        name: "Complex Department".to_string(),
        manager: "Manager Name".to_string(),
        employee_count: 100,
        budget: 5000000.0,
        office_locations: vec![simple_address.clone(); 10], // 10 identical addresses
    };

    let complex_project = Project {
        name: "Complex Project".to_string(),
        description: "Large project with many components".to_string(),
        status: ProjectStatus::InProgress,
        budget: 2000000.0,
        team_members: (1..=50).map(|i| format!("Team Member {}", i)).collect(),
        milestones: (1..=20)
            .map(|i| Milestone {
                name: format!("Milestone {}", i),
                description: format!("Description for milestone {}", i),
                due_date: "2024-12-31".to_string(),
                is_completed: i <= 10,
                progress_percentage: if i <= 10 { 100.0 } else { 50.0 },
                dependencies: if i > 1 {
                    vec![format!("Milestone {}", i - 1)]
                } else {
                    vec![]
                },
            })
            .collect(),
        metadata: HashMap::new(),
    };

    // Measure serialization performance
    println!("Performance comparison:");

    // Simple address
    let addr_json = simple_address.to_json()?;
    let addr_binary = simple_address.to_binary()?;
    println!("  Simple Address:");
    println!("    JSON: {} bytes", addr_json.len());
    println!("    Binary: {} bytes", addr_binary.len());

    // Complex department
    let dept_json = complex_department.to_json()?;
    let dept_binary = complex_department.to_binary()?;
    println!("  Complex Department (10 addresses):");
    println!("    JSON: {} bytes", dept_json.len());
    println!("    Binary: {} bytes", dept_binary.len());

    // Complex project
    let proj_json = complex_project.to_json()?;
    let proj_binary = complex_project.to_binary()?;
    println!("  Complex Project (50 members, 20 milestones):");
    println!("    JSON: {} bytes", proj_json.len());
    println!("    Binary: {} bytes", proj_binary.len());

    // Calculate efficiency ratios
    let dept_ratio = dept_json.len() as f64 / dept_binary.len() as f64;
    let proj_ratio = proj_json.len() as f64 / proj_binary.len() as f64;

    println!("\nFormat efficiency (JSON/Binary ratio):");
    println!("  Department: {:.2}x", dept_ratio);
    println!("  Project: {:.2}x", proj_ratio);

    // Verify complex structure roundtrip
    let proj_json_parsed = Project::from_json(&proj_json)?;
    let proj_binary_parsed = Project::from_binary(&proj_binary)?;

    assert_eq!(complex_project, proj_json_parsed);
    assert_eq!(complex_project, proj_binary_parsed);
    println!("Complex structure roundtrip: VERIFIED");

    Ok(())
}

examples/serialization/basic_structs.rs (line 80)

    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,
        })
    }
}

impl ToFieldValue for AppSettings {
    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) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for AppSettings {
    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 AppSettings 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 AppSettings from binary: {}", e),
                }
            });
        }

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Basic Struct Serialization Example ===\n");

    demonstrate_user_profile_serialization()?;
    demonstrate_app_settings_serialization()?;
    demonstrate_format_comparison()?;
    demonstrate_roundtrip_verification()?;
    demonstrate_field_access_patterns()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate basic struct serialization with simple field types
fn demonstrate_user_profile_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- User Profile Serialization ---");

    // Create a user profile with various field types
    let user = UserProfile {
        id: 12345,
        username: "alice_cooper".to_string(),
        email: "alice@example.com".to_string(),
        age: 28,
        is_active: true,
        score: 95.7,
    };

    println!("Original user profile:");
    println!("  ID: {}", user.id);
    println!("  Username: {}", user.username);
    println!("  Email: {}", user.email);
    println!("  Age: {}", user.age);
    println!("  Active: {}", user.is_active);
    println!("  Score: {}", user.score);

    // Serialize to JSON
    let json_data = user.to_json()?;
    println!("\nSerialized to JSON:");
    println!("{}", json_data);

    // Save to JSON file
    user.save_json("temp_user_profile.json")?;
    println!("Saved to file: temp_user_profile.json");

    // Load from JSON file
    let loaded_user = UserProfile::load_json("temp_user_profile.json")?;
    println!("\nLoaded user profile:");
    println!("  ID: {}", loaded_user.id);
    println!("  Username: {}", loaded_user.username);
    println!("  Email: {}", loaded_user.email);
    println!("  Age: {}", loaded_user.age);
    println!("  Active: {}", loaded_user.is_active);
    println!("  Score: {}", loaded_user.score);

    // Verify data integrity
    assert_eq!(user, loaded_user);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate serialization with collections and optional fields
fn demonstrate_app_settings_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- App Settings Serialization ---");

    // Create app settings with collections and optional fields
    let mut env_vars = HashMap::new();
    env_vars.insert("LOG_LEVEL".to_string(), "info".to_string());
    env_vars.insert("PORT".to_string(), "8080".to_string());
    env_vars.insert("HOST".to_string(), "localhost".to_string());

    let settings = AppSettings {
        app_name: "Train Station Example".to_string(),
        version: "1.0.0".to_string(),
        debug_mode: true,
        max_connections: 100,
        timeout_seconds: 30.5,
        features: vec![
            "authentication".to_string(),
            "logging".to_string(),
            "metrics".to_string(),
        ],
        environment_vars: env_vars,
        optional_database_url: Some("postgresql://localhost:5432/mydb".to_string()),
    };

    println!("Original app settings:");
    println!("  App Name: {}", settings.app_name);
    println!("  Version: {}", settings.version);
    println!("  Debug Mode: {}", settings.debug_mode);
    println!("  Max Connections: {}", settings.max_connections);
    println!("  Timeout: {} seconds", settings.timeout_seconds);
    println!("  Features: {:?}", settings.features);
    println!("  Environment Variables: {:?}", settings.environment_vars);
    println!("  Database URL: {:?}", settings.optional_database_url);

    // Serialize to binary format for efficient storage
    let binary_data = settings.to_binary()?;
    println!("\nSerialized to binary: {} bytes", binary_data.len());

    // Save to binary file
    settings.save_binary("temp_app_settings.bin")?;
    println!("Saved to file: temp_app_settings.bin");

    // Load from binary file
    let loaded_settings = AppSettings::load_binary("temp_app_settings.bin")?;
    println!("\nLoaded app settings:");
    println!("  App Name: {}", loaded_settings.app_name);
    println!("  Version: {}", loaded_settings.version);
    println!("  Debug Mode: {}", loaded_settings.debug_mode);
    println!("  Features count: {}", loaded_settings.features.len());
    println!(
        "  Environment variables count: {}",
        loaded_settings.environment_vars.len()
    );

    // Verify data integrity
    assert_eq!(settings, loaded_settings);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison between JSON and binary
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    let user = UserProfile {
        id: 98765,
        username: "bob_builder".to_string(),
        email: "bob@construction.com".to_string(),
        age: 35,
        is_active: false,
        score: 87.2,
    };

    // Save in both formats
    user.save_json("temp_format_comparison.json")?;
    user.save_binary("temp_format_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_format_comparison.json")?.len();
    let binary_size = fs::metadata("temp_format_comparison.bin")?.len();

    println!("Format comparison for UserProfile:");
    println!("  JSON file size: {} bytes", json_size);
    println!("  Binary file size: {} bytes", binary_size);
    println!(
        "  Size ratio (JSON/Binary): {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Demonstrate readability
    let json_content = fs::read_to_string("temp_format_comparison.json")?;
    println!("\nJSON format (human-readable):");
    println!("{}", json_content);

    println!("\nBinary format (first 32 bytes as hex):");
    let binary_content = fs::read("temp_format_comparison.bin")?;
    for (i, byte) in binary_content.iter().take(32).enumerate() {
        if i % 16 == 0 && i > 0 {
            println!();
        }
        print!("{:02x} ", byte);
    }
    println!("\n... ({} total bytes)", binary_content.len());

    // Load and verify both formats produce identical results
    let json_loaded = UserProfile::load_json("temp_format_comparison.json")?;
    let binary_loaded = UserProfile::load_binary("temp_format_comparison.bin")?;

    assert_eq!(json_loaded, binary_loaded);
    println!("\nFormat consistency verification: PASSED");

    Ok(())
}

/// Demonstrate roundtrip verification with multiple data variations
fn demonstrate_roundtrip_verification() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Roundtrip Verification ---");

    // Test various data patterns
    let test_users = [
        UserProfile {
            id: 0,
            username: "".to_string(),
            email: "empty@test.com".to_string(),
            age: 0,
            is_active: false,
            score: 0.0,
        },
        UserProfile {
            id: u32::MAX,
            username: "maximal_user_with_very_long_name_123456789".to_string(),
            email: "test@verylongdomainname.example.org".to_string(),
            age: i32::MAX,
            is_active: true,
            score: 999999.5,
        },
        UserProfile {
            id: 42,
            username: "unicode_tëst_🦀".to_string(),
            email: "unicode@tëst.com".to_string(),
            age: 25,
            is_active: true,
            score: -123.456,
        },
    ];

    println!(
        "Testing roundtrip serialization with {} variations:",
        test_users.len()
    );

    for (i, user) in test_users.iter().enumerate() {
        println!(
            "  Test case {}: ID={}, Username='{}'",
            i + 1,
            user.id,
            user.username
        );

        // JSON roundtrip
        let json_data = user.to_json()?;
        let json_parsed = UserProfile::from_json(&json_data)?;
        assert_eq!(*user, json_parsed);

        // Binary roundtrip
        let binary_data = user.to_binary()?;
        let binary_parsed = UserProfile::from_binary(&binary_data)?;
        assert_eq!(*user, binary_parsed);

        println!("    JSON roundtrip: PASSED");
        println!("    Binary roundtrip: PASSED");
    }

    println!("All roundtrip tests: PASSED");

    Ok(())
}

/// Demonstrate field access patterns and validation
fn demonstrate_field_access_patterns() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Field Access Patterns ---");

    let settings = AppSettings {
        app_name: "Field Test App".to_string(),
        version: "2.1.0".to_string(),
        debug_mode: false,
        max_connections: 50,
        timeout_seconds: 15.0,
        features: vec!["basic".to_string(), "advanced".to_string()],
        environment_vars: HashMap::new(),
        optional_database_url: None,
    };

    // Convert to JSON to inspect structure
    let json_data = settings.to_json()?;
    println!("JSON structure for field inspection:");

    // Count approximate fields by counting field separators
    let field_count = json_data.matches(':').count();
    println!("Estimated fields: {}", field_count);

    // Show structure (first few lines)
    let lines: Vec<&str> = json_data.lines().take(5).collect();
    for line in lines {
        println!("  {}", line.trim());
    }
    if json_data.lines().count() > 5 {
        println!("  ... ({} more lines)", json_data.lines().count() - 5);
    }

    // Demonstrate optional field handling
    println!("\nOptional field handling:");
    println!(
        "  Database URL is None: {}",
        settings.optional_database_url.is_none()
    );

    // Create version with optional field populated
    let settings_with_db = AppSettings {
        optional_database_url: Some("sqlite:///tmp/test.db".to_string()),
        ..settings.clone()
    };

    println!(
        "  Database URL with value: {:?}",
        settings_with_db.optional_database_url
    );

    // Verify both versions serialize/deserialize correctly
    let json_none = settings.to_json()?;
    let json_some = settings_with_db.to_json()?;

    let parsed_none = AppSettings::from_json(&json_none)?;
    let parsed_some = AppSettings::from_json(&json_some)?;

    assert_eq!(settings, parsed_none);
    assert_eq!(settings_with_db, parsed_some);
    assert!(parsed_none.optional_database_url.is_none());
    assert!(parsed_some.optional_database_url.is_some());

    println!("Optional field serialization: PASSED");

    Ok(())
}

fn to_binary(&self) -> SerializationResult<Vec<u8>>

Converts the struct to binary data

Serializes the struct to a compact binary format optimized for efficient storage and transmission.

Returns

Ok(Vec<u8>) containing the binary representation on success Err(SerializationError) if serialization fails

Examples

Converts struct to binary data with efficient compact format.

Examples found in repository

examples/serialization/nested_structures.rs (line 743)

fn demonstrate_deep_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Deep Serialization Analysis ---");

    let deep_milestone = Milestone {
        name: "Deep Milestone".to_string(),
        description: "Testing deep nesting serialization".to_string(),
        due_date: "2024-12-31".to_string(),
        is_completed: false,
        progress_percentage: 50.0,
        dependencies: vec!["Parent Task".to_string(), "Sibling Task".to_string()],
    };

    let deep_project = Project {
        name: "Deep Nesting Test".to_string(),
        description: "Project for testing serialization depth".to_string(),
        status: ProjectStatus::Planning,
        budget: 100000.0,
        team_members: vec!["Developer 1".to_string(), "Developer 2".to_string()],
        milestones: vec![deep_milestone],
        metadata: HashMap::new(),
    };

    // Analyze serialization output
    let json_output = deep_project.to_json()?;
    let binary_output = deep_project.to_binary()?;

    println!("Deep structure serialization analysis:");
    println!("  JSON size: {} bytes", json_output.len());
    println!("  Binary size: {} bytes", binary_output.len());
    println!("  Nesting levels: Address -> Project -> Milestone -> Dependencies");

    // Count nested objects in JSON (rough estimate)
    let object_count = json_output.matches('{').count();
    let array_count = json_output.matches('[').count();
    println!("  JSON objects: {}", object_count);
    println!("  JSON arrays: {}", array_count);

    // Verify deep roundtrip
    let json_parsed = Project::from_json(&json_output)?;
    let binary_parsed = Project::from_binary(&binary_output)?;

    assert_eq!(deep_project, json_parsed);
    assert_eq!(deep_project, binary_parsed);
    println!("Deep serialization roundtrip: VERIFIED");

    Ok(())
}

/// Demonstrate collection nesting patterns
fn demonstrate_collection_nesting() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Collection Nesting Patterns ---");

    // Create multiple departments with varying complexity
    let departments = vec![
        Department {
            name: "Research".to_string(),
            manager: "Dr. Science".to_string(),
            employee_count: 25,
            budget: 1200000.0,
            office_locations: vec![
                Address {
                    street: "1 Research Blvd".to_string(),
                    city: "Innovation Hub".to_string(),
                    state: "MA".to_string(),
                    postal_code: "02101".to_string(),
                    country: "USA".to_string(),
                },
                Address {
                    street: "2 Lab Street".to_string(),
                    city: "Tech Valley".to_string(),
                    state: "NY".to_string(),
                    postal_code: "12180".to_string(),
                    country: "USA".to_string(),
                },
            ],
        },
        Department {
            name: "Quality Assurance".to_string(),
            manager: "Test Master".to_string(),
            employee_count: 12,
            budget: 600000.0,
            office_locations: vec![], // Empty collection
        },
    ];

    println!("Collection nesting analysis:");
    println!("  Departments: {}", departments.len());

    let total_locations: usize = departments.iter().map(|d| d.office_locations.len()).sum();
    println!("  Total office locations: {}", total_locations);

    // Test serialization with mixed empty and populated collections
    // Note: Vec<Department> doesn't implement StructSerializable directly.
    // For this example, we'll serialize each department individually
    let department_json_strings: Result<Vec<String>, _> =
        departments.iter().map(|dept| dept.to_json()).collect();
    let department_json_strings = department_json_strings?;

    // Deserialize each department back
    let parsed_departments: Result<Vec<Department>, _> = department_json_strings
        .iter()
        .map(|json_str| Department::from_json(json_str))
        .collect();
    let parsed_departments = parsed_departments?;

    assert_eq!(departments, parsed_departments);
    println!("Collection nesting serialization: VERIFIED");

    // Analyze collection patterns
    for (i, dept) in departments.iter().enumerate() {
        println!(
            "  Department {}: {} locations",
            i + 1,
            dept.office_locations.len()
        );
    }

    Ok(())
}

/// Demonstrate partial loading and field access
fn demonstrate_partial_loading() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Partial Loading and Field Access ---");

    // Create a simple project for analysis
    let project = Project {
        name: "Sample Project".to_string(),
        description: "For testing partial loading".to_string(),
        status: ProjectStatus::InProgress,
        budget: 50000.0,
        team_members: vec!["Alice".to_string(), "Bob".to_string()],
        milestones: vec![Milestone {
            name: "Phase 1".to_string(),
            description: "Initial phase".to_string(),
            due_date: "2024-06-01".to_string(),
            is_completed: true,
            progress_percentage: 100.0,
            dependencies: vec![],
        }],
        metadata: HashMap::new(),
    };

    // Convert to JSON and analyze structure
    println!("Project JSON structure analysis:");

    // Parse to examine available fields by inspecting JSON structure
    let json_data = project.to_json()?;
    let field_count = json_data.matches(':').count();
    println!("  Estimated fields: {}", field_count);

    // Show top-level structure
    let lines: Vec<&str> = json_data.lines().take(10).collect();
    println!("  JSON structure preview:");
    for line in lines.iter().take(5) {
        if let Some(colon_pos) = line.find(':') {
            let field_name = line[..colon_pos].trim().trim_matches('"').trim();
            if !field_name.is_empty() {
                println!("    - {}", field_name);
            }
        }
    }

    // Demonstrate field type analysis
    println!("\nField type analysis:");
    println!("  name: String");
    println!("  status: Enum -> String");
    println!("  budget: f64 -> Number");
    println!("  team_members: Vec<String> -> Array");
    println!("  milestones: Vec<Milestone> -> Array of Objects");

    Ok(())
}

/// Demonstrate performance analysis for nested structures
fn demonstrate_performance_analysis() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Performance Analysis ---");

    // Create structures of varying complexity
    let simple_address = Address {
        street: "123 Main St".to_string(),
        city: "Anytown".to_string(),
        state: "ST".to_string(),
        postal_code: "12345".to_string(),
        country: "USA".to_string(),
    };

    let complex_department = Department {
        name: "Complex Department".to_string(),
        manager: "Manager Name".to_string(),
        employee_count: 100,
        budget: 5000000.0,
        office_locations: vec![simple_address.clone(); 10], // 10 identical addresses
    };

    let complex_project = Project {
        name: "Complex Project".to_string(),
        description: "Large project with many components".to_string(),
        status: ProjectStatus::InProgress,
        budget: 2000000.0,
        team_members: (1..=50).map(|i| format!("Team Member {}", i)).collect(),
        milestones: (1..=20)
            .map(|i| Milestone {
                name: format!("Milestone {}", i),
                description: format!("Description for milestone {}", i),
                due_date: "2024-12-31".to_string(),
                is_completed: i <= 10,
                progress_percentage: if i <= 10 { 100.0 } else { 50.0 },
                dependencies: if i > 1 {
                    vec![format!("Milestone {}", i - 1)]
                } else {
                    vec![]
                },
            })
            .collect(),
        metadata: HashMap::new(),
    };

    // Measure serialization performance
    println!("Performance comparison:");

    // Simple address
    let addr_json = simple_address.to_json()?;
    let addr_binary = simple_address.to_binary()?;
    println!("  Simple Address:");
    println!("    JSON: {} bytes", addr_json.len());
    println!("    Binary: {} bytes", addr_binary.len());

    // Complex department
    let dept_json = complex_department.to_json()?;
    let dept_binary = complex_department.to_binary()?;
    println!("  Complex Department (10 addresses):");
    println!("    JSON: {} bytes", dept_json.len());
    println!("    Binary: {} bytes", dept_binary.len());

    // Complex project
    let proj_json = complex_project.to_json()?;
    let proj_binary = complex_project.to_binary()?;
    println!("  Complex Project (50 members, 20 milestones):");
    println!("    JSON: {} bytes", proj_json.len());
    println!("    Binary: {} bytes", proj_binary.len());

    // Calculate efficiency ratios
    let dept_ratio = dept_json.len() as f64 / dept_binary.len() as f64;
    let proj_ratio = proj_json.len() as f64 / proj_binary.len() as f64;

    println!("\nFormat efficiency (JSON/Binary ratio):");
    println!("  Department: {:.2}x", dept_ratio);
    println!("  Project: {:.2}x", proj_ratio);

    // Verify complex structure roundtrip
    let proj_json_parsed = Project::from_json(&proj_json)?;
    let proj_binary_parsed = Project::from_binary(&proj_binary)?;

    assert_eq!(complex_project, proj_json_parsed);
    assert_eq!(complex_project, proj_binary_parsed);
    println!("Complex structure roundtrip: VERIFIED");

    Ok(())
}

examples/serialization/basic_structs.rs (line 307)

fn demonstrate_app_settings_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- App Settings Serialization ---");

    // Create app settings with collections and optional fields
    let mut env_vars = HashMap::new();
    env_vars.insert("LOG_LEVEL".to_string(), "info".to_string());
    env_vars.insert("PORT".to_string(), "8080".to_string());
    env_vars.insert("HOST".to_string(), "localhost".to_string());

    let settings = AppSettings {
        app_name: "Train Station Example".to_string(),
        version: "1.0.0".to_string(),
        debug_mode: true,
        max_connections: 100,
        timeout_seconds: 30.5,
        features: vec![
            "authentication".to_string(),
            "logging".to_string(),
            "metrics".to_string(),
        ],
        environment_vars: env_vars,
        optional_database_url: Some("postgresql://localhost:5432/mydb".to_string()),
    };

    println!("Original app settings:");
    println!("  App Name: {}", settings.app_name);
    println!("  Version: {}", settings.version);
    println!("  Debug Mode: {}", settings.debug_mode);
    println!("  Max Connections: {}", settings.max_connections);
    println!("  Timeout: {} seconds", settings.timeout_seconds);
    println!("  Features: {:?}", settings.features);
    println!("  Environment Variables: {:?}", settings.environment_vars);
    println!("  Database URL: {:?}", settings.optional_database_url);

    // Serialize to binary format for efficient storage
    let binary_data = settings.to_binary()?;
    println!("\nSerialized to binary: {} bytes", binary_data.len());

    // Save to binary file
    settings.save_binary("temp_app_settings.bin")?;
    println!("Saved to file: temp_app_settings.bin");

    // Load from binary file
    let loaded_settings = AppSettings::load_binary("temp_app_settings.bin")?;
    println!("\nLoaded app settings:");
    println!("  App Name: {}", loaded_settings.app_name);
    println!("  Version: {}", loaded_settings.version);
    println!("  Debug Mode: {}", loaded_settings.debug_mode);
    println!("  Features count: {}", loaded_settings.features.len());
    println!(
        "  Environment variables count: {}",
        loaded_settings.environment_vars.len()
    );

    // Verify data integrity
    assert_eq!(settings, loaded_settings);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison between JSON and binary
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    let user = UserProfile {
        id: 98765,
        username: "bob_builder".to_string(),
        email: "bob@construction.com".to_string(),
        age: 35,
        is_active: false,
        score: 87.2,
    };

    // Save in both formats
    user.save_json("temp_format_comparison.json")?;
    user.save_binary("temp_format_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_format_comparison.json")?.len();
    let binary_size = fs::metadata("temp_format_comparison.bin")?.len();

    println!("Format comparison for UserProfile:");
    println!("  JSON file size: {} bytes", json_size);
    println!("  Binary file size: {} bytes", binary_size);
    println!(
        "  Size ratio (JSON/Binary): {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Demonstrate readability
    let json_content = fs::read_to_string("temp_format_comparison.json")?;
    println!("\nJSON format (human-readable):");
    println!("{}", json_content);

    println!("\nBinary format (first 32 bytes as hex):");
    let binary_content = fs::read("temp_format_comparison.bin")?;
    for (i, byte) in binary_content.iter().take(32).enumerate() {
        if i % 16 == 0 && i > 0 {
            println!();
        }
        print!("{:02x} ", byte);
    }
    println!("\n... ({} total bytes)", binary_content.len());

    // Load and verify both formats produce identical results
    let json_loaded = UserProfile::load_json("temp_format_comparison.json")?;
    let binary_loaded = UserProfile::load_binary("temp_format_comparison.bin")?;

    assert_eq!(json_loaded, binary_loaded);
    println!("\nFormat consistency verification: PASSED");

    Ok(())
}

/// Demonstrate roundtrip verification with multiple data variations
fn demonstrate_roundtrip_verification() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Roundtrip Verification ---");

    // Test various data patterns
    let test_users = [
        UserProfile {
            id: 0,
            username: "".to_string(),
            email: "empty@test.com".to_string(),
            age: 0,
            is_active: false,
            score: 0.0,
        },
        UserProfile {
            id: u32::MAX,
            username: "maximal_user_with_very_long_name_123456789".to_string(),
            email: "test@verylongdomainname.example.org".to_string(),
            age: i32::MAX,
            is_active: true,
            score: 999999.5,
        },
        UserProfile {
            id: 42,
            username: "unicode_tëst_🦀".to_string(),
            email: "unicode@tëst.com".to_string(),
            age: 25,
            is_active: true,
            score: -123.456,
        },
    ];

    println!(
        "Testing roundtrip serialization with {} variations:",
        test_users.len()
    );

    for (i, user) in test_users.iter().enumerate() {
        println!(
            "  Test case {}: ID={}, Username='{}'",
            i + 1,
            user.id,
            user.username
        );

        // JSON roundtrip
        let json_data = user.to_json()?;
        let json_parsed = UserProfile::from_json(&json_data)?;
        assert_eq!(*user, json_parsed);

        // Binary roundtrip
        let binary_data = user.to_binary()?;
        let binary_parsed = UserProfile::from_binary(&binary_data)?;
        assert_eq!(*user, binary_parsed);

        println!("    JSON roundtrip: PASSED");
        println!("    Binary roundtrip: PASSED");
    }

    println!("All roundtrip tests: PASSED");

    Ok(())
}

examples/serialization/json_vs_binary.rs (line 385)

fn demonstrate_format_characteristics() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Format Characteristics ---");

    // Create sample data structures
    let mut metadata = HashMap::new();
    metadata.insert("operation_type".to_string(), "benchmark".to_string());
    metadata.insert("system".to_string(), "train_station".to_string());

    let metrics = PerformanceMetrics {
        operation: "tensor_multiplication".to_string(),
        duration_micros: 1234,
        memory_usage_bytes: 8192,
        cpu_usage_percent: 75.5,
        throughput_ops_per_sec: 1000.0,
        metadata,
    };

    println!("Format characteristics analysis:");

    // JSON characteristics
    let json_data = metrics.to_json()?;
    let json_lines = json_data.lines().count();
    let json_chars = json_data.chars().count();

    println!("\nJSON Format:");
    println!("  Size: {} bytes", json_data.len());
    println!("  Characters: {}", json_chars);
    println!("  Lines: {}", json_lines);
    println!("  Human readable: Yes");
    println!("  Self-describing: Yes");
    println!("  Cross-platform: Yes");
    println!("  Compression ratio: Variable (depends on content)");

    // Show sample JSON output
    println!("  Sample output:");
    for line in json_data.lines().take(3) {
        println!("    {}", line);
    }
    if json_lines > 3 {
        println!("    ... ({} more lines)", json_lines - 3);
    }

    // Binary characteristics
    let binary_data = metrics.to_binary()?;

    println!("\nBinary Format:");
    println!("  Size: {} bytes", binary_data.len());
    println!("  Human readable: No");
    println!("  Self-describing: No (requires schema)");
    println!("  Cross-platform: Yes (with proper endianness handling)");
    println!("  Compression ratio: High (efficient encoding)");

    // Show sample binary output (hex)
    println!("  Sample output (first 32 bytes as hex):");
    print!("    ");
    for (i, byte) in binary_data.iter().take(32).enumerate() {
        if i > 0 && i % 16 == 0 {
            println!();
            print!("    ");
        }
        print!("{:02x} ", byte);
    }
    if binary_data.len() > 32 {
        println!("\n    ... ({} more bytes)", binary_data.len() - 32);
    } else {
        println!();
    }

    // Verify roundtrip for both formats
    let json_parsed = PerformanceMetrics::from_json(&json_data)?;
    let binary_parsed = PerformanceMetrics::from_binary(&binary_data)?;

    assert_eq!(metrics, json_parsed);
    assert_eq!(metrics, binary_parsed);
    println!("\nRoundtrip verification: PASSED");

    Ok(())
}

/// Demonstrate size comparisons across different data types
fn demonstrate_size_comparisons() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Size Comparison Analysis ---");

    // Test 1: Small configuration data (typical JSON use case)
    let mut db_settings = HashMap::new();
    db_settings.insert("host".to_string(), "localhost".to_string());
    db_settings.insert("port".to_string(), "5432".to_string());
    db_settings.insert("database".to_string(), "myapp".to_string());

    let config = Configuration {
        version: "1.2.3".to_string(),
        debug_enabled: true,
        log_level: "info".to_string(),
        database_settings: db_settings,
        feature_flags_enabled: true,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    // Test 2: Large numeric dataset (typical binary use case)
    let large_dataset = LargeDataset {
        name: "ML Training Data".to_string(),
        values: (0..1000).map(|i| i as f32 * 0.1).collect(),
        labels: (0..1000).map(|i| format!("label_{}", i)).collect(),
        feature_count: 100,
        feature_dimension: 50,
        timestamp_count: 1000,
        metadata: HashMap::new(),
    };

    println!("Size comparison results:");

    // Configuration comparison
    let config_json = config.to_json()?;
    let config_binary = config.to_binary()?;

    println!("\nConfiguration Data (small, text-heavy):");
    println!("  JSON: {} bytes", config_json.len());
    println!("  Binary: {} bytes", config_binary.len());
    println!(
        "  Ratio (JSON/Binary): {:.2}x",
        config_json.len() as f64 / config_binary.len() as f64
    );
    println!("  Recommendation: JSON (human readable, small size difference)");

    // Large dataset comparison
    let dataset_json = large_dataset.to_json()?;
    let dataset_binary = large_dataset.to_binary()?;

    println!("\nLarge Numeric Dataset (1000 values, 100x50 matrix):");
    println!(
        "  JSON: {} bytes ({:.1} KB)",
        dataset_json.len(),
        dataset_json.len() as f64 / 1024.0
    );
    println!(
        "  Binary: {} bytes ({:.1} KB)",
        dataset_binary.len(),
        dataset_binary.len() as f64 / 1024.0
    );
    println!(
        "  Ratio (JSON/Binary): {:.2}x",
        dataset_json.len() as f64 / dataset_binary.len() as f64
    );
    if dataset_json.len() > dataset_binary.len() {
        println!(
            "  Space saved with binary: {} bytes ({:.1} KB)",
            dataset_json.len() - dataset_binary.len(),
            (dataset_json.len() - dataset_binary.len()) as f64 / 1024.0
        );
        println!("  Recommendation: Binary (significant size reduction)");
    } else {
        println!(
            "  Binary overhead: {} bytes ({:.1} KB)",
            dataset_binary.len() - dataset_json.len(),
            (dataset_binary.len() - dataset_json.len()) as f64 / 1024.0
        );
        println!("  Recommendation: JSON (binary overhead not justified for this size)");
    }

    // Content analysis
    println!("\nContent Type Analysis:");

    // Analyze JSON content patterns
    let json_numbers = dataset_json.matches(char::is_numeric).count();
    let json_brackets = dataset_json.matches('[').count() + dataset_json.matches(']').count();
    let json_quotes = dataset_json.matches('"').count();

    println!("  JSON overhead sources:");
    println!("    Numeric characters: ~{}", json_numbers);
    println!("    Brackets and commas: ~{}", json_brackets);
    println!("    Quote marks: {}", json_quotes);
    println!("    Formatting/whitespace: Varies");

    println!("  Binary advantages:");
    println!("    Direct numeric encoding: 4-8 bytes per number");
    println!("    No formatting overhead: Zero bytes");
    println!("    Efficient length encoding: Minimal bytes");

    Ok(())
}

/// Demonstrate performance benchmarks
fn demonstrate_performance_benchmarks() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Performance Benchmark Analysis ---");

    // Create test data of varying sizes
    let small_config = Configuration {
        version: "1.0.0".to_string(),
        debug_enabled: false,
        log_level: "warn".to_string(),
        database_settings: HashMap::new(),
        feature_flags_enabled: false,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    let large_dataset = LargeDataset {
        name: "Large Dataset".to_string(),
        values: (0..5000).map(|i| i as f32 * 0.001).collect(),
        labels: (0..5000).map(|i| format!("large_item_{}", i)).collect(),
        feature_count: 200,
        feature_dimension: 25,
        timestamp_count: 5000,
        metadata: HashMap::new(),
    };

    println!("Performance benchmark results:");

    // Benchmark each dataset (avoiding trait objects due to object safety)
    let dataset_names = ["Small Config", "Large Dataset"];

    for (i, name) in dataset_names.iter().enumerate() {
        let mut comparison = FormatComparison::new(name.to_string());

        // JSON serialization benchmark
        let start = Instant::now();
        let json_data = match i {
            0 => small_config.to_json()?,
            _ => large_dataset.to_json()?,
        };
        comparison.json_serialize_micros = start.elapsed().as_micros() as u64;
        comparison.json_size_bytes = json_data.len() as u64;

        // JSON deserialization benchmark (using PerformanceMetrics as example)
        if *name == "Small Config" {
            let start = Instant::now();
            let _parsed = Configuration::from_json(&json_data)?;
            comparison.json_deserialize_micros = start.elapsed().as_micros() as u64;
        } else {
            let start = Instant::now();
            let _parsed = LargeDataset::from_json(&json_data)?;
            comparison.json_deserialize_micros = start.elapsed().as_micros() as u64;
        }

        // Binary serialization benchmark
        let start = Instant::now();
        let binary_data = match i {
            0 => small_config.to_binary()?,
            _ => large_dataset.to_binary()?,
        };
        comparison.binary_serialize_micros = start.elapsed().as_micros() as u64;
        comparison.binary_size_bytes = binary_data.len() as u64;

        // Binary deserialization benchmark
        if *name == "Small Config" {
            let start = Instant::now();
            let _parsed = Configuration::from_binary(&binary_data)?;
            comparison.binary_deserialize_micros = start.elapsed().as_micros() as u64;
        } else {
            let start = Instant::now();
            let _parsed = LargeDataset::from_binary(&binary_data)?;
            comparison.binary_deserialize_micros = start.elapsed().as_micros() as u64;
        }

        // Calculate ratios
        comparison.calculate_ratios();

        // Display results
        println!("\n{}:", name);
        println!(
            "  Size - JSON: {} bytes, Binary: {} bytes (ratio: {:.2}x)",
            comparison.json_size_bytes, comparison.binary_size_bytes, comparison.size_ratio
        );
        println!(
            "  Serialize - JSON: {}μs, Binary: {}μs (binary relative speed: {:.2}x)",
            comparison.json_serialize_micros,
            comparison.binary_serialize_micros,
            comparison.serialize_speed_ratio
        );
        println!(
            "  Deserialize - JSON: {}μs, Binary: {}μs (binary relative speed: {:.2}x)",
            comparison.json_deserialize_micros,
            comparison.binary_deserialize_micros,
            comparison.deserialize_speed_ratio
        );
    }

    println!("\nPerformance Summary:");
    println!("  - Binary format consistently uses less storage space");
    println!("  - Performance differences vary by data type and size");
    println!("  - Larger datasets show more significant binary advantages");
    println!("  - JSON parsing overhead increases with structure complexity");

    Ok(())
}

/// Demonstrate use case recommendations
fn demonstrate_use_case_recommendations() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Use Case Recommendations ---");

    println!("JSON Format - Recommended for:");
    println!("  ✓ Configuration files (human-editable)");
    println!("  ✓ API responses (web compatibility)");
    println!("  ✓ Debugging and development (readability)");
    println!("  ✓ Small data structures (minimal overhead)");
    println!("  ✓ Cross-language interoperability");
    println!("  ✓ Schema evolution (self-describing)");
    println!("  ✓ Text-heavy data with few numbers");

    println!("\nBinary Format - Recommended for:");
    println!("  ✓ Large datasets (memory/storage efficiency)");
    println!("  ✓ High-performance applications (speed critical)");
    println!("  ✓ Numeric-heavy data (ML models, matrices)");
    println!("  ✓ Network transmission (bandwidth limited)");
    println!("  ✓ Embedded systems (resource constrained)");
    println!("  ✓ Long-term storage (space efficiency)");
    println!("  ✓ Frequent serialization/deserialization");

    // Demonstrate decision matrix
    println!("\nDecision Matrix Example:");

    let scenarios = vec![
        (
            "Web API Configuration",
            "JSON",
            "Human readable, web standard, small size",
        ),
        (
            "ML Model Weights",
            "Binary",
            "Large numeric data, performance critical",
        ),
        (
            "User Preferences",
            "JSON",
            "Human editable, self-documenting",
        ),
        (
            "Real-time Telemetry",
            "Binary",
            "High frequency, bandwidth limited",
        ),
        (
            "Application Settings",
            "JSON",
            "Developer accessible, version control friendly",
        ),
        (
            "Scientific Dataset",
            "Binary",
            "Large arrays, storage efficiency critical",
        ),
    ];

    for (scenario, recommendation, reason) in scenarios {
        println!("  {} -> {} ({})", scenario, recommendation, reason);
    }

    // Create examples for common scenarios
    println!("\nPractical Examples:");

    // Configuration file example (JSON)
    let config = Configuration {
        version: "2.1.0".to_string(),
        debug_enabled: false,
        log_level: "info".to_string(),
        database_settings: {
            let mut map = HashMap::new();
            map.insert("url".to_string(), "postgresql://localhost/app".to_string());
            map.insert("pool_size".to_string(), "10".to_string());
            map
        },
        feature_flags_enabled: true,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    config.save_json("temp_config_example.json")?;
    let config_content = fs::read_to_string("temp_config_example.json")?;

    println!("\nConfiguration File (JSON) - Human readable:");
    for line in config_content.lines().take(5) {
        println!("  {}", line);
    }
    println!("  ... (easily editable by developers)");

    // Data export example (Binary)
    let export_data = LargeDataset {
        name: "Training Export".to_string(),
        values: (0..1000).map(|i| (i as f32).sin()).collect(),
        labels: (0..1000).map(|i| format!("sample_{:04}", i)).collect(),
        feature_count: 50,
        feature_dimension: 20,
        timestamp_count: 1000,
        metadata: HashMap::new(),
    };

    export_data.save_binary("temp_export_example.bin")?;
    let export_size = fs::metadata("temp_export_example.bin")?.len();

    println!("\nData Export (Binary) - Efficient storage:");
    println!(
        "  File size: {} bytes ({:.1} KB)",
        export_size,
        export_size as f64 / 1024.0
    );
    println!("  1000 numeric values + 50x20 matrix + metadata");
    println!("  Compact encoding saves significant space vs JSON");

    Ok(())
}

/// Demonstrate debugging capabilities
fn demonstrate_debugging_capabilities() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Debugging Capabilities ---");

    let mut metadata = HashMap::new();
    metadata.insert("debug_session".to_string(), "session_123".to_string());
    metadata.insert("error_code".to_string(), "E001".to_string());

    let debug_metrics = PerformanceMetrics {
        operation: "debug_test".to_string(),
        duration_micros: 5432,
        memory_usage_bytes: 16384,
        cpu_usage_percent: 42.7,
        throughput_ops_per_sec: 750.0,
        metadata,
    };

    println!("Debugging Comparison:");

    // JSON debugging advantages
    let json_data = debug_metrics.to_json()?;
    println!("\nJSON Format - Debugging Advantages:");
    println!("  ✓ Human readable without tools");
    println!("  ✓ Can inspect values directly");
    println!("  ✓ Text editors show structure");
    println!("  ✓ Diff tools work naturally");
    println!("  ✓ Version control friendly");

    println!("\n  Sample JSON output for debugging:");
    for (i, line) in json_data.lines().enumerate() {
        if i < 5 {
            println!("    {}", line);
        }
    }

    // Binary debugging limitations
    let binary_data = debug_metrics.to_binary()?;
    println!("\nBinary Format - Debugging Limitations:");
    println!("  ✗ Requires special tools to inspect");
    println!("  ✗ Not human readable");
    println!("  ✗ Difficult to debug data corruption");
    println!("  ✗ Version control shows as binary diff");

    println!("\n  Binary data (hex dump for debugging):");
    print!("    ");
    for (i, byte) in binary_data.iter().take(40).enumerate() {
        if i > 0 && i % 16 == 0 {
            println!();
            print!("    ");
        }
        print!("{:02x} ", byte);
    }
    println!("\n    (requires hex editor or custom tools)");

    // Development workflow comparison
    println!("\nDevelopment Workflow Impact:");

    println!("\nJSON Workflow:");
    println!("  1. Save data to JSON file");
    println!("  2. Open in any text editor");
    println!("  3. Inspect values directly");
    println!("  4. Make manual edits if needed");
    println!("  5. Version control tracks changes");

    println!("\nBinary Workflow:");
    println!("  1. Save data to binary file");
    println!("  2. Write debugging code to load and print");
    println!("  3. Use hex editor for low-level inspection");
    println!("  4. Cannot make manual edits easily");
    println!("  5. Version control shows binary changes only");

    // Hybrid approach recommendation
    println!("\nHybrid Approach for Development:");
    println!("  - Use JSON during development/debugging");
    println!("  - Switch to binary for production deployment");
    println!("  - Provide debugging tools that export binary to JSON");
    println!("  - Include format conversion utilities");

    // Demonstrate debugging scenario
    println!("\nDebugging Scenario Example:");
    println!("  Problem: Performance metrics show unexpected values");

    // Save both formats for comparison
    debug_metrics.save_json("temp_debug_metrics.json")?;
    debug_metrics.save_binary("temp_debug_metrics.bin")?;

    println!("  JSON approach: Open temp_debug_metrics.json in editor");
    println!("    -> Immediately see cpu_usage_percent: 42.7");
    println!("    -> Compare with expected range");
    println!("    -> Check metadata for debug_session: 'session_123'");

    println!("  Binary approach: Write debugging code");
    println!("    -> Load binary file programmatically");
    println!("    -> Print values to console");
    println!("    -> Additional development time required");

    Ok(())
}

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

Creates the struct from a JSON string

Deserializes a JSON string into a new instance of the struct. The JSON should contain all required fields in the expected format.

Arguments

• json - JSON string containing the struct data

Returns

Ok(Self) on successful deserialization Err(SerializationError) if JSON parsing or deserialization fails

Examples

Creates struct from JSON string with proper parsing and validation.

Examples found in repository

examples/serialization/basic_structs.rs (line 94)

    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,
        })
    }
}

impl ToFieldValue for AppSettings {
    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) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for AppSettings {
    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 AppSettings 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 AppSettings from binary: {}", e),
                }
            });
        }

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Basic Struct Serialization Example ===\n");

    demonstrate_user_profile_serialization()?;
    demonstrate_app_settings_serialization()?;
    demonstrate_format_comparison()?;
    demonstrate_roundtrip_verification()?;
    demonstrate_field_access_patterns()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate basic struct serialization with simple field types
fn demonstrate_user_profile_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- User Profile Serialization ---");

    // Create a user profile with various field types
    let user = UserProfile {
        id: 12345,
        username: "alice_cooper".to_string(),
        email: "alice@example.com".to_string(),
        age: 28,
        is_active: true,
        score: 95.7,
    };

    println!("Original user profile:");
    println!("  ID: {}", user.id);
    println!("  Username: {}", user.username);
    println!("  Email: {}", user.email);
    println!("  Age: {}", user.age);
    println!("  Active: {}", user.is_active);
    println!("  Score: {}", user.score);

    // Serialize to JSON
    let json_data = user.to_json()?;
    println!("\nSerialized to JSON:");
    println!("{}", json_data);

    // Save to JSON file
    user.save_json("temp_user_profile.json")?;
    println!("Saved to file: temp_user_profile.json");

    // Load from JSON file
    let loaded_user = UserProfile::load_json("temp_user_profile.json")?;
    println!("\nLoaded user profile:");
    println!("  ID: {}", loaded_user.id);
    println!("  Username: {}", loaded_user.username);
    println!("  Email: {}", loaded_user.email);
    println!("  Age: {}", loaded_user.age);
    println!("  Active: {}", loaded_user.is_active);
    println!("  Score: {}", loaded_user.score);

    // Verify data integrity
    assert_eq!(user, loaded_user);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate serialization with collections and optional fields
fn demonstrate_app_settings_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- App Settings Serialization ---");

    // Create app settings with collections and optional fields
    let mut env_vars = HashMap::new();
    env_vars.insert("LOG_LEVEL".to_string(), "info".to_string());
    env_vars.insert("PORT".to_string(), "8080".to_string());
    env_vars.insert("HOST".to_string(), "localhost".to_string());

    let settings = AppSettings {
        app_name: "Train Station Example".to_string(),
        version: "1.0.0".to_string(),
        debug_mode: true,
        max_connections: 100,
        timeout_seconds: 30.5,
        features: vec![
            "authentication".to_string(),
            "logging".to_string(),
            "metrics".to_string(),
        ],
        environment_vars: env_vars,
        optional_database_url: Some("postgresql://localhost:5432/mydb".to_string()),
    };

    println!("Original app settings:");
    println!("  App Name: {}", settings.app_name);
    println!("  Version: {}", settings.version);
    println!("  Debug Mode: {}", settings.debug_mode);
    println!("  Max Connections: {}", settings.max_connections);
    println!("  Timeout: {} seconds", settings.timeout_seconds);
    println!("  Features: {:?}", settings.features);
    println!("  Environment Variables: {:?}", settings.environment_vars);
    println!("  Database URL: {:?}", settings.optional_database_url);

    // Serialize to binary format for efficient storage
    let binary_data = settings.to_binary()?;
    println!("\nSerialized to binary: {} bytes", binary_data.len());

    // Save to binary file
    settings.save_binary("temp_app_settings.bin")?;
    println!("Saved to file: temp_app_settings.bin");

    // Load from binary file
    let loaded_settings = AppSettings::load_binary("temp_app_settings.bin")?;
    println!("\nLoaded app settings:");
    println!("  App Name: {}", loaded_settings.app_name);
    println!("  Version: {}", loaded_settings.version);
    println!("  Debug Mode: {}", loaded_settings.debug_mode);
    println!("  Features count: {}", loaded_settings.features.len());
    println!(
        "  Environment variables count: {}",
        loaded_settings.environment_vars.len()
    );

    // Verify data integrity
    assert_eq!(settings, loaded_settings);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison between JSON and binary
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    let user = UserProfile {
        id: 98765,
        username: "bob_builder".to_string(),
        email: "bob@construction.com".to_string(),
        age: 35,
        is_active: false,
        score: 87.2,
    };

    // Save in both formats
    user.save_json("temp_format_comparison.json")?;
    user.save_binary("temp_format_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_format_comparison.json")?.len();
    let binary_size = fs::metadata("temp_format_comparison.bin")?.len();

    println!("Format comparison for UserProfile:");
    println!("  JSON file size: {} bytes", json_size);
    println!("  Binary file size: {} bytes", binary_size);
    println!(
        "  Size ratio (JSON/Binary): {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Demonstrate readability
    let json_content = fs::read_to_string("temp_format_comparison.json")?;
    println!("\nJSON format (human-readable):");
    println!("{}", json_content);

    println!("\nBinary format (first 32 bytes as hex):");
    let binary_content = fs::read("temp_format_comparison.bin")?;
    for (i, byte) in binary_content.iter().take(32).enumerate() {
        if i % 16 == 0 && i > 0 {
            println!();
        }
        print!("{:02x} ", byte);
    }
    println!("\n... ({} total bytes)", binary_content.len());

    // Load and verify both formats produce identical results
    let json_loaded = UserProfile::load_json("temp_format_comparison.json")?;
    let binary_loaded = UserProfile::load_binary("temp_format_comparison.bin")?;

    assert_eq!(json_loaded, binary_loaded);
    println!("\nFormat consistency verification: PASSED");

    Ok(())
}

/// Demonstrate roundtrip verification with multiple data variations
fn demonstrate_roundtrip_verification() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Roundtrip Verification ---");

    // Test various data patterns
    let test_users = [
        UserProfile {
            id: 0,
            username: "".to_string(),
            email: "empty@test.com".to_string(),
            age: 0,
            is_active: false,
            score: 0.0,
        },
        UserProfile {
            id: u32::MAX,
            username: "maximal_user_with_very_long_name_123456789".to_string(),
            email: "test@verylongdomainname.example.org".to_string(),
            age: i32::MAX,
            is_active: true,
            score: 999999.5,
        },
        UserProfile {
            id: 42,
            username: "unicode_tëst_🦀".to_string(),
            email: "unicode@tëst.com".to_string(),
            age: 25,
            is_active: true,
            score: -123.456,
        },
    ];

    println!(
        "Testing roundtrip serialization with {} variations:",
        test_users.len()
    );

    for (i, user) in test_users.iter().enumerate() {
        println!(
            "  Test case {}: ID={}, Username='{}'",
            i + 1,
            user.id,
            user.username
        );

        // JSON roundtrip
        let json_data = user.to_json()?;
        let json_parsed = UserProfile::from_json(&json_data)?;
        assert_eq!(*user, json_parsed);

        // Binary roundtrip
        let binary_data = user.to_binary()?;
        let binary_parsed = UserProfile::from_binary(&binary_data)?;
        assert_eq!(*user, binary_parsed);

        println!("    JSON roundtrip: PASSED");
        println!("    Binary roundtrip: PASSED");
    }

    println!("All roundtrip tests: PASSED");

    Ok(())
}

/// Demonstrate field access patterns and validation
fn demonstrate_field_access_patterns() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Field Access Patterns ---");

    let settings = AppSettings {
        app_name: "Field Test App".to_string(),
        version: "2.1.0".to_string(),
        debug_mode: false,
        max_connections: 50,
        timeout_seconds: 15.0,
        features: vec!["basic".to_string(), "advanced".to_string()],
        environment_vars: HashMap::new(),
        optional_database_url: None,
    };

    // Convert to JSON to inspect structure
    let json_data = settings.to_json()?;
    println!("JSON structure for field inspection:");

    // Count approximate fields by counting field separators
    let field_count = json_data.matches(':').count();
    println!("Estimated fields: {}", field_count);

    // Show structure (first few lines)
    let lines: Vec<&str> = json_data.lines().take(5).collect();
    for line in lines {
        println!("  {}", line.trim());
    }
    if json_data.lines().count() > 5 {
        println!("  ... ({} more lines)", json_data.lines().count() - 5);
    }

    // Demonstrate optional field handling
    println!("\nOptional field handling:");
    println!(
        "  Database URL is None: {}",
        settings.optional_database_url.is_none()
    );

    // Create version with optional field populated
    let settings_with_db = AppSettings {
        optional_database_url: Some("sqlite:///tmp/test.db".to_string()),
        ..settings.clone()
    };

    println!(
        "  Database URL with value: {:?}",
        settings_with_db.optional_database_url
    );

    // Verify both versions serialize/deserialize correctly
    let json_none = settings.to_json()?;
    let json_some = settings_with_db.to_json()?;

    let parsed_none = AppSettings::from_json(&json_none)?;
    let parsed_some = AppSettings::from_json(&json_some)?;

    assert_eq!(settings, parsed_none);
    assert_eq!(settings_with_db, parsed_some);
    assert!(parsed_none.optional_database_url.is_none());
    assert!(parsed_some.optional_database_url.is_some());

    println!("Optional field serialization: PASSED");

    Ok(())
}

examples/serialization/nested_structures.rs (line 86)

    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,
        })
    }
}

impl ToFieldValue for Department {
    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 Department {
    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 Department 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 Department from binary: {}", e),
                }
            });
        }

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Nested Structures Serialization Example ===\n");

    demonstrate_nested_struct_creation()?;
    demonstrate_deep_serialization()?;
    demonstrate_collection_nesting()?;
    demonstrate_partial_loading()?;
    demonstrate_performance_analysis()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate creating complex nested structures
fn demonstrate_nested_struct_creation() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Nested Structure Creation ---");

    // Create nested address and contact info
    let headquarters = Address {
        street: "123 Innovation Drive".to_string(),
        city: "Tech City".to_string(),
        state: "CA".to_string(),
        postal_code: "94000".to_string(),
        country: "USA".to_string(),
    };

    let mut social_media = HashMap::new();
    social_media.insert("twitter".to_string(), "@techcorp".to_string());
    social_media.insert("linkedin".to_string(), "techcorp-inc".to_string());

    let contact_info = ContactInfo {
        email: "info@techcorp.com".to_string(),
        phone: Some("+1-555-0123".to_string()),
        address_city: headquarters.city.clone(),
        address_state: headquarters.state.clone(),
        social_media,
    };

    // Create departments with nested office locations
    let engineering_office = Address {
        street: "456 Developer Lane".to_string(),
        city: "Code City".to_string(),
        state: "CA".to_string(),
        postal_code: "94001".to_string(),
        country: "USA".to_string(),
    };

    let departments = [
        Department {
            name: "Engineering".to_string(),
            manager: "Alice Johnson".to_string(),
            employee_count: 50,
            budget: 2500000.0,
            office_locations: vec![engineering_office, headquarters.clone()],
        },
        Department {
            name: "Marketing".to_string(),
            manager: "Bob Smith".to_string(),
            employee_count: 15,
            budget: 800000.0,
            office_locations: vec![headquarters.clone()],
        },
    ];

    // Create projects with milestones
    let milestones = vec![
        Milestone {
            name: "Requirements Analysis".to_string(),
            description: "Complete system requirements documentation".to_string(),
            due_date: "2024-03-15".to_string(),
            is_completed: true,
            progress_percentage: 100.0,
            dependencies: vec![],
        },
        Milestone {
            name: "Architecture Design".to_string(),
            description: "Define system architecture and components".to_string(),
            due_date: "2024-04-01".to_string(),
            is_completed: false,
            progress_percentage: 75.0,
            dependencies: vec!["Requirements Analysis".to_string()],
        },
    ];

    let mut project_metadata = HashMap::new();
    project_metadata.insert("priority".to_string(), "high".to_string());
    project_metadata.insert("client".to_string(), "internal".to_string());

    let projects = [Project {
        name: "Train Station ML Platform".to_string(),
        description: "Next-generation machine learning infrastructure".to_string(),
        status: ProjectStatus::InProgress,
        budget: 1500000.0,
        team_members: vec![
            "Alice Johnson".to_string(),
            "Charlie Brown".to_string(),
            "Diana Prince".to_string(),
        ],
        milestones: milestones.clone(),
        metadata: project_metadata,
    }];

    // Create the complete company structure
    let mut company_metadata = HashMap::new();
    company_metadata.insert("industry".to_string(), "technology".to_string());
    company_metadata.insert("stock_symbol".to_string(), "TECH".to_string());

    let company = Company {
        name: "TechCorp Inc.".to_string(),
        founded_year: 2015,
        headquarters_city: headquarters.city.clone(),
        headquarters_state: headquarters.state.clone(),
        employee_count: 250,
        department_names: departments.iter().map(|d| d.name.clone()).collect(),
        active_project_names: projects.iter().map(|p| p.name.clone()).collect(),
        company_metadata,
    };

    println!("Created complex company structure:");
    println!("  Company: {}", company.name);
    println!("  Founded: {}", company.founded_year);
    println!(
        "  Headquarters: {}, {}",
        company.headquarters_city, company.headquarters_state
    );
    println!("  Employee Count: {}", company.employee_count);
    println!("  Departments: {}", company.department_names.len());
    println!("  Active Projects: {}", company.active_project_names.len());

    // Save the complete structure
    company.save_json("temp_nested_company.json")?;
    println!("Saved nested structure to: temp_nested_company.json");

    // Verify loading preserves all nested data
    let loaded_company = Company::load_json("temp_nested_company.json")?;
    assert_eq!(company, loaded_company);
    println!("Successfully verified Company roundtrip serialization");

    // Also demonstrate individual component serialization
    let address_json = headquarters.to_json()?;
    let loaded_address = Address::from_json(&address_json)?;
    assert_eq!(headquarters, loaded_address);
    println!("Successfully serialized/deserialized Address component");

    let contact_json = contact_info.to_json()?;
    let loaded_contact = ContactInfo::from_json(&contact_json)?;
    assert_eq!(contact_info, loaded_contact);
    println!("Successfully serialized/deserialized ContactInfo component");
    println!("Nested structure integrity: VERIFIED");

    Ok(())
}

/// Demonstrate deep serialization with complex nesting
fn demonstrate_deep_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Deep Serialization Analysis ---");

    let deep_milestone = Milestone {
        name: "Deep Milestone".to_string(),
        description: "Testing deep nesting serialization".to_string(),
        due_date: "2024-12-31".to_string(),
        is_completed: false,
        progress_percentage: 50.0,
        dependencies: vec!["Parent Task".to_string(), "Sibling Task".to_string()],
    };

    let deep_project = Project {
        name: "Deep Nesting Test".to_string(),
        description: "Project for testing serialization depth".to_string(),
        status: ProjectStatus::Planning,
        budget: 100000.0,
        team_members: vec!["Developer 1".to_string(), "Developer 2".to_string()],
        milestones: vec![deep_milestone],
        metadata: HashMap::new(),
    };

    // Analyze serialization output
    let json_output = deep_project.to_json()?;
    let binary_output = deep_project.to_binary()?;

    println!("Deep structure serialization analysis:");
    println!("  JSON size: {} bytes", json_output.len());
    println!("  Binary size: {} bytes", binary_output.len());
    println!("  Nesting levels: Address -> Project -> Milestone -> Dependencies");

    // Count nested objects in JSON (rough estimate)
    let object_count = json_output.matches('{').count();
    let array_count = json_output.matches('[').count();
    println!("  JSON objects: {}", object_count);
    println!("  JSON arrays: {}", array_count);

    // Verify deep roundtrip
    let json_parsed = Project::from_json(&json_output)?;
    let binary_parsed = Project::from_binary(&binary_output)?;

    assert_eq!(deep_project, json_parsed);
    assert_eq!(deep_project, binary_parsed);
    println!("Deep serialization roundtrip: VERIFIED");

    Ok(())
}

/// Demonstrate collection nesting patterns
fn demonstrate_collection_nesting() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Collection Nesting Patterns ---");

    // Create multiple departments with varying complexity
    let departments = vec![
        Department {
            name: "Research".to_string(),
            manager: "Dr. Science".to_string(),
            employee_count: 25,
            budget: 1200000.0,
            office_locations: vec![
                Address {
                    street: "1 Research Blvd".to_string(),
                    city: "Innovation Hub".to_string(),
                    state: "MA".to_string(),
                    postal_code: "02101".to_string(),
                    country: "USA".to_string(),
                },
                Address {
                    street: "2 Lab Street".to_string(),
                    city: "Tech Valley".to_string(),
                    state: "NY".to_string(),
                    postal_code: "12180".to_string(),
                    country: "USA".to_string(),
                },
            ],
        },
        Department {
            name: "Quality Assurance".to_string(),
            manager: "Test Master".to_string(),
            employee_count: 12,
            budget: 600000.0,
            office_locations: vec![], // Empty collection
        },
    ];

    println!("Collection nesting analysis:");
    println!("  Departments: {}", departments.len());

    let total_locations: usize = departments.iter().map(|d| d.office_locations.len()).sum();
    println!("  Total office locations: {}", total_locations);

    // Test serialization with mixed empty and populated collections
    // Note: Vec<Department> doesn't implement StructSerializable directly.
    // For this example, we'll serialize each department individually
    let department_json_strings: Result<Vec<String>, _> =
        departments.iter().map(|dept| dept.to_json()).collect();
    let department_json_strings = department_json_strings?;

    // Deserialize each department back
    let parsed_departments: Result<Vec<Department>, _> = department_json_strings
        .iter()
        .map(|json_str| Department::from_json(json_str))
        .collect();
    let parsed_departments = parsed_departments?;

    assert_eq!(departments, parsed_departments);
    println!("Collection nesting serialization: VERIFIED");

    // Analyze collection patterns
    for (i, dept) in departments.iter().enumerate() {
        println!(
            "  Department {}: {} locations",
            i + 1,
            dept.office_locations.len()
        );
    }

    Ok(())
}

/// Demonstrate partial loading and field access
fn demonstrate_partial_loading() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Partial Loading and Field Access ---");

    // Create a simple project for analysis
    let project = Project {
        name: "Sample Project".to_string(),
        description: "For testing partial loading".to_string(),
        status: ProjectStatus::InProgress,
        budget: 50000.0,
        team_members: vec!["Alice".to_string(), "Bob".to_string()],
        milestones: vec![Milestone {
            name: "Phase 1".to_string(),
            description: "Initial phase".to_string(),
            due_date: "2024-06-01".to_string(),
            is_completed: true,
            progress_percentage: 100.0,
            dependencies: vec![],
        }],
        metadata: HashMap::new(),
    };

    // Convert to JSON and analyze structure
    println!("Project JSON structure analysis:");

    // Parse to examine available fields by inspecting JSON structure
    let json_data = project.to_json()?;
    let field_count = json_data.matches(':').count();
    println!("  Estimated fields: {}", field_count);

    // Show top-level structure
    let lines: Vec<&str> = json_data.lines().take(10).collect();
    println!("  JSON structure preview:");
    for line in lines.iter().take(5) {
        if let Some(colon_pos) = line.find(':') {
            let field_name = line[..colon_pos].trim().trim_matches('"').trim();
            if !field_name.is_empty() {
                println!("    - {}", field_name);
            }
        }
    }

    // Demonstrate field type analysis
    println!("\nField type analysis:");
    println!("  name: String");
    println!("  status: Enum -> String");
    println!("  budget: f64 -> Number");
    println!("  team_members: Vec<String> -> Array");
    println!("  milestones: Vec<Milestone> -> Array of Objects");

    Ok(())
}

/// Demonstrate performance analysis for nested structures
fn demonstrate_performance_analysis() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Performance Analysis ---");

    // Create structures of varying complexity
    let simple_address = Address {
        street: "123 Main St".to_string(),
        city: "Anytown".to_string(),
        state: "ST".to_string(),
        postal_code: "12345".to_string(),
        country: "USA".to_string(),
    };

    let complex_department = Department {
        name: "Complex Department".to_string(),
        manager: "Manager Name".to_string(),
        employee_count: 100,
        budget: 5000000.0,
        office_locations: vec![simple_address.clone(); 10], // 10 identical addresses
    };

    let complex_project = Project {
        name: "Complex Project".to_string(),
        description: "Large project with many components".to_string(),
        status: ProjectStatus::InProgress,
        budget: 2000000.0,
        team_members: (1..=50).map(|i| format!("Team Member {}", i)).collect(),
        milestones: (1..=20)
            .map(|i| Milestone {
                name: format!("Milestone {}", i),
                description: format!("Description for milestone {}", i),
                due_date: "2024-12-31".to_string(),
                is_completed: i <= 10,
                progress_percentage: if i <= 10 { 100.0 } else { 50.0 },
                dependencies: if i > 1 {
                    vec![format!("Milestone {}", i - 1)]
                } else {
                    vec![]
                },
            })
            .collect(),
        metadata: HashMap::new(),
    };

    // Measure serialization performance
    println!("Performance comparison:");

    // Simple address
    let addr_json = simple_address.to_json()?;
    let addr_binary = simple_address.to_binary()?;
    println!("  Simple Address:");
    println!("    JSON: {} bytes", addr_json.len());
    println!("    Binary: {} bytes", addr_binary.len());

    // Complex department
    let dept_json = complex_department.to_json()?;
    let dept_binary = complex_department.to_binary()?;
    println!("  Complex Department (10 addresses):");
    println!("    JSON: {} bytes", dept_json.len());
    println!("    Binary: {} bytes", dept_binary.len());

    // Complex project
    let proj_json = complex_project.to_json()?;
    let proj_binary = complex_project.to_binary()?;
    println!("  Complex Project (50 members, 20 milestones):");
    println!("    JSON: {} bytes", proj_json.len());
    println!("    Binary: {} bytes", proj_binary.len());

    // Calculate efficiency ratios
    let dept_ratio = dept_json.len() as f64 / dept_binary.len() as f64;
    let proj_ratio = proj_json.len() as f64 / proj_binary.len() as f64;

    println!("\nFormat efficiency (JSON/Binary ratio):");
    println!("  Department: {:.2}x", dept_ratio);
    println!("  Project: {:.2}x", proj_ratio);

    // Verify complex structure roundtrip
    let proj_json_parsed = Project::from_json(&proj_json)?;
    let proj_binary_parsed = Project::from_binary(&proj_binary)?;

    assert_eq!(complex_project, proj_json_parsed);
    assert_eq!(complex_project, proj_binary_parsed);
    println!("Complex structure roundtrip: VERIFIED");

    Ok(())
}

examples/serialization/error_handling.rs (line 97)

    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,
        })
    }
}

impl ToFieldValue for RecoverableData {
    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 RecoverableData {
    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 RecoverableData 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 RecoverableData from binary: {}", e),
                }
            });
        }

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Error Handling and Validation Example ===\n");

    demonstrate_common_error_scenarios()?;
    demonstrate_validation_patterns()?;
    demonstrate_schema_evolution()?;
    demonstrate_recovery_strategies()?;
    demonstrate_production_error_handling()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate common serialization error scenarios
fn demonstrate_common_error_scenarios() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Common Error Scenarios ---");

    fs::create_dir_all("temp_error_tests")?;

    // Scenario 1: Corrupted JSON file
    println!("1. Corrupted JSON File:");
    let corrupted_json = r#"{"name": "test", "value": 42, "incomplete"#;
    fs::write("temp_error_tests/corrupted.json", corrupted_json)?;

    match VersionedData::load_json("temp_error_tests/corrupted.json") {
        Ok(_) => println!("   Unexpected: Corrupted JSON was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 2: Missing required fields
    println!("\n2. Missing Required Fields:");
    let incomplete_json = r#"{"name": "test"}"#;
    fs::write("temp_error_tests/incomplete.json", incomplete_json)?;

    match VersionedData::load_json("temp_error_tests/incomplete.json") {
        Ok(_) => println!("   Unexpected: Incomplete JSON was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 3: Type mismatches
    println!("\n3. Type Mismatch:");
    let type_mismatch_json = r#"{"version": "not_a_number", "name": "test", "value": 42.0}"#;
    fs::write("temp_error_tests/type_mismatch.json", type_mismatch_json)?;

    match VersionedData::load_json("temp_error_tests/type_mismatch.json") {
        Ok(_) => println!("   Unexpected: Type mismatch was handled gracefully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 4: File not found
    println!("\n4. File Not Found:");
    match VersionedData::load_json("temp_error_tests/nonexistent.json") {
        Ok(_) => println!("   Unexpected: Non-existent file was loaded"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 5: Binary format mismatch
    println!("\n5. Binary Format Mismatch:");
    let invalid_binary = vec![0xFF, 0xFF, 0xFF, 0xFF]; // Invalid binary data
    fs::write("temp_error_tests/invalid.bin", invalid_binary)?;

    match VersionedData::load_binary("temp_error_tests/invalid.bin") {
        Ok(_) => println!("   Unexpected: Invalid binary was parsed successfully"),
        Err(e) => println!("   Expected error: {}", e),
    }

    // Scenario 6: Wrong format loading
    println!("\n6. Wrong Format Loading:");
    let valid_data = VersionedData {
        version: 1,
        name: "test".to_string(),
        value: 42.0,
        optional_field: None,
        new_field: None,
    };
    valid_data.save_binary("temp_error_tests/valid.bin")?;

    // Try to load binary file as JSON
    match VersionedData::load_json("temp_error_tests/valid.bin") {
        Ok(_) => println!("   Unexpected: Binary file was loaded as JSON"),
        Err(e) => println!("   Expected error: {}", e),
    }

    Ok(())
}

/// Demonstrate validation patterns
fn demonstrate_validation_patterns() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Validation Patterns ---");

    println!("Testing input validation with various scenarios:");

    // Valid input
    println!("\n1. Valid Input:");
    let mut valid_preferences = HashMap::new();
    valid_preferences.insert("theme".to_string(), "dark".to_string());
    valid_preferences.insert("language".to_string(), "en".to_string());

    let valid_input = ValidatedUserInput {
        username: "john_doe".to_string(),
        email: "john@example.com".to_string(),
        age: 25,
        preferences: valid_preferences,
    };

    match valid_input.to_json() {
        Ok(json) => {
            println!("   ✓ Valid input serialized successfully");
            match ValidatedUserInput::from_json(&json) {
                Ok(_) => println!("   ✓ Valid input deserialized successfully"),
                Err(e) => println!("   ✗ Deserialization failed: {}", e),
            }
        }
        Err(e) => println!("   ✗ Serialization failed: {}", e),
    }

    // Test validation errors
    let validation_tests = vec![
        (
            "Empty username",
            ValidatedUserInput {
                username: "".to_string(),
                email: "test@example.com".to_string(),
                age: 25,
                preferences: HashMap::new(),
            },
        ),
        (
            "Invalid username characters",
            ValidatedUserInput {
                username: "user@name!".to_string(),
                email: "test@example.com".to_string(),
                age: 25,
                preferences: HashMap::new(),
            },
        ),
        (
            "Invalid email",
            ValidatedUserInput {
                username: "username".to_string(),
                email: "invalid_email".to_string(),
                age: 25,
                preferences: HashMap::new(),
            },
        ),
        (
            "Age too low",
            ValidatedUserInput {
                username: "username".to_string(),
                email: "test@example.com".to_string(),
                age: 10,
                preferences: HashMap::new(),
            },
        ),
        (
            "Age too high",
            ValidatedUserInput {
                username: "username".to_string(),
                email: "test@example.com".to_string(),
                age: 150,
                preferences: HashMap::new(),
            },
        ),
    ];

    for (description, invalid_input) in validation_tests {
        println!("\n2. {}:", description);
        match invalid_input.to_json() {
            Ok(json) => match ValidatedUserInput::from_json(&json) {
                Ok(_) => println!("   ✗ Unexpected: Invalid input was accepted"),
                Err(e) => println!("   ✓ Expected validation error: {}", e),
            },
            Err(e) => println!("   ✗ Serialization error: {}", e),
        }
    }

    // Test preferences validation
    println!("\n3. Preferences Validation:");
    let mut too_many_preferences = HashMap::new();
    for i in 0..25 {
        too_many_preferences.insert(format!("pref_{}", i), "value".to_string());
    }

    let invalid_prefs_input = ValidatedUserInput {
        username: "username".to_string(),
        email: "test@example.com".to_string(),
        age: 25,
        preferences: too_many_preferences,
    };

    match invalid_prefs_input.to_json() {
        Ok(json) => match ValidatedUserInput::from_json(&json) {
            Ok(_) => println!("   ✗ Unexpected: Too many preferences were accepted"),
            Err(e) => println!("   ✓ Expected validation error: {}", e),
        },
        Err(e) => println!("   ✗ Serialization error: {}", e),
    }

    Ok(())
}

/// Demonstrate schema evolution patterns
fn demonstrate_schema_evolution() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Schema Evolution Patterns ---");

    fs::create_dir_all("temp_schema_tests")?;

    // Create data with different schema versions
    println!("Creating data with different schema versions:");

    // Version 1 data (minimal)
    let v1_json = r#"{
        "version": 1,
        "name": "legacy_data",
        "value": 123.45
    }"#;
    fs::write("temp_schema_tests/v1_data.json", v1_json)?;
    println!("  ✓ Version 1 data created (minimal fields)");

    // Version 2 data (with optional field)
    let v2_json = r#"{
        "version": 2,
        "name": "v2_data",
        "value": 678.90,
        "optional_field": "added_in_v2"
    }"#;
    fs::write("temp_schema_tests/v2_data.json", v2_json)?;
    println!("  ✓ Version 2 data created (with optional field)");

    // Version 3 data (with all fields)
    let v3_data = VersionedData {
        version: 3,
        name: "v3_data".to_string(),
        value: 999.99,
        optional_field: Some("present".to_string()),
        new_field: Some(42),
    };
    v3_data.save_json("temp_schema_tests/v3_data.json")?;
    println!("  ✓ Version 3 data created (all fields)");

    // Test backward compatibility
    println!("\nTesting backward compatibility:");

    // Load v1 data with current deserializer
    match VersionedData::load_json("temp_schema_tests/v1_data.json") {
        Ok(data) => {
            println!("  ✓ V1 data loaded successfully:");
            println!("    Name: {}", data.name);
            println!("    Value: {}", data.value);
            println!("    Optional field: {:?}", data.optional_field);
            println!("    New field: {:?}", data.new_field);
        }
        Err(e) => println!("  ✗ Failed to load V1 data: {}", e),
    }

    // Load v2 data with current deserializer
    match VersionedData::load_json("temp_schema_tests/v2_data.json") {
        Ok(data) => {
            println!("  ✓ V2 data loaded successfully:");
            println!("    Name: {}", data.name);
            println!("    Value: {}", data.value);
            println!("    Optional field: {:?}", data.optional_field);
            println!("    New field: {:?}", data.new_field);
        }
        Err(e) => println!("  ✗ Failed to load V2 data: {}", e),
    }

    // Test future version rejection
    println!("\nTesting future version handling:");
    let future_version_json = r#"{
        "version": 99,
        "name": "future_data",
        "value": 123.45,
        "unknown_field": "should_be_ignored"
    }"#;
    fs::write("temp_schema_tests/future_data.json", future_version_json)?;

    match VersionedData::load_json("temp_schema_tests/future_data.json") {
        Ok(_) => println!("  ✗ Unexpected: Future version was accepted"),
        Err(e) => println!("  ✓ Expected rejection of future version: {}", e),
    }

    // Demonstrate migration strategy
    println!("\nDemonstrating migration strategy:");
    println!("  Strategy: Load old format, upgrade to new format, save");

    // Simulate migrating v1 data to v3 format
    let v1_loaded = VersionedData::load_json("temp_schema_tests/v1_data.json")?;
    let v1_upgraded = VersionedData {
        version: 3,
        name: v1_loaded.name,
        value: v1_loaded.value,
        optional_field: Some("migrated_default".to_string()),
        new_field: Some(0),
    };

    v1_upgraded.save_json("temp_schema_tests/v1_migrated.json")?;
    println!("  ✓ V1 data migrated to V3 format");

    Ok(())
}

/// Demonstrate recovery strategies
fn demonstrate_recovery_strategies() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Recovery Strategies ---");

    fs::create_dir_all("temp_recovery_tests")?;

    // Strategy 1: Graceful degradation
    println!("1. Graceful Degradation Strategy:");

    // Create complete data
    let complete_data = RecoverableData {
        critical_field: "essential_info".to_string(),
        important_field: Some("important_info".to_string()),
        optional_field: Some("nice_to_have".to_string()),
        metadata: {
            let mut map = HashMap::new();
            map.insert("key1".to_string(), "value1".to_string());
            map.insert("key2".to_string(), "value2".to_string());
            map
        },
    };

    // Save complete data
    complete_data.save_json("temp_recovery_tests/complete.json")?;

    // Create partial data (missing some fields)
    let partial_json = r#"{
        "critical_field": "essential_info",
        "optional_field": "nice_to_have"
    }"#;
    fs::write("temp_recovery_tests/partial.json", partial_json)?;

    // Load partial data and demonstrate recovery
    match RecoverableData::load_json("temp_recovery_tests/partial.json") {
        Ok(recovered) => {
            println!("  ✓ Partial data recovered successfully:");
            println!("    Critical field: {}", recovered.critical_field);
            println!(
                "    Important field: {:?} (missing, set to None)",
                recovered.important_field
            );
            println!("    Optional field: {:?}", recovered.optional_field);
            println!(
                "    Metadata: {} entries (defaulted to empty)",
                recovered.metadata.len()
            );
        }
        Err(e) => println!("  ✗ Recovery failed: {}", e),
    }

    // Strategy 2: Error context preservation
    println!("\n2. Error Context Preservation:");

    let malformed_json = r#"{
        "critical_field": "essential_info",
        "important_field": 12345,
        "metadata": "not_a_map"
    }"#;
    fs::write("temp_recovery_tests/malformed.json", malformed_json)?;

    match RecoverableData::load_json("temp_recovery_tests/malformed.json") {
        Ok(_) => println!("  ✗ Unexpected: Malformed data was accepted"),
        Err(e) => {
            println!("  ✓ Error context preserved:");
            println!("    Error: {}", e);
            println!("    Error type: {:?}", std::mem::discriminant(&e));
        }
    }

    // Strategy 3: Fallback data sources
    println!("\n3. Fallback Data Sources:");

    // Primary source (corrupted)
    let corrupted_primary = "corrupted data";
    fs::write("temp_recovery_tests/primary.json", corrupted_primary)?;

    // Backup source (valid)
    let backup_data = RecoverableData {
        critical_field: "backup_critical".to_string(),
        important_field: Some("backup_important".to_string()),
        optional_field: None,
        metadata: HashMap::new(),
    };
    backup_data.save_json("temp_recovery_tests/backup.json")?;

    // Default fallback
    let default_data = RecoverableData {
        critical_field: "default_critical".to_string(),
        important_field: None,
        optional_field: None,
        metadata: HashMap::new(),
    };

    println!("  Attempting to load data with fallback chain:");

    // Try primary source
    let loaded_data = match RecoverableData::load_json("temp_recovery_tests/primary.json") {
        Ok(data) => {
            println!("    ✓ Loaded from primary source");
            data
        }
        Err(_) => {
            println!("    ✗ Primary source failed, trying backup");

            // Try backup source
            match RecoverableData::load_json("temp_recovery_tests/backup.json") {
                Ok(data) => {
                    println!("    ✓ Loaded from backup source");
                    data
                }
                Err(_) => {
                    println!("    ✗ Backup source failed, using default");
                    default_data
                }
            }
        }
    };

    println!("  Final loaded data:");
    println!("    Critical field: {}", loaded_data.critical_field);

    Ok(())
}

/// Demonstrate production-ready error handling
fn demonstrate_production_error_handling() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Production Error Handling ---");

    fs::create_dir_all("temp_production_tests")?;

    // Error logging and monitoring
    println!("1. Error Logging and Monitoring:");

    let test_data = VersionedData {
        version: 2,
        name: "production_test".to_string(),
        value: 42.0,
        optional_field: Some("test".to_string()),
        new_field: None,
    };

    // Create error log for demonstration
    let mut error_log = fs::OpenOptions::new()
        .create(true)
        .append(true)
        .open("temp_production_tests/error.log")?;

    // Function to log errors in production format
    let mut log_error =
        |error: &SerializationError, context: &str| -> Result<(), Box<dyn std::error::Error>> {
            let timestamp = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)?
                .as_secs();

            writeln!(error_log, "[{}] ERROR in {}: {}", timestamp, context, error)?;
            Ok(())
        };

    // Simulate various error scenarios with logging
    let error_scenarios = vec![
        ("corrupted_file.json", "invalid json content"),
        ("missing_fields.json", r#"{"version": 1}"#),
        (
            "type_error.json",
            r#"{"version": "not_number", "name": "test", "value": 42.0}"#,
        ),
    ];

    for (filename, content) in error_scenarios {
        let filepath = format!("temp_production_tests/{}", filename);
        fs::write(&filepath, content)?;

        match VersionedData::load_json(&filepath) {
            Ok(_) => println!("  ✗ Unexpected success for {}", filename),
            Err(e) => {
                log_error(&e, &format!("load_config({})", filename))?;
                println!("  ✓ Error logged for {}: {}", filename, e);
            }
        }
    }

    // Health check pattern
    println!("\n2. Health Check Pattern:");

    let health_check = || -> Result<bool, SerializationError> {
        // Check if we can serialize/deserialize basic data
        let test_data = VersionedData {
            version: 1,
            name: "health_check".to_string(),
            value: 1.0,
            optional_field: None,
            new_field: None,
        };

        let serialized = test_data.to_json()?;
        let _deserialized = VersionedData::from_json(&serialized)?;
        Ok(true)
    };

    match health_check() {
        Ok(_) => println!("  ✓ Serialization system health check passed"),
        Err(e) => {
            log_error(&e, "health_check")?;
            println!("  ✗ Serialization system health check failed: {}", e);
        }
    }

    // Circuit breaker pattern simulation
    println!("\n3. Circuit Breaker Pattern:");

    struct CircuitBreaker {
        failure_count: u32,
        failure_threshold: u32,
        is_open: bool,
    }

    impl CircuitBreaker {
        fn new(threshold: u32) -> Self {
            Self {
                failure_count: 0,
                failure_threshold: threshold,
                is_open: false,
            }
        }

        fn call<F, T>(&mut self, operation: F) -> Result<T, String>
        where
            F: FnOnce() -> Result<T, SerializationError>,
        {
            if self.is_open {
                return Err("Circuit breaker is open".to_string());
            }

            match operation() {
                Ok(result) => {
                    self.failure_count = 0; // Reset on success
                    Ok(result)
                }
                Err(e) => {
                    self.failure_count += 1;
                    if self.failure_count >= self.failure_threshold {
                        self.is_open = true;
                        println!(
                            "    Circuit breaker opened after {} failures",
                            self.failure_count
                        );
                    }
                    Err(e.to_string())
                }
            }
        }
    }

    let mut circuit_breaker = CircuitBreaker::new(3);

    // Simulate operations that fail
    for i in 1..=5 {
        let result = circuit_breaker
            .call(|| VersionedData::load_json("temp_production_tests/corrupted_file.json"));

        match result {
            Ok(_) => println!("  Operation {} succeeded", i),
            Err(e) => println!("  Operation {} failed: {}", i, e),
        }
    }

    // Retry mechanism
    println!("\n4. Retry Mechanism:");

    let retry_operation = |max_attempts: u32| -> Result<VersionedData, String> {
        for attempt in 1..=max_attempts {
            println!("    Attempt {}/{}", attempt, max_attempts);

            // Try different sources in order
            let sources = vec![
                "temp_production_tests/corrupted_file.json",
                "temp_production_tests/missing_fields.json",
                "temp_production_tests/backup_valid.json",
            ];

            if attempt == max_attempts {
                // On final attempt, create valid backup
                test_data
                    .save_json("temp_production_tests/backup_valid.json")
                    .map_err(|e| format!("Failed to create backup: {}", e))?;
            }

            for source in &sources {
                match VersionedData::load_json(source) {
                    Ok(data) => {
                        println!("    ✓ Succeeded loading from {}", source);
                        return Ok(data);
                    }
                    Err(_) => {
                        println!("    ✗ Failed to load from {}", source);
                        continue;
                    }
                }
            }

            if attempt < max_attempts {
                println!("    Waiting before retry...");
                // In real code, would sleep here
            }
        }

        Err("All retry attempts exhausted".to_string())
    };

    match retry_operation(3) {
        Ok(data) => println!("  ✓ Retry succeeded: {}", data.name),
        Err(e) => println!("  ✗ Retry failed: {}", e),
    }

    Ok(())
}

examples/serialization/json_vs_binary.rs (line 90)

    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,
        })
    }
}

impl ToFieldValue for Configuration {
    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 Configuration {
    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 Configuration 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 Configuration from binary: {}", e),
                }
            });
        }

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

/// Format comparison results
#[derive(Debug)]
pub struct FormatComparison {
    pub data_type: String,
    pub json_size_bytes: u64,
    pub binary_size_bytes: u64,
    pub json_serialize_micros: u64,
    pub binary_serialize_micros: u64,
    pub json_deserialize_micros: u64,
    pub binary_deserialize_micros: u64,
    pub size_ratio: f64,
    pub serialize_speed_ratio: f64,
    pub deserialize_speed_ratio: f64,
}

impl FormatComparison {
    fn new(data_type: String) -> Self {
        Self {
            data_type,
            json_size_bytes: 0,
            binary_size_bytes: 0,
            json_serialize_micros: 0,
            binary_serialize_micros: 0,
            json_deserialize_micros: 0,
            binary_deserialize_micros: 0,
            size_ratio: 0.0,
            serialize_speed_ratio: 0.0,
            deserialize_speed_ratio: 0.0,
        }
    }

    fn calculate_ratios(&mut self) {
        self.size_ratio = self.json_size_bytes as f64 / self.binary_size_bytes as f64;
        self.serialize_speed_ratio =
            self.binary_serialize_micros as f64 / self.json_serialize_micros as f64;
        self.deserialize_speed_ratio =
            self.binary_deserialize_micros as f64 / self.json_deserialize_micros as f64;
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== JSON vs Binary Format Comparison Example ===\n");

    demonstrate_format_characteristics()?;
    demonstrate_size_comparisons()?;
    demonstrate_performance_benchmarks()?;
    demonstrate_use_case_recommendations()?;
    demonstrate_debugging_capabilities()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate basic format characteristics
fn demonstrate_format_characteristics() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Format Characteristics ---");

    // Create sample data structures
    let mut metadata = HashMap::new();
    metadata.insert("operation_type".to_string(), "benchmark".to_string());
    metadata.insert("system".to_string(), "train_station".to_string());

    let metrics = PerformanceMetrics {
        operation: "tensor_multiplication".to_string(),
        duration_micros: 1234,
        memory_usage_bytes: 8192,
        cpu_usage_percent: 75.5,
        throughput_ops_per_sec: 1000.0,
        metadata,
    };

    println!("Format characteristics analysis:");

    // JSON characteristics
    let json_data = metrics.to_json()?;
    let json_lines = json_data.lines().count();
    let json_chars = json_data.chars().count();

    println!("\nJSON Format:");
    println!("  Size: {} bytes", json_data.len());
    println!("  Characters: {}", json_chars);
    println!("  Lines: {}", json_lines);
    println!("  Human readable: Yes");
    println!("  Self-describing: Yes");
    println!("  Cross-platform: Yes");
    println!("  Compression ratio: Variable (depends on content)");

    // Show sample JSON output
    println!("  Sample output:");
    for line in json_data.lines().take(3) {
        println!("    {}", line);
    }
    if json_lines > 3 {
        println!("    ... ({} more lines)", json_lines - 3);
    }

    // Binary characteristics
    let binary_data = metrics.to_binary()?;

    println!("\nBinary Format:");
    println!("  Size: {} bytes", binary_data.len());
    println!("  Human readable: No");
    println!("  Self-describing: No (requires schema)");
    println!("  Cross-platform: Yes (with proper endianness handling)");
    println!("  Compression ratio: High (efficient encoding)");

    // Show sample binary output (hex)
    println!("  Sample output (first 32 bytes as hex):");
    print!("    ");
    for (i, byte) in binary_data.iter().take(32).enumerate() {
        if i > 0 && i % 16 == 0 {
            println!();
            print!("    ");
        }
        print!("{:02x} ", byte);
    }
    if binary_data.len() > 32 {
        println!("\n    ... ({} more bytes)", binary_data.len() - 32);
    } else {
        println!();
    }

    // Verify roundtrip for both formats
    let json_parsed = PerformanceMetrics::from_json(&json_data)?;
    let binary_parsed = PerformanceMetrics::from_binary(&binary_data)?;

    assert_eq!(metrics, json_parsed);
    assert_eq!(metrics, binary_parsed);
    println!("\nRoundtrip verification: PASSED");

    Ok(())
}

/// Demonstrate size comparisons across different data types
fn demonstrate_size_comparisons() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Size Comparison Analysis ---");

    // Test 1: Small configuration data (typical JSON use case)
    let mut db_settings = HashMap::new();
    db_settings.insert("host".to_string(), "localhost".to_string());
    db_settings.insert("port".to_string(), "5432".to_string());
    db_settings.insert("database".to_string(), "myapp".to_string());

    let config = Configuration {
        version: "1.2.3".to_string(),
        debug_enabled: true,
        log_level: "info".to_string(),
        database_settings: db_settings,
        feature_flags_enabled: true,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    // Test 2: Large numeric dataset (typical binary use case)
    let large_dataset = LargeDataset {
        name: "ML Training Data".to_string(),
        values: (0..1000).map(|i| i as f32 * 0.1).collect(),
        labels: (0..1000).map(|i| format!("label_{}", i)).collect(),
        feature_count: 100,
        feature_dimension: 50,
        timestamp_count: 1000,
        metadata: HashMap::new(),
    };

    println!("Size comparison results:");

    // Configuration comparison
    let config_json = config.to_json()?;
    let config_binary = config.to_binary()?;

    println!("\nConfiguration Data (small, text-heavy):");
    println!("  JSON: {} bytes", config_json.len());
    println!("  Binary: {} bytes", config_binary.len());
    println!(
        "  Ratio (JSON/Binary): {:.2}x",
        config_json.len() as f64 / config_binary.len() as f64
    );
    println!("  Recommendation: JSON (human readable, small size difference)");

    // Large dataset comparison
    let dataset_json = large_dataset.to_json()?;
    let dataset_binary = large_dataset.to_binary()?;

    println!("\nLarge Numeric Dataset (1000 values, 100x50 matrix):");
    println!(
        "  JSON: {} bytes ({:.1} KB)",
        dataset_json.len(),
        dataset_json.len() as f64 / 1024.0
    );
    println!(
        "  Binary: {} bytes ({:.1} KB)",
        dataset_binary.len(),
        dataset_binary.len() as f64 / 1024.0
    );
    println!(
        "  Ratio (JSON/Binary): {:.2}x",
        dataset_json.len() as f64 / dataset_binary.len() as f64
    );
    if dataset_json.len() > dataset_binary.len() {
        println!(
            "  Space saved with binary: {} bytes ({:.1} KB)",
            dataset_json.len() - dataset_binary.len(),
            (dataset_json.len() - dataset_binary.len()) as f64 / 1024.0
        );
        println!("  Recommendation: Binary (significant size reduction)");
    } else {
        println!(
            "  Binary overhead: {} bytes ({:.1} KB)",
            dataset_binary.len() - dataset_json.len(),
            (dataset_binary.len() - dataset_json.len()) as f64 / 1024.0
        );
        println!("  Recommendation: JSON (binary overhead not justified for this size)");
    }

    // Content analysis
    println!("\nContent Type Analysis:");

    // Analyze JSON content patterns
    let json_numbers = dataset_json.matches(char::is_numeric).count();
    let json_brackets = dataset_json.matches('[').count() + dataset_json.matches(']').count();
    let json_quotes = dataset_json.matches('"').count();

    println!("  JSON overhead sources:");
    println!("    Numeric characters: ~{}", json_numbers);
    println!("    Brackets and commas: ~{}", json_brackets);
    println!("    Quote marks: {}", json_quotes);
    println!("    Formatting/whitespace: Varies");

    println!("  Binary advantages:");
    println!("    Direct numeric encoding: 4-8 bytes per number");
    println!("    No formatting overhead: Zero bytes");
    println!("    Efficient length encoding: Minimal bytes");

    Ok(())
}

/// Demonstrate performance benchmarks
fn demonstrate_performance_benchmarks() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Performance Benchmark Analysis ---");

    // Create test data of varying sizes
    let small_config = Configuration {
        version: "1.0.0".to_string(),
        debug_enabled: false,
        log_level: "warn".to_string(),
        database_settings: HashMap::new(),
        feature_flags_enabled: false,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    let large_dataset = LargeDataset {
        name: "Large Dataset".to_string(),
        values: (0..5000).map(|i| i as f32 * 0.001).collect(),
        labels: (0..5000).map(|i| format!("large_item_{}", i)).collect(),
        feature_count: 200,
        feature_dimension: 25,
        timestamp_count: 5000,
        metadata: HashMap::new(),
    };

    println!("Performance benchmark results:");

    // Benchmark each dataset (avoiding trait objects due to object safety)
    let dataset_names = ["Small Config", "Large Dataset"];

    for (i, name) in dataset_names.iter().enumerate() {
        let mut comparison = FormatComparison::new(name.to_string());

        // JSON serialization benchmark
        let start = Instant::now();
        let json_data = match i {
            0 => small_config.to_json()?,
            _ => large_dataset.to_json()?,
        };
        comparison.json_serialize_micros = start.elapsed().as_micros() as u64;
        comparison.json_size_bytes = json_data.len() as u64;

        // JSON deserialization benchmark (using PerformanceMetrics as example)
        if *name == "Small Config" {
            let start = Instant::now();
            let _parsed = Configuration::from_json(&json_data)?;
            comparison.json_deserialize_micros = start.elapsed().as_micros() as u64;
        } else {
            let start = Instant::now();
            let _parsed = LargeDataset::from_json(&json_data)?;
            comparison.json_deserialize_micros = start.elapsed().as_micros() as u64;
        }

        // Binary serialization benchmark
        let start = Instant::now();
        let binary_data = match i {
            0 => small_config.to_binary()?,
            _ => large_dataset.to_binary()?,
        };
        comparison.binary_serialize_micros = start.elapsed().as_micros() as u64;
        comparison.binary_size_bytes = binary_data.len() as u64;

        // Binary deserialization benchmark
        if *name == "Small Config" {
            let start = Instant::now();
            let _parsed = Configuration::from_binary(&binary_data)?;
            comparison.binary_deserialize_micros = start.elapsed().as_micros() as u64;
        } else {
            let start = Instant::now();
            let _parsed = LargeDataset::from_binary(&binary_data)?;
            comparison.binary_deserialize_micros = start.elapsed().as_micros() as u64;
        }

        // Calculate ratios
        comparison.calculate_ratios();

        // Display results
        println!("\n{}:", name);
        println!(
            "  Size - JSON: {} bytes, Binary: {} bytes (ratio: {:.2}x)",
            comparison.json_size_bytes, comparison.binary_size_bytes, comparison.size_ratio
        );
        println!(
            "  Serialize - JSON: {}μs, Binary: {}μs (binary relative speed: {:.2}x)",
            comparison.json_serialize_micros,
            comparison.binary_serialize_micros,
            comparison.serialize_speed_ratio
        );
        println!(
            "  Deserialize - JSON: {}μs, Binary: {}μs (binary relative speed: {:.2}x)",
            comparison.json_deserialize_micros,
            comparison.binary_deserialize_micros,
            comparison.deserialize_speed_ratio
        );
    }

    println!("\nPerformance Summary:");
    println!("  - Binary format consistently uses less storage space");
    println!("  - Performance differences vary by data type and size");
    println!("  - Larger datasets show more significant binary advantages");
    println!("  - JSON parsing overhead increases with structure complexity");

    Ok(())
}

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

Creates the struct from binary data

Deserializes binary data into a new instance of the struct. The binary data should contain all required fields in the expected format.

Arguments

• data - Binary data containing the struct data

Returns

Ok(Self) on successful deserialization Err(SerializationError) if binary parsing or deserialization fails

Examples

Creates struct from binary data with proper parsing and validation.

Examples found in repository

examples/serialization/basic_structs.rs (line 102)

    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,
        })
    }
}

impl ToFieldValue for AppSettings {
    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) => FieldValue::from_json_object(json_str),
            Err(_) => FieldValue::from_string("serialization_error".to_string()),
        }
    }
}

impl FromFieldValue for AppSettings {
    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 AppSettings 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 AppSettings from binary: {}", e),
                }
            });
        }

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Basic Struct Serialization Example ===\n");

    demonstrate_user_profile_serialization()?;
    demonstrate_app_settings_serialization()?;
    demonstrate_format_comparison()?;
    demonstrate_roundtrip_verification()?;
    demonstrate_field_access_patterns()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate basic struct serialization with simple field types
fn demonstrate_user_profile_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- User Profile Serialization ---");

    // Create a user profile with various field types
    let user = UserProfile {
        id: 12345,
        username: "alice_cooper".to_string(),
        email: "alice@example.com".to_string(),
        age: 28,
        is_active: true,
        score: 95.7,
    };

    println!("Original user profile:");
    println!("  ID: {}", user.id);
    println!("  Username: {}", user.username);
    println!("  Email: {}", user.email);
    println!("  Age: {}", user.age);
    println!("  Active: {}", user.is_active);
    println!("  Score: {}", user.score);

    // Serialize to JSON
    let json_data = user.to_json()?;
    println!("\nSerialized to JSON:");
    println!("{}", json_data);

    // Save to JSON file
    user.save_json("temp_user_profile.json")?;
    println!("Saved to file: temp_user_profile.json");

    // Load from JSON file
    let loaded_user = UserProfile::load_json("temp_user_profile.json")?;
    println!("\nLoaded user profile:");
    println!("  ID: {}", loaded_user.id);
    println!("  Username: {}", loaded_user.username);
    println!("  Email: {}", loaded_user.email);
    println!("  Age: {}", loaded_user.age);
    println!("  Active: {}", loaded_user.is_active);
    println!("  Score: {}", loaded_user.score);

    // Verify data integrity
    assert_eq!(user, loaded_user);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate serialization with collections and optional fields
fn demonstrate_app_settings_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- App Settings Serialization ---");

    // Create app settings with collections and optional fields
    let mut env_vars = HashMap::new();
    env_vars.insert("LOG_LEVEL".to_string(), "info".to_string());
    env_vars.insert("PORT".to_string(), "8080".to_string());
    env_vars.insert("HOST".to_string(), "localhost".to_string());

    let settings = AppSettings {
        app_name: "Train Station Example".to_string(),
        version: "1.0.0".to_string(),
        debug_mode: true,
        max_connections: 100,
        timeout_seconds: 30.5,
        features: vec![
            "authentication".to_string(),
            "logging".to_string(),
            "metrics".to_string(),
        ],
        environment_vars: env_vars,
        optional_database_url: Some("postgresql://localhost:5432/mydb".to_string()),
    };

    println!("Original app settings:");
    println!("  App Name: {}", settings.app_name);
    println!("  Version: {}", settings.version);
    println!("  Debug Mode: {}", settings.debug_mode);
    println!("  Max Connections: {}", settings.max_connections);
    println!("  Timeout: {} seconds", settings.timeout_seconds);
    println!("  Features: {:?}", settings.features);
    println!("  Environment Variables: {:?}", settings.environment_vars);
    println!("  Database URL: {:?}", settings.optional_database_url);

    // Serialize to binary format for efficient storage
    let binary_data = settings.to_binary()?;
    println!("\nSerialized to binary: {} bytes", binary_data.len());

    // Save to binary file
    settings.save_binary("temp_app_settings.bin")?;
    println!("Saved to file: temp_app_settings.bin");

    // Load from binary file
    let loaded_settings = AppSettings::load_binary("temp_app_settings.bin")?;
    println!("\nLoaded app settings:");
    println!("  App Name: {}", loaded_settings.app_name);
    println!("  Version: {}", loaded_settings.version);
    println!("  Debug Mode: {}", loaded_settings.debug_mode);
    println!("  Features count: {}", loaded_settings.features.len());
    println!(
        "  Environment variables count: {}",
        loaded_settings.environment_vars.len()
    );

    // Verify data integrity
    assert_eq!(settings, loaded_settings);
    println!("Data integrity verification: PASSED");

    Ok(())
}

/// Demonstrate format comparison between JSON and binary
fn demonstrate_format_comparison() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Format Comparison ---");

    let user = UserProfile {
        id: 98765,
        username: "bob_builder".to_string(),
        email: "bob@construction.com".to_string(),
        age: 35,
        is_active: false,
        score: 87.2,
    };

    // Save in both formats
    user.save_json("temp_format_comparison.json")?;
    user.save_binary("temp_format_comparison.bin")?;

    // Compare file sizes
    let json_size = fs::metadata("temp_format_comparison.json")?.len();
    let binary_size = fs::metadata("temp_format_comparison.bin")?.len();

    println!("Format comparison for UserProfile:");
    println!("  JSON file size: {} bytes", json_size);
    println!("  Binary file size: {} bytes", binary_size);
    println!(
        "  Size ratio (JSON/Binary): {:.2}x",
        json_size as f64 / binary_size as f64
    );

    // Demonstrate readability
    let json_content = fs::read_to_string("temp_format_comparison.json")?;
    println!("\nJSON format (human-readable):");
    println!("{}", json_content);

    println!("\nBinary format (first 32 bytes as hex):");
    let binary_content = fs::read("temp_format_comparison.bin")?;
    for (i, byte) in binary_content.iter().take(32).enumerate() {
        if i % 16 == 0 && i > 0 {
            println!();
        }
        print!("{:02x} ", byte);
    }
    println!("\n... ({} total bytes)", binary_content.len());

    // Load and verify both formats produce identical results
    let json_loaded = UserProfile::load_json("temp_format_comparison.json")?;
    let binary_loaded = UserProfile::load_binary("temp_format_comparison.bin")?;

    assert_eq!(json_loaded, binary_loaded);
    println!("\nFormat consistency verification: PASSED");

    Ok(())
}

/// Demonstrate roundtrip verification with multiple data variations
fn demonstrate_roundtrip_verification() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Roundtrip Verification ---");

    // Test various data patterns
    let test_users = [
        UserProfile {
            id: 0,
            username: "".to_string(),
            email: "empty@test.com".to_string(),
            age: 0,
            is_active: false,
            score: 0.0,
        },
        UserProfile {
            id: u32::MAX,
            username: "maximal_user_with_very_long_name_123456789".to_string(),
            email: "test@verylongdomainname.example.org".to_string(),
            age: i32::MAX,
            is_active: true,
            score: 999999.5,
        },
        UserProfile {
            id: 42,
            username: "unicode_tëst_🦀".to_string(),
            email: "unicode@tëst.com".to_string(),
            age: 25,
            is_active: true,
            score: -123.456,
        },
    ];

    println!(
        "Testing roundtrip serialization with {} variations:",
        test_users.len()
    );

    for (i, user) in test_users.iter().enumerate() {
        println!(
            "  Test case {}: ID={}, Username='{}'",
            i + 1,
            user.id,
            user.username
        );

        // JSON roundtrip
        let json_data = user.to_json()?;
        let json_parsed = UserProfile::from_json(&json_data)?;
        assert_eq!(*user, json_parsed);

        // Binary roundtrip
        let binary_data = user.to_binary()?;
        let binary_parsed = UserProfile::from_binary(&binary_data)?;
        assert_eq!(*user, binary_parsed);

        println!("    JSON roundtrip: PASSED");
        println!("    Binary roundtrip: PASSED");
    }

    println!("All roundtrip tests: PASSED");

    Ok(())
}

examples/serialization/nested_structures.rs (line 94)

    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,
        })
    }
}

impl ToFieldValue for Department {
    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 Department {
    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 Department 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 Department from binary: {}", e),
                }
            });
        }

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Nested Structures Serialization Example ===\n");

    demonstrate_nested_struct_creation()?;
    demonstrate_deep_serialization()?;
    demonstrate_collection_nesting()?;
    demonstrate_partial_loading()?;
    demonstrate_performance_analysis()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate creating complex nested structures
fn demonstrate_nested_struct_creation() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Nested Structure Creation ---");

    // Create nested address and contact info
    let headquarters = Address {
        street: "123 Innovation Drive".to_string(),
        city: "Tech City".to_string(),
        state: "CA".to_string(),
        postal_code: "94000".to_string(),
        country: "USA".to_string(),
    };

    let mut social_media = HashMap::new();
    social_media.insert("twitter".to_string(), "@techcorp".to_string());
    social_media.insert("linkedin".to_string(), "techcorp-inc".to_string());

    let contact_info = ContactInfo {
        email: "info@techcorp.com".to_string(),
        phone: Some("+1-555-0123".to_string()),
        address_city: headquarters.city.clone(),
        address_state: headquarters.state.clone(),
        social_media,
    };

    // Create departments with nested office locations
    let engineering_office = Address {
        street: "456 Developer Lane".to_string(),
        city: "Code City".to_string(),
        state: "CA".to_string(),
        postal_code: "94001".to_string(),
        country: "USA".to_string(),
    };

    let departments = [
        Department {
            name: "Engineering".to_string(),
            manager: "Alice Johnson".to_string(),
            employee_count: 50,
            budget: 2500000.0,
            office_locations: vec![engineering_office, headquarters.clone()],
        },
        Department {
            name: "Marketing".to_string(),
            manager: "Bob Smith".to_string(),
            employee_count: 15,
            budget: 800000.0,
            office_locations: vec![headquarters.clone()],
        },
    ];

    // Create projects with milestones
    let milestones = vec![
        Milestone {
            name: "Requirements Analysis".to_string(),
            description: "Complete system requirements documentation".to_string(),
            due_date: "2024-03-15".to_string(),
            is_completed: true,
            progress_percentage: 100.0,
            dependencies: vec![],
        },
        Milestone {
            name: "Architecture Design".to_string(),
            description: "Define system architecture and components".to_string(),
            due_date: "2024-04-01".to_string(),
            is_completed: false,
            progress_percentage: 75.0,
            dependencies: vec!["Requirements Analysis".to_string()],
        },
    ];

    let mut project_metadata = HashMap::new();
    project_metadata.insert("priority".to_string(), "high".to_string());
    project_metadata.insert("client".to_string(), "internal".to_string());

    let projects = [Project {
        name: "Train Station ML Platform".to_string(),
        description: "Next-generation machine learning infrastructure".to_string(),
        status: ProjectStatus::InProgress,
        budget: 1500000.0,
        team_members: vec![
            "Alice Johnson".to_string(),
            "Charlie Brown".to_string(),
            "Diana Prince".to_string(),
        ],
        milestones: milestones.clone(),
        metadata: project_metadata,
    }];

    // Create the complete company structure
    let mut company_metadata = HashMap::new();
    company_metadata.insert("industry".to_string(), "technology".to_string());
    company_metadata.insert("stock_symbol".to_string(), "TECH".to_string());

    let company = Company {
        name: "TechCorp Inc.".to_string(),
        founded_year: 2015,
        headquarters_city: headquarters.city.clone(),
        headquarters_state: headquarters.state.clone(),
        employee_count: 250,
        department_names: departments.iter().map(|d| d.name.clone()).collect(),
        active_project_names: projects.iter().map(|p| p.name.clone()).collect(),
        company_metadata,
    };

    println!("Created complex company structure:");
    println!("  Company: {}", company.name);
    println!("  Founded: {}", company.founded_year);
    println!(
        "  Headquarters: {}, {}",
        company.headquarters_city, company.headquarters_state
    );
    println!("  Employee Count: {}", company.employee_count);
    println!("  Departments: {}", company.department_names.len());
    println!("  Active Projects: {}", company.active_project_names.len());

    // Save the complete structure
    company.save_json("temp_nested_company.json")?;
    println!("Saved nested structure to: temp_nested_company.json");

    // Verify loading preserves all nested data
    let loaded_company = Company::load_json("temp_nested_company.json")?;
    assert_eq!(company, loaded_company);
    println!("Successfully verified Company roundtrip serialization");

    // Also demonstrate individual component serialization
    let address_json = headquarters.to_json()?;
    let loaded_address = Address::from_json(&address_json)?;
    assert_eq!(headquarters, loaded_address);
    println!("Successfully serialized/deserialized Address component");

    let contact_json = contact_info.to_json()?;
    let loaded_contact = ContactInfo::from_json(&contact_json)?;
    assert_eq!(contact_info, loaded_contact);
    println!("Successfully serialized/deserialized ContactInfo component");
    println!("Nested structure integrity: VERIFIED");

    Ok(())
}

/// Demonstrate deep serialization with complex nesting
fn demonstrate_deep_serialization() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Deep Serialization Analysis ---");

    let deep_milestone = Milestone {
        name: "Deep Milestone".to_string(),
        description: "Testing deep nesting serialization".to_string(),
        due_date: "2024-12-31".to_string(),
        is_completed: false,
        progress_percentage: 50.0,
        dependencies: vec!["Parent Task".to_string(), "Sibling Task".to_string()],
    };

    let deep_project = Project {
        name: "Deep Nesting Test".to_string(),
        description: "Project for testing serialization depth".to_string(),
        status: ProjectStatus::Planning,
        budget: 100000.0,
        team_members: vec!["Developer 1".to_string(), "Developer 2".to_string()],
        milestones: vec![deep_milestone],
        metadata: HashMap::new(),
    };

    // Analyze serialization output
    let json_output = deep_project.to_json()?;
    let binary_output = deep_project.to_binary()?;

    println!("Deep structure serialization analysis:");
    println!("  JSON size: {} bytes", json_output.len());
    println!("  Binary size: {} bytes", binary_output.len());
    println!("  Nesting levels: Address -> Project -> Milestone -> Dependencies");

    // Count nested objects in JSON (rough estimate)
    let object_count = json_output.matches('{').count();
    let array_count = json_output.matches('[').count();
    println!("  JSON objects: {}", object_count);
    println!("  JSON arrays: {}", array_count);

    // Verify deep roundtrip
    let json_parsed = Project::from_json(&json_output)?;
    let binary_parsed = Project::from_binary(&binary_output)?;

    assert_eq!(deep_project, json_parsed);
    assert_eq!(deep_project, binary_parsed);
    println!("Deep serialization roundtrip: VERIFIED");

    Ok(())
}

/// Demonstrate collection nesting patterns
fn demonstrate_collection_nesting() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Collection Nesting Patterns ---");

    // Create multiple departments with varying complexity
    let departments = vec![
        Department {
            name: "Research".to_string(),
            manager: "Dr. Science".to_string(),
            employee_count: 25,
            budget: 1200000.0,
            office_locations: vec![
                Address {
                    street: "1 Research Blvd".to_string(),
                    city: "Innovation Hub".to_string(),
                    state: "MA".to_string(),
                    postal_code: "02101".to_string(),
                    country: "USA".to_string(),
                },
                Address {
                    street: "2 Lab Street".to_string(),
                    city: "Tech Valley".to_string(),
                    state: "NY".to_string(),
                    postal_code: "12180".to_string(),
                    country: "USA".to_string(),
                },
            ],
        },
        Department {
            name: "Quality Assurance".to_string(),
            manager: "Test Master".to_string(),
            employee_count: 12,
            budget: 600000.0,
            office_locations: vec![], // Empty collection
        },
    ];

    println!("Collection nesting analysis:");
    println!("  Departments: {}", departments.len());

    let total_locations: usize = departments.iter().map(|d| d.office_locations.len()).sum();
    println!("  Total office locations: {}", total_locations);

    // Test serialization with mixed empty and populated collections
    // Note: Vec<Department> doesn't implement StructSerializable directly.
    // For this example, we'll serialize each department individually
    let department_json_strings: Result<Vec<String>, _> =
        departments.iter().map(|dept| dept.to_json()).collect();
    let department_json_strings = department_json_strings?;

    // Deserialize each department back
    let parsed_departments: Result<Vec<Department>, _> = department_json_strings
        .iter()
        .map(|json_str| Department::from_json(json_str))
        .collect();
    let parsed_departments = parsed_departments?;

    assert_eq!(departments, parsed_departments);
    println!("Collection nesting serialization: VERIFIED");

    // Analyze collection patterns
    for (i, dept) in departments.iter().enumerate() {
        println!(
            "  Department {}: {} locations",
            i + 1,
            dept.office_locations.len()
        );
    }

    Ok(())
}

/// Demonstrate partial loading and field access
fn demonstrate_partial_loading() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Partial Loading and Field Access ---");

    // Create a simple project for analysis
    let project = Project {
        name: "Sample Project".to_string(),
        description: "For testing partial loading".to_string(),
        status: ProjectStatus::InProgress,
        budget: 50000.0,
        team_members: vec!["Alice".to_string(), "Bob".to_string()],
        milestones: vec![Milestone {
            name: "Phase 1".to_string(),
            description: "Initial phase".to_string(),
            due_date: "2024-06-01".to_string(),
            is_completed: true,
            progress_percentage: 100.0,
            dependencies: vec![],
        }],
        metadata: HashMap::new(),
    };

    // Convert to JSON and analyze structure
    println!("Project JSON structure analysis:");

    // Parse to examine available fields by inspecting JSON structure
    let json_data = project.to_json()?;
    let field_count = json_data.matches(':').count();
    println!("  Estimated fields: {}", field_count);

    // Show top-level structure
    let lines: Vec<&str> = json_data.lines().take(10).collect();
    println!("  JSON structure preview:");
    for line in lines.iter().take(5) {
        if let Some(colon_pos) = line.find(':') {
            let field_name = line[..colon_pos].trim().trim_matches('"').trim();
            if !field_name.is_empty() {
                println!("    - {}", field_name);
            }
        }
    }

    // Demonstrate field type analysis
    println!("\nField type analysis:");
    println!("  name: String");
    println!("  status: Enum -> String");
    println!("  budget: f64 -> Number");
    println!("  team_members: Vec<String> -> Array");
    println!("  milestones: Vec<Milestone> -> Array of Objects");

    Ok(())
}

/// Demonstrate performance analysis for nested structures
fn demonstrate_performance_analysis() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Performance Analysis ---");

    // Create structures of varying complexity
    let simple_address = Address {
        street: "123 Main St".to_string(),
        city: "Anytown".to_string(),
        state: "ST".to_string(),
        postal_code: "12345".to_string(),
        country: "USA".to_string(),
    };

    let complex_department = Department {
        name: "Complex Department".to_string(),
        manager: "Manager Name".to_string(),
        employee_count: 100,
        budget: 5000000.0,
        office_locations: vec![simple_address.clone(); 10], // 10 identical addresses
    };

    let complex_project = Project {
        name: "Complex Project".to_string(),
        description: "Large project with many components".to_string(),
        status: ProjectStatus::InProgress,
        budget: 2000000.0,
        team_members: (1..=50).map(|i| format!("Team Member {}", i)).collect(),
        milestones: (1..=20)
            .map(|i| Milestone {
                name: format!("Milestone {}", i),
                description: format!("Description for milestone {}", i),
                due_date: "2024-12-31".to_string(),
                is_completed: i <= 10,
                progress_percentage: if i <= 10 { 100.0 } else { 50.0 },
                dependencies: if i > 1 {
                    vec![format!("Milestone {}", i - 1)]
                } else {
                    vec![]
                },
            })
            .collect(),
        metadata: HashMap::new(),
    };

    // Measure serialization performance
    println!("Performance comparison:");

    // Simple address
    let addr_json = simple_address.to_json()?;
    let addr_binary = simple_address.to_binary()?;
    println!("  Simple Address:");
    println!("    JSON: {} bytes", addr_json.len());
    println!("    Binary: {} bytes", addr_binary.len());

    // Complex department
    let dept_json = complex_department.to_json()?;
    let dept_binary = complex_department.to_binary()?;
    println!("  Complex Department (10 addresses):");
    println!("    JSON: {} bytes", dept_json.len());
    println!("    Binary: {} bytes", dept_binary.len());

    // Complex project
    let proj_json = complex_project.to_json()?;
    let proj_binary = complex_project.to_binary()?;
    println!("  Complex Project (50 members, 20 milestones):");
    println!("    JSON: {} bytes", proj_json.len());
    println!("    Binary: {} bytes", proj_binary.len());

    // Calculate efficiency ratios
    let dept_ratio = dept_json.len() as f64 / dept_binary.len() as f64;
    let proj_ratio = proj_json.len() as f64 / proj_binary.len() as f64;

    println!("\nFormat efficiency (JSON/Binary ratio):");
    println!("  Department: {:.2}x", dept_ratio);
    println!("  Project: {:.2}x", proj_ratio);

    // Verify complex structure roundtrip
    let proj_json_parsed = Project::from_json(&proj_json)?;
    let proj_binary_parsed = Project::from_binary(&proj_binary)?;

    assert_eq!(complex_project, proj_json_parsed);
    assert_eq!(complex_project, proj_binary_parsed);
    println!("Complex structure roundtrip: VERIFIED");

    Ok(())
}

examples/serialization/error_handling.rs (line 105)

    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,
        })
    }
}

impl ToFieldValue for RecoverableData {
    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 RecoverableData {
    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 RecoverableData 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 RecoverableData from binary: {}", e),
                }
            });
        }

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

examples/serialization/json_vs_binary.rs (line 98)

    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,
        })
    }
}

impl ToFieldValue for Configuration {
    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 Configuration {
    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 Configuration 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 Configuration from binary: {}", e),
                }
            });
        }

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

/// Format comparison results
#[derive(Debug)]
pub struct FormatComparison {
    pub data_type: String,
    pub json_size_bytes: u64,
    pub binary_size_bytes: u64,
    pub json_serialize_micros: u64,
    pub binary_serialize_micros: u64,
    pub json_deserialize_micros: u64,
    pub binary_deserialize_micros: u64,
    pub size_ratio: f64,
    pub serialize_speed_ratio: f64,
    pub deserialize_speed_ratio: f64,
}

impl FormatComparison {
    fn new(data_type: String) -> Self {
        Self {
            data_type,
            json_size_bytes: 0,
            binary_size_bytes: 0,
            json_serialize_micros: 0,
            binary_serialize_micros: 0,
            json_deserialize_micros: 0,
            binary_deserialize_micros: 0,
            size_ratio: 0.0,
            serialize_speed_ratio: 0.0,
            deserialize_speed_ratio: 0.0,
        }
    }

    fn calculate_ratios(&mut self) {
        self.size_ratio = self.json_size_bytes as f64 / self.binary_size_bytes as f64;
        self.serialize_speed_ratio =
            self.binary_serialize_micros as f64 / self.json_serialize_micros as f64;
        self.deserialize_speed_ratio =
            self.binary_deserialize_micros as f64 / self.json_deserialize_micros as f64;
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== JSON vs Binary Format Comparison Example ===\n");

    demonstrate_format_characteristics()?;
    demonstrate_size_comparisons()?;
    demonstrate_performance_benchmarks()?;
    demonstrate_use_case_recommendations()?;
    demonstrate_debugging_capabilities()?;
    cleanup_temp_files()?;

    println!("\n=== Example completed successfully! ===");
    Ok(())
}

/// Demonstrate basic format characteristics
fn demonstrate_format_characteristics() -> Result<(), Box<dyn std::error::Error>> {
    println!("--- Format Characteristics ---");

    // Create sample data structures
    let mut metadata = HashMap::new();
    metadata.insert("operation_type".to_string(), "benchmark".to_string());
    metadata.insert("system".to_string(), "train_station".to_string());

    let metrics = PerformanceMetrics {
        operation: "tensor_multiplication".to_string(),
        duration_micros: 1234,
        memory_usage_bytes: 8192,
        cpu_usage_percent: 75.5,
        throughput_ops_per_sec: 1000.0,
        metadata,
    };

    println!("Format characteristics analysis:");

    // JSON characteristics
    let json_data = metrics.to_json()?;
    let json_lines = json_data.lines().count();
    let json_chars = json_data.chars().count();

    println!("\nJSON Format:");
    println!("  Size: {} bytes", json_data.len());
    println!("  Characters: {}", json_chars);
    println!("  Lines: {}", json_lines);
    println!("  Human readable: Yes");
    println!("  Self-describing: Yes");
    println!("  Cross-platform: Yes");
    println!("  Compression ratio: Variable (depends on content)");

    // Show sample JSON output
    println!("  Sample output:");
    for line in json_data.lines().take(3) {
        println!("    {}", line);
    }
    if json_lines > 3 {
        println!("    ... ({} more lines)", json_lines - 3);
    }

    // Binary characteristics
    let binary_data = metrics.to_binary()?;

    println!("\nBinary Format:");
    println!("  Size: {} bytes", binary_data.len());
    println!("  Human readable: No");
    println!("  Self-describing: No (requires schema)");
    println!("  Cross-platform: Yes (with proper endianness handling)");
    println!("  Compression ratio: High (efficient encoding)");

    // Show sample binary output (hex)
    println!("  Sample output (first 32 bytes as hex):");
    print!("    ");
    for (i, byte) in binary_data.iter().take(32).enumerate() {
        if i > 0 && i % 16 == 0 {
            println!();
            print!("    ");
        }
        print!("{:02x} ", byte);
    }
    if binary_data.len() > 32 {
        println!("\n    ... ({} more bytes)", binary_data.len() - 32);
    } else {
        println!();
    }

    // Verify roundtrip for both formats
    let json_parsed = PerformanceMetrics::from_json(&json_data)?;
    let binary_parsed = PerformanceMetrics::from_binary(&binary_data)?;

    assert_eq!(metrics, json_parsed);
    assert_eq!(metrics, binary_parsed);
    println!("\nRoundtrip verification: PASSED");

    Ok(())
}

/// Demonstrate size comparisons across different data types
fn demonstrate_size_comparisons() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Size Comparison Analysis ---");

    // Test 1: Small configuration data (typical JSON use case)
    let mut db_settings = HashMap::new();
    db_settings.insert("host".to_string(), "localhost".to_string());
    db_settings.insert("port".to_string(), "5432".to_string());
    db_settings.insert("database".to_string(), "myapp".to_string());

    let config = Configuration {
        version: "1.2.3".to_string(),
        debug_enabled: true,
        log_level: "info".to_string(),
        database_settings: db_settings,
        feature_flags_enabled: true,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    // Test 2: Large numeric dataset (typical binary use case)
    let large_dataset = LargeDataset {
        name: "ML Training Data".to_string(),
        values: (0..1000).map(|i| i as f32 * 0.1).collect(),
        labels: (0..1000).map(|i| format!("label_{}", i)).collect(),
        feature_count: 100,
        feature_dimension: 50,
        timestamp_count: 1000,
        metadata: HashMap::new(),
    };

    println!("Size comparison results:");

    // Configuration comparison
    let config_json = config.to_json()?;
    let config_binary = config.to_binary()?;

    println!("\nConfiguration Data (small, text-heavy):");
    println!("  JSON: {} bytes", config_json.len());
    println!("  Binary: {} bytes", config_binary.len());
    println!(
        "  Ratio (JSON/Binary): {:.2}x",
        config_json.len() as f64 / config_binary.len() as f64
    );
    println!("  Recommendation: JSON (human readable, small size difference)");

    // Large dataset comparison
    let dataset_json = large_dataset.to_json()?;
    let dataset_binary = large_dataset.to_binary()?;

    println!("\nLarge Numeric Dataset (1000 values, 100x50 matrix):");
    println!(
        "  JSON: {} bytes ({:.1} KB)",
        dataset_json.len(),
        dataset_json.len() as f64 / 1024.0
    );
    println!(
        "  Binary: {} bytes ({:.1} KB)",
        dataset_binary.len(),
        dataset_binary.len() as f64 / 1024.0
    );
    println!(
        "  Ratio (JSON/Binary): {:.2}x",
        dataset_json.len() as f64 / dataset_binary.len() as f64
    );
    if dataset_json.len() > dataset_binary.len() {
        println!(
            "  Space saved with binary: {} bytes ({:.1} KB)",
            dataset_json.len() - dataset_binary.len(),
            (dataset_json.len() - dataset_binary.len()) as f64 / 1024.0
        );
        println!("  Recommendation: Binary (significant size reduction)");
    } else {
        println!(
            "  Binary overhead: {} bytes ({:.1} KB)",
            dataset_binary.len() - dataset_json.len(),
            (dataset_binary.len() - dataset_json.len()) as f64 / 1024.0
        );
        println!("  Recommendation: JSON (binary overhead not justified for this size)");
    }

    // Content analysis
    println!("\nContent Type Analysis:");

    // Analyze JSON content patterns
    let json_numbers = dataset_json.matches(char::is_numeric).count();
    let json_brackets = dataset_json.matches('[').count() + dataset_json.matches(']').count();
    let json_quotes = dataset_json.matches('"').count();

    println!("  JSON overhead sources:");
    println!("    Numeric characters: ~{}", json_numbers);
    println!("    Brackets and commas: ~{}", json_brackets);
    println!("    Quote marks: {}", json_quotes);
    println!("    Formatting/whitespace: Varies");

    println!("  Binary advantages:");
    println!("    Direct numeric encoding: 4-8 bytes per number");
    println!("    No formatting overhead: Zero bytes");
    println!("    Efficient length encoding: Minimal bytes");

    Ok(())
}

/// Demonstrate performance benchmarks
fn demonstrate_performance_benchmarks() -> Result<(), Box<dyn std::error::Error>> {
    println!("\n--- Performance Benchmark Analysis ---");

    // Create test data of varying sizes
    let small_config = Configuration {
        version: "1.0.0".to_string(),
        debug_enabled: false,
        log_level: "warn".to_string(),
        database_settings: HashMap::new(),
        feature_flags_enabled: false,
        max_connections: 100.0,
        timeout_seconds: 30.0,
    };

    let large_dataset = LargeDataset {
        name: "Large Dataset".to_string(),
        values: (0..5000).map(|i| i as f32 * 0.001).collect(),
        labels: (0..5000).map(|i| format!("large_item_{}", i)).collect(),
        feature_count: 200,
        feature_dimension: 25,
        timestamp_count: 5000,
        metadata: HashMap::new(),
    };

    println!("Performance benchmark results:");

    // Benchmark each dataset (avoiding trait objects due to object safety)
    let dataset_names = ["Small Config", "Large Dataset"];

    for (i, name) in dataset_names.iter().enumerate() {
        let mut comparison = FormatComparison::new(name.to_string());

        // JSON serialization benchmark
        let start = Instant::now();
        let json_data = match i {
            0 => small_config.to_json()?,
            _ => large_dataset.to_json()?,
        };
        comparison.json_serialize_micros = start.elapsed().as_micros() as u64;
        comparison.json_size_bytes = json_data.len() as u64;

        // JSON deserialization benchmark (using PerformanceMetrics as example)
        if *name == "Small Config" {
            let start = Instant::now();
            let _parsed = Configuration::from_json(&json_data)?;
            comparison.json_deserialize_micros = start.elapsed().as_micros() as u64;
        } else {
            let start = Instant::now();
            let _parsed = LargeDataset::from_json(&json_data)?;
            comparison.json_deserialize_micros = start.elapsed().as_micros() as u64;
        }

        // Binary serialization benchmark
        let start = Instant::now();
        let binary_data = match i {
            0 => small_config.to_binary()?,
            _ => large_dataset.to_binary()?,
        };
        comparison.binary_serialize_micros = start.elapsed().as_micros() as u64;
        comparison.binary_size_bytes = binary_data.len() as u64;

        // Binary deserialization benchmark
        if *name == "Small Config" {
            let start = Instant::now();
            let _parsed = Configuration::from_binary(&binary_data)?;
            comparison.binary_deserialize_micros = start.elapsed().as_micros() as u64;
        } else {
            let start = Instant::now();
            let _parsed = LargeDataset::from_binary(&binary_data)?;
            comparison.binary_deserialize_micros = start.elapsed().as_micros() as u64;
        }

        // Calculate ratios
        comparison.calculate_ratios();

        // Display results
        println!("\n{}:", name);
        println!(
            "  Size - JSON: {} bytes, Binary: {} bytes (ratio: {:.2}x)",
            comparison.json_size_bytes, comparison.binary_size_bytes, comparison.size_ratio
        );
        println!(
            "  Serialize - JSON: {}μs, Binary: {}μs (binary relative speed: {:.2}x)",
            comparison.json_serialize_micros,
            comparison.binary_serialize_micros,
            comparison.serialize_speed_ratio
        );
        println!(
            "  Deserialize - JSON: {}μs, Binary: {}μs (binary relative speed: {:.2}x)",
            comparison.json_deserialize_micros,
            comparison.binary_deserialize_micros,
            comparison.deserialize_speed_ratio
        );
    }

    println!("\nPerformance Summary:");
    println!("  - Binary format consistently uses less storage space");
    println!("  - Performance differences vary by data type and size");
    println!("  - Larger datasets show more significant binary advantages");
    println!("  - JSON parsing overhead increases with structure complexity");

    Ok(())
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl StructSerializable for Adam

impl StructSerializable for AdamConfig

impl StructSerializable for Tensor