mirror of
https://github.com/USCiLab/cereal.git
synced 2025-07-21 02:32:00 +02:00
254 lines
10 KiB
Markdown
254 lines
10 KiB
Markdown
Archive Specialization
|
|
============
|
|
|
|
cereal supports having specific serialization behaviors for different archive types.
|
|
|
|
---
|
|
|
|
### TLDR Version
|
|
|
|
You can specialize your own types or types that cereal comes with support for to exhibit specific behaviors with
|
|
specific archives. This is typically done by replacing at least one generic templated parameter with the type you wish to specialize for. Specializations will be given precedence over any templated serialization function.
|
|
|
|
If you want to specialize for several types of archives, you will need to use templates and type traits to restrict
|
|
template instantiation. cereal provides several traits to help with this, defined in `<cereal/details/traits.hpp>`.
|
|
|
|
---
|
|
|
|
## Specializing Built-in Types
|
|
|
|
Although cereal comes with a support for nearly every type in the [standard library](stl_support.html), there can be
|
|
times when it is desirable to have custom functionality for a type that cereal provides the serialization for. Function
|
|
overloading can be used to override the cereal implementation with a custom one. This will work even if you include the
|
|
cereal support for a type - assuming that the compiler doesn't find any ambiguity in your overload (more on that later).
|
|
|
|
### Specializing the archive
|
|
|
|
If you want to make an archive behave differently for some type, you can do this by creating overloads where the archive
|
|
is explicitly defined (and not a template parameter):
|
|
|
|
```cpp
|
|
namespace cereal
|
|
{
|
|
// Overload the std::complex serialization code for a specific archive
|
|
template <class T>
|
|
void save( cereal::XMLOutputArchive & ar, std::complex<T> const & comp )
|
|
{ /* your code here */ }
|
|
|
|
template <class T>
|
|
void load( cereal::XMLInputArchive & ar, std::complex<T> & comp )
|
|
{ /* your code here */ }
|
|
|
|
// Note that it doesn't make much sense to overload a plain serialize function
|
|
// (i.e. void serialize()) because it expects to be called
|
|
// for loading (an input archive) and saving (an output archive).
|
|
// We would end up needing to implement two versions of it, so using a load/save
|
|
// pair makes more sense.
|
|
}
|
|
```
|
|
|
|
<span class="label label-warning">Important!</span>
|
|
When overloading a cereal provided serialization function, you should place it in the `xCEREAL` namespace.
|
|
|
|
### Specializing the type
|
|
|
|
It is also easy to specialize the behavior of a specific type for all archives or a group of archives. This is done by
|
|
restricting the serialized type instead of restricting the archive (though you can definitely specialize on both the
|
|
archive and the type).
|
|
|
|
The following example shows how to specialize serialization for `std::map<std::string, std::string>` for text archives such that it
|
|
roughly matches the output of an SQL \`WHERE\` clause in which all the expressions (from a name-value-pair perspective)
|
|
are ANDed together (inspired by [this](http://stackoverflow.com/questions/22569832/is-there-a-way-to-specify-a-simpler-json-de-serialization-for-stdmap-using-c) stackoverflow post):
|
|
|
|
#### The serialization code:
|
|
```cpp
|
|
namespace cereal
|
|
{
|
|
//! Saving for std::map<std::string, std::string> for text based archives
|
|
// Note that this shows off some internal xCEREAL traits such as EnableIf,
|
|
// which will only allow this template to be instantiated if its predicates
|
|
// are true
|
|
template <class Archive, class C, class A,
|
|
traits::EnableIf<traits::is_text_archive<Archive>::value> = traits::sfinae> inline
|
|
void save( Archive & ar, std::map<std::string, std::string, C, A> const & map )
|
|
{
|
|
for( const auto & i : map )
|
|
ar( cereal::make_nvp( i.first, i.second ) );
|
|
}
|
|
|
|
//! Loading for std::map<std::string, std::string> for text based archives
|
|
template <class Archive, class C, class A,
|
|
traits::EnableIf<traits::is_text_archive<Archive>::value> = traits::sfinae> inline
|
|
void load( Archive & ar, std::map<std::string, std::string, C, A> & map )
|
|
{
|
|
map.clear();
|
|
|
|
auto hint = map.begin();
|
|
while( true )
|
|
{
|
|
const auto namePtr = ar.getNodeName();
|
|
|
|
if( !namePtr )
|
|
break;
|
|
|
|
std::string key = namePtr;
|
|
std::string value; ar( value );
|
|
hint = map.emplace_hint( hint, std::move( key ), std::move( value ) );
|
|
}
|
|
}
|
|
} // namespace cereal
|
|
```
|
|
<span class="label label-warning">Important!</span>
|
|
Please note that for all specializations, you must have at least one parameter that has higher precedence than the
|
|
default templated version that cereal provides. This usually means you need to explicitly specialize at least one
|
|
template parameter. In the above examples we specialized two of the template parameters for `std::map`.
|
|
|
|
#### Using the serialization code:
|
|
```cpp
|
|
int main()
|
|
{
|
|
std::stringstream ss;
|
|
{
|
|
cereal::JSONOutputArchive ar(ss);
|
|
std::map<std::string, std::string> filter = {% raw %}{{"type", "sensor"}, {"status", "critical"}}{% endraw %};
|
|
|
|
ar( CEREAL_NVP(filter) );
|
|
}
|
|
|
|
std::cout << ss.str() << std::endl;
|
|
|
|
{
|
|
cereal::JSONInputArchive ar(ss);
|
|
cereal::JSONOutputArchive ar2(std::cout);
|
|
|
|
std::map<std::string, std::string> filter;
|
|
|
|
ar( CEREAL_NVP(filter) );
|
|
ar2( CEREAL_NVP(filter) );
|
|
}
|
|
|
|
std::cout << std::endl;
|
|
return 0;
|
|
}
|
|
```
|
|
|
|
#### Output using xCEREAL built in support:
|
|
```json
|
|
{
|
|
"filter": [
|
|
{ "key": "type", "value": "sensor" },
|
|
{ "key": "status", "value": "critical" }
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Output using the above specialized serializaton code:
|
|
```json
|
|
{
|
|
"filter": {
|
|
"status": "critical",
|
|
"type": "sensor"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Specializing User Defined Types
|
|
|
|
Specializing a user defined type works in almost exactly the same fashion to types in the standard library that cereal provides
|
|
the implementation for. The only real difference is that there is no longer a requirement that the serialization code
|
|
reside in the `xCEREAL` namespace - it now goes wherever you would normally put your serialization code.
|
|
|
|
Since there is no provided implementation to conflict with, you have more control over the generality of your
|
|
implementations. It is much easier to use templates to restrict how the serialization functions are instantiated, as
|
|
shown in the following example, which uses different serialization depending on whether a binary archive is used versus
|
|
some other type:
|
|
|
|
<a name="user_defined_types_example"></a>
|
|
|
|
```cpp
|
|
struct Hello
|
|
{
|
|
int x;
|
|
|
|
// Enabled for text archives (e.g. XML, JSON)
|
|
template <class Archive,
|
|
cereal::traits::EnableIf<cereal::traits::is_text_archive<Archive>::value>
|
|
= cereal::traits::sfinae>
|
|
std::string save_minimal( Archive & ) const
|
|
{
|
|
return std::to_string( x ) + "hello";
|
|
}
|
|
|
|
// Enabled for text archives (e.g. XML, JSON)
|
|
template <class Archive,
|
|
cereal::traits::EnableIf<cereal::traits::is_text_archive<Archive>::value>
|
|
= cereal::traits::sfinae>
|
|
void load_minimal( Archive const &, std::string const & str )
|
|
{
|
|
x = std::stoi( str.substr(0, 1) );
|
|
}
|
|
|
|
// Enabled for binary archives (e.g. binary, portable binary)
|
|
template <class Archive,
|
|
cereal::traits::DisableIf<cereal::traits::is_text_archive<Archive>::value>
|
|
= cereal::traits::sfinae>
|
|
int save_minimal( Archive & ) const
|
|
{
|
|
return x;
|
|
}
|
|
|
|
// Enabled for binary archives (e.g. binary, portable binary)
|
|
template <class Archive,
|
|
cereal::traits::DisableIf<cereal::traits::is_text_archive<Archive>::value>
|
|
= cereal::traits::sfinae>
|
|
void load_minimal( Archive const &, int const & xx )
|
|
{
|
|
x = xx;
|
|
}
|
|
};
|
|
```
|
|
|
|
## Useful Type Traits
|
|
|
|
There are several useful type traits defined in `<cereal/details/traits.hpp>` which are useful when specializing serialization functions. The doxygen documentation for this entire file can be found [here]({{ site.baseurl }}/assets/doxygen/traits_8hpp.html). The following are a few especially helpful traits:
|
|
|
|
### EnableIf and DisableIf
|
|
|
|
If you are used to template metaprogramming in C++, you may already be familiar with techniques such as
|
|
[`std::enable_if`](http://en.cppreference.com/w/cpp/types/enable_if), which can be used to selectively disable function
|
|
overloads.
|
|
|
|
cereal provides some similar functionality in a slightly more aesthetically pleasing manner with `EnableIf`
|
|
([documentation]({{ site.baseurl }}/assets/doxygen/traits_8hpp.html#a07719740a7cec6692b44244201a92603)) and
|
|
`DisableIf` ([documentation]({{ site.baseurl }}/assets/doxygen/traits_8hpp.html#a42e5f793ba5a1b3d2fd674d7334b12bd)). These will enable (with `EnableIf`) or disable (with `DisableIf`) a function overload if all of their variadic bool parameters, when ANDed together, are true. Since they perform an AND operation of their arguments, OR operations or other more complicated boolean expressions should be done manually beforehand.
|
|
|
|
Instead of using the clumsy syntax of `std::enable_if`, which requires replacing the function return type, `EnableIf`
|
|
and `DisableIf` are added as an extra template parameter to the function, with the default value of
|
|
`cereal::traits::sfinae`. See any of the above [examples](#user_defined_types_example) or the
|
|
linked documentation for useage details.
|
|
|
|
### is\_same_archive
|
|
|
|
`is_same_archive` operates in a similar manner to [`std::is_same`](http://en.cppreference.com/w/cpp/types/is_same)
|
|
except that it will automatically strip various wrappers and CV (const or volatile) qualifiers that may be applied. Its
|
|
use is recommended over `std::is_same` because cereal will often slightly adjust archive parameters so that they become
|
|
const or are wrapped in some internal traits class. See the [documentation]({{ site.baseurl }}/assets/doxygen/structcereal_1_1traits_1_1is__same__archive.html) for more information and an example.
|
|
|
|
### is\_text_archive
|
|
|
|
`is_text_archive` checks to see if an archive has been tagged with the `cereal::traits::TextArchive` tag. JSON and XML
|
|
archives that ship with cereal both have this tag. See [here]({{ site.baseurl }}/assets/doxygen/structcereal_1_1traits_1_1is__text__archive.html) for more information.
|
|
|
|
<a name="strip_minimal"></a>
|
|
|
|
### strip\_minimal
|
|
|
|
`strip_minimal` is especially useful when working with custom `save_minimal` or `load_minimal` functions. cereal may
|
|
wrap types when performing compile time checks to ensure the validity of such functions, which may cause some custom
|
|
metaprogramming to fail unexpectedly. Using the type provided by `strip_minimal`, instead of the raw template
|
|
parameter, will help prevent this. Check out the [documentation]({{ site.baseurl }}/assets/doxygen/structcereal_1_1traits_1_1strip__minimal.html) as well as its use for serializing enums in the
|
|
`common.hpp` type support [here]({{ site.baseurl }}/assets/doxygen/common_8hpp_source.html).
|
|
|