Added quickstart page
This commit is contained in:
Randolph Voorhies
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
<br/>
|
||||
|
||||
{% capture class_begin %}struct MyClass {
|
||||
int x, y, z;{% endcapture %}
|
||||
|
||||
|
||||
<div class="row">
|
||||
<div class="span1"></div>
|
||||
<div class="span5">
|
||||
|
||||
Internal serialize function
|
||||
|
||||
{% highlight cpp %}
|
||||
{{ class_begin }}
|
||||
|
||||
template<class Archive>
|
||||
void serialize(Archive & archive)
|
||||
{
|
||||
archive( x, y, z );
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
{% endhighlight %}
|
||||
</div>
|
||||
<div class="span5">
|
||||
|
||||
Internal split/load functions
|
||||
|
||||
{% highlight cpp %}
|
||||
{{ class_begin }}
|
||||
|
||||
template<class Archive>
|
||||
void save(Archive & archive) const
|
||||
{
|
||||
archive( x, y, z );
|
||||
}
|
||||
|
||||
template<class Archive>
|
||||
void load(Archive & archive)
|
||||
{
|
||||
archive( x, y, z );
|
||||
}
|
||||
};
|
||||
{% endhighlight %}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="row">
|
||||
<div class="span1"></div>
|
||||
<div class="span5">
|
||||
|
||||
External serialize function
|
||||
|
||||
{% highlight cpp %}
|
||||
{{ class_begin }}
|
||||
};
|
||||
|
||||
template<class Archive>
|
||||
void serialize(Archive & archive,
|
||||
MyClass & m)
|
||||
{
|
||||
archive( m.x, m.y, m.z );
|
||||
}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
{% endhighlight %}
|
||||
</div>
|
||||
|
||||
<div class="span5">
|
||||
|
||||
External split/load functions
|
||||
|
||||
{% highlight cpp %}
|
||||
{{ class_begin }}
|
||||
};
|
||||
|
||||
template<class Archive>
|
||||
void save(Archive & archive,
|
||||
MyClass const & m)
|
||||
{
|
||||
archive( m.x, m.y, m.z );
|
||||
}
|
||||
|
||||
template<class Archive>
|
||||
void load(Archive & archive)
|
||||
MyClass & m)
|
||||
{
|
||||
archive( m.x, m.y, m.z );
|
||||
}
|
||||
{% endhighlight %}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
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 <cereal/archives/binary.hpp>`
|
||||
|
||||
`#include <cereal/archives/xml.hpp>`
|
||||
|
||||
or
|
||||
|
||||
`#include <cereal/archives/json.hpp>`
|
||||
|
||||
---
|
||||
|
||||
### Serialize your data
|
||||
|
||||
```{cpp}
|
||||
#include <cereal/archives/binary.hpp>
|
||||
#include <fstream>
|
||||
|
||||
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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
@@ -41,12 +41,17 @@ Although detailed at length [elsewhere](polymorphism.html), if you will be seria
|
||||
|
||||
---
|
||||
|
||||
<a name="binary_archive"></a>
|
||||
|
||||
## Binary Data
|
||||
|
||||
The binary archive can be used by including `<cereal/archives/binary.hpp>`. 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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
<a name="xml_archive"></a>
|
||||
|
||||
## XML
|
||||
|
||||
The XML archive can be used by including `<cereal/archives/xml.hpp>`. 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
|
||||
|
||||
---
|
||||
|
||||
<a name="json_archive"></a>
|
||||
|
||||
## JSON
|
||||
|
||||
The JSON archive can be used by including `<cereal/archives/json.hpp>`. JSON is a human readable format and should not be used in situations where serialized data size is critical.
|
||||
|
||||
+14
-5
@@ -43,13 +43,24 @@
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<div class="container-fluid">
|
||||
|
||||
|
||||
<div class="navbar">
|
||||
<div class="navbar-inner">
|
||||
<a class="brand" href="{{ site.baseurl }}">cereal</a>
|
||||
<ul class="nav">
|
||||
<li><a href="{{ site.baseurl }}/index.html">Documentation</a></li>
|
||||
<li><a href="{{ site.baseurl }}/assets/doxygen/index.html">Doxygen Docs</a></li>
|
||||
<li><a href="https://github.com/USCiLab/cereal">Github</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="row-fluid">
|
||||
<div class="span3">
|
||||
<div class="well sidebar-nav">
|
||||
<ul class="nav nav-list">
|
||||
<!--<li class="active"><a href="#">Link</a></li>-->
|
||||
<li class="nav-header">Documentation</li>
|
||||
<li><a href="index.html">Home</a></li>
|
||||
<li><a href="quickstart.html">Quick Start</a></li>
|
||||
@@ -58,13 +69,11 @@
|
||||
<li><a href="pointers.html">Pointers (Smart and Dumb)</a></li>
|
||||
<li><a href="inheritance.html">Inheritance</a></li>
|
||||
<li><a href="polymorphism.html">Polymorphism</a></li>
|
||||
<hr/>
|
||||
<li><a href="{{ site.baseurl }}/assets/doxygen/index.html">Doxygen Docs</a></li>
|
||||
</ul>
|
||||
|
||||
</div><!--/.well -->
|
||||
</div><!--/span-->
|
||||
<div class="span9">
|
||||
<div class="span7">
|
||||
{{content}}
|
||||
</div><!--/span-->
|
||||
</div><!--/row-->
|
||||
|
||||
Reference in New Issue
Block a user