SurgSim::DataStructures::NamedData< T > Class Template Reference

A templated dictionary in which data can be accessed by name or index, with immutable names & indices. More...

`#include <SurgSim/DataStructures/NamedData.h>`

## Public Member Functions

| NamedData ()
| Create an empty object, with no associated names and indices yet. More...
| NamedData (std::shared_ptr< const IndexDirectory > directory)
| Create an object containing items from an index directory. More...
| NamedData (const std::vector< std::string > &names)
| Construct an object, using the names from a vector of strings. More...
| NamedData (const NamedData &namedData)
| Construct an object as a copy of the data from another object. More...
NamedData & | operator= (const NamedData &namedData)
| Copy the data from another object. More...
| NamedData (NamedData &&namedData)
| Create an object and move the data from another object. More...
NamedData & | operator= (NamedData &&namedData)
| Move the data from another object. More...
bool | isValid () const
| Check if the object has been initialized, which means it has a set of entries (i.e., names, indices, and the map between them). More...
std::shared_ptr< const IndexDirectory > | getDirectory () const
| Return the object's layout directory, which is its collection of names and indices. More...
int | getIndex (const std::string &name) const
| Given a name, return the corresponding index (or -1). More...
std::string | getName (int index) const
| Given an index, return the corresponding name (or ""). More...
bool | hasEntry (int index) const
| Check whether the object contains an entry with the specified index. More...
bool | hasEntry (const std::string &name) const
| Check whether the object contains an entry with the specified name. More...
bool | hasData (int index) const
| Check whether the entry with the specified index contains valid data. More...
bool | hasData (const std::string &name) const
| Check whether the entry with the specified name contains valid data. More...
bool | get (int index, T *value) const
| Given an index, get the corresponding value. More...
bool | get (const std::string &name, T *value) const
| Given a name, get the corresponding value. More...
bool | set (int index, const T &value)
| Record the data for an entry specified by an index. More...
bool | set (int index, T &&value)
| Record the data for an entry specified by an index. More...
bool | set (const std::string &name, const T &value)
| Record the data for an entry specified by a name. More...
bool | set (const std::string &name, T &&value)
| Record the data for an entry specified by a name. More...
bool | reset (int index)
| Invalidate an entry— mark it as not containing any valid data. More...
bool | reset (const std::string &name)
| Invalidate an entry— mark it as not containing any valid data. More...
void | resetAll ()
| Invalidate all entries— mark everything as not containing any valid data. More...
size_t | size () const
| Check the number of existing entries. More...
int | getNumEntries () const
| Check the number of existing entries. More...
template<typename N >
void | copy (const NamedData< N > &source, const NamedDataCopyMap &map)
| Copy the data from another NamedData, based on a map of indices. More...
void | cacheIndex (const std::string &name, int *index) const
| Caches an entry's index if it is not already cached. More...

## Private Attributes

std::shared_ptr< const IndexDirectory > | m_directory
| The mapping between names and indices. More...
std::vector< T > | m_data
| The array of values. More...
std::vector< bool > | m_isDataValid
| The array storing whether the data is currently valid. More...

## Detailed Description

### template<typename T>
class SurgSim::DataStructures::NamedData< T >

A templated dictionary in which data can be accessed by name or index, with immutable names & indices.

A NamedData object consists of a collection of entries of type T. The data value for each entry can be accessed by either the entry's unique name (a std::string) or the entry's unique index (a non-negative integer). Access by name is more convenient, but less efficient.

A NamedData object constructed by the default constructor has no entries, meaning it has not been associated with a set of names and indices, and is called invalid or empty.

An non-empty object contains an immutable collection of entries. For a non-empty object: entries cannot be added or removed, and the entries' names and indices cannot be changed. Further, a non-empty object cannot become empty. These properties ensure that a stable data layout is available to the code using this class so that it can, for example, record entry indices and use them to retrieve the same entries later on.

The data associated with an entry (e.g., the true or false associated with a particular name and index in a NamedData<bool>) can be changed, and each entry can be reset to a "missing" state. A reset entry remains in the collection, but has no associated data.

The entries (i.e., names & indices) in a NamedData object can be set by passing a vector of names to the constructor, or by using the NamedDataBuilder class. Given one non-empty object, other objects with the same entries can be created via copy construction or assignment of the non-empty object to an empty (default-constructed) object.

Template Parameters

  T | the data type used for values contained in this collection.

## Constructor & Destructor Documentation

## NamedData() [1/5]

template<typename T >

SurgSim::DataStructures::NamedData< T >::NamedData | ( |  | ) |

inline

Create an empty object, with no associated names and indices yet.

## NamedData() [2/5]

template<typename T >

SurgSim::DataStructures::NamedData< T >::NamedData | ( | std::shared_ptr< const IndexDirectory > | directory | ) |

inline explicit

Create an object containing items from an index directory.

You should probably use NamedDataBuilder or copy construction/assignment instead.

Parameters

  directory | The IndexDirectory object describing the names and indices to be used.

## NamedData() [3/5]

template<typename T >

SurgSim::DataStructures::NamedData< T >::NamedData | ( | const std::vector< std::string > & | names | ) |

inline explicit

Construct an object, using the names from a vector of strings.

The indices corresponding to each name's entry will be the same as that name's index in the vector.

Parameters

  names | The names, which should be unique.

## NamedData() [4/5]

template<typename T >

SurgSim::DataStructures::NamedData< T >::NamedData | ( | const NamedData< T > & | namedData | ) |

inline

Construct an object as a copy of the data from another object.

This is used in the NamedVariantData copy constructor.

Parameters

  namedData | The object to copy from.

## NamedData() [5/5]

template<typename T >

SurgSim::DataStructures::NamedData< T >::NamedData | ( | NamedData< T > && | namedData | ) |

inline

Create an object and move the data from another object.

Parameters

  [in,out] | namedData | The object to copy from, which will be left in an unusable state.

## Member Function Documentation

## cacheIndex()

template<typename T >

void SurgSim::DataStructures::NamedData< T >::cacheIndex | ( | const std::string & | name,
|  | int * | index
| ) |  | const

Caches an entry's index if it is not already cached.

An index is considered already cached if it is >= 0.

Parameters

  | name | The name of the entry.
  [in,out] | index | The cached index.

## copy()

template<typename T >
template<typename N >

void SurgSim::DataStructures::NamedData< T >::copy | ( | const NamedData< N > & | source,
|  | const NamedDataCopyMap & | map
| ) |  |

inline

Copy the data from another NamedData, based on a map of indices.

Resets entries that are reset in the other.

Parameters

  source | The source NamedData.
  map | The map of indices.

Exceptions

  Asserts | if the objects do not have the same template type.

## get() [1/2]

template<typename T>

bool SurgSim::DataStructures::NamedData< T >::get | ( | int | index,
|  | T * | value
| ) |  | const

inline

Given an index, get the corresponding value.

It's only possible to get the value if the data was set using set(int, const T&) or set(const std::string&, const T&), without being subsequently invalidated by reset(int) or reset(const std::string&). In other words, get returns the same value as hasData would return.

Parameters

  | index | The index of the entry.
  [out] | value | The location for the retrieved value. Must not be null.

Returns
  true if a valid value is available and was written to value.

## get() [2/2]

template<typename T>

bool SurgSim::DataStructures::NamedData< T >::get | ( | const std::string & | name,
|  | T * | value
| ) |  | const

inline

Given a name, get the corresponding value.

It's only possible to get the value if the data was set using set(int, const T&) or set(const std::string&, const T&), without being subsequently invalidated by reset(int) or reset(const std::string&). In other words, get returns the same value as hasData would return.

Parameters

  | name | The name of the entry.
  [out] | value | The location for the retrieved value. Must not be null.

Returns
  true if a valid value is available and was written to value.

## getDirectory()

template<typename T >

std::shared_ptr< const IndexDirectory > SurgSim::DataStructures::NamedData< T >::getDirectory | ( |  | ) | const

inline

Return the object's layout directory, which is its collection of names and indices.

In most cases, you should use direct assignment instead of doing things via the directory.

Returns
  The IndexDirectory object containing the names and indices of entries.

## getIndex()

template<typename T >

int SurgSim::DataStructures::NamedData< T >::getIndex | ( | const std::string & | name | ) | const

inline

Given a name, return the corresponding index (or -1).

Parameters

  name | The name.

Returns
  the index for that name if one exists; -1 otherwise.

## getName()

template<typename T >

std::string SurgSim::DataStructures::NamedData< T >::getName | ( | int | index | ) | const

inline

Given an index, return the corresponding name (or "").

Parameters

  index | The index.

Returns
  the name for that index if one exists; an empty string otherwise.

## getNumEntries()

template<typename T >

int SurgSim::DataStructures::NamedData< T >::getNumEntries | ( |  | ) | const

inline

Check the number of existing entries.

Returns
  the size of the data collection.

See also
  size()

## hasData() [1/2]

template<typename T >

bool SurgSim::DataStructures::NamedData< T >::hasData | ( | int | index | ) | const

inline

Check whether the entry with the specified index contains valid data.

The check verifies that the entry's data was set using set(int, const T&) or set(const std::string&, const T&), without being subsequently invalidated by reset(int) or reset(const std::string&).

Parameters

  index | The index of the entry.

Returns
  true if that entry exists and contains valid data.

## hasData() [2/2]

template<typename T >

bool SurgSim::DataStructures::NamedData< T >::hasData | ( | const std::string & | name | ) | const

inline

Check whether the entry with the specified name contains valid data.

The check verifies that the entry's data was set using set(int, const T&) or set(const std::string&, const T&), without being subsequently invalidated by reset(int) or reset(const std::string&).

Parameters

  name | The name of the entry.

Returns
  true if that entry exists and contains valid data.

## hasEntry() [1/2]

template<typename T >

bool SurgSim::DataStructures::NamedData< T >::hasEntry | ( | int | index | ) | const

inline

Check whether the object contains an entry with the specified index.

Logically equivalent to `getName(index) != ""`.

Parameters

  index | The index corresponding to the entry.

Returns
  true if that entry exists, false if not.

## hasEntry() [2/2]

template<typename T >

bool SurgSim::DataStructures::NamedData< T >::hasEntry | ( | const std::string & | name | ) | const

inline

Check whether the object contains an entry with the specified name.

Logically equivalent to `getIndex(name) != -1`.

Parameters

  name | The name corresponding to the entry.

Returns
  true if that entry exists, false if not.

## isValid()

template<typename T >

bool SurgSim::DataStructures::NamedData< T >::isValid | ( |  | ) | const

inline

Check if the object has been initialized, which means it has a set of entries (i.e., names, indices, and the map between them).

If the object has not been initialized, it can become initialized on assignment from an initialized object.

Returns
  true if initialized.

## operator=() [1/2]

template<typename T >

NamedData< T > & SurgSim::DataStructures::NamedData< T >::operator= | ( | const NamedData< T > & | namedData | ) |

inline

Copy the data from another object.

The object being assigned into must either be empty (not yet associated with a set of names and indices), or the two objects must share the same data layout, resulting from earlier copy construction or assignment.

DataGroup initial;
// ...initialize "initial" to some non-empty value...
NamedData copyConstructed(initial); // Layout is shared with initial
copyConstructed = initial // OK, using the same layout
NamedData another; // Object is empty (no layout)
another = initial; // OK, layout is now shared with initial
another = initial // OK, using the same layout

Note that the data layout must be the same, i.e. related to one another by object assignment or copy construction. Objects that merely contain entries with the same names and indices are not acceptable! (Otherwise, we'd need to inefficiently compare layout contents each time we assign.)

std::vector<std::string> names // = ...initialized to some value...;
NamedData first(names); // Layout of entries created from names
NamedData second(names); // Another layout of entries created from names; names and indices match
second = first; // ERROR at run-time, layouts were created separately!

Parameters

  namedData | The object to copy from.

Returns
  The object that was assigned into.

## operator=() [2/2]

template<typename T >

NamedData< T > & SurgSim::DataStructures::NamedData< T >::operator= | ( | NamedData< T > && | namedData | ) |

inline

Move the data from another object.

The same restrictions on object compatibility apply as in the case of the copy assignment operator=(const NamedData&).

Parameters

  [in,out] | namedData | The object to copy from, which will be left in an unusable state.

Returns
  The object that was assigned into.

## reset() [1/2]

template<typename T >

bool SurgSim::DataStructures::NamedData< T >::reset | ( | int | index | ) |

inline

Invalidate an entry— mark it as not containing any valid data.

Parameters

  index | The index of the entry.

Returns
  true if successful.

## reset() [2/2]

template<typename T >

bool SurgSim::DataStructures::NamedData< T >::reset | ( | const std::string & | name | ) |

inline

Invalidate an entry— mark it as not containing any valid data.

Parameters

  name | The name of the entry.

Returns
  true if successful.

## resetAll()

template<typename T >

void SurgSim::DataStructures::NamedData< T >::resetAll | ( |  | ) |

inline

Invalidate all entries— mark everything as not containing any valid data.

## set() [1/4]

template<typename T>

bool SurgSim::DataStructures::NamedData< T >::set | ( | int | index,
|  | const T & | value
| ) |  |

inline

Record the data for an entry specified by an index.

The entry will also be marked as containing valid data.

Parameters

  index | The index of the entry.
  value | The value to be set.

Returns
  true if successful.

## set() [2/4]

template<typename T>

bool SurgSim::DataStructures::NamedData< T >::set | ( | int | index,
|  | T && | value
| ) |  |

inline

Record the data for an entry specified by an index.

This version accepts rvalues, and the data will be moved The entry will also be marked as containing valid data.

Parameters

  index | The index of the entry.
  value | The value to be set.

Returns
  true if successful.

## set() [3/4]

template<typename T>

bool SurgSim::DataStructures::NamedData< T >::set | ( | const std::string & | name,
|  | const T & | value
| ) |  |

inline

Record the data for an entry specified by a name.

The entry will also be marked as containing valid data.

Parameters

  name | The name of the entry.
  value | The value to be set.

Returns
  true if successful.

## set() [4/4]

template<typename T>

bool SurgSim::DataStructures::NamedData< T >::set | ( | const std::string & | name,
|  | T && | value
| ) |  |

inline

Record the data for an entry specified by a name.

This version accepts rvalues, and the data will be moved The entry will also be marked as containing valid data.

Parameters

  name | The name of the entry.
  value | The value to be set.

Returns
  true if successful.

## size()

template<typename T >

size_t SurgSim::DataStructures::NamedData< T >::size | ( |  | ) | const

inline

Check the number of existing entries.

Returns
  the size of the data collection.

See also
  getNumEntries()

## Member Data Documentation

## m_data

template<typename T>

std::vector<T> SurgSim::DataStructures::NamedData< T >::m_data

private

The array of values.

## m_directory

template<typename T>

std::shared_ptr<const IndexDirectory> SurgSim::DataStructures::NamedData< T >::m_directory

private

The mapping between names and indices.

## m_isDataValid

template<typename T>

std::vector<bool> SurgSim::DataStructures::NamedData< T >::m_isDataValid

private

The array storing whether the data is currently valid.

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

- SurgSim/DataStructures/NamedData.h
- SurgSim/DataStructures/NamedData-inl.h