Data Format

Data Formats

Plancake makes use of three "formats", namely "raw" (fixed-width) data, "block" (variable-width), and "object" (combination of fixed and/or variable width) data.

Be careful not to mix up raw and block data, as they have slightly different byte representations that will result in some sneaky errors.

TL;DR

Type	Read Method	Write Method	Advantages
Raw	DataConstructor.WriteRaw	DataDestructor.ReadRaw	Low size footprint
Block	DataConstructor.WriteByteBlock	DataDestructor.ReadNextBlock	Flexible sizing
Object	DataConstructor.WriteObject	DataDestructor.TryReadObject	Multiple elements

Raw Data

"Raw data" refers to a fixed-width chunk of data. It is recommended to use raw data for basic struct-type values such as int, float, double, short, byte, etc.

Raw data can be written using DataConstructor.WriteRaw(ReadOnlySpan<byte>) and read via DataDestructor.ReadRaw(int). In order for the data to be read properly, you must know the size of the value in bytes.

Raw data only uses the number of bytes provided to it, with no additional padding.

Block Data

"Block data" refers to a variable-width chunk of data. It is recommended to use block data for anything that could have a varying size, such as strings, some arrays, lists, and dictionaries.

The advantage to block data over raw data is that the length of the data block is provided within the data. Therefore, each block can be read using DataDestructor.ReadNextBlock() (notice the lack of length parameter), and written using DataConstructor.WriteByteBlock(ReadOnlySpan<byte>).

Block data uses the number of bytes provided to it, as well as two additional bytes for defining the length of the block as a ushort.

Object Data

"Object data" refers to a collection of values that make up an object, along with the type hash of said object.

As this is the data generated by DataConstructor.WriteObject, Plancake technically represents everything as object data at the highest level. However, object data can contain other object data, allowing for more complex "tree" structures to be formed.

Object data is written using DataConstructor.WriteObject and read using DataDestructor.TryReadObject<T> (generic) or DataDestructor.TryReadObject (always returns type object).