serialized_data Class

namespace keychain → class serialized_data

Overview

The serialized_data class provides type-safe serialization and deserialization of various data types with support for multiple output formats including JSON, XML, Protocol Buffers, and binary.

Class Hierarchy

namespace keychain {
    class serialized_data : public serializable {
        // Type-safe data serialization container
    };
}

Constructor

serialized_data();
serialized_data(const serialized_data& other);

// Type-specific constructors
template<typename T>
serialized_data(const T& value);

serialized_data(const std::string& value);
serialized_data(const char* value);
serialized_data(int value);
serialized_data(double value);
serialized_data(bool value);

Properties

Data Type Information

data_type get_type() const;
void set_type(data_type type);

std::string get_type_name() const;
bool is_null() const;
bool is_primitive() const;
bool is_complex() const;

Access to type information and classification.

Size and Capacity

size_t size() const;
size_t byte_size() const;
bool empty() const;
void clear();

Container size and capacity management.

Methods

Value Setting (Type-Safe)

template<typename T>
void set_value(const T& value);

void set_value(const std::string& value);
void set_value(const char* value);
void set_value(int value);
void set_value(long value);
void set_value(float value);
void set_value(double value);
void set_value(bool value);

// Array and object types
template<typename T>
void set_array(const std::vector<T>& array);
void set_object(const std::map<std::string, serialized_data>& object);

// Binary data
void set_bytes(const std::vector<uint8_t>& data);
void set_bytes(const void* data, size_t length);

Type-safe value assignment with automatic type detection.

Value Retrieval (Type-Safe)

template<typename T>
T get_value() const;

std::string get_string() const;
int get_int() const;
long get_long() const;
float get_float() const;
double get_double() const;
bool get_bool() const;

// Array and object access
template<typename T>
std::vector<T> get_array() const;
std::map<std::string, serialized_data> get_object() const;

// Binary data access
std::vector<uint8_t> get_bytes() const;
const uint8_t* get_raw_bytes() const;

Type-safe value retrieval with automatic type conversion.

Serialization Operations

std::string serialize(serialization_format format = serialization_format::JSON) const;
std::vector<uint8_t> serialize_binary(serialization_format format = serialization_format::BINARY) const;

void deserialize(const std::string& data, serialization_format format = serialization_format::JSON);
void deserialize_binary(const std::vector<uint8_t>& data, serialization_format format = serialization_format::BINARY);

// Format-specific serialization
std::string to_json() const;
std::string to_xml() const;
std::vector<uint8_t> to_protobuf() const;
std::vector<uint8_t> to_binary() const;

// Format-specific deserialization
static serialized_data from_json(const std::string& json);
static serialized_data from_xml(const std::string& xml);
static serialized_data from_protobuf(const std::vector<uint8_t>& data);
static serialized_data from_binary(const std::vector<uint8_t>& data);

Comprehensive serialization and deserialization support.

Type Conversion

template<typename T>
bool can_convert_to() const;

template<typename T>
T convert_to() const;

bool can_convert_to_string() const;
bool can_convert_to_number() const;

std::string to_string() const;
double to_number() const;

Safe type conversion with capability checking.

Validation

bool is_valid() const;
std::vector<std::string> get_validation_errors() const;

bool validate_type() const;
bool validate_content() const;

Data validation and integrity checking.

Usage Examples

Basic Type Operations

#include <keychain/keychain.h>

// Create and set different types
keychain::serialized_data str_data("Hello, World!");
keychain::serialized_data int_data(42);
keychain::serialized_data float_data(3.14159);
keychain::serialized_data bool_data(true);

// Check types
assert(str_data.get_type() == keychain::data_type::STRING);
assert(int_data.get_type() == keychain::data_type::INT);
assert(float_data.get_type() == keychain::data_type::DOUBLE);
assert(bool_data.get_type() == keychain::data_type::BOOL);

// Retrieve values
std::string str_val = str_data.get_string();
int int_val = int_data.get_int();
double float_val = float_data.get_double();
bool bool_val = bool_data.get_bool();

std::cout << "String: " << str_val << std::endl;
std::cout << "Integer: " << int_val << std::endl;
std::cout << "Float: " << float_val << std::endl;
std::cout << "Boolean: " << (bool_val ? "true" : "false") << std::endl;

Array and Object Handling

// Create array data
std::vector<int> numbers = {1, 2, 3, 4, 5};
keychain::serialized_data array_data;
array_data.set_array(numbers);

// Retrieve array
auto retrieved_numbers = array_data.get_array<int>();
for (int num : retrieved_numbers) {
    std::cout << num << " ";
}
std::cout << std::endl;

// Create object data
std::map<std::string, keychain::serialized_data> person_data;
person_data["name"] = keychain::serialized_data("Alice Smith");
person_data["age"] = keychain::serialized_data(30);
person_data["active"] = keychain::serialized_data(true);

keychain::serialized_data object_data;
object_data.set_object(person_data);

// Retrieve object
auto person_obj = object_data.get_object();
std::string name = person_obj["name"].get_string();
int age = person_obj["age"].get_int();
bool active = person_obj["active"].get_bool();

std::cout << "Person: " << name << ", Age: " << age
         << ", Active: " << (active ? "Yes" : "No") << std::endl;

Serialization and Deserialization

// Complex data structure
keychain::serialized_data complex_data;
std::map<std::string, keychain::serialized_data> document;

document["title"] = keychain::serialized_data("Quarterly Report");
document["version"] = keychain::serialized_data(1.2);
document["pages"] = keychain::serialized_data();
document["pages"].set_array(std::vector<int>{1, 2, 3, 4, 5});

std::map<std::string, keychain::serialized_data> metadata;
metadata["author"] = keychain::serialized_data("Bob Johnson");
metadata["created"] = keychain::serialized_data("2024-01-15");
metadata["confidential"] = keychain::serialized_data(true);
document["metadata"] = keychain::serialized_data();
document["metadata"].set_object(metadata);

complex_data.set_object(document);

// Serialize to different formats
std::string json_output = complex_data.to_json();
std::string xml_output = complex_data.to_xml();
auto protobuf_output = complex_data.to_protobuf();
auto binary_output = complex_data.to_binary();

std::cout << "JSON size: " << json_output.size() << " bytes" << std::endl;
std::cout << "XML size: " << xml_output.size() << " bytes" << std::endl;
std::cout << "ProtoBuf size: " << protobuf_output.size() << " bytes" << std::endl;
std::cout << "Binary size: " << binary_output.size() << " bytes" << std::endl;

// Deserialize from JSON
auto reconstructed = keychain::serialized_data::from_json(json_output);
auto reconstructed_obj = reconstructed.get_object();
std::string title = reconstructed_obj["title"].get_string();
std::cout << "Reconstructed title: " << title << std::endl;

Type Conversion and Validation

// Safe type conversion
keychain::serialized_data numeric_string("123.45");
keychain::serialized_data integer_data(42);

// Check conversion capabilities
if (numeric_string.can_convert_to<double>()) {
    double value = numeric_string.convert_to<double>();
    std::cout << "Converted string to double: " << value << std::endl;
}

if (integer_data.can_convert_to_string()) {
    std::string str_value = integer_data.to_string();
    std::cout << "Converted int to string: " << str_value << std::endl;
}

// Validation
keychain::serialized_data test_data("test value");
if (test_data.is_valid()) {
    std::cout << "Data is valid" << std::endl;
} else {
    auto errors = test_data.get_validation_errors();
    for (const auto& error : errors) {
        std::cerr << "Validation error: " << error << std::endl;
    }
}

// Type checking
void process_data(const keychain::serialized_data& data) {
    switch (data.get_type()) {
        case keychain::data_type::STRING:
            std::cout << "Processing string: " << data.get_string() << std::endl;
            break;
        case keychain::data_type::INT:
            std::cout << "Processing integer: " << data.get_int() << std::endl;
            break;
        case keychain::data_type::ARRAY:
            std::cout << "Processing array with " << data.size() << " elements" << std::endl;
            break;
        case keychain::data_type::OBJECT:
            std::cout << "Processing object" << std::endl;
            break;
        default:
            std::cout << "Processing other type: " << data.get_type_name() << std::endl;
            break;
    }
}

Binary Data Handling

// Handle binary data
std::vector<uint8_t> binary_content = {0x89, 0x50, 0x4E, 0x47}; // PNG header
keychain::serialized_data binary_data;
binary_data.set_bytes(binary_content);

assert(binary_data.get_type() == keychain::data_type::BYTE_ARRAY);

// Retrieve binary data
auto retrieved_bytes = binary_data.get_bytes();
std::cout << "Binary data size: " << retrieved_bytes.size() << " bytes" << std::endl;

// Access raw pointer (for performance-critical operations)
const uint8_t* raw_data = binary_data.get_raw_bytes();
size_t data_size = binary_data.byte_size();

// Process raw binary data efficiently
for (size_t i = 0; i < data_size; ++i) {
    printf("%02X ", raw_data[i]);
}
std::cout << std::endl;

Integration with Keychain Operations

// Use serialized_data with Keychain operations
void demonstrate_keychain_integration() {
    // Create structured data for signing
    keychain::serialized_data contract_data;
    std::map<std::string, keychain::serialized_data> contract;

    contract["party_a"] = keychain::serialized_data("Alice Corporation");
    contract["party_b"] = keychain::serialized_data("Bob Industries");
    contract["amount"] = keychain::serialized_data(1000000.00);
    contract["currency"] = keychain::serialized_data("USD");
    contract["date"] = keychain::serialized_data("2024-01-15");

    contract_data.set_object(contract);

    // Sign the serialized data
    keychain::persona signer = gateway.get_persona("alice", "legal");
    keychain::verifiable_data signed_contract = gateway.sign(signer, contract_data);

    // Encrypt the signed contract
    std::vector<keychain::contact> recipients = { /* ... */ };
    keychain::encrypted_data encrypted_contract = gateway.encrypt(
        signer, signed_contract.serialize(), recipients
    );

    // The original data can be reconstructed after decryption and verification
    std::cout << "Contract successfully processed with type-safe data" << std::endl;
}

Performance Considerations

// Performance optimization tips
void optimize_serialized_data_usage() {
    // 1. Prefer move semantics for large objects
    keychain::serialized_data large_data;
    std::vector<int> large_array(1000000, 42);
    large_data.set_array(std::move(large_array)); // Avoid copy

    // 2. Use binary format for performance-critical serialization
    auto binary_data = large_data.to_binary(); // Fastest serialization

    // 3. Reserve capacity for known-size data
    keychain::serialized_data optimized_data;
    // optimized_data.reserve(estimated_size); // If available

    // 4. Batch operations when possible
    std::map<std::string, keychain::serialized_data> batch_data;
    for (int i = 0; i < 100; ++i) {
        batch_data["item_" + std::to_string(i)] = keychain::serialized_data(i);
    }

    keychain::serialized_data batch_container;
    batch_container.set_object(std::move(batch_data)); // Single operation
}

JSON Examples

Simple Value

{
  "type": "STRING",
  "value": "Hello, World!"
}

Complex Object

{
  "type": "OBJECT",
  "value": {
    "title": {
      "type": "STRING",
      "value": "Quarterly Report"
    },
    "version": {
      "type": "DOUBLE",
      "value": 1.2
    },
    "pages": {
      "type": "ARRAY",
      "value": [1, 2, 3, 4, 5]
    }
  }
}

See Also

  • gateway - Data operations with serialized_data

  • char_encoding - Character encoding options

  • {json-spec}[JSON Specification]

  • {protobuf-guide}[Protocol Buffers Guide]