Databases

Databases are made up of objects, up to 65536 of them, and each one can have up to 65536 fields and 65536 arrays.
They are a good choice to store game data, settings...

Using databases

We can easily create a database like so:

Cereal.Database myDatabase = new Cereal.Database("Database name");

And that's it, we've just created a database with the name Database name!

Now it's time to add objects to our database:

Cereal.Object myObject = new Cereal.Object("Object name"); // Create an object
myObject.AddField(new Cereal.Field("Field name", 42)); // Add a field to the object

myDatabase.AddObject(myObject); // Add 'myObject' to the database

Alternatively, objects can be added using the Objects property:

myDatabase.Objects.Add(myObject);

Once our database is filled with our objects, we can then write it into a buffer:

myDatabase.Write(ref buffer);

This function will return true if everything was serialized properly, and false if it failed. Normally, if the function returns false means that the buffer is too small to store that database, its objects and the fields and arrays of each object.

We can also read a database by doing:

Cereal.Database otherDatabase = new Cereal.Database(); // Create an empty database
otherDatabase.Read(ref buffer); // Read the buffer

Cereal.Object object = otherDatabase.GetObject("Object name"); // Get the object

Once a database is read, it will automatically re-create the objects it contained originally, with its fields and its arrays. Isn't it magical?
If an object is not found inside the database, Database.GetObject() will return null

Database versions

Version 1.0

This is the initial version, and only encodes the data without any security measures. It can be selected using the class constructor:

Cereal.Database myDatabase = new Cereal.Database("Database name", Cereal.Global.Version.VERSION_1_0);

Note that this version is considered deprecated and the new 2.0 version should be used, but it is still available for backwards-compatibility with older versions of Cereal.

Version 2.0

This is the newer (and default) version for databases. You can force this version by including the version number in the database constructor:

Cereal.Database myDatabase = new Cereal.Database("Database name", Cereal.Global.Version.VERSION_2_0);

This version has exactly the same features and capabilities of the version 1.0, but it adds a checksum to check for file corruptions. Each database has one, so that if a file contains multiple databases and the file gets corrupted, it is possible to check which databases are damaged and which are intact.

The library will check the database integrity upon loading. If it finds a mismatch between the written database checksum and the calculated one, it will throw an ArgumentOutOfRangeException. You can use a try...catch block to detect this events.

Note that using VERSION_LATEST instead of VERSION_2_0 or not specifying a version at all will use this version by default.

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)
Objects	get; set	getObjects()	-	Objects contained in the database (List<Cereal.Object>)

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.Database myDatabase = new Cereal.Database("Test database"); // Create a database
            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

            // Adding objects to a databases
            myDatabase.AddObject(myObject); // Add the object containing the field and the array to the database

            // Writing databases
            myDatabase.Write(ref buffer); // Write the database to the buffer

            // Reading databases
            Cereal.Database otherDatabase = new Cereal.Database(); // Create another object
            buffer.Position = 0; // Move the buffer back to the beginning
            otherDatabase.Read(ref buffer); // Read the object from the buffer

            // Getting an object from a database
            Cereal.Object otherObject = otherDatabase.GetObject("Object name");

            // 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
        }
    }
}