All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Private Attributes | List of all members
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>

Collaboration diagram for SurgSim::DataStructures::NamedData< T >:
Collaboration graph
[legend]

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...
 
NamedDataoperator= (const NamedData &namedData)
 Copy the data from another object. More...
 
 NamedData (NamedData &&namedData)
 Create an object and move the data from another object. More...
 
NamedDataoperator= (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 (const std::string &name, const 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
Tthe data type used for values contained in this collection.

Constructor & Destructor Documentation

template<typename T >
SurgSim::DataStructures::NamedData< T >::NamedData ( )
inline

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

template<typename T >
SurgSim::DataStructures::NamedData< T >::NamedData ( std::shared_ptr< const IndexDirectory directory)
inlineexplicit

Create an object containing items from an index directory.

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

Parameters
directoryThe IndexDirectory object describing the names and indices to be used.
template<typename T >
SurgSim::DataStructures::NamedData< T >::NamedData ( const std::vector< std::string > &  names)
inlineexplicit

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
namesThe names, which should be unique.
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
namedDataThe object to copy from.
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]namedDataThe object to copy from, which will be left in an unusable state.

Member Function Documentation

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
nameThe name of the entry.
[in,out]indexThe cached index.
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
sourceThe source NamedData.
mapThe map of indices.
Exceptions
Assertsif the objects do not have the same template type.
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
indexThe index of the entry.
[out]valueThe location for the retrieved value. Must not be null.
Returns
true if a valid value is available and was written to value.
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
nameThe name of the entry.
[out]valueThe location for the retrieved value. Must not be null.
Returns
true if a valid value is available and was written to value.
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.
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
nameThe name.
Returns
the index for that name if one exists; -1 otherwise.
template<typename T >
std::string SurgSim::DataStructures::NamedData< T >::getName ( int  index) const
inline

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

Parameters
indexThe index.
Returns
the name for that index if one exists; an empty string otherwise.
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()
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
indexThe index of the entry.
Returns
true if that entry exists and contains valid data.
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
nameThe name of the entry.
Returns
true if that entry exists and contains valid data.
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
indexThe index corresponding to the entry.
Returns
true if that entry exists, false if not.
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
nameThe name corresponding to the entry.
Returns
true if that entry exists, false if not.
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.
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
namedDataThe object to copy from.
Returns
The object that was assigned into.
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]namedDataThe object to copy from, which will be left in an unusable state.
Returns
The object that was assigned into.
template<typename T >
bool SurgSim::DataStructures::NamedData< T >::reset ( int  index)
inline

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

Parameters
indexThe index of the entry.
Returns
true if successful.
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
nameThe name of the entry.
Returns
true if successful.
template<typename T >
void SurgSim::DataStructures::NamedData< T >::resetAll ( )
inline

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

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
indexThe index of the entry.
valueThe value to be set.
Returns
true if successful.
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
nameThe name of the entry.
valueThe value to be set.
Returns
true if successful.
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

template<typename T>
std::vector<T> SurgSim::DataStructures::NamedData< T >::m_data
private

The array of values.

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

The mapping between names and indices.

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: