palimpsest::Dictionary Class Reference

Dictionary of values and sub-dictionaries. More...

#include <Dictionary.h>

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...
std::vector< std::pair< std::string, std::reference_wrapper< const Dictionary > > >	items () const noexcept
	Return an iterable view of the dictionary's (key, value) pairs. More...
std::vector< std::reference_wrapper< const Dictionary > >	values () const noexcept
	Return an iterable view of the dictionary's values. 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 >
T &	setdefault (const std::string &key, const T &default_value)
	If key is in the dictionary, return its value. 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...
template<typename T >
T	pop (const std::string &key)
	Remove a key-value pair from the dictionary and return its value. More...
template<typename T >
T	pop (const std::string &key, const T &default_value)
	Remove a key-value pair from the dictionary and return its value, or return a default value if the key doesn't exist. More...
std::pair< std::string, Dictionary >	popitem ()
	Remove and return 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 Dictionary &other)
	Update dictionary from another dictionary. More...
void	deserialize (const char *data, size_t size)
	Update dictionary from raw MessagePack data. More...
Dictionary	difference (const Dictionary &other) const
	Compute the difference between this dictionary and another. 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...

Static Public Member Functions
static Dictionary	deepcopy (const Dictionary &other)
	Create a deep copy of an existing dictionary. More...
template<typename Container , typename T >
static Dictionary	fromkeys (const Container &keys, const T &value)
	Create a new dictionary with keys from an iterable container and all values set to the same value. More...
template<typename Container >
static Dictionary	fromkeys (const Container &keys)
	Create a new dictionary with keys from an iterable container and all values set to empty dictionaries. 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...

Detailed Description

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:

Dictionary dict;
// create a vector of 4 double-precision numbers with value 42
dict.insert<std::vector<double>>("TheAnswer", 4, 42);
 
auto & answer = dict.get<std::vector<double>>("TheAnswer");
answer[3] = 0;  // manipulate the object directly
 
// Get another reference to the object
auto &same_answer = dict.get<std::vector<double>>("TheAnswer");
same_answer.push_back(0);
spdlog::info(answer.size());  // vector now has size 5

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:

struct A {};
struct B : public A {};
 
// Creating an inherited object and checking virtual inheritance
dict.insert<B, A>("foo");
auto & base = dict.get<A>("foo");
auto & derived = dict.get<B>("foo");

Note

Dictionaries are move-only.

We are cheating on the class name a bit: a "dictionary" is actually either empty, or a single value, or a map of key-"dictionary" pairs. If that helps, for OCaml-lovers:

type Dictionary =
    | Empty
    | Value
    | Map of (std::string -> Dictionary)

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 96 of file Dictionary.h.

Constructor & Destructor Documentation

Dictionary() [1/3]

palimpsest::Dictionary::Dictionary ( )

default

Default constructor.

Dictionary() [2/3]

palimpsest::Dictionary::Dictionary ( const Dictionary &  )

delete

No copy constructor.

Dictionary() [3/3]

palimpsest::Dictionary::Dictionary ( Dictionary &&  )

default

Default move constructor.

~Dictionary()

palimpsest::Dictionary::~Dictionary ( )

default

Default destructor.

Note

Child dictionaries will be recursively destroyed as they are held by unique pointers in an unordered_map;

Member Function Documentation

as() [1/2]

template<typename T >

T & palimpsest::Dictionary::as ( )

inline

Get reference to the internal value.

Returns

Reference to the object.

Exceptions

TypeError

if the dictionary is not a value, or it is but the stored value type is not T.

Definition at line 217 of file Dictionary.h.

as() [2/2]

template<typename T >

const T & palimpsest::Dictionary::as ( ) const

inline

Const variant of as.

Returns

Reference to the object.

Exceptions

TypeError

if the stored object type is not T.

Definition at line 231 of file Dictionary.h.

become()

template<typename T , typename... ArgsT, typename... Args>

void palimpsest::Dictionary::become ( Args &&...  args )

inlineprotected

Definition at line 891 of file Dictionary.h.

clear()

void palimpsest::Dictionary::clear ( )

noexcept

Remove all entries from the dictionary.

Example:

Dictionary dict;
dict("pressure") = 99.8;
dict("temperature") = 27.2;
std::cout << dict.size() << std::endl;  // 2
dict.clear();
std::cout << dict.size() << std::endl;  // 0

Definition at line 38 of file Dictionary.cpp.

deepcopy()

Dictionary palimpsest::Dictionary::deepcopy ( const Dictionary &  other )

static

Create a deep copy of an existing dictionary.

Parameters

[in]

other

Dictionary to copy.

Returns

New dictionary that is a deep copy of the input.

Exceptions

TypeError

if deserialized data types cannot be handled.

Example:

Dictionary original;
original("temperature") = 30.1;
original("sensors")("count") = 3;
 
Dictionary copy = Dictionary::deepcopy(original);
copy("temperature") = 30.0;  // Does not affect original
std::cout << original.get<double>("temperature") << std::endl;  // 25.5

Definition at line 43 of file Dictionary.cpp.

deserialize()

void palimpsest::Dictionary::deserialize	(	const char *	data,
		size_t	size
	)

Update dictionary from raw MessagePack data.

Parameters

[in]	data	Buffer to read MessagePack from.
[in]	size	Buffer size.

Exceptions

TypeError

if deserialized data types don't match those of the corresponding objects in the dictionary.

Definition at line 49 of file Dictionary.cpp.

difference()

Dictionary palimpsest::Dictionary::difference

(

const Dictionary &

other

)

const

Compute the difference between this dictionary and another.

Parameters

[in]

other

Dictionary to compare with.

Returns

New dictionary containing key-value pairs that are in this dictionary and either not in other, or in other but with different values.

The returned dictionary maintains the nested structure of differences. For nested dictionaries, only the differing sub-keys are included in the result. Values are compared by serializing both objects and comparing the serialized data.

Definition at line 190 of file Dictionary.cpp.

fromkeys() [1/2]

template<typename Container >

static Dictionary palimpsest::Dictionary::fromkeys ( const Container &  keys )

inlinestatic

Create a new dictionary with keys from an iterable container and all values set to empty dictionaries.

Parameters

[in]

keys

Container of keys (any iterable with string elements).

Returns

New dictionary with the specified keys and empty dictionary values.

This function is similar to Python's dict.fromkeys(iterable) when no value is specified. However, in Python default values are set to None, while in palimpsest default values are set to empty dictionaries (that may become either values or dictionaries).

Example:

std::vector<std::string> keys = {"config", "temperature"};
Dictionary dict = Dictionary::fromkeys(keys);
sensor_dict("temperature") = 12.1;       // Can become a value
sensor_dict("config")("checks") = true;  // Can become a dictionary

Definition at line 693 of file Dictionary.h.

fromkeys() [2/2]

template<typename Container , typename T >

static Dictionary palimpsest::Dictionary::fromkeys ( const Container &  keys, const T &  value  )

inlinestatic

Create a new dictionary with keys from an iterable container and all values set to the same value.

Parameters

[in]	keys	Container of keys (any iterable with string elements).
[in]	value	Value to set for all keys.

Returns

New dictionary with the specified keys and value.

This function has the same semantics as Python's dict.fromkeys(iterable, value). All keys will be set to the same value.

Example:

std::vector<std::string> keys = {"name", "age", "city"};
Dictionary dict = Dictionary::fromkeys(keys, std::string("unknown"));
std::cout << dict.get<std::string>("name") << std::endl;  // "unknown"
std::cout << dict.get<std::string>("age") << std::endl;   // "unknown"
std::cout << dict.get<std::string>("city") << std::endl;  // "unknown"

Definition at line 665 of file Dictionary.h.

get() [1/3]

template<typename T >

T & palimpsest::Dictionary::get ( const std::string &  key )

inline

Get reference to the object at a given key.

Parameters

[in]

key

Key to the object.

Returns

Reference to the object.

Exceptions

KeyError	if there is no object at this key.
TypeError	if there is an object at this key, but its type is not T.

Example:

Dictionary dict;
dict("temperature") = 25.5;
double& temp = dict.get<double>("temperature");
temp = 30.0;  // Modifies the value in the dictionary

Definition at line 255 of file Dictionary.h.

get() [2/3]

template<typename T >

const T & palimpsest::Dictionary::get ( const std::string &  key ) const

inline

Const variant of get.

Parameters

[in]

key

Key to the object.

Returns

Reference to the object.

Exceptions

KeyError	if there is no object at this key.
TypeError	if there is an object at this key, but its type is not T.

Example:

const Dictionary dict;
const double& temp = dict.get<double>("temperature");

Definition at line 274 of file Dictionary.h.

get() [3/3]

template<typename T >

const T & palimpsest::Dictionary::get ( const std::string &  key, const T &  default_value  ) const

inline

Get object at a given key if it exists, or a default value otherwise.

Parameters

[in]	key	Key to look for.
[in]	default_value	Default value used if there is no value at this key.

Returns

Reference to the object if it exists, default_value otherwise.

Exceptions

TypeError

if the object at this key is not a value, or it is but its type does is not T.

Example:

Dictionary dict;
dict("count") = 42;
int value = dict.get<int>("count", 0);     // Returns 42
int missing = dict.get<int>("missing", 0); // Returns 0 (default)

Definition at line 297 of file Dictionary.h.

has()

bool palimpsest::Dictionary::has ( const std::string &  key ) const

inlinenoexcept

Check whether a key is in the dictionary.

Parameters

[in]

key

Key to look for.

Returns

true when the key is in the dictionary.

Definition at line 134 of file Dictionary.h.

insert()

template<typename T , typename... ArgsT, typename... Args>

T & palimpsest::Dictionary::insert ( const std::string &  key, Args &&...  args  )

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.

Parameters

[in]	key	Key to create the object at.
	args	Parameters passed to the object's constructor.

Returns

Reference to the constructed object.

Exceptions

TypeError

if the dictionary is not a map, and therefore we cannot insert at a given key inside it.

Note

To STL practitioners: although it is named like e.g. unordered_map::insert, this function behaves like unordered_map::emplace as it forwards its argument to the constructor T::T() called internally. Also it doesn't return an insertion confirmation boolean.

Definition at line 337 of file Dictionary.h.

is_empty()

bool palimpsest::Dictionary::is_empty ( ) const

inlinenoexcept

We are empty if and only if we are a dictionary with no element.

Definition at line 124 of file Dictionary.h.

is_map()

bool palimpsest::Dictionary::is_map ( ) const

inlinenoexcept

We are a (potentially empty) map if and only if the value is empty.

Definition at line 121 of file Dictionary.h.

is_value()

bool palimpsest::Dictionary::is_value ( ) const

inlinenoexcept

We are a value if and only if the internal value is non-empty.

Definition at line 127 of file Dictionary.h.

items()

std::vector< std::pair< std::string, std::reference_wrapper< const Dictionary > > > palimpsest::Dictionary::items ( ) const

noexcept

Return an iterable view of the dictionary's (key, value) pairs.

Returns

Vector of pairs containing key strings and references to Dictionary values.

This function has the same semantics as Python's dict.items(). Each pair contains the key as a string and a reference to the Dictionary at that key. The Dictionary reference can be further used with as to get typed values.

Example:

Dictionary dict;
dict("pressure") = 101.3;
dict("temperature") = 25.5;
dict("sensors")("count") = 3;
 
for (const auto& [key, value_ref] : dict.items()) {
  const Dictionary& value = value_ref.get();
  std::cout << key << ": " << value << std::endl;
}

Definition at line 256 of file Dictionary.cpp.

keys()

std::vector< std::string > palimpsest::Dictionary::keys ( ) const

noexcept

Return the list of keys of the dictionary.

Returns

Vector containing all keys in the dictionary.

Example:

Dictionary dict;
dict("pressure") = 102.4;
dict("temperature") = 26.2;
dict("sensors")("count") = 3;
 
std::vector<std::string> keys = dict.keys();
for (const std::string& key : keys) {
  std::cout << "Key: " << key << std::endl;
}

Definition at line 246 of file Dictionary.cpp.

operator bool &()

palimpsest::Dictionary::operator bool & ( )

inline

Allow implicit conversion to (bool &).

Definition at line 770 of file Dictionary.h.

operator const bool &()

palimpsest::Dictionary::operator const bool & ( ) const

inline

Allow implicit conversion to (const bool &).

Definition at line 773 of file Dictionary.h.

operator const double &()

palimpsest::Dictionary::operator const double & ( ) const

inline

Allow implicit conversion to (const double &).

Definition at line 833 of file Dictionary.h.

operator const Eigen::Matrix3d &()

palimpsest::Dictionary::operator const Eigen::Matrix3d & ( ) const

inline

Allow implicit conversion to (const Eigen::Matrix3d &).

Definition at line 877 of file Dictionary.h.

operator const Eigen::Quaterniond &()

palimpsest::Dictionary::operator const Eigen::Quaterniond & ( ) const

inline

Allow implicit conversion to (const Eigen::Quaterniond &).

Definition at line 869 of file Dictionary.h.

operator const Eigen::Vector2d &()

palimpsest::Dictionary::operator const Eigen::Vector2d & ( ) const

inline

Allow implicit conversion to (const Eigen::Vector2d &).

Definition at line 845 of file Dictionary.h.

operator const Eigen::Vector3d &()

palimpsest::Dictionary::operator const Eigen::Vector3d & ( ) const

inline

Allow implicit conversion to (const Eigen::Vector3d &).

Definition at line 853 of file Dictionary.h.

operator const Eigen::VectorXd &()

palimpsest::Dictionary::operator const Eigen::VectorXd & ( ) const

inline

Allow implicit conversion to (const Eigen::VectorXd&).

Definition at line 861 of file Dictionary.h.

operator const float &()

palimpsest::Dictionary::operator const float & ( ) const

inline

Allow implicit conversion to (const float &).

Definition at line 827 of file Dictionary.h.

operator const int16_t &()

palimpsest::Dictionary::operator const int16_t & ( ) const

inline

Allow implicit conversion to (const int16_t &).

Definition at line 785 of file Dictionary.h.

operator const int32_t &()

palimpsest::Dictionary::operator const int32_t & ( ) const

inline

Allow implicit conversion to (const int32_t &).

Definition at line 791 of file Dictionary.h.

operator const int64_t &()

palimpsest::Dictionary::operator const int64_t & ( ) const

inline

Allow implicit conversion to (const int64_t &).

Definition at line 797 of file Dictionary.h.

operator const int8_t &()

palimpsest::Dictionary::operator const int8_t & ( ) const

inline

Allow implicit conversion to (const int8_t &).

Definition at line 779 of file Dictionary.h.

operator const std::string &()

palimpsest::Dictionary::operator const std::string & ( ) const

inline

Allow implicit conversion to (const std::string &).

Definition at line 839 of file Dictionary.h.

operator const uint16_t &()

palimpsest::Dictionary::operator const uint16_t & ( ) const

inline

Allow implicit conversion to (const uint16_t &).

Definition at line 809 of file Dictionary.h.

operator const uint32_t &()

palimpsest::Dictionary::operator const uint32_t & ( ) const

inline

Allow implicit conversion to (const uint32_t &).

Definition at line 815 of file Dictionary.h.

operator const uint64_t &()

palimpsest::Dictionary::operator const uint64_t & ( ) const

inline

Allow implicit conversion to (const uint64_t &).

Definition at line 821 of file Dictionary.h.

operator const uint8_t &()

palimpsest::Dictionary::operator const uint8_t & ( ) const

inline

Allow implicit conversion to (const uint8_t &).

Definition at line 803 of file Dictionary.h.

operator double &()

palimpsest::Dictionary::operator double & ( )

inline

Allow implicit conversion to (double &).

Definition at line 830 of file Dictionary.h.

operator Eigen::Matrix3d &()

palimpsest::Dictionary::operator Eigen::Matrix3d & ( )

inline

Allow implicit conversion to (Eigen::Matrix3d &).

Definition at line 874 of file Dictionary.h.

operator Eigen::Quaterniond &()

palimpsest::Dictionary::operator Eigen::Quaterniond & ( )

inline

Allow implicit conversion to (Eigen::Quaterniond &).

Definition at line 866 of file Dictionary.h.

operator Eigen::Vector2d &()

palimpsest::Dictionary::operator Eigen::Vector2d & ( )

inline

Allow implicit conversion to (Eigen::Vector2d &).

Definition at line 842 of file Dictionary.h.

operator Eigen::Vector3d &()

palimpsest::Dictionary::operator Eigen::Vector3d & ( )

inline

Allow implicit conversion to (Eigen::Vector3d &).

Definition at line 850 of file Dictionary.h.

operator Eigen::VectorXd &()

palimpsest::Dictionary::operator Eigen::VectorXd & ( )

inline

Allow implicit conversion to (Eigen::VectorXd&).

Definition at line 858 of file Dictionary.h.

operator float &()

palimpsest::Dictionary::operator float & ( )

inline

Allow implicit conversion to (float &).

Definition at line 824 of file Dictionary.h.

operator int16_t &()

palimpsest::Dictionary::operator int16_t & ( )

inline

Allow implicit conversion to (int16_t &).

Definition at line 782 of file Dictionary.h.

operator int32_t &()

palimpsest::Dictionary::operator int32_t & ( )

inline

Allow implicit conversion to (int32_t &).

Definition at line 788 of file Dictionary.h.

operator int64_t &()

palimpsest::Dictionary::operator int64_t & ( )

inline

Allow implicit conversion to (int64_t &).

Definition at line 794 of file Dictionary.h.

operator int8_t &()

palimpsest::Dictionary::operator int8_t & ( )

inline

Allow implicit conversion to (int8_t &).

Definition at line 776 of file Dictionary.h.

operator std::string &()

palimpsest::Dictionary::operator std::string & ( )

inline

Allow implicit conversion to (std::string &).

Definition at line 836 of file Dictionary.h.

operator uint16_t &()

palimpsest::Dictionary::operator uint16_t & ( )

inline

Allow implicit conversion to (uint16_t &).

Definition at line 806 of file Dictionary.h.

operator uint32_t &()

palimpsest::Dictionary::operator uint32_t & ( )

inline

Allow implicit conversion to (uint32_t &).

Definition at line 812 of file Dictionary.h.

operator uint64_t &()

palimpsest::Dictionary::operator uint64_t & ( )

inline

Allow implicit conversion to (uint64_t &).

Definition at line 818 of file Dictionary.h.

operator uint8_t &()

palimpsest::Dictionary::operator uint8_t & ( )

inline

Allow implicit conversion to (uint8_t &).

Definition at line 800 of file Dictionary.h.

operator()() [1/2]

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.

Parameters

[in]

key

Key to look at.

Returns

Reference to the new dictionary at this key if there was none, or to the existing dictionary otherwise.

Exceptions

TypeError

if the dictionary is not a map, and therefore we cannot look up a key from it.

Note

The behavior of this operator is the same as std::unordered_map::operator[]. It differs from that of Python dictionaries, where an exception is throw if the key doesn't exist.

The reason why we use operator() instead of operator[] is that the class includes user-defined conversion functions to value types, so that we can write:

Eigen::Vector3d& position = dict("position");
auto& position = dict("position").as<Eigen::Vector3d>();  // equivalent
auto& position = dict.get<Eigen::Vector3d>("position");   // equivalent

With operator[], these conversions would be ambiguous as [] is commutative in C (c_str[int] == *(c_str + int) == int[c_str]).

Definition at line 308 of file Dictionary.cpp.

operator()() [2/2]

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.

Parameters

[in]

key

Key to look at.

Returns

Reference to the dictionary at this key.

Exceptions

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 319 of file Dictionary.cpp.

operator=() [1/4]

Dictionary & palimpsest::Dictionary::operator= ( const char *  c_string )

inline

Assignment operator for C-style strings.

Parameters

[in]

c_string

C-style string to assign.

Exceptions

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 452 of file Dictionary.h.

operator=() [2/4]

Dictionary & palimpsest::Dictionary::operator= ( const Dictionary &  )

delete

No copy assignment operator.

operator=() [3/4]

template<typename T >

Dictionary & palimpsest::Dictionary::operator= ( const T &  new_value )

inline

Assign value directly.

Parameters

[in]

new_value

New value to assign.

Exceptions

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 430 of file Dictionary.h.

operator=() [4/4]

Dictionary & palimpsest::Dictionary::operator= ( Dictionary &&  )

default

Default move assignment operator.

pop() [1/2]

template<typename T >

T palimpsest::Dictionary::pop ( const std::string &  key )

inline

Remove a key-value pair from the dictionary and return its value.

Parameters

[in]

key

Key to remove.

Returns

Value that was stored at the key.

Exceptions

KeyError	if there is no object at this key.
TypeError	if there is an object at this key but it is not a value, or it is but its type does not match T.

This function has the same semantics as Python's dict.pop(key).

Example:

Dictionary dict;
dict("pressure") = 101.2;
dict("temperature") = 25.5;
 
double temp = dict.pop<double>("temperature");
std::cout << "Removed: " << temp << std::endl;  // 25.5
std::cout << "Size: " << dict.size() << std::endl;  // 1

Definition at line 485 of file Dictionary.h.

pop() [2/2]

template<typename T >

T palimpsest::Dictionary::pop ( const std::string &  key, const T &  default_value  )

inline

Remove a key-value pair from the dictionary and return its value, or return a default value if the key doesn't exist.

Parameters

[in]	key	Key to remove.
[in]	default_value	Default value to return if key doesn't exist.

Returns

Value that was stored at the key, or default_value if key doesn't exist.

Exceptions

TypeError

if there is an object at this key but it is not a value, or it is but its type does not match T.

This function has the same semantics as Python's dict.pop(key, default).

Example:

Dictionary dict;
dict("temperature") = 35.5;
 
double temp = dict.pop<double>("temperature", 20.0);  // 25.5
double missing = dict.pop<double>("missing", 20.0);   // 20.0
std::cout << "Size: " << dict.size() << std::endl;    // 0

Definition at line 515 of file Dictionary.h.

popitem()

std::pair< std::string, Dictionary > palimpsest::Dictionary::popitem

(

)

Remove and return a (key, value) pair from the dictionary.

Returns

Pair containing the key string and the Dictionary value that was removed. The latter value can be further used with as to recover a typed reference.

Exceptions

KeyError	if the dictionary is empty.
TypeError	if the dictionary is not a map.

Note

Contrary to Python's dict.popitem(), this function does not guarantee that pairs are returned in LIFO (last-in, first-out) order (although they will likely be in practice).

Example:

Dictionary dict;
dict("temperature") = 25.5;
dict("pressure") = 101.3;
 
auto [key, value] = dict.popitem();
std::cout << "Popped ('" << key << "', " << value.as<double>() << ")\n";
std::cout << "Size: " << dict.size() << std::endl;  // 1

Definition at line 276 of file Dictionary.cpp.

read()

void palimpsest::Dictionary::read

(

const std::string &

filename

)

Update dictionary from a MessagePack binary file.

Parameters

[in]

filename

Path to the input file.

Definition at line 334 of file Dictionary.cpp.

remove()

void palimpsest::Dictionary::remove ( const std::string &  key )

noexcept

Remove a key-value pair from the dictionary.

Parameters

[in]

key

Key to remove.

Definition at line 299 of file Dictionary.cpp.

serialize()

size_t palimpsest::Dictionary::serialize

(

std::vector< char > &

buffer

)

const

Serialize to raw MessagePack data.

Parameters

[out]

buffer

Buffer that will hold the message data.

Returns

Size of the message. Note that it is not the same as the size of the buffer after execution.

Definition at line 355 of file Dictionary.cpp.

setdefault()

template<typename T >

T & palimpsest::Dictionary::setdefault ( const std::string &  key, const T &  default_value  )

inline

If key is in the dictionary, return its value.

If not, insert key with a value of default_value and return default_value.

Parameters

[in]	key	Key to look for or insert.
[in]	default_value	Default value to insert and return if key doesn't exist.

Returns

Reference to the value at key (either existing or newly inserted).

Exceptions

TypeError

if the dictionary is not a map, or if there is already an object at this key but it is not a value, or it is but its type does not match T.

Note

This function has the same semantics as Python's dict.setdefault(key, default). It has the same semantics as insert, except that it does not warn when returning an existing value.

Example:

Dictionary dict;
dict("temperature") = 25.5;
 
double& temp = dict.setdefault<double>("temperature", 20.0);  // 25.5
double& pressure = dict.setdefault<double>("pressure", 101.3); // 101.3
std::cout << dict.size() << std::endl;  // 2

Definition at line 385 of file Dictionary.h.

size()

unsigned palimpsest::Dictionary::size ( ) const

inlinenoexcept

Return the number of keys in the dictionary.

Definition at line 207 of file Dictionary.h.

update()

void palimpsest::Dictionary::update

(

const Dictionary &

other

)

Update dictionary from another dictionary.

Parameters

[in]

other

Dictionary to update from.

Exceptions

TypeError

if deserialized data types don't match those of the corresponding objects in the dictionary.

Example:

Dictionary dict1;
dict1("pressure") = 98.9;
dict1("temperature") = 21.2;
 
Dictionary dict2;
dict2("temperature") = 30.0;  // Update will overwrite dict1's temperature
dict2("humidity") = 65.0;     // Update will add this to dict1
 
dict1.update(dict2);
std::cout << dict1.get<double>("temperature") << std::endl;  // 30.0
std::cout << dict1.get<double>("humidity") << std::endl;     // 65.0

Definition at line 411 of file Dictionary.cpp.

values()

std::vector< std::reference_wrapper< const Dictionary > > palimpsest::Dictionary::values ( ) const

noexcept

Return an iterable view of the dictionary's values.

Returns

Vector of references to Dictionary values.

This function has the same semantics as Python's dict.values(). Each reference points to a Dictionary value that can be further used with as to get typed values.

Example:

Dictionary dict;
dict("pressure") = 101.2;
dict("temperature") = 25.6;
dict("sensors")("count") = 3;
 
for (const auto& value_ref : dict.values()) {
  const Dictionary& value = value_ref.get();
  std::cout << "Value: " << value << std::endl;
}

Definition at line 266 of file Dictionary.cpp.

write()

void palimpsest::Dictionary::write

(

const std::string &

filename

)

const

Write MessagePack serialization to a binary file.

Parameters

[in]

filename

Path to the output file.

Definition at line 345 of file Dictionary.cpp.

Friends And Related Function Documentation

operator<<

std::ostream & operator<< ( std::ostream &  stream, const Dictionary &  dict  )

friend

Output stream operator for printing.

Parameters

[out]	stream	Output stream.
[in]	dict	Dictionary to print.

Returns

Updated output stream.

Definition at line 388 of file Dictionary.cpp.

Member Data Documentation

map_

std::unordered_map<std::string, std::unique_ptr<Dictionary> > palimpsest::Dictionary::map_

protected

Key-value map, used if we are a map.

Definition at line 960 of file Dictionary.h.

value_

Value palimpsest::Dictionary::value_

protected

Internal value, used if we are a value.

Definition at line 957 of file Dictionary.h.

---

The documentation for this class was generated from the following files:

• include/palimpsest/Dictionary.h
• src/Dictionary.cpp