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

Databases can be found inside src/Database.h, but Cereal.h should be included instead to prevent any compilation issues.

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

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

myDatabase->write(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(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 nullptr

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::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::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 std::logic_error exception. 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 will use this version by default.

Sample code

#include <Cereal.h> // Include the library

int main()
{
    Cereal::Buffer buffer(1024); // Create a buffer

    Cereal::Database* myDatabase = new Cereal::Database("Test database"); // Create a database

    Cereal::Object* myObject = new Cereal::Object("Test object");

    // Adding fields to objects
    myObject->addField(new Cereal::Field("Test field", 42)); // Create a field and add it to the object

    // Adding objects to databases
    myDatabase->addObject(myObject); // Add 'myObject' to the database

    // Writing databases
    myDatabase->write(buffer);

    // Reading databases
    Cereal::Database* otherDatabase = new Cereal::Database; // Create another database
    buffer.setOffset(0); // Move the offset of the buffer to the beginning
    otherDatabase->read(buffer); // Read the buffer

    // Getting an object from a database
    Cereal::Object* otherObject = otherDatabase->getObject("Test object");

    // Getting a field and an array from an object
    Cereal::Field* field = otherObject->getField("Test field"); // Get the field
    // Cereal::Array* array = otherObject->getArray("Array name"); // There are no arrays in our object

    // Free dynamic memory
    delete myDatabase; // Databases will automatically delete all the objects, fields and arrays they contain
    delete otherDatabase;

    return 0;
}