palimpsest — Fast serializable C++ dictionaries
v2.2.0
|
Dictionary of values and sub-dictionaries. More...
Public Member Functions | |
Dictionary ()=default | |
Default constructor. More... | |
Dictionary (const Dictionary &)=delete | |
No copy constructor. More... | |
Dictionary & | operator= (const Dictionary &)=delete |
No copy assignment operator. More... | |
Dictionary (Dictionary &&)=default | |
Default move constructor. More... | |
Dictionary & | operator= (Dictionary &&)=default |
Default move assignment operator. More... | |
~Dictionary ()=default | |
Default destructor. More... | |
bool | is_map () const noexcept |
We are a (potentially empty) map if and only if the value is empty. More... | |
bool | is_empty () const noexcept |
We are empty if and only if we are a dictionary with no element. More... | |
bool | is_value () const noexcept |
We are a value if and only if the internal value is non-empty. More... | |
bool | has (const std::string &key) const noexcept |
Check whether a key is in the dictionary. More... | |
std::vector< std::string > | keys () const noexcept |
Return the list of keys of the dictionary. More... | |
unsigned | size () const noexcept |
Return the number of keys in the dictionary. More... | |
template<typename T > | |
T & | as () |
Get reference to the internal value. More... | |
template<typename T > | |
const T & | as () const |
Const variant of as. More... | |
template<typename T > | |
T & | get (const std::string &key) |
Get reference to the object at a given key. More... | |
template<typename T > | |
const T & | get (const std::string &key) const |
Const variant of get. More... | |
template<typename T > | |
const T & | get (const std::string &key, const T &default_value) const |
Get object at a given key if it exists, or a default value otherwise. More... | |
template<typename T , typename... ArgsT, typename... Args> | |
T & | insert (const std::string &key, Args &&...args) |
Create an object at a given key and return a reference to it. More... | |
template<typename T > | |
Dictionary & | operator= (const T &new_value) |
Assign value directly. More... | |
Dictionary & | operator= (const char *c_string) |
Assignment operator for C-style strings. More... | |
void | remove (const std::string &key) noexcept |
Remove a key-value pair from the dictionary. More... | |
void | clear () noexcept |
Remove all entries from the dictionary. More... | |
Dictionary & | operator() (const std::string &key) |
Return a reference to the dictionary at key, performing an insertion if such a key does not already exist. More... | |
const Dictionary & | operator() (const std::string &key) const |
Return a reference to the dictionary at key, performing an insertion if such a key does not already exist. More... | |
size_t | serialize (std::vector< char > &buffer) const |
Serialize to raw MessagePack data. More... | |
void | write (const std::string &filename) const |
Write MessagePack serialization to a binary file. More... | |
void | read (const std::string &filename) |
Update dictionary from a MessagePack binary file. More... | |
void | update (const char *data, size_t size) |
Update dictionary from raw MessagePack data. More... | |
void | update (mpack_node_t node) |
Update existing values from an MPack node. More... | |
operator bool & () | |
Allow implicit conversion to (bool &). More... | |
operator const bool & () const | |
Allow implicit conversion to (const bool &). More... | |
operator int8_t & () | |
Allow implicit conversion to (int8_t &). More... | |
operator const int8_t & () const | |
Allow implicit conversion to (const int8_t &). More... | |
operator int16_t & () | |
Allow implicit conversion to (int16_t &). More... | |
operator const int16_t & () const | |
Allow implicit conversion to (const int16_t &). More... | |
operator int32_t & () | |
Allow implicit conversion to (int32_t &). More... | |
operator const int32_t & () const | |
Allow implicit conversion to (const int32_t &). More... | |
operator int64_t & () | |
Allow implicit conversion to (int64_t &). More... | |
operator const int64_t & () const | |
Allow implicit conversion to (const int64_t &). More... | |
operator uint8_t & () | |
Allow implicit conversion to (uint8_t &). More... | |
operator const uint8_t & () const | |
Allow implicit conversion to (const uint8_t &). More... | |
operator uint16_t & () | |
Allow implicit conversion to (uint16_t &). More... | |
operator const uint16_t & () const | |
Allow implicit conversion to (const uint16_t &). More... | |
operator uint32_t & () | |
Allow implicit conversion to (uint32_t &). More... | |
operator const uint32_t & () const | |
Allow implicit conversion to (const uint32_t &). More... | |
operator uint64_t & () | |
Allow implicit conversion to (uint64_t &). More... | |
operator const uint64_t & () const | |
Allow implicit conversion to (const uint64_t &). More... | |
operator float & () | |
Allow implicit conversion to (float &). More... | |
operator const float & () const | |
Allow implicit conversion to (const float &). More... | |
operator double & () | |
Allow implicit conversion to (double &). More... | |
operator const double & () const | |
Allow implicit conversion to (const double &). More... | |
operator std::string & () | |
Allow implicit conversion to (std::string &). More... | |
operator const std::string & () const | |
Allow implicit conversion to (const std::string &). More... | |
operator Eigen::Vector2d & () | |
Allow implicit conversion to (Eigen::Vector2d &). More... | |
operator const Eigen::Vector2d & () const | |
Allow implicit conversion to (const Eigen::Vector2d &). More... | |
operator Eigen::Vector3d & () | |
Allow implicit conversion to (Eigen::Vector3d &). More... | |
operator const Eigen::Vector3d & () const | |
Allow implicit conversion to (const Eigen::Vector3d &). More... | |
operator Eigen::VectorXd & () | |
Allow implicit conversion to (Eigen::VectorXd&). More... | |
operator const Eigen::VectorXd & () const | |
Allow implicit conversion to (const Eigen::VectorXd&). More... | |
operator Eigen::Quaterniond & () | |
Allow implicit conversion to (Eigen::Quaterniond &). More... | |
operator const Eigen::Quaterniond & () const | |
Allow implicit conversion to (const Eigen::Quaterniond &). More... | |
operator Eigen::Matrix3d & () | |
Allow implicit conversion to (Eigen::Matrix3d &). More... | |
operator const Eigen::Matrix3d & () const | |
Allow implicit conversion to (const Eigen::Matrix3d &). More... | |
Protected Member Functions | |
template<typename T , typename... ArgsT, typename... Args> | |
void | become (Args &&...args) |
Protected Attributes | |
Value | value_ |
Internal value, used if we are a value. More... | |
std::unordered_map< std::string, std::unique_ptr< Dictionary > > | map_ |
Key-value map, used if we are a map. More... | |
Friends | |
std::ostream & | operator<< (std::ostream &stream, const Dictionary &dict) |
Output stream operator for printing. More... | |
Dictionary of values and sub-dictionaries.
The grammar here is a subset of e.g. JSON or YAML: a dictionary maps keys to either values (number, string, std::vector, Eigen::MatrixXd, ...) or other dictionaries.
This type allows us to store and retrieve C++ objects as follows:
When retrieving an object using get<T>, checks are performed to ensure that the value type and T are compatible. Hence, once an object is inserted in the dictionary, it is not meant to change type later on.
To handle inheritance, we need to explicitely recall the class hierarchy:
This is practical because the root is always an actual dictionary (value insertion in the tree is performed by parents on their children), so that the type we see when declaring Dictionary foo;
is right. The downside is that the type of foo("var")
is still Dictionary; it only becomes its proper value type after an explicit conversion foo("bar").as<T>()
or foo.get<T>("bar")
, or an implicit conversion T& bar = foo("bar");
.
Definition at line 97 of file Dictionary.h.
|
default |
Default constructor.
|
delete |
No copy constructor.
|
default |
Default move constructor.
|
default |
Default destructor.
|
inline |
Get reference to the internal value.
TypeError | if the dictionary is not a value, or it is but the stored value type is not T. |
Definition at line 279 of file Dictionary.h.
|
inline |
Const variant of as.
TypeError | if the stored object type is not T. |
Definition at line 293 of file Dictionary.h.
|
inlineprotected |
Definition at line 652 of file Dictionary.h.
|
noexcept |
Remove all entries from the dictionary.
Definition at line 34 of file Dictionary.cpp.
|
inline |
Get reference to the object at a given key.
[in] | key | Key to the object. |
KeyError | if there is no object at this key. |
TypeError | if there is an object at this key, but its type is not T. |
Definition at line 309 of file Dictionary.h.
|
inline |
Const variant of get.
[in] | key | Key to the object. |
KeyError | if there is no object at this key. |
TypeError | if there is an object at this key, but its type is not T. |
Definition at line 322 of file Dictionary.h.
|
inline |
Get object at a given key if it exists, or a default value otherwise.
[in] | key | Key to look for. |
[in] | default_value | Default value used if there is no value at this key. |
TypeError | if the object at this key is not a value, or it is but its type does is not T. |
Definition at line 337 of file Dictionary.h.
|
inlinenoexcept |
Check whether a key is in the dictionary.
[in] | key | Key to look for. |
Definition at line 261 of file Dictionary.h.
|
inline |
Create an object at a given key and return a reference to it.
If there is already a value at this key, return the existing object instead.
[in] | key | Key to create the object at. |
args | Parameters passed to the object's constructor. |
TypeError | if the dictionary is not a map, and therefore we cannot insert at a given key inside it. |
Definition at line 377 of file Dictionary.h.
|
inlinenoexcept |
We are empty if and only if we are a dictionary with no element.
Definition at line 251 of file Dictionary.h.
|
inlinenoexcept |
We are a (potentially empty) map if and only if the value is empty.
Definition at line 248 of file Dictionary.h.
|
inlinenoexcept |
We are a value if and only if the internal value is non-empty.
Definition at line 254 of file Dictionary.h.
|
noexcept |
Return the list of keys of the dictionary.
Definition at line 180 of file Dictionary.cpp.
|
inline |
Allow implicit conversion to (bool &).
Definition at line 531 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const bool &).
Definition at line 534 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const double &).
Definition at line 594 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const Eigen::Matrix3d &).
Definition at line 638 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const Eigen::Quaterniond &).
Definition at line 630 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const Eigen::Vector2d &).
Definition at line 606 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const Eigen::Vector3d &).
Definition at line 614 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const Eigen::VectorXd&).
Definition at line 622 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const float &).
Definition at line 588 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const int16_t &).
Definition at line 546 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const int32_t &).
Definition at line 552 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const int64_t &).
Definition at line 558 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const int8_t &).
Definition at line 540 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const std::string &).
Definition at line 600 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const uint16_t &).
Definition at line 570 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const uint32_t &).
Definition at line 576 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const uint64_t &).
Definition at line 582 of file Dictionary.h.
|
inline |
Allow implicit conversion to (const uint8_t &).
Definition at line 564 of file Dictionary.h.
|
inline |
Allow implicit conversion to (double &).
Definition at line 591 of file Dictionary.h.
|
inline |
Allow implicit conversion to (Eigen::Matrix3d &).
Definition at line 635 of file Dictionary.h.
|
inline |
Allow implicit conversion to (Eigen::Quaterniond &).
Definition at line 627 of file Dictionary.h.
|
inline |
Allow implicit conversion to (Eigen::Vector2d &).
Definition at line 603 of file Dictionary.h.
|
inline |
Allow implicit conversion to (Eigen::Vector3d &).
Definition at line 611 of file Dictionary.h.
|
inline |
Allow implicit conversion to (Eigen::VectorXd&).
Definition at line 619 of file Dictionary.h.
|
inline |
Allow implicit conversion to (float &).
Definition at line 585 of file Dictionary.h.
|
inline |
Allow implicit conversion to (int16_t &).
Definition at line 543 of file Dictionary.h.
|
inline |
Allow implicit conversion to (int32_t &).
Definition at line 549 of file Dictionary.h.
|
inline |
Allow implicit conversion to (int64_t &).
Definition at line 555 of file Dictionary.h.
|
inline |
Allow implicit conversion to (int8_t &).
Definition at line 537 of file Dictionary.h.
|
inline |
Allow implicit conversion to (std::string &).
Definition at line 597 of file Dictionary.h.
|
inline |
Allow implicit conversion to (uint16_t &).
Definition at line 567 of file Dictionary.h.
|
inline |
Allow implicit conversion to (uint32_t &).
Definition at line 573 of file Dictionary.h.
|
inline |
Allow implicit conversion to (uint64_t &).
Definition at line 579 of file Dictionary.h.
|
inline |
Allow implicit conversion to (uint8_t &).
Definition at line 561 of file Dictionary.h.
Dictionary & palimpsest::Dictionary::operator() | ( | const std::string & | key | ) |
Return a reference to the dictionary at key, performing an insertion if such a key does not already exist.
[in] | key | Key to look at. |
TypeError | if the dictionary is not a map, and therefore we cannot look up a key from it. |
With operator[], these conversions would be ambiguous as [] is commutative in C (c_str[int] == *(c_str + int) == int[c_str]).
Definition at line 198 of file Dictionary.cpp.
const Dictionary & palimpsest::Dictionary::operator() | ( | const std::string & | key | ) | const |
Return a reference to the dictionary at key, performing an insertion if such a key does not already exist.
[in] | key | Key to look at. |
KeyError | if there is no object at this key. |
TypeError | if the dictionary is not a map, and therefore we cannot lookup a key from it. |
Since we cannot insert a new element in a const object, this const operator will throw if the key is not already in the dictionary. See the documentation for the non-const variant of this operator.
Definition at line 209 of file Dictionary.cpp.
|
inline |
Assignment operator for C-style strings.
[in] | c_string | C-style string to assign. |
TypeError | if the object was already a value of a different type. |
This specialization avoids "invalid array assignment" errors. Note that the string is cast to an std::string.
Definition at line 431 of file Dictionary.h.
|
delete |
No copy assignment operator.
|
inline |
Assign value directly.
[in] | new_value | New value to assign. |
TypeError | if the object was already a value of a different type. |
If the object was a dictionary, all entries are cleared and it becomes a value. If a previous value is already present, it will be assigned (not reallocated), therefore the new value needs to have the same type.
Definition at line 409 of file Dictionary.h.
|
default |
Default move assignment operator.
void palimpsest::Dictionary::read | ( | const std::string & | filename | ) |
Update dictionary from a MessagePack binary file.
[in] | filename | Path to the input file. |
Definition at line 224 of file Dictionary.cpp.
|
noexcept |
Remove a key-value pair from the dictionary.
[in] | key | Key to remove. |
Definition at line 189 of file Dictionary.cpp.
size_t palimpsest::Dictionary::serialize | ( | std::vector< char > & | buffer | ) | const |
Serialize to raw MessagePack data.
[out] | buffer | Buffer that will hold the message data. |
Definition at line 245 of file Dictionary.cpp.
|
inlinenoexcept |
Return the number of keys in the dictionary.
Definition at line 269 of file Dictionary.h.
void palimpsest::Dictionary::update | ( | const char * | data, |
size_t | size | ||
) |
Update dictionary from raw MessagePack data.
[in] | data | Buffer to read MessagePack from. |
[in] | size | Buffer size. |
TypeError | if deserialized data types don't match those of the corresponding objects in the dictionary. |
Definition at line 39 of file Dictionary.cpp.
void palimpsest::Dictionary::update | ( | mpack_node_t | node | ) |
Update existing values from an MPack node.
[in] | node | MPack node. Its key-values should match those of the dictionary. Keys that don't match will be ignored. Values whose type does not match will raise an exception. |
TypeError | if a deserialized object's type does not match the type of an existing entry in the dictionary. |
Definition at line 53 of file Dictionary.cpp.
void palimpsest::Dictionary::write | ( | const std::string & | filename | ) | const |
Write MessagePack serialization to a binary file.
[in] | filename | Path to the output file. |
Definition at line 235 of file Dictionary.cpp.
|
friend |
Output stream operator for printing.
[out] | stream | Output stream. |
[in] | dict | Dictionary to print. |
Definition at line 279 of file Dictionary.cpp.
|
protected |
Key-value map, used if we are a map.
Definition at line 712 of file Dictionary.h.
|
protected |
Internal value, used if we are a value.
Definition at line 709 of file Dictionary.h.