diff --git a/_includes/pointers.markdown b/_includes/pointers.markdown index 7e517d5a..69c575ce 100644 --- a/_includes/pointers.markdown +++ b/_includes/pointers.markdown @@ -60,9 +60,10 @@ namespace cereal return new MyType( x ); } }; -`` +``` + --- -` + ### Implementation notes When saving an `std::shared_ptr`, we first check to make sure we haven't serialized it before. This is done by keeping a map from addresses to pointer ids (an `std::uint32_t`), which are unique. Pointers that are newly serialized are given a new id with the most significant bit set to `1`. When saved, an `std::shared_ptr` will first output its id, which will either have its MSB set to `1` if it is the first instance of that id, or will be an id already in the archive. This is immediately followed by the data found by dereferencing the pointer. If the pointer was equal to `nullptr`, its id is set to `0` and nothing else is saved. diff --git a/_includes/quickstart.markdown b/_includes/quickstart.markdown index 3b84ede9..2ab92c64 100644 --- a/_includes/quickstart.markdown +++ b/_includes/quickstart.markdown @@ -1,3 +1,171 @@ Quick Start =========== +--- + +### Get cereal + +cereal was designed to be included in your project, so just grab the latest +version from [Github] (https://github.com/USCiLab/cereal) and drop it somewhere +your project can find it. + +--- + +### Add Serialization Methods for Your Classes + +cereal has to know what data members to serialize in your classes. Let it know +by implementing one of the following types of serialization methods. + +
+ +{% capture class_begin %}struct MyClass { + int x, y, z;{% endcapture %} + + +
+
+
+ + Internal serialize function + + {% highlight cpp %} +{{ class_begin }} + + template + void serialize(Archive & archive) + { + archive( x, y, z ); + } +}; + + + + + + + {% endhighlight %} +
+
+ + Internal split/load functions + + {% highlight cpp %} +{{ class_begin }} + + template + void save(Archive & archive) const + { + archive( x, y, z ); + } + + template + void load(Archive & archive) + { + archive( x, y, z ); + } +}; + {% endhighlight %} +
+
+ +
+
+
+ + External serialize function + + {% highlight cpp %} +{{ class_begin }} +}; + +template + void serialize(Archive & archive, + MyClass & m) + { + archive( m.x, m.y, m.z ); + } + + + + + + + + {% endhighlight %} +
+ +
+ + External split/load functions + + {% highlight cpp %} +{{ class_begin }} +}; + + template + void save(Archive & archive, + MyClass const & m) + { + archive( m.x, m.y, m.z ); + } + + template + void load(Archive & archive) + MyClass & m) + { + archive( m.x, m.y, m.z ); + } + {% endhighlight %} +
+
+ +Internal serialization functions can also be made private or protected by adding `friend class cereal::access;` to your class. + +--- + +### Choose an archive + +cereal currently supports three archive types: +[binary] (serialization_archives.html#binary_archive), +[XML] (serialization_archives.html#xml_archive), and +[JSON] (serialization_archives.html#json_archive). + +Include your preferred archive type with: + +`#include ` + +`#include ` + +or + +`#include ` + +--- + +### Serialize your data + +```{cpp} +#include +#include + +int main() +{ + { + std::ofstream os("data.cereal"); // Open a file for writing + cereal::BinaryOutputArchive oarchive(os); // Create an output archive + + MyData m1, m2, m3; + oarchive(m1, m2, m3); // Write the data to the archive + } + + { + std::ifstream is("data.cereal"); // Open a file for reading + cereal::BinaryInputArchive iarchive(is); // Create an input archive + + MyData m1, m2, m3; + iarchive(m1, m2, m3); // Read the data from the archive + } +} +``` + + diff --git a/_includes/serialization_archives.markdown b/_includes/serialization_archives.markdown index ace5c790..0d57d9bd 100644 --- a/_includes/serialization_archives.markdown +++ b/_includes/serialization_archives.markdown @@ -41,12 +41,17 @@ Although detailed at length [elsewhere](polymorphism.html), if you will be seria --- + + ## Binary Data The binary archive can be used by including ``. The binary archive is designed to produce compact bit level representations of data and is not human readable. It is a good choice when computers will be looking at the data on both ends of the serialization. The binary archive is also the fastest archive that comes with cereal. Binary archives will ignore name-value pairs and only serialize the values. --- + + + ## XML The XML archive can be used by including ``. XML is a human readable format and should not be used in situations where serialized data size is critical. Unlike the binary archive, which outputs its data incrementally as serialization functions are called, the XML archive builds a tree in memory and only outputs it upon destruction of the archive. @@ -88,6 +93,8 @@ XML can optionally output complete demangled type information as an attribute an --- + + ## JSON The JSON archive can be used by including ``. JSON is a human readable format and should not be used in situations where serialized data size is critical. diff --git a/_layouts/default.html b/_layouts/default.html index 3becb1c6..b1c9df20 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -43,13 +43,24 @@ -
+ + +
+
+ cereal + +
+
+
-
+
{{content}}