Reflex Data

The Data module handles property storage, serialization, encoding/decoding, hashing, and compression. PropertySet is one of the most important classes in the framework — it's the base for GLX::Object, GLX::Style, and most configurable entities.

Format Constants

Predefined format identifiers used throughout the Data module for encoding, decoding, and serialization of PropertySet data.

const kBinaryFormat;            // Reflex native binary format
const kJsonFormat;              // JSON
const kPropertySetFormat;       // Reflex PropertySet format
const kPropertySheetFormat;     // StyleSheet format (CSS-like)
const kReflexMarkupFormat;      // Reflex markup
const kReflexXmlFormat;         // Reflex XML
const kRiffFormat;              // RIFF container format

Pass these to EncodePropertySet, DecodePropertySet, and the Format class methods to control how property data is read and written. kJsonFormat is the most common choice for human-readable configuration files, while kBinaryFormat is used for compact, high-performance storage.

Type Aliases

Convenience aliases for common Data module types, including binary buffers and typed property wrappers.

Binary Data

using Archive = Array<UInt8>;                  // Binary data buffer
using Archive::View = ArrayView<UInt8>;        // Non-owning binary view

Archive is the standard container for binary data throughout Reflex. It inherits all Array operations and is used for serialization streams, file I/O, and compression buffers.

Property Wrappers

Heap-allocated typed wrappers using ObjectOf<T>, suitable for storage as properties inside a PropertySet.

using Float32Property = ObjectOf<Float32>;
using Float64Property = ObjectOf<Float64>;
using Int32Property = ObjectOf<Int32>;
using Int64Property = ObjectOf<Int64>;
using UInt32Property = ObjectOf<UInt32>;
using UInt64Property = ObjectOf<UInt64>;
using KeyMap = ObjectOf<Map<Key<UInt32>, Array<char>>>;

KeyMap is the string-to-key registry used by PropertySetto map human-readable names to compact Key32 identifiers.

Property Accessors

Free functions for reading and writing typed properties on PropertySet and its derivatives (including GLX::Object). Each type has Get, Set, and Unset variants.

Getters

Each getter takes a fallback value returned when the property is not set.

bool GetBool(const Object& propertyset, Key32 id, bool fallback);
Float32 GetFloat32(const Object& propertyset, Key32 id, Float32 fallback);
Float64 GetFloat64(const Object& propertyset, Key32 id, Float64 fallback);
Int32 GetInt32(const Object& propertyset, Key32 id, Int32 fallback);
Int64 GetInt64(const Object& propertyset, Key32 id, Int64 fallback);
UInt8 GetUInt8(const Object& propertyset, Key32 id, UInt8 fallback);
UInt32 GetUInt32(const Object& propertyset, Key32 id, UInt32 fallback);
UInt64 GetUInt64(const Object& propertyset, Key32 id, UInt64 fallback);
Key32 GetKey32(const Object& propertyset, Key32 id, Key32 fallback);

Setters

void SetBool(Object& propertyset, Key32 id, bool value);
void SetFloat32(Object& propertyset, Key32 id, Float32 value);
void SetFloat64(Object& propertyset, Key32 id, Float64 value);
void SetInt32(Object& propertyset, Key32 id, Int32 value);
void SetInt64(Object& propertyset, Key32 id, Int64 value);
void SetUInt8(Object& propertyset, Key32 id, UInt8 value);
void SetUInt32(Object& propertyset, Key32 id, UInt32 value);
void SetUInt64(Object& propertyset, Key32 id, UInt64 value);
void SetKey32(Object& propertyset, Key32 id, Key32 value);
void SetBinary(Object& propertyset, Key32 id, const Archive::View& value);
void SetCString(Object& propertyset, Key32 id, const CString::View& value);
void SetWString(Object& propertyset, Key32 id, const WString::View& value);
void SetPropertySet(Object& propertyset, Key32 id, TRef<PropertySet> value);

Unsetters

Remove a typed property from the set entirely.

void UnsetBool(Object& propertyset, Key32 id);
void UnsetFloat32(Object& propertyset, Key32 id);
void UnsetFloat64(Object& propertyset, Key32 id);
void UnsetInt32(Object& propertyset, Key32 id);
void UnsetInt64(Object& propertyset, Key32 id);
void UnsetUInt8(Object& propertyset, Key32 id);
void UnsetUInt32(Object& propertyset, Key32 id);
void UnsetUInt64(Object& propertyset, Key32 id);
void UnsetKey32(Object& propertyset, Key32 id);
void UnsetBinary(Object& propertyset, Key32 id);
void UnsetCString(Object& propertyset, Key32 id);
void UnsetWString(Object& propertyset, Key32 id);
void UnsetPropertySet(Object& propertyset, Key32 id);
void UnsetPropertySetArray(PropertySet& propertyset, Key32 id);

Example

// Store user preferences
Data::SetUInt32(Bootstrap::global->prefs, "notely.selected_tab", 2);
Data::SetBool(Bootstrap::global->prefs, "app.dark_mode", true);

// Read with defaults
UInt32 tab = Data::GetUInt32(Bootstrap::global->prefs, "notely.selected_tab", 0);
bool dark = Data::GetBool(Bootstrap::global->prefs, "app.dark_mode", false);

PropertySet Functions

Functions for navigating, composing, and managing PropertySet hierarchies. These cover nested access, array properties, bulk operations, and the string-to-key registry.

Nested Access

Navigate into child PropertySet nodes by key or by path (an array of keys).

ConstTRef<PropertySet> GetPropertySet(const Object& propertyset, Key32 id);
ConstTRef<PropertySet> GetPropertySet(const PropertySet& propertyset, const ArrayView<Key<UInt32>>& path);
TRef<PropertySet> AcquirePropertySet(PropertySet& propertyset, Key32 id);          // Get or create
TRef<PropertySet> AcquirePropertySet(PropertySet& propertyset, const ArrayView<Key<UInt32>>& path);

PropertySet Arrays

Store and retrieve ordered collections of PropertySet objects under a single key.

ArrayView<ConstReference<PropertySet>> GetPropertySetArray(const PropertySet& propertyset, Key32 id);
TRef<ObjectArray<PropertySet>> AcquirePropertySetArray(PropertySet& propertyset, Key32 id);
TRef<PropertySet> AddPropertySet(ObjectArray<PropertySet>& array);

Bulk Operations

void Assimilate(PropertySet& target, const PropertySet& source);    // Copy all from source
PropertySet Merge(const PropertySet& a, const PropertySet& b);      // Merge two into new
PropertySet CopyPropertySet(const Format& format, const PropertySet& propertyset);
void ResetPropertySet(const Format& format, PropertySet& propertyset);

Assimilate overwrites matching keys in the target. Merge returns a new PropertySet combining both inputs without modifying either.

KeyMap

The string-to-Key32 registry. Register human-readable names and resolve them back from compact key identifiers.

TRef<ObjectOf<Map<Key<UInt32>, Array<char>>>> AcquireKeyMap(PropertySet& root);
ConstTRef<ObjectOf<Map<Key<UInt32>, Array<char>>>> GetKeyMap(const PropertySet& root);
Key32 RegisterKey(KeyMap& keymap, const CString::View& string);
CString::View GetKey(const KeyMap& keymap, Key32 key);

Serialization

Binary serialization for arbitrary types and PropertySet data, plus string encoding helpers and line-based stream I/O.

Generic Serialization

Serialize one or more values into a binary Archive stream, and deserialize them back. Supports variadic packing for multiple values in a single call.

// Serialize to binary stream
void Serialize(Archive& stream, const VARGS...& ...);

// Deserialize from binary stream
void Deserialize(Archive::View& stream, VARGS...& ...);
TYPE Deserialize(Archive::View& stream);
Tuple<VARGS...> Deserialize(Archive::View& stream);

PropertySet Serialization

void SerializePropertySet(Archive& stream, const SerializableFormat& format, const PropertySet& in);
void DeserializePropertySet(Archive::View& stream, const SerializableFormat& format, PropertySet& out);

String Serialization

Serialize wide strings to UTF-8 or UCS-2 encoded binary streams.

void SerializeUTF8(Archive& stream, const WString::View& string);
void SerializeUCS2(Archive& stream, const WString::View& string);
WString DeserializeUTF8(Archive::View& stream);
WString DeserializeUCS2(Archive::View& stream);

Pack & Unpack

Convert raw values directly to and from Archive byte buffers.

Archive::View Pack(const TYPE& value);
void Unpack(const Archive::View& bytes, TYPE& output);
TYPE Unpack(const Archive::View& bytes);

Line-Based I/O

Read and write individual lines from Archive streams. Useful for text-based formats and log processing.

bool ReadLine(Archive::View& stream, WString& line_out);
bool ReadLine(Archive::View& stream, CString& line_out);
void WriteLine(Archive& stream, const WString::View& line);
void WriteLine(Archive& stream, const CString::View& line);

Example

// Save state
Archive stream;
Data::Serialize(stream, playerX, playerY, health);

// Load state
Archive::View view(stream);
auto [x, y, hp] = Data::Deserialize<Float32, Float32, Int32>(view);

Encoding & Decoding

Convert PropertySet data to and from various formats (JSON, binary, XML, etc.) and encode/decode strings between wide and byte representations.

PropertySet Encoding

Encode a PropertySet into an Archive using any supported format constant, or decode one back from bytes.

Archive EncodePropertySet(const Format& format, const PropertySet& propertyset);
PropertySet DecodePropertySet(const Format& format, const Archive::View& bytes, UInt32 options);

String Encoding

Convert between wide strings and byte-encoded representations. Void-return variants that write into existing output buffers are also available.

WString DecodeUTF8(const Archive::View& bytes);
WString DecodeUCS2(const Archive::View& bytes);
Archive EncodeUTF8(const WString::View& string);
Archive EncodeUCS2(const WString::View& string);

Example

// Load a JSON file into a PropertySet
auto jsonData = File::Open(L"config.json");
auto config = Data::DecodePropertySet(Data::kJsonFormat, jsonData, 0);

// Read values
auto name = Data::GetCString(config, "app_name", "Untitled");

Hashing & Compression

Hash functions, hex conversion utilities, and compression support built into the Data module.

Hash Functions

CRC32 and FNV-1a accept a previous value for incremental hashing across multiple buffers. SHA variants return the digest as an Archive.

UInt32 CRC32(const Archive::View& bytes, UInt32 previous);
UInt32 FNV1a32(const Archive::View& bytes, UInt32 previous);
UInt64 FNV1a64(const Archive::View& bytes, UInt64 previous);
Archive SHA1(const Archive::View& bytes);
Archive SHA256(const Archive::View& bytes);

Hex Conversion

CString BytesToHex(const Archive::View& bytes);
Archive HexToBytes(const CString::View& hex);

Compression

Compress and decompress binary data. The built-in kLZ4 constant provides the LZ4 algorithm.

Archive Compress(const CompressionAlgorithm& algorithm, const Archive::View& bytes);
Archive Decompress(const DecompressionAlgorithm& algorithm, const Archive::View& bytes);

Data Classes

The class hierarchy underpinning the Data module. PropertySet is one of the most important classes in Reflex — it's the base for GLX::Object,GLX::Style, and most configurable entities.

Class	Inherits	Purpose
PropertySet	Object	Generic key-value property container. Base for GLX::Object and GLX::Style.
Format	Object	Base class for format encoders/decoders
SerializableFormat	Format	Format with streaming Serialize/Deserialize
CompressionAlgorithm	—	Compression support
DecompressionAlgorithm	Object	Decompression support
ArchiveObject	Object	Heap-allocated Archive
ObjectArray<TYPE>	Object	Array of Objects stored as properties

PropertySet

bool PropertySet::Empty();
bool PropertySet::operator bool();                              // True if non-empty
PropertySet::PropertyIterator<TYPE> PropertySet::Iterate();     // Iterate typed properties
PropertySet::ConstPropertyIterator<TYPE> PropertySet::Iterate();

Format

void Format::Reset(PropertySet& propertyset);
bool Format::Encode(Archive& out, const PropertySet& data);
bool Format::Decode(PropertySet& out, const Archive::View& data, UInt32 options);

SerializableFormat

void SerializableFormat::Serialize(Archive& stream, const PropertySet& propertyset);
void SerializableFormat::Deserialize(Archive::View& stream, PropertySet& propertyset);