Context
-
class Context
Thread-safe key-value container that consults the blueprint for allowed keys and defaults.
Case-insensitive keys are stored as uppercase.
If a key is absent on get(), a default from the blueprint is inserted if available.
The blueprint also enforces a maximum capacity (|value_N[0]|).
Due to storing a std::mutex and a reference to the blueprint, it is move-only.
Public Functions
-
Context(Context &&other) noexcept
Move constructor. Transfers ownership of storage_ while retaining the same blueprint reference.
-
Context &operator=(Context &&other) noexcept
Move assignment. Transfers ownership of storage_ while retaining the same blueprint reference.
-
const std::vector<std::string> &operator()(const std::string &key) const
Returns all values for a key.
If absent, tries inserting the blueprint’s default. If still missing, throws std::runtime_error.
- Parameters:
key – Key to retrieve (case-insensitive).
- Returns:
const reference to the stored vector of string values.
-
template<typename T>
inline T get(const std::string &key) const Returns the first value for the key, converted to type T.
If absent, attempts to insert a default from the blueprint. Throws std::runtime_error on failure or if conversion fails.
- Template Parameters:
T – Destination type (e.g., int, double, bool, etc.).
- Parameters:
key – Key name.
- Returns:
The converted value.
-
template<typename T>
inline T get(const std::string &key, size_t n) const Returns the n-th value for the key, converted to type T.
If absent, attempts to insert a blueprint default, then checks range. Throws std::runtime_error if still missing, or if n is out-of-range, or conversion fails.
- Template Parameters:
T – Destination type.
- Parameters:
key – Key name.
n – Index in the values vector.
- Returns:
The converted value.
-
template<typename Container>
inline void get(const std::string &key, Container &out) const Fills a provided container with values for the key.
If the key is absent, attempts to insert the blueprint default. Logs a warning if there are more stored values than the container size.
- Template Parameters:
Container – type with operator[] and size() (e.g., std::vector<T>).
- Parameters:
key – Key name.
out – The container to fill.
- Throws:
std::runtime_error – if the key is missing or conversion fails.
-
template<typename T>
inline void add(const std::string &key, const T &val, size_t maxVals = 0) Appends a value to an existing key, respecting blueprint capacity.
If the key is not allowed by blueprint, or if capacity is reached, throws std::runtime_error.
- Template Parameters:
T – Type convertible to string with operator<<.
- Parameters:
key – Key name.
val – Value to append.
-
size_t remove(const std::string &key)
Removes all values for a given key.
- Parameters:
key – The key name.
- Returns:
1 if the key existed and was removed, 0 otherwise.
-
void clear()
Clears all key-value pairs.
-
size_t size(const std::string &key) const
Returns the number of values stored for a key.
If the key doesn’t exist, attempts blueprint default insertion. Throws std::runtime_error if still missing afterwards.
- Parameters:
key – The key name.
- Returns:
Number of values for that key.
-
size_t size() const
Returns the number of distinct keys currently stored.
-
bool contains(const std::string &key) const
Checks if the context contains a given key.
If absent, tries to insert a default from blueprint if available. This means calling contains() can cause side effects.
- Parameters:
key – The key name.
- Returns:
True if eventually found or default inserted, false otherwise.
-
std::vector<char> serialize() const
Serializes all data into a vector of chars (plaintext).
Format is lines of “KEY value1 value2 …”.
-
void deserialize(const std::vector<char> &buffer)
Deserializes from a vector of chars (plaintext). Clears existing data first.
Each line is “KEY value1 value2 …”. Keys must be allowed by blueprint. Over-capacity triggers an error.
- Parameters:
buffer – The serialized data.
- Throws:
std::runtime_error – on invalid key or capacity exceed.
-
const std::map<std::string, std::vector<std::string>> &getMapRef() const
Return a const reference to the storage map.
-
template<typename T>
inline void addInternal(const std::string &key, const T &val) Method for inserting an internal key (not in allowedKeys_).
Internal keys come from [INTERNAL_KEYS] section of the blueprint.
The overwriting logic is as follows:
If key is full at the time of call, the entire key is cleared and the default is set. Then values are appended.
Otherwise, values are appended until capacity is reached.
If capacity is exceeded, an error is thrown.
Warning
This method is not intended for general usage.
Public Static Functions
-
static inline Context merge(const Context &ctx1, const Context &ctx2, bool allowOverwrite = true)
Merges two contexts, add/override ALLOWED_KEYS keys from ctx2 into ctx1.
- Parameters:
ctx1 – The first context (base).
ctx2 – The second context (overrides).
- Returns:
A new Context object with merged values.
Friends
-
inline friend std::ostream &operator<<(std::ostream &os, const Context &ctx)
Streams the Context to an output stream.
Each key is looked up in the blueprint to determine how many values to place per line. If value_N[0] > 0, each value is printed on its own line with the key. If value_N[0] < 0, all values for that key appear on a single line after the key. If value_N[0] == 0 or value_N is empty, it is skipped.