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

#include <NamedData.h>

Public Member Functions
	NamedData ()
	Create an empty object, with no associated names and indices yet.

	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.

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...

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/4]

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

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

§ NamedData() [2/4]

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

names The names, which should be unique.

§ NamedData() [3/4]

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() [4/4]

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.

§ 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()

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

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

Public Member Functions

Detailed Description

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

Constructor & Destructor Documentation

§ NamedData() [1/4]

§ NamedData() [2/4]

§ NamedData() [3/4]

§ NamedData() [4/4]

Member Function Documentation

§ cacheIndex()

§ copy()

§ get() [1/2]

§ get() [2/2]

§ getDirectory()

§ getIndex()

§ getName()

§ getNumEntries()

§ hasData() [1/2]

§ hasData() [2/2]

§ hasEntry() [1/2]

§ hasEntry() [2/2]

§ isValid()

§ operator=() [1/2]

§ operator=() [2/2]

§ reset() [1/2]

§ reset() [2/2]

§ set() [1/4]

§ set() [2/4]

§ set() [3/4]

§ set() [4/4]

§ size()

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