icarus::KeyValuesData Class Reference

Collection of items with key/values structure. More...

#include <KeyValuesData.h>

Classes
struct	ConversionFailed
struct	DuplicateKey
struct	Error
struct	ErrorOnKey
struct	Item
	Representation of a single item of data: a key and several values. More...
struct	ItemNotFound
struct	MissingSize
struct	ValueNotAvailable
struct	WrongSize

Public Member Functions
Setter interface
Item &	makeItem (std::string key)
	Creates and registers a new item with the specified key. More...
Item &	makeOrFetchItem (std::string const &key)
	Creates or retrieves an item with the specified key. More...
Item *	findItem (std::string const &key) noexcept
	Returns the item with specified key, nullptr if none. More...
Query interface
Item const *	findItem (std::string const &key) const noexcept
	Returns the item with specified key, nullptr if none. More...
Item const &	getItem (std::string const &key) const
	Returns the item with specified key, throws std::out_of_range if none. More...
bool	hasItem (std::string const &key) const noexcept
	Returns whether an item with the specified key is present. More...
bool	empty () const noexcept
	Returns whether there is no item in data. More...
std::size_t	size () const noexcept
	Returns the number of items in the data. More...
decltype(auto)	items () const noexcept
	Returns a forward-iterable list of references to items. More...

Private Member Functions
Item &	makeItemImpl (std::string key)
	Creates, registers and return a new item (assumed not to exist yet). More...

Private Attributes
std::vector< Item >	fItems
	Collection of data items. More...

Detailed Description

Collection of items with key/values structure.

This class collects Item objects, each being a string key and a sequence of zero or more values. An specific item can be accessed by its key (findItem(), getItem()) or all items may be iterated through (items()).

Value type conversions

The Item objects in this class contain unparsed strings. Each Item has a key and a sequence of values. The values can be queried as strings or as other data types. Conversions are performed by icarus::details::KeyValuesConverter, which can be specialized with the needed conversion logic. Only one type of conversion to any given type is supported. Alternative conversions may be achieved using type wrappers (e.g. specializing for a CaseInsensitive<S> object that contains a string of type S and reading/converting into the string the result of the conversion).

Each converter object specialization for a type T should support a call with argument std::string returning a std::optional<T>.

Initialization and updates

A KeyValuesData object always starts empty (implicit default constructor). A new item is also always created empty (makeItem(), makeOrFetchItem()) and with a set key.

After an empty item (i.e. an item with a key but no values) is created, values can be added using the Item subclass interface (addValue()). Item values and keys can be modified by changing Item data members directly. The item to be modified is immediately returned by makeItem(); afterwards, an existing item may be still retrieved for changes with makeOrFetchItem() and findItem().

This object will refuse to create a new item with the same key as an existing one. However, the key of the item may be changed to any value after makeItem() is called, although the interface does not encourage that. If this introduces a duplicate key, the query functions will systematically retrieve only one of the items with the repeated key (which one and whether always the same one are undefined).

Example:

icarus::KeyValuesData data;
data.makeItem("TriggerType").addValue("S5");
data.makeItem("Triggers");
data.makeItem("TriggerWindows").addValue("0C0B");
data.makeItem("TPChits")
  .addValue("12").addValue("130").addValue("0").addValue("0");
data.makeItem("TPChitTimes")
  .addValue("3").addValue("-1.1").addValue("-0.3").addValue("0.1");
data.makeItem("PMThits").addValue("8");
data.makeOrFetchItem("TPChits").addValue("115");
data.makeOrFetchItem("TPChitTimes").addValue("-0.7");

creates a data object with four items, a TriggerType one with one value, a Triggers one with no values, a TriggerWindows with a single value (expressed as a hexadecimal number), a TPChits one with four values, a TPChitTimes with four values (the first meant to be the number of remaining ones) and a PMThits with one. Finally, it adds one value to TPChits and one to TPChitTimes, which will both have five afterwards.

Query

The interface is quite terse.

General query methods reports whether there is no item in the object (empty()) and how many items there are (size()).

A item with a known key can be retrieved (getItem(), findItem()), or its existence may be tested (hasItem()).

Finally, all items can be iterated (items()). In this case, the items are presented in the creation order.

The Item interface is documented in that subclass.

Example using the data object from the previous example:

std::string triggerType = data.getItem("TriggerType").values()[0];
std::vector<int> triggers = data.getItem("Triggers").getVector<int>();
std::uint32_t triggerWindowBits
 = data.getItem("TriggerWindows").getNumber<std::uint32_t>(0, 16); // base 16
std::vector<int> TPChits = data.getItem("TPChits").getVector<int>();
std::vector<float> TPCtimes
 = data.getItem("TPChitTimes").getSizedVector<float>();
std::vector<int> CRThits;
if (auto const* item = data.findItem("CRThits"))
  CRThits = item->getVector<int>();

Type conversion customization

The values in a Item object can be queried as strings or as other data types using the GetAs() interface. Conversions are performed by icarus::details::KeyValuesConverter, which can be specialized with the needed conversion logic. Only one type of conversion to any given type is supported.

Each converter object specialization for a type T should support a call with argument std::string returning a std::optional<T>.

Definition at line 158 of file KeyValuesData.h.

Member Function Documentation

bool icarus::KeyValuesData::empty ( ) const

noexcept

Returns whether there is no item in data.

Definition at line 72 of file KeyValuesData.cxx.

  { return fItems.empty(); }

auto icarus::KeyValuesData::findItem ( std::string const &  key )

noexcept

Returns the item with specified key, nullptr if none.

Definition at line 46 of file KeyValuesData.cxx.

{
  // no violations here: this is a non-const method, with the right to modify
  // object data; and this avoids code duplication.
  return const_cast<Item*>(std::as_const(*this).findItem(key));
} // icarus::KeyValuesData<>::findItem()

auto icarus::KeyValuesData::findItem ( std::string const &  key ) const

noexcept

Returns the item with specified key, nullptr if none.

Definition at line 37 of file KeyValuesData.cxx.

{
  for (auto const& item: fItems) if (key == item.key()) return &item;
  return nullptr;
} // icarus::KeyValuesData<>::findItem() const

auto icarus::KeyValuesData::getItem

(

std::string const &

key

)

const

Returns the item with specified key, throws std::out_of_range if none.

Definition at line 55 of file KeyValuesData.cxx.

{
  if (auto item = findItem(key); item) return *item;
  throw ItemNotFound(key);
} // icarus::KeyValuesData<>::getItem()

bool icarus::KeyValuesData::hasItem ( std::string const &  key ) const

noexcept

Returns whether an item with the specified key is present.

Definition at line 65 of file KeyValuesData.cxx.

{
  return findItem(key);
} // icarus::KeyValuesData<>::hasItem()

decltype(auto) icarus::KeyValuesData::items ( ) const

noexcept

Returns a forward-iterable list of references to items.

auto icarus::KeyValuesData::makeItem

(

std::string

key

)

Creates and registers a new item with the specified key.

Returns

the newly created item for modifications

Definition at line 20 of file KeyValuesData.cxx.

                                                         {
  if (hasItem(key)) throw DuplicateKey{ std::move(key) };
  return makeItemImpl(std::move(key));
} // icarus::KeyValuesData<>::makeItem()

auto icarus::KeyValuesData::makeItemImpl ( std::string  key )

private

Creates, registers and return a new item (assumed not to exist yet).

Definition at line 82 of file KeyValuesData.cxx.

                                                             {
  fItems.emplace_back(std::move(key));
  return fItems.back();
} // icarus::KeyValuesData<>::makeItemImpl()

auto icarus::KeyValuesData::makeOrFetchItem

(

std::string const &

key

)

Creates or retrieves an item with the specified key.

Returns

the newly created or existing item for modifications

Definition at line 27 of file KeyValuesData.cxx.

                                                                       {
  
  Item* item = findItem(key);
  return item? *item: makeItemImpl(key);
  
} // icarus::KeyValuesData<>::makeOrFetchItem()

std::size_t icarus::KeyValuesData::size ( ) const

noexcept

Returns the number of items in the data.

Definition at line 77 of file KeyValuesData.cxx.

  { return fItems.size(); }

Member Data Documentation

std::vector<Item> icarus::KeyValuesData::fItems

private

Collection of data items.

Definition at line 533 of file KeyValuesData.h.

---

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

• KeyValuesData.h
• KeyValuesData.cxx