Serialization and File I/O

Vectors and matrices can be saved to and loaded from files or streams in MtxVec's binary format.

Storage precision — the Precision property:

Precision defines the precision used by the streaming routines — the format in which data is written to a file or stream. It is not FloatPrecision: that one is the in-memory computation format, while Precision affects only what is stored. Assigning it never touches or converts the data held in memory.

This lets you store values far more compactly than you compute with them — for example, hold double-precision data in memory but write it as 16-bit integers.

TPrecision values: prDouble, prSingle, prInteger, prCardinal, prSmallInt, prWord, prShortInt, prByte, prMuLaw, prALaw, prInt24.

The companion Rounding property (TRounding = rnTrunc, rnRound) defines the rounding used by the streaming routines — it decides how values are rounded when the storage format cannot represent them exactly, which is the case for every integer and companded (prMuLaw / prALaw) format.

a.Precision = TPrecision.prSmallInt;   // store as 16-bit integers
a.Rounding  = TRounding.rnRound;       // round rather than truncate when converting
a.SaveToFile("data.vec");              // values are converted as they are written

File I/O:

// C#
a.SaveToFile("data.vec");
a.LoadFromFile("data.vec");

Stream I/O (for embedding in larger files):

// Write to stream
a.WriteHeader(stream);   // writes size, precision, complexity metadata
a.WriteValues(stream);   // writes raw data

// Read from stream
a.ReadHeader(stream);    // reads metadata, auto-sizes the object
a.ReadValues(stream);    // reads raw data

The header contains: element count, float precision (single/double), complexity (real/complex), and format version. This allows LoadFromFile to auto-configure the object.

Custom I/O interface:

Any class can implement IMtxVecStreamIO to support custom serialization formats (CSV, JSON, HDF5, etc.). The interface requires:

  • SaveToStream(stream)
  • LoadFromStream(stream)

Cross-precision loading: Files saved in single precision can be loaded into double precision objects and vice versa — conversion is automatic.

Text format: For human-readable output, use CopyToArray to get a Delphi dynamic array, then write elements manually. There is no built-in text format export.