Serializable

train_station::serialization

Trait Serializable 

Source 
pub trait Serializable: Sized {
    // Required methods
    fn to_json(&self) -> SerializationResult<String>;
    fn from_json(json: &str) -> SerializationResult<Self>;
    fn to_binary(&self) -> SerializationResult<Vec<u8>>;
    fn from_binary(data: &[u8]) -> SerializationResult<Self>;

    // Provided methods
    fn save<P: AsRef<Path>>(
        &self,
        path: P,
        format: Format,
    ) -> SerializationResult<()> { ... }
    fn save_to_writer<W: Write>(
        &self,
        writer: &mut W,
        format: Format,
    ) -> SerializationResult<()> { ... }
    fn load<P: AsRef<Path>>(
        path: P,
        format: Format,
    ) -> SerializationResult<Self> { ... }
    fn load_from_reader<R: Read>(
        reader: &mut R,
        format: Format,
    ) -> SerializationResult<Self> { ... }
}
Expand description

Core serialization trait for Train Station objects

This trait provides a unified interface for saving and loading objects in multiple formats. All serializable objects must implement this trait to enable persistent storage and model checkpointing. The trait includes both file-based and writer-based operations for maximum flexibility.

§Required Methods

  • to_json - Serialize the object to JSON format
  • from_json - Deserialize an object from JSON format
  • to_binary - Serialize the object to binary format
  • from_binary - Deserialize an object from binary format

§Provided Methods

  • save - Save the object to a file in the specified format
  • save_to_writer - Save the object to a writer in the specified format
  • load - Load an object from a file in the specified format
  • load_from_reader - Load an object from a reader in the specified format

§Safety

Implementations must ensure that:

  • Serialized data contains all necessary information for reconstruction
  • Deserialization validates all input data thoroughly
  • Memory safety is maintained during reconstruction
  • No undefined behavior occurs with malformed input

§Examples

use train_station::serialization::{Serializable, Format, SerializationResult};

// Example implementation for a simple struct
#[derive(Debug, PartialEq)]
struct SimpleData {
    value: i32,
}

impl Serializable for SimpleData {
    fn to_json(&self) -> SerializationResult<String> {
        Ok(format!(r#"{{"value":{}}}"#, self.value))
    }
     
    fn from_json(json: &str) -> SerializationResult<Self> {
        // Simple parsing for demonstration
        if let Some(start) = json.find("value\":") {
            let value_str = &json[start + 7..];
            if let Some(end) = value_str.find('}') {
                let value: i32 = value_str[..end].parse()
                    .map_err(|_| "Invalid number format")?;
                return Ok(SimpleData { value });
            }
        }
        Err("Invalid JSON format".into())
    }
     
    fn to_binary(&self) -> SerializationResult<Vec<u8>> {
        Ok(self.value.to_le_bytes().to_vec())
    }
     
    fn from_binary(data: &[u8]) -> SerializationResult<Self> {
        if data.len() != 4 {
            return Err("Invalid binary data length".into());
        }
        let value = i32::from_le_bytes([data[0], data[1], data[2], data[3]]);
        Ok(SimpleData { value })
    }
}

// Usage example
let data = SimpleData { value: 42 };
let json = data.to_json().unwrap();
let loaded = SimpleData::from_json(&json).unwrap();
assert_eq!(data, loaded);

§Implementors

Common types that implement this trait include:

  • Tensor - For serializing tensor data and metadata
  • AdamConfig - For serializing optimizer configuration
  • SerializableAdam - For serializing optimizer state

Required Methods§

Source

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

Serialize the object to JSON format

This method converts the object into a human-readable JSON string representation. The JSON format is suitable for debugging, configuration files, and cross-language interoperability.

§Returns

JSON string representation of the object on success, or SerializationError on failure

Source

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

Deserialize an object from JSON format

This method parses a JSON string and reconstructs an object of the implementing type. The JSON must contain all necessary fields and data in the expected format.

§Arguments
  • json - JSON string containing serialized object
§Returns

The deserialized object on success, or SerializationError on failure

Source

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

Serialize the object to binary format

This method converts the object into a compact binary representation optimized for storage and transmission. The binary format provides maximum performance and minimal file sizes.

§Returns

Binary representation of the object on success, or SerializationError on failure

Source

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

Deserialize an object from binary format

This method parses binary data and reconstructs an object of the implementing type. The binary data must contain complete serialized information in the expected format.

§Arguments
  • data - Binary data containing serialized object
§Returns

The deserialized object on success, or SerializationError on failure

Provided Methods§

Source

fn save<P: AsRef<Path>>( &self, path: P, format: Format, ) -> SerializationResult<()>

Save the object to a file in the specified format

This method creates or overwrites a file at the specified path and writes the serialized object data in the requested format. The file is created with write permissions and truncated if it already exists.

§Arguments
  • path - File path where the object should be saved
  • format - Serialization format (JSON or Binary)
§Returns

Ok(()) on success, or SerializationError on failure

§Examples
use train_station::serialization::{Serializable, Format, SerializationResult};
use std::io::Write;

// Simple example struct
struct TestData { value: i32 }
impl Serializable for TestData {
    fn to_json(&self) -> SerializationResult<String> {
        Ok(format!(r#"{{"value":{}}}"#, self.value))
    }
    fn from_json(json: &str) -> SerializationResult<Self> {
        Ok(TestData { value: 42 }) // Simplified for example
    }
    fn to_binary(&self) -> SerializationResult<Vec<u8>> {
        Ok(self.value.to_le_bytes().to_vec())
    }
    fn from_binary(_data: &[u8]) -> SerializationResult<Self> {
        Ok(TestData { value: 42 }) // Simplified for example
    }
}

let data = TestData { value: 42 };

// Save to temporary file (cleanup handled by temp directory)
let temp_dir = std::env::temp_dir();
let json_path = temp_dir.join("test_data.json");
data.save(&json_path, Format::Json).unwrap();

// Verify file was created
assert!(json_path.exists());

// Clean up
std::fs::remove_file(&json_path).ok();
Source

fn save_to_writer<W: Write>( &self, writer: &mut W, format: Format, ) -> SerializationResult<()>

Save the object to a writer in the specified format

This method serializes the object and writes the data to the provided writer. The writer is flushed after writing to ensure all data is written. This method is useful for streaming serialization or writing to non-file destinations.

§Arguments
  • writer - Writer to output serialized data
  • format - Serialization format (JSON or Binary)
§Returns

Ok(()) on success, or SerializationError on failure

Source

fn load<P: AsRef<Path>>(path: P, format: Format) -> SerializationResult<Self>

Load an object from a file in the specified format

This method reads the entire file content and deserializes it into an object of the implementing type. The file must exist and contain valid serialized data in the specified format.

§Arguments
  • path - File path to read from
  • format - Expected serialization format
§Returns

The deserialized object on success, or SerializationError on failure

§Examples
use train_station::serialization::{Serializable, Format, SerializationResult};
use std::io::Write;

// Simple example struct
#[derive(Debug, PartialEq)]
struct TestData { value: i32 }
impl Serializable for TestData {
    fn to_json(&self) -> SerializationResult<String> {
        Ok(format!(r#"{{"value":{}}}"#, self.value))
    }
    fn from_json(json: &str) -> SerializationResult<Self> {
        // Simple parsing for demonstration
        if json.contains("42") {
            Ok(TestData { value: 42 })
        } else {
            Ok(TestData { value: 0 })
        }
    }
    fn to_binary(&self) -> SerializationResult<Vec<u8>> {
        Ok(self.value.to_le_bytes().to_vec())
    }
    fn from_binary(data: &[u8]) -> SerializationResult<Self> {
        if data.len() >= 4 {
            let value = i32::from_le_bytes([data[0], data[1], data[2], data[3]]);
            Ok(TestData { value })
        } else {
            Ok(TestData { value: 0 })
        }
    }
}

let original = TestData { value: 42 };

// Save and load from temporary file
let temp_dir = std::env::temp_dir();
let json_path = temp_dir.join("test_load.json");
original.save(&json_path, Format::Json).unwrap();

let loaded = TestData::load(&json_path, Format::Json).unwrap();
assert_eq!(original, loaded);

// Clean up
std::fs::remove_file(&json_path).ok();
Source

fn load_from_reader<R: Read>( reader: &mut R, format: Format, ) -> SerializationResult<Self>

Load an object from a reader in the specified format

This method reads all available data from the provided reader and deserializes it into an object of the implementing type. The reader must contain complete serialized data in the specified format.

§Arguments
  • reader - Reader containing serialized data
  • format - Expected serialization format
§Returns

The deserialized object on success, or SerializationError on failure

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§