SKeyedVector Class Template Reference
[Utility Classes and Functions]

#include <support/KeyedVector.h>

Inheritance diagram for SKeyedVector:

Detailed Description

template<class KEY, class VALUE>
class SKeyedVector< KEY, VALUE >

Templatized container of key/value pairs.

This template class defines a container object holding a set of key/value pairs of arbitrary types. It is built on top of the SVector and SSortedVector classes (containing the value and key data, respectively). As such, look-up operations in a keyed vector are a binary search -- an O(log(N)) operation.

When constructing a keyed vector, you can optionally supply a default value (if not supplied, this will be the result of the default constructor for the value type). When requesting a key that does not exist in the vector, the default value will be returned -- but ONLY for read-only operations. Edit operations on an undefined key will fail.

Note that this class is designed to not use exceptions, so error handling semantics -- out of memory, key not found -- are different than container classes in the STL.

Public Types

typedef KEY key_type

typedef VALUE value_type

Public Member Functions

ssize_t AddItem (const KEY &key, const VALUE &value)

Add a new key/value pair to the vector.

size_t Capacity () const

Return the total space allocated for the vector.

ssize_t CeilIndexOf (const KEY &key) const

As per SSortedVector::CeilIndexOf().

const VALUE & CeilValueFor (const KEY &key, bool *found=NULL) const

Like FloorValueFor(), but performs a key ceiling operation.

size_t CountItems () const

Return the number of actual items in the vector.

VALUE & EditValueAt (size_t i)

Edit value at a specific index in the vector.

VALUE & EditValueFor (const KEY &key, bool *found=NULL)

Retrieve a value for editing.

ssize_t FloorIndexOf (const KEY &key) const

As per SSortedVector::FloorIndexOf().

const VALUE & FloorValueFor (const KEY &key, bool *found=NULL) const

Perform a floor operation and return the resulting value.

bool GetIndexOf (const KEY &key, size_t *index) const

As per SSortedVector::GetIndexOf().

ssize_t IndexOf (const KEY &key) const

As per SSortedVector::IndexOf().

const KEY & KeyAt (size_t i) const

Return key at a specific index in the vector.

const SSortedVector< KEY > & KeyVector () const

Return the raw SSortedVector of keys.

void MakeEmpty ()

Remove all data.

const VALUE & operator[] (const KEY &key) const

Synonym for ValueFor().

ssize_t RemoveItemFor (const KEY &key)

Remove the item for the given key.

void RemoveItemsAt (size_t index, size_t count=1)

Remove one or more items from the vector, starting at 'index'.

void SetCapacity (size_t total_space)

Set the total space in the keyed vector.

void SetExtraCapacity (size_t extra_space)

Set the amount of space in the keyed vector for new items.

void SetTo (const SKeyedVector< KEY, VALUE > &o)

Copy another keyed vector in to this one.

SKeyedVector (const SSortedVector< KEY > &keys, const SVector< VALUE > &values, const VALUE &undef=VALUE())

SKeyedVector (const VALUE &undef)

SKeyedVector ()

void Swap (SKeyedVector< KEY, VALUE > &o)

Swap contents of this keyed vector with another.

const VALUE & ValueAt (size_t i) const

Return value at a specific index in the vector.

const VALUE & ValueFor (const KEY &key, bool *found=NULL) const

Retrieve the value corresponding to the given key.

SVector< VALUE > & ValueVector ()

Return an editable SSortedVector of values.

const SVector< VALUE > & ValueVector () const

Return the raw SSortedVector of values.

virtual ~SKeyedVector ()

Member Typedef Documentation

typedef KEY key_type

typedef VALUE value_type

Constructor & Destructor Documentation

SKeyedVector ( ) [inline]

SKeyedVector ( const VALUE & undef ) [inline]

SKeyedVector ( const SSortedVector< KEY > & keys,

const SVector< VALUE > & values,

const VALUE & undef = VALUE()

) [inline]

~SKeyedVector ( ) [inline, virtual]

Member Function Documentation

ssize_t AddItem ( const KEY & key,

const VALUE & value

) [inline]

Add a new key/value pair to the vector.
If the given key already exists, it is replaced with the new value. Returns the index of the added key, else an error such as B_NO_MEMORY.

size_t Capacity ( ) const [inline]

Return the total space allocated for the vector.
This will be >= CountItems() -- the difference is the number of items in the vector that have been allocated but not yet used.

ssize_t CeilIndexOf ( const KEY & key ) const [inline]

As per SSortedVector::CeilIndexOf().

const VALUE & CeilValueFor ( const KEY & key,

bool * found = NULL

) const [inline]

Like FloorValueFor(), but performs a key ceiling operation.

size_t CountItems ( ) const [inline]

Return the number of actual items in the vector.

Reimplemented from SAbstractKeyedVector.

VALUE & EditValueAt ( size_t i ) [inline]

Edit value at a specific index in the vector.

VALUE & EditValueFor ( const KEY & key,

bool * found = NULL

) [inline]

Retrieve a value for editing.
The given key must exist. 'found' will be false if it doesn't exist, in which case you must not access the returned value.

ssize_t FloorIndexOf ( const KEY & key ) const [inline]

As per SSortedVector::FloorIndexOf().

const VALUE & FloorValueFor ( const KEY & key,

bool * found = NULL

) const [inline]

Perform a floor operation and return the resulting value.
This function performs a FloorIndexOf() on the underlying SSortedVector to find closest key <= the requested key, and returns the value corresponding to that key.
For example:
SVector<int32_t, char> vector;
vector.AddItem(3, 'a'); vector.AddItem(7, 'b');
vector.FloorValueFor(1) => 'a' vector.FloorValueFor(3) => 'a' vector.FloorValueFor(5) => 'a' vector.FloorValueFor(100) => 'b'

bool GetIndexOf ( const KEY & key,

size_t * index

) const [inline]

As per SSortedVector::GetIndexOf().

ssize_t IndexOf ( const KEY & key ) const [inline]

As per SSortedVector::IndexOf().

const KEY & KeyAt ( size_t i ) const [inline]

Return key at a specific index in the vector.

const SSortedVector< KEY > & KeyVector ( ) const [inline]

Return the raw SSortedVector of keys.

void MakeEmpty ( ) [inline]

Remove all data.

const VALUE& operator[] ( const KEY & key ) const [inline]

Synonym for ValueFor().

ssize_t RemoveItemFor ( const KEY & key ) [inline]

Remove the item for the given key.
If the key exists, the index that it was removed from is returned. Otherwise an error is returned.

void RemoveItemsAt ( size_t index,

size_t count = 1

) [inline]

Remove one or more items from the vector, starting at 'index'.

Reimplemented from SAbstractKeyedVector.

void SetCapacity ( size_t total_space ) [inline]

Set the total space in the keyed vector.
This function is used to make room in the vector before a series of operations. It specifies the total number of items you would like to have room for in the vector, however it will NOT decrease the capacity below the number of actual items currently in the vector.

void SetExtraCapacity ( size_t extra_space ) [inline]

Set the amount of space in the keyed vector for new items.
This is like SetCapacity(), but sets the amount of space beyond the number of items currently in the vector.

void SetTo ( const SKeyedVector< KEY, VALUE > & o ) [inline]

Copy another keyed vector in to this one.
This is functionally the same as an = operator. The = operator is not defined for this class because it can be a very expensive operation -- so you must explicitly call SetTo().

void Swap ( SKeyedVector< KEY, VALUE > & o ) [inline]

Swap contents of this keyed vector with another.

const VALUE & ValueAt ( size_t i ) const [inline]

Return value at a specific index in the vector.

const VALUE & ValueFor ( const KEY & key,

bool * found = NULL

) const [inline]

Retrieve the value corresponding to the given key.
Returns the undefined value if the requested key does not exist. In this case 'found' will be false; if the key does exist then 'found' is true.

SVector< VALUE > & ValueVector ( ) [inline]

Return an editable SSortedVector of values.

const SVector< VALUE > & ValueVector ( ) const [inline]

Return the raw SSortedVector of values.

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

KeyedVector.h


Public Types
typedef KEY	key_type
typedef VALUE	value_type
Public Member Functions
ssize_t	AddItem (const KEY &key, const VALUE &value)
	Add a new key/value pair to the vector.
size_t	Capacity () const
	Return the total space allocated for the vector.
ssize_t	CeilIndexOf (const KEY &key) const
	As per SSortedVector::CeilIndexOf().
const VALUE &	CeilValueFor (const KEY &key, bool *found=NULL) const
	Like FloorValueFor(), but performs a key ceiling operation.
size_t	CountItems () const
	Return the number of actual items in the vector.
VALUE &	EditValueAt (size_t i)
	Edit value at a specific index in the vector.
VALUE &	EditValueFor (const KEY &key, bool *found=NULL)
	Retrieve a value for editing.
ssize_t	FloorIndexOf (const KEY &key) const
	As per SSortedVector::FloorIndexOf().
const VALUE &	FloorValueFor (const KEY &key, bool *found=NULL) const
	Perform a floor operation and return the resulting value.
bool	GetIndexOf (const KEY &key, size_t *index) const
	As per SSortedVector::GetIndexOf().
ssize_t	IndexOf (const KEY &key) const
	As per SSortedVector::IndexOf().
const KEY &	KeyAt (size_t i) const
	Return key at a specific index in the vector.
const SSortedVector< KEY > &	KeyVector () const
	Return the raw SSortedVector of keys.
void	MakeEmpty ()
	Remove all data.
const VALUE &	operator[] (const KEY &key) const
	Synonym for ValueFor().
ssize_t	RemoveItemFor (const KEY &key)
	Remove the item for the given key.
void	RemoveItemsAt (size_t index, size_t count=1)
	Remove one or more items from the vector, starting at 'index'.
void	SetCapacity (size_t total_space)
	Set the total space in the keyed vector.
void	SetExtraCapacity (size_t extra_space)
	Set the amount of space in the keyed vector for new items.
void	SetTo (const SKeyedVector< KEY, VALUE > &o)
	Copy another keyed vector in to this one.
	SKeyedVector (const SSortedVector< KEY > &keys, const SVector< VALUE > &values, const VALUE &undef=VALUE())
	SKeyedVector (const VALUE &undef)
	SKeyedVector ()
void	Swap (SKeyedVector< KEY, VALUE > &o)
	Swap contents of this keyed vector with another.
const VALUE &	ValueAt (size_t i) const
	Return value at a specific index in the vector.
const VALUE &	ValueFor (const KEY &key, bool *found=NULL) const
	Retrieve the value corresponding to the given key.
SVector< VALUE > &	ValueVector ()
	Return an editable SSortedVector of values.
const SVector< VALUE > &	ValueVector () const
	Return the raw SSortedVector of values.
virtual	~SKeyedVector ()

SKeyedVector Class Template Reference [Utility Classes and Functions]

Detailed Description

template<class KEY, class VALUE> class SKeyedVector< KEY, VALUE >

Public Types

Public Member Functions

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

SKeyedVector Class Template Reference
[Utility Classes and Functions]

template<class KEY, class VALUE>
class SKeyedVector< KEY, VALUE >