Installation and Usage

How to Add Cista to Your Project

There are now two ways to use Cista:

The cista.h single-header file can be downloaded in a release version or generated via CMake using the cista-test-single-header target.

For larger projects, it is recommended to use Cista as a CMake library:

add_subdirectory(cista)
# ...
target_link_libraries(my_target cista)

And in your project source code:

#include "cista/containers/vector.h"
#include "cista/reflection/to_tuple.h"
// ...

You can extract the ZIP file to your project or add cista as a Git submodule:

git submodule add https://github.com/felixguendling/cista.git cista

This way, you can include only the headers you need which could improve compilation times.

Declare the data structures you want to serialize as regular C++ structs (using scalar types, cista::raw/offset::string, cista::raw/offset::unique_ptr<T&>, and cista::raw/offset::vector<T&> - more types such as map/set/etc. may follow). To be precise, they need to be standard layout, non-polymorphic aggregate types.
Do NOT declare any constructors (reflection will not work otherwise).
Always use data types with known sizes such as int32_t, uint8_t for compatibility across platforms (with the same architecture).
To use pointers: store the object you want to reference as cista::raw/offset::unique_ptr<T&> and use a raw pointer T* to reference it.
Optional: if you need deterministic buffer contents, you need to fill spare bytes in your structs (see the advanced example below).

Hint: using pointers in hashed keys of hash_map or hash_set will not work because pointer values change at serialization.

Cista++ supports two serialization formats:

Offset Based Data Structures

+ can be read without any deserialization step (i.e. reinterpret_cast<T> is sufficient).
+ suitable for shared memory applications
- slower at runtime (pointers need to be resolved using one more add)

Raw Data Structures