HeaderStorage
-
class HeaderStorage
Base class for objects that read/write to an experiment header file.
This class provides a common interface to an experiment header file (which itself is in csv format). The experiment header format contains 6 fields:
Object Key: Identifies which object a value is associated with
Array Key: Indicates which array a value is associated with (may be blank)
Array Index: Indicates which array index the array value is associated with
Key: Identifies the specific variable
Value: The value
Unit: Units associated with the value
Similar to SettingsStorage, this class stores data in associative containers either as individual key-value pairs or as part of an array of maps. Values are added using the store() or storeArrayValue() functions as appropriate, and they can be read back with the retrieve() or retrieveArrayValue() functions. When read, the value is removed from the HeaderStorage internal containers. Subclasses should store values by implementing the storeValues() function, which is called right before data are formatted for writing. The getStrings() function grabs all of the keys, values, and units, packages them into strings, and returns them as a std::multimap for writing.
In addition, a HeaderStorage object may have a list of children HeaderStorage objects. For practical usage, the Experiment class will be the main HeaderStorage object, and the, e.g., FtmwConfig class is added as one of its children. The FtmwConfig class in turn has the FtmwDigitizer, RfConfig, etc as children. The getStrings() function also grabs data from the children.
When an object is to be reconstructed from the header file, the storeLine() function is called. This function determines if the object key stored in the line is associated with this object or one of its children, and if so, it adds the value to its internal containers (or is passed to the child, as appropriate). Once this is complete, subclasses can extract the values using the retrieve() and retrieveArrayValue() functions. This should be done in the retrieveValues() virtual function, which is called after all of the lines in the header have been processed.
Subclassed by ChirpConfig, DigitizerConfig, Experiment, ExperimentValidator, FlowConfig, FtmwConfig, LifConfig, PressureControllerConfig, PulseGenConfig, RfConfig, TemperatureControllerConfig
Public Types
-
using ValueUnit = std::pair<QVariant, QString>
Alias for storing a value and unit
-
using HeaderStrings = std::multimap<QString, std::tuple<QString, QString, QString, QString, QString>>
Alias for a set of strings representing header data, together with the object key
Public Functions
-
HeaderStorage(const QString objKey, const QString hwSubKey = QString(""))
Constructor. Sets the object key, which should be unique to the most derived class.
- Parameters:
objKey – The object key. Values written to the header file will be associated with this string
hwSubKey – For data storage associated with a HardwareObject, contains the subKey of that object
-
inline virtual ~HeaderStorage()
Destructor. Does nothing.
-
inline QString headerKey() const
Accesses ::d_headerKey.
- Returns:
Header Key
-
int headerIndex() const
Parses ::d_headerKey and returns the index.
This function is only useful if the header key is a HardwareOject::d_key. Otherwise, it simply returns 0.
- Returns:
Index or 0
-
inline QString hwSubKey() const
Acceses ::d_hwSubKey.
- Returns:
Subkey or empty string
-
HeaderStrings getStrings()
Converts stored values to strings, and clears them from memory.
This function is used when writing the data to disk. Because the contents are in almost all cases copies of data that already exists elsewhere, the internal maps are cleared out when this operation completes.
storeValues() is called at the beginning of this function.
Returned is a std::multimap that contains a tuple of 5 QStrings. The key of the multimap is the object key for the class. The 5 strings are:
Array key (may be empty)
Array index (may be empty)
Key
Value
Unit (may be empty)
If this object has any children, their getStrings() function is also called, and the returned map is merged into this one.
- Returns:
A multimap containing the data in string format
-
void prepareToStore()
Called to setup children before storing/retrieving data.
This function needs to be called before the first call to storeLine()
-
bool storeLine(const QVariantList l)
Stores the contents of the strings provided if object key matches.
This function is intended for parsing one line of the csv header file. The line is assumed to have been previously split into a list of 6 strings as described below (the caller should verify this!). If the object key does not match, then any children are searched as well. The function returns true if the value was matched, and false otherwise (or if there was an error).
- Parameters:
l – List of 6 strings:
Object Key
Array key (optional)
Array index (optional)
Key
Value
Unit (optional)
- Returns:
Whether the value was added to this object or a child.
-
void readComplete()
Calls retrieveValues() on self and readComplete() on all children.
-
void addChild(HeaderStorage *other)
Adds a pointer to a child HeaderStorage object.
Child storage objects are stored in a vector as pointers; ownership is not assumed here. Children will be searched when adding a value through storeLine(), and their getStrings() function will be called from the parent’s getStrings() function. It is safe to pass nullptr to this function.
- Parameters:
other – Pointer to the child header storage object. If the object is destroyed, calls to getStrings() or storeLine() will crash the program.
-
HeaderStorage *removeChild(HeaderStorage *child)
Removes a pointer to a child HeaderStorage object.
The caller is responsible for deleting the object if needed.
- Parameters:
child – Pointer to the child to remove
- Returns:
Pointer to the removed child, or nullptr if no child is found
-
inline virtual void prepareChildren()
Called before storing/retrieving values.
Derived classes may reimplement this function to add child objects. The default implementation does nothing.
Protected Functions
-
virtual void storeValues() = 0
Function called before saving.
This function is where subclasses should store all values that should be saved in the header (using store and storeArrayValue as desired).
-
virtual void retrieveValues() = 0
Called when all header lines have been processed when reading.
Subclasses should perform their initialization here by using retrieve() and retrieveArrayValue() as appropriate.
-
template<typename T>
inline void store(const QString key, const T &val, const QString unit = "") Stores a value-unit pair for writing (overload)
- Parameters:
key – The key assocociated with the value
val – The value to store
unit – Unit associated with the value
-
void store(const QString key, const QVariant val, const QString unit = "")
Stores a value-unit pair for writing.
- Parameters:
key – The key assocociated with the value
val – The value to store
unit – Unit associated with the value
-
template<typename T>
inline void storeArrayValue(const QString arrayKey, std::size_t index, const QString key, const T &val, const QString unit = "") Stores a value-unit pair as part of an array (overload)
An array value is useful when storing repetitive entries that are part of a list (e.g., settings for the pulse generator channels). If arrayKey does not exist, it will be created, and if index is larger than the current array size, it will be expanded until it is large enough.
- Parameters:
arrayKey – Key identifying the array
index – Position in the array
key – Key associated with the value
val – Value to be stored
unit – Unit associated with the value
-
void storeArrayValue(const QString arrayKey, std::size_t index, const QString key, const QVariant val, const QString unit = "")
Stores a value-unit pair as part of an array.
An array value is useful when storing repetitive entries that are part of a list (e.g., settings for the pulse generator channels). If arrayKey does not exist, it will be created, and if index is larger than the current array size, it will be expanded until it is large enough.
- Parameters:
arrayKey – Key identifying the array
index – Position in the array
key – Key associated with the value
val – Value to be stored
unit – Unit associated with the value (optional
-
template<typename T>
inline T retrieve(const QString key, const T &defaultValue = QVariant().value<T>()) Retrieves a value from storage.
When a value is retrieved, it is removed from storage. A second call to retrieve with the same key will return the default value.
- Parameters:
key – The key associated with a value
defaultValue – Return value if key not found. By default, this will be a default-constructed value.
- Returns:
The value, or default value
-
std::size_t arrayStoreSize(const QString key) const
Returns the size of the array specified by key.
- Parameters:
key – The key of the array
- Returns:
The size of the array. Returns 0 if the array does not exist.
-
template<typename T>
inline T retrieveArrayValue(const QString arrayKey, std::size_t index, const QString key, const T &defaultValue = QVariant().value<T>()) Equivalent to retrieve() but for array values.
The retrieved value is removed from storage. However, the individual HeaderMaps are never removed, so the HeaderList size remains constant even when the HeaderMaps are empty.
- Parameters:
arrayKey – The key associated with the array
index – Position of the value in the array
key – Key associated with the value
defaultValue – Return value if any key not found or if index >= array size.
- Returns:
The value, or default value
Protected Attributes
-
QString d_headerKey
Object key used for storage. Should not be modified!
-
QString d_hwSubKey
Key used for settings in some hardware config objects
Private Members
-
std::map<QString, HeaderArray> d_arrayValues
Map containing lists of key-value pairs
-
std::vector<HeaderStorage*> d_children
List containing pointers to children
-
namespace BC
Blackchirp global namespace
-
namespace Store
Namespace for HeaderStorage keys
-
namespace Store