Writing and Committing

Warning

This page is Work-in-Progress.

Writing and Committing

The most essential actions in a data persistence library are writing and reading. While reading will be covered in a later section, we will explain how writing and committing works in this page.

In cpersist, what writing does is serialize data and load the result into the file buffer. In simple words, it turns the data into zeros and ones ("serialization") and puts those zeros and ones into the buffer. However, we realize that, at some point, you would want to read the data. This causes a problem. Let us demonstrate.

What are Keys and Why Use Them?

Assume we have a file myfile.bin. Let us write & commit, say, the player's score, 3, to it. The binary representation of 3 is "00000011". The file becomes:

00000011

Now let us write & commit, say, the player's health, 8, to the file. The binary representation of 8 is "00001000". We append it to the end of the file so that our 3 doesn't disappear. Our file becomes:

00000011 00001000

Now we close the program and reopen it. Right now, all the information we have is the file above. Now what if we want to load the player's score? How do we know which one it is? Is is 3, 00000011, or 8, 00001000? With our current information, there's no way to know.

That's why we have keys associated with our values. A key is a piece of information that matches with its data, making the act of finding the value simply finding the key and getting its associated value. Let us demonstrate.

Let us write the player's score, 3, again, but this time under the key "a". The binary representation of "a" is 01100001. Usually, we would write the data contiguously, but for simplicity, we'll add an arrow that points from the key to the value. Our file becomes:

01100001 → 00000011

Let us write the player's health, 8, under the key "b", whose binary representation is 01100010. Our file becomes:

01100001 → 00000011
01100010 → 00001000

Now if we want to find the player's health, we simply get the data associated with its key, which is "b". Here, we find that this value is 00001000, which is indeed the player's health we just saved.

Usage

Now that we have understood the importance of having keys, we can see how we use write() in cpersist. To use write, you simply do:

auto file = cpersist::File("myfile");
file.write("number", 3); // the writing is done here

What this does is that it writes the number 3 and associates the key number with it. This does not write anything into the file, only to the buffer on the memory. You can repeat this operation as many times as you want:

file.write("a", 5);
file.write("b", 3);
file.write("c", 13);

You can also write other types.

file.write("mystring", "hello");

You can use the bracket [] operator too.

file["d"] = 15;
file["username"] = "Alice";

All of those operations will dump this content into an in-memory buffer. To save those changes such that they can be accessed with A) another session, or B) another file instance with the same name, you call commit():

file.commit();

This will dump the buffer into a file, letting the data persist regardless of the actual file instance now.

The process of saving now becomes:

auto file = cpersist::File("myfile");
file.write("a", 5);
file.write("b", 2);
file.commit();

When a cpersist::File is created with the same name, the data is loaded automatically. See:

{
    auto file = cpersist::File("myfile");
    file.write("a", 5);
    file.commit()'
} // file is destroyed here, but because we called commit(), the data isn't.
{
    auto file = cpersist::File("myfile"); // the data is loaded automatically from the file
    std::cout << file.read<int>("a") << std::endl; // prints 5
}

read<T>() will be covered later. What you need to know now is:

1. write() does not persist data, it only keeps it in the buffer associated with the cpersist::File you wrote to.
2. commit() is what makes data persist across sessions and cpersist::File instances.
3. For data to persist across cpersist::File instances, their names must be the saeme.
4. If the filenames match, cpersist::File automatically loads the data from its associated file.

Note

When creating a file, you are allowed to choose the extension of the file that is generated on commit() via:

auto file = cpersist::File("myfile", "extension");

If not passed, the extension is set to .bin.

← Files and Buffers