Reference

These are the interfaces of the various parts of the immer::persist library.

Policy

concept immer::persist::Policy = requires(Value value, T policy) { policy.get_pool_types(value); }

Policy is a type that describes certain aspects of serialization for immer::persist.

• How to call into the cereal archive to save and load the user-provided value. Can be used to serealize the value inline (without the value0 node) by taking a dependency on cereal-inline, for example.
• Types of immer containers that will be serialized using pools. One pool contains nodes of only one immer container type.
• Names for each per-type pool.

auto immer::persist::via_get_pools_names_policy(const auto &value)

Create an immer::persist policy that uses the user-provided get_pools_names function (located in the same namespace as the value user serializes) to determine:

• the types of immer containers that should be serialized in a pool
• the names of those pools in JSON (and possibly other formats).

The get_pools_names function is expected to return a boost::hana::map where key is a container type and value is the name for this container’s pool as a BOOST_HANA_STRING.

Parameters

• value: Value that is going to be serialized, only type of the value matters.

auto immer::persist::hana_struct_auto_member_name_policy(const auto &value)

Create an immer::persist policy that recursively finds all immer containers in a serialized value and uses member names to name the pools.

The value must be a boost::hana::Struct.

Parameters

• value: Value that is going to be serialized, only type of the value matters.

struct immer::persist::value0_serialize_t

#include <policy.hpp>

This struct provides functions that immer::persist uses to serialize the user-provided value using cereal.

In this case, we use cereal’s default name, value0. It’s used in all policies provided by immer::persist.

Other possible way would be to use a third-party library to serialize the value inline (without the value0 node) by taking a dependency on cereal-inline, for example.

Subclassed by immer::persist::hana_struct_auto_member_name_policy_t< T >, immer::persist::via_get_pools_names_policy_t< T >, immer::persist::via_get_pools_types_policy

struct immer::persist::demangled_names_t

#include <policy.hpp>

This struct is used in some policies to provide names to each pool by using a demangled name of the immer container corresponding to the pool.

Subclassed by immer::persist::hana_struct_auto_policy, immer::persist::via_get_pools_types_policy

struct immer::persist::via_get_pools_types_policy

#include <policy.hpp>

An immer::persist policy that uses the user-provided get_pools_types function to determine the types of immer containers that should be serialized in a pool.

The get_pools_types function is expected to return a boost::hana::set of types of the desired containers.

The names for the pools are determined via demangled_names_t.

Inherits from immer::persist::demangled_names_t, immer::persist::value0_serialize_t

struct immer::persist::hana_struct_auto_policy

#include <policy.hpp>

An immer::persist policy that recursively finds all immer containers in a serialized value.

The value must be a boost::hana::Struct.

The names for the pools are determined via demangled_names_t.

Inherits from immer::persist::demangled_names_t

API Overview

template <class T, class Archive = cereal::JSONInputArchive, Policy< T > Policy = default_policy, class… Args>

T immer::persist::cereal_load_with_pools(std::istream &is, const Policy &policy = Policy{}, Args&&... args)

Load a value of the given type T from the provided stream using pools.

By default, cereal::JSONInputArchive is used but a different cereal input archive can be provided.

template <class T, class Archive = cereal::JSONInputArchive, Policy< T > Policy = default_policy>

T immer::persist::cereal_load_with_pools(const std::string &input, const Policy &policy = Policy{})

Load a value of the given type T from the provided string using pools.

By default, cereal::JSONInputArchive is used but a different cereal input archive can be provided.

template <class Archive = cereal::JSONOutputArchive, class T, Policy< T > Policy = default_policy, class… Args>

void immer::persist::cereal_save_with_pools(std::ostream &os, const T &value0, const Policy &policy = Policy{}, Args&&... args)

Serialize the provided value with pools using the provided policy outputting into the provided stream.

By default, cereal::JSONOutputArchive is used but a different cereal output archive can be provided.

See

Policy

template <class Archive = cereal::JSONOutputArchive, class T, Policy< T > Policy = default_policy, class… Args>

std::string immer::persist::cereal_save_with_pools(const T &value0, const Policy &policy = Policy{}, Args&&... args)

Serialize the provided value with pools using the provided policy.

By default, cereal::JSONOutputArchive is used but a different cereal output archive can be provided.

Return

std::string The resulting JSON.

template <class T>

struct immer::persist::xx_hash

#include <xxhash.hpp>

xxHash is a good option to be used with immer::persist as it produces hashes identical across all platforms.

See

https://xxhash.com/

template <class Previous, class Pools, class WrapFn, class PoolNameFn>

class immer::persist::output_pools_cereal_archive_wrapper

#include <archives.hpp>

A wrapper type that wraps a cereal::OutputArchive (for example, JSONOutputArchive), provides access to the Pools object stored inside, and serializes the pools object alongside the user document.

Normally, the function cereal_save_with_pools should be used instead of using this wrapper directly.

See

cereal_save_with_pools

Inherits from cereal::OutputArchive< output_pools_cereal_archive_wrapper< Previous, Pools, WrapFn, PoolNameFn > >, TextArchive

template <class Previous, class Pools, class WrapFn, class PoolNameFn>

class immer::persist::input_pools_cereal_archive_wrapper

#include <archives.hpp>

A wrapper type that wraps a cereal::InputArchive (for example, JSONInputArchive) and provides access to the pools object.

Normally, the function cereal_load_with_pools should be used instead of using this wrapper directly.

See

cereal_load_with_pools

Inherits from cereal::InputArchive< input_pools_cereal_archive_wrapper< Previous, Pools, WrapFn, PoolNameFn > >, TextArchive

Transform API

template <typename T, Policy< T > Policy = hana_struct_auto_policy>

auto immer::persist::get_output_pools(const T &value0, const Policy &policy = Policy{})

Return just the pools of all the containers of the provided value serialized using the provided policy.

See

convert_container

template <class Storage, class ConversionMap>

auto immer::persist::transform_output_pool(const detail::output_pools<Storage> &old_pools, const ConversionMap &conversion_map)

Given output_pools and a map of transformations, produce a new type of input pools with those transformations applied.

conversion_map is a boost::hana::map where keys are types of immer containers and values are the transforming functions.

See

get_output_pools

transformations-with-pools Transforming nested containers

template <class SaveStorage, class LoadStorage, class Container>

auto immer::persist::convert_container(const detail::output_pools<SaveStorage> &output_pools, detail::input_pools<LoadStorage> &new_input_pools, const Container &container)

Given output_pools and new (transformed) input_pools, effectively convert the given container.

See

get_output_pools

transformations-with-pools Transforming nested containers

template <class Container>

struct immer::persist::incompatible_hash_wrapper

#include <hash_container_conversion.hpp>

The wrapper is used to enable the incompatible hash mode which is required when the key of a hash-based container transformed in a way that changes its hash.

A value of this type should be returned from a transforming function accepting target_container_type_request.

See

Modifying the hash of the ID

struct immer::persist::target_container_type_request

#include <hash_container_conversion.hpp>

This type is used as an argument for a transforming function.

The return type of the function is used to specify the desired container type to contain the transformed values.

See

Hash-based containers

Exceptions

class immer::persist::pool_exception

#include <errors.hpp>

Base class from which all the exceptions in immer::persist are derived.

Inherits from invalid_argument

Subclassed by immer::persist::duplicate_name_pool_detected, immer::persist::invalid_children_count, immer::persist::invalid_container_id, immer::persist::invalid_node_id, immer::persist::pool_has_cycles

class immer::persist::pool_has_cycles

#include <errors.hpp>

Thrown when a cycle is detected in the pool of vectors.

Inherits from immer::persist::pool_exception

class immer::persist::invalid_node_id

#include <errors.hpp>

Thrown when a non-existent node is mentioned.

Inherits from immer::persist::pool_exception

class immer::persist::invalid_container_id

#include <errors.hpp>

Thrown when a non-existent container is mentioned.

Inherits from immer::persist::pool_exception

class immer::persist::invalid_children_count

#include <errors.hpp>

Thrown when a node has more children than expected.

Inherits from immer::persist::pool_exception

class immer::persist::duplicate_name_pool_detected

#include <errors.hpp>

Thrown when duplicate pool name is detected.

Inherits from immer::persist::pool_exception