Detailed Description

Various helper functions related to STL classes.

Files
file	STLUtils.h
	Helper functions for STL classes.

Functions
template<typename T >
void	ola::STLEmptyStack (T *stack)
	Clear a stack.
template<typename T >
void	ola::STLEmptyStackAndDelete (T *stack)
	Clear a stack and delete all pointers..
template<typename T >
void	ola::STLDeleteElements (T *sequence)
	Delete the elements of a Sequence.
template<typename T >
void	ola::STLDeleteValues (T *container)
template<typename T1 , typename T2 >
bool	ola::STLContains (const T1 &container, const T2 &value)
template<typename T1 >
void	ola::STLKeys (const T1 &container, std::vector< typename T1::key_type > *keys)
template<typename T1 , typename T2 >
void	ola::STLValues (const T1 &container, std::vector< T2 > *values)
	Extract a vector of values from a pair associative container.
template<typename T1 >
T1::mapped_type *	ola::STLFind (T1 *container, const typename T1::key_type &key)
	Lookup a value by key in a associative container.
template<typename T1 >
T1::mapped_type const *	ola::STLFind (const T1 *container, const typename T1::key_type &key)
	Lookup a value by key in a associative container.
template<typename T1 >
T1::mapped_type	ola::STLFindOrNull (const T1 &container, const typename T1::key_type &key)
	Lookup a value by key in a associative container.
template<typename T1 >
bool	ola::STLReplace (T1 *container, const typename T1::key_type &key, const typename T1::mapped_type &value)
	Replace a value in a pair associative container, inserting the key, value if it doesn't already exist.
template<typename T1 >
T1::mapped_type	ola::STLReplacePtr (T1 *container, const typename T1::key_type &key, const typename T1::mapped_type &value)
	Replace a value in a pair associative container. If the key existed, the old value is returned, otherwise NULL is returned.
template<typename T1 >
bool	ola::STLReplaceAndDelete (T1 *container, const typename T1::key_type &key, const typename T1::mapped_type &value)
	Similar to STLReplace but this will delete the value if the replacement occurs.
template<typename T1 >
bool	ola::STLInsertIfNotPresent (T1 *container, const typename T1::value_type &key_value)
	Insert a value into a container only if this value doesn't already exist.
template<typename T1 >
bool	ola::STLInsertIfNotPresent (T1 *container, const typename T1::key_type &key, const typename T1::mapped_type &value)
	Insert a value into a container only if this value doesn't already exist.
template<typename T1 >
void	ola::STLInsertOrDie (T1 *container, const typename T1::key_type &key, const typename T1::mapped_type &value)
	Insert an key : value into a pair associative container, or abort the program if the key already exists.
template<typename T1 >
bool	ola::STLRemove (T1 *container, const typename T1::key_type &key)
	Remove a key / value from a container.
template<typename T1 >
bool	ola::STLLookupAndRemove (T1 container, const typename T1::key_type &key, typename T1::mapped_type value)
	Lookup and remove a key from a pair associative container.
template<typename T1 >
T1::iterator	ola::STLLookupOrInsertNull (T1 *container, const typename T1::key_type &key)
	Lookup or insert a NULL value into a pair associative container.
template<typename T1 >
void	ola::PairAssociativeAssignNew (T1 **location)
template<typename T1 >
T1::iterator	ola::STLLookupOrInsertNew (T1 *container, const typename T1::key_type &key)
	Lookup or insert a new object into a pair associative container.
template<typename T1 >
bool	ola::STLRemoveAndDelete (T1 *container, const typename T1::key_type &key)
	Remove a value from a pair associative container and delete it.
template<typename T1 >
T1::mapped_type	ola::STLLookupAndRemovePtr (T1 *container, const typename T1::key_type &key)
	Remove a value from a pair associative container and return the value.
template<typename T1 , typename T2 >
void	ola::STLMapFromKeys (T1 *output, const T2 input, typename T1::mapped_type value)

Function Documentation

template<typename T1 , typename T2 >

bool ola::STLContains	(	const T1 &	container,
		const T2 &	value
	)

inline

Returns true if the container contains the value.

Template Parameters

T1	A container.
T2	The value to search for.

Parameters

container	the container to search in.
value	the value to search for.

template<typename T >

void ola::STLDeleteElements ( T * sequence )

Delete the elements of a Sequence.

Parameters

sequence the Sequence to delete the elements from.

Template Parameters

T	A Sequence.

Postcondition: The sequence is empty.

All elements in the sequence will be deleted. The sequence will be cleared.

Example

class Foo() {
 public:
   Foo() {
     // populate m_objects
   }
   ~Foo() {
     STLDeleteElements(&m_objects);
   }
 private:
   vector<Bar*> m_objects;
};

template<typename T >

void ola::STLDeleteValues ( T * container )

Delete all values in a pair associative container.

Parameters

container

Template Parameters

T	A pair associative container.

Postcondition: The container is empty.

All elements in the container will be deleted. The container will be cleared.

Example

class Foo() {
 public:
   Foo() {
     // populate m_objects
   }
   ~Foo() {
     STLDeleteValues(&m_objects);
   }
 private:
   map<int, Bar*> m_objects;
};

See Also: STLDeleteElements.

template<typename T >

void ola::STLEmptyStack ( T * stack )

Clear a stack.

Template Parameters

T A stack.

Postcondition: The stack is empty.

template<typename T >

void ola::STLEmptyStackAndDelete ( T * stack )

Clear a stack and delete all pointers..

Template Parameters

T	A stack of pointers.

Postcondition: The stack is empty.

template<typename T1 >

T1::mapped_type* ola::STLFind	(	T1 *	container,
		const typename T1::key_type &	key
	)

Lookup a value by key in a associative container.

Template Parameters

T1	A container.

Parameters

container	the container to search in.
key	the key to search for.

Returns: A pointer to the value, or NULL if the value isn't found.

template<typename T1 >

T1::mapped_type const* ola::STLFind	(	const T1 *	container,
		const typename T1::key_type &	key
	)

Lookup a value by key in a associative container.

Template Parameters

T1	A container.

Parameters

container	the container to search in.
key	the key to search for.

Returns: A pointer to the value, or NULL if the value isn't found.

template<typename T1 >

T1::mapped_type ola::STLFindOrNull	(	const T1 &	container,
		const typename T1::key_type &	key
	)

Lookup a value by key in a associative container.

Template Parameters

T1	A container.

Parameters

container	the container to search in.
key	the key to search for.

Returns: The value matching the key, or NULL if the value isn't found.

This assumes that NULL can be co-erced to the mapped_type of the container. It's most suitable for containers with pointers.

template<typename T1 >

bool ola::STLInsertIfNotPresent	(	T1 *	container,
		const typename T1::value_type &	key_value
	)

Insert a value into a container only if this value doesn't already exist.

Template Parameters

T1	A container.

Parameters

container	the container to insert the value in.
key_value	the pair<key, value> to insert.

Returns: true if the key/value was inserted, false if the key already exists.

template<typename T1 >

bool ola::STLInsertIfNotPresent	(	T1 *	container,
		const typename T1::key_type &	key,
		const typename T1::mapped_type &	value
	)

Insert a value into a container only if this value doesn't already exist.

Template Parameters

T1	A container.

Parameters

container	the container to insert the value in.
key	the key to insert.
value	the value to insert.

Returns: true if the key/value was inserted, false if the key already exists.

See Also: STLInsertIfNotPresent.

template<typename T1 >

void ola::STLInsertOrDie	(	T1 *	container,
		const typename T1::key_type &	key,
		const typename T1::mapped_type &	value
	)

Insert an key : value into a pair associative container, or abort the program if the key already exists.

Template Parameters

T1	A container.

Parameters

container	the container to insert the value in.
key	the key to insert.
value	the value to insert.

Note: This should only be used in unit-testing code.

template<typename T1 >

void ola::STLKeys	(	const T1 &	container,
		std::vector< typename T1::key_type > *	keys
	)

Extract the list of keys from a pair associative container.

Template Parameters

T1	A container.

Parameters

[in]	container	the container to extract the keys for.
[out]	keys	the vector to populate with the keys.

template<typename T1 >

bool ola::STLLookupAndRemove	(	T1 *	container,
		const typename T1::key_type &	key,
		typename T1::mapped_type *	value
	)

Lookup and remove a key from a pair associative container.

Template Parameters

T1	A container.

Parameters

[in]	container	the container to remove the key from.
[in]	key	the key to remove.
[out]	value	A pointer which will be set to the removed value.

Returns: true if the item was found and removed, false otherwise.

Lookup a value by key in a pair associative container. If the value exists, it's removed from the container, the value placed in value and true is returned.

template<typename T1 >

T1::mapped_type ola::STLLookupAndRemovePtr	(	T1 *	container,
		const typename T1::key_type &	key
	)

Remove a value from a pair associative container and return the value.

Template Parameters

T1	A container.

Parameters

[in]	container	the container to remove the key from.
[in]	key	the key to remove.

Returns: The value matching the key, or NULL if the value isn't found.

Note: This assumes that NULL can be co-erced to the mapped_type of the container. It's most suitable for containers with pointers.

template<typename T1 >

T1::iterator ola::STLLookupOrInsertNew	(	T1 *	container,
		const typename T1::key_type &	key
	)

Lookup or insert a new object into a pair associative container.

Template Parameters

T1	A container.

Parameters

[in]	container	the container to lookup from or insert into.
[in]	key	the key to lookup.

Returns: An iterator pointing to the value.

template<typename T1 >

T1::iterator ola::STLLookupOrInsertNull	(	T1 *	container,
		const typename T1::key_type &	key
	)

Lookup or insert a NULL value into a pair associative container.

Template Parameters

T1	A container.

Parameters

[in]	container	the container to lookup from or insert into.
[in]	key	the key to lookup.

Returns: An iterator pointing to the value.

Lookup a value by key in a pair associative container or insert NULL if it doesn't already exist.

template<typename T1 , typename T2 >

void ola::STLMapFromKeys	(	T1 *	output,
		const T2	input,
		typename T1::mapped_type	value
	)

Add elements of a sequence to an associative container.

Parameters

output	The associative container to add to.
input	The sequence containing the elements to add.
value	The value to use for each key in input.

Template Parameters

T1	A pair associative container.
T2	A sequence.

Any existing elements that conflict with the values in the sequence will be replaced.

template<typename T1 >

bool ola::STLRemove	(	T1 *	container,
		const typename T1::key_type &	key
	)

Remove a key / value from a container.

Template Parameters

T1	A container.

Parameters

container	the container to remove the key from.
key	the key to remove.

Returns: true if the item was removed, false otherwise.

template<typename T1 >

bool ola::STLRemoveAndDelete	(	T1 *	container,
		const typename T1::key_type &	key
	)

Remove a value from a pair associative container and delete it.

Template Parameters

T1	A container.

Parameters

[in]	container	the container to remove the key from.
[in]	key	the key to remove.

Returns: true if the item was found and removed from the container, false otherwise.

template<typename T1 >

bool ola::STLReplace	(	T1 *	container,
		const typename T1::key_type &	key,
		const typename T1::mapped_type &	value
	)

Replace a value in a pair associative container, inserting the key, value if it doesn't already exist.

Template Parameters

T1	A container.

Parameters

container	the container to replace the value in.
key	the key to insert / replace.
value	the value to insert / replace.

Returns: true if the value was replaced, false if the value was inserted.

Note: Note if the value type is a pointer, and the container has ownership of the pointer, replacing a value will leak memory. Use STLReplaceAndDelete to avoid this.

See Also: STLReplaceAndDelete.

template<typename T1 >

bool ola::STLReplaceAndDelete	(	T1 *	container,
		const typename T1::key_type &	key,
		const typename T1::mapped_type &	value
	)

Similar to STLReplace but this will delete the value if the replacement occurs.

Template Parameters

T1	A container.

Parameters

container	the container to replace the value in.
key	the key to insert / replace.
value	the value to insert / replace.

Returns: true if the value was replaced, false if the value was inserted.

template<typename T1 >

T1::mapped_type ola::STLReplacePtr	(	T1 *	container,
		const typename T1::key_type &	key,
		const typename T1::mapped_type &	value
	)

Replace a value in a pair associative container. If the key existed, the old value is returned, otherwise NULL is returned.

Template Parameters

T1	A container.

Parameters

container	the container to replace the value in.
key	the key to insert / replace.
value	the value to insert / replace.

Returns: The value matching the key, or NULL if the value isn't found.

Note: This assumes that NULL can be co-erced to the mapped_type of the container. It's most suitable for containers with pointers.

See Also: STLReplaceAndDelete.

template<typename T1 , typename T2 >

void ola::STLValues	(	const T1 &	container,
		std::vector< T2 > *	values
	)

Extract a vector of values from a pair associative container.

Template Parameters

T1	A container.
T2	The type of the values.

Parameters

[in]	container	the container to extract the values for.
[out]	values	the vector to populate with the values.

Detailed Description

Files

Functions

Function Documentation