Objects

Objects are the main component of databases. An object can store up to 65536 fields and 65536 arrays.

Using objects

Lets begin creating an object:

Cereal.Object myObject = new Cereal.Object("Object name"); // Create an object with name "Object name"

Now, our object has the name "Object name" and is ready to store fields and arrays:

short[] arrayValues = { 32, 18, 21, 30 };

Cereal.Array myArray = new Cereal.Array("Array name", arrayValues); // Create an array with 4 values
Cereal.Field myField = new Cereal.Field("Field name", 3.141592f); // Store pi inside that field

myObject.AddArray(myArray); // Add the array to the object
myObject.AddField(myField); // Add the field to the object

Alternatively, you can use the properties Fields and Arrays to add fields and arrays to objects:

myObject.Arrays.Add(myArray); // Add the array to the object
myObject.Fields.Add(myField); // Add the field to the object

Once our object has all the fields and all the arrays we need inside it, we can call Object.Write(ref Buffer buffer) to serialize it:

Cereal.Buffer buffer = new Cereal.Buffer(1024); // Create a buffer of 1 kilobyte
myObject.Write(ref buffer);

A call to Object.Write(ref Buffer buffer) will return true if the data contained by the object was successfully serialized. If not, it will return false. Normally this means the buffer is too small to store this object (and the fields and arrays it contains). Always make sure that myObject.Size <= buffer.FreeSpace

Finally, we can deserialize our object and get its fields and arrays like so:

Cereal.Object obj = new Cereal.Object(); // Create an empty object
obj.Read(ref buffer); // Read the buffer and get all the fields and arrays

Cereal.Field field = obj.GetField("Field name"); // Get the field
Cereal.Array array = obj.GetArray("Array name"); // Get the array

If the field or the array is not found, it will return null.

Properties

This is the list of the properties exposed by this class and their C++ equivalent, along with the accessor of each property:

Property	Accessor	C++ getter	C++ setter	Return data
Name	get; set	getName()	-	Name of the array (string)
Size	get	getSize()	-	Size (in bytes) of the serialized array (uint)
Fields	get; set	getFields()	-	Fields contained in the object (List<Cereal.Field>)
Arrays	get; set	getArrays()	-	Arrays contained in the object (List<Cereal.Array>)

Sample code

namespace MyProgram
{
    class Program
    {
        static void Main(string[] args)
        {
            Cereal.Buffer buffer = new Cereal.Buffer(1024); // Create a buffer with 1024 bytes
            string[] words = { "array", "of", "words", "to save in the serialized array" };

            Cereal.Object myObject = new Cereal.Object("Object name"); // Create an object to store our arrays & fields

            Cereal.Array myArray = new Cereal.Array("Array name", words); // Create an array containing the strings in 'words'
            Cereal.Field myField = new Cereal.Field("Field name", 42); // Create a field with the value '42'

            // Adding fields and arrays to objects
            myObject.AddField(myField); // Add the field to the object
            myObject.AddArray(myArray); // Add the array to the object

            // Writing an object
            myObject.Write(ref buffer); // Write the object to the buffer

            // Reading an object
            Cereal.Object otherObject = new Cereal.Object(); // Create another object
            buffer.Position = 0; // Move the buffer back to the beginning
            otherObject.Read(ref buffer); // Read the object from the buffer

            // Getting a field and an array from an object
            Cereal.Field field = otherObject.GetField("Field name"); // Get the field
            Cereal.Array array = otherObject.GetArray("Array name"); // Get the array
        }
    }
}