HTM SpatialIndex Class Reference

template class PtrVec

Dynamic array of pointers This is a template for a dynamic array of pointers

Public Fields

size_t increment_
linear growth increment
T** vector_
dynamic array of pointers

Public Methods

~PtrVec ( void )
Destructor
PtrVec ( bool internal=true, size_t capacity=0, size_t increment=0 )
Default constructor
PtrVec ( const PtrVec&, bool internalize = true )
Copy constructor
PtrVec& copy ( const PtrVec&, bool internalize )
Copy method
PtrVec& operator = ( const PtrVec &obj )
Assignment/copy operator
const T*& operator () ( size_t index ) const
Efficient array operator (const version): no bounds checking
T*& operator () ( size_t index )
Efficient array operator (non-const version): no bounds checking
const T*& operator [] ( size_t index ) const
Bounds-checking array operator (const version): throws sxBoundsError
T*& operator [] ( size_t index )
Bounds-checking array operator (non-const version): throws sxBoundsError
T*& at ( size_t index )
Bounds-adjusting array operator
size_t length ( void ) const
Returns current occupied length of array
size_t entries ( void ) const
Return the number of non-NULL entries in vector
size_t append ( T* )
Append: efficiently insert given element at end of array
size_t insert ( size_t count, size_t offset = 0 )
Insert new array elements
size_t nextEmpty ()
Return the index of the next available empty slot
size_t add ( T* )
Add a new array element in the first available empty slot
int index ( const T* )
Return the index of the given element
size_t cut ( size_t count, size_t offset = 0 )
Remove array elements
void remove ( size_t offset )
Removes the element specified by offset
void internalize ( void )
Replace external pointers with internal copies of the referenced objects
void externalize ( void )
Change status of pointers to external
bool internal ( void ) const
internal method: returns true if the pointers are internal

Documentation

Dynamic array of pointers This is a template for a dynamic array of pointers. The design is very similar to the general-purpose version, ValVec, but specialized according to the memory management issues peculiar to storing pointers. This version uses nil as the fill value, which cannot be customized or disabled. By default, the cut method uses the delete operator to free pointers as they are removed from the array. Before disposing the array, the destructor clears it out with cut. This behavior is avoided if the pointers are designated as external, or shared. In that case it is entirely up to the user to free pointers left dangling by cut. When copying the array, one must choose whether the copy will share with the original the objects referenced by the pointers (shallow copy), or whether the copy will have its own internal duplicates.

--------------- WARNING ---------------

The user must provide a specialization of PtrDup() for every polymorphic class that will instantiate this template. Failure to do this may result in unexpected truncation of derived objects. The template methods use PtrDup() when duplication of objects is required, but duplicating a polymorphic object requires assistance from the object itself. For example, consider class B:

class B { public:
virtual B* duplicate(void) const = 0;
};
inline B* PtrDup(const B *b) { return b ? b->duplicate() : 0; }
To avoid confusion and mistakes, place the specialization immediately after the declaration of class B. If class B does not have a duplicator use the following specialization instead:
inline B* PtrDup(const B *b) {
if (b) throw sxUnimplemented("PtrDup","class B has no duplicator");
else return 0;
}
~PtrVec( void )
Destructor

PtrVec( bool internal=true, size_t capacity=0, size_t increment=0 )
Default constructor. optionally specify initial capacity, reallocation increment, and whether the pointers are internal.

PtrVec( const PtrVec&, bool internalize = true )
Copy constructor. optionally specify either a shallow copy or an internalized copy (the default). The initial capacity is the current capacity of the duplicated array.

PtrVec& copy( const PtrVec&, bool internalize )
Copy method. does not decrease the capacity. The copy is shallow if internalize is false; otherwise the referenced objects are duplicated and the copy is internal, in which case class T must have well-defined copy semantics.

PtrVec& operator =( const PtrVec &obj )
Assignment/copy operator. does not decrease the capacity. This is not a shallow copy, so class T must have well-defined copy semantics.

const T*& operator ()( size_t index ) const
Efficient array operator (const version): no bounds checking

T*& operator ()( size_t index )
Efficient array operator (non-const version): no bounds checking

const T*& operator []( size_t index ) const
Bounds-checking array operator (const version): throws sxBoundsError

T*& operator []( size_t index )
Bounds-checking array operator (non-const version): throws sxBoundsError

T*& at( size_t index )
Bounds-adjusting array operator. Returns the array element at the specified index, extending the array as necessary to bring it within bounds. Any new elements are set to nil.

size_t length( void ) const
Returns current occupied length of array

size_t entries( void ) const
Return the number of non-NULL entries in vector. NOTE: this is different from length(), which also counts NULL pointers.

size_t append( T* )
Append: efficiently insert given element at end of array. Avoids redundant initialization of new array element, except for when a reallocation is required. Returns the new length.

size_t insert( size_t count, size_t offset = 0 )
Insert new array elements. count specifies the number of new elements, and offset specifies where in the array to insert them. By default the new elements are appended. The new elements are initialized with the nil pointer value. offset refers to the end of the array: the first new element is located at index (length - offset). Returns the new length. Throws sxBoundsError if offset is greater than length.

size_t nextEmpty()
Return the index of the next available empty slot

size_t add( T* )
Add a new array element in the first available empty slot. This should be used when the ordering of elements is not important and empty slots are to be minimized. Returns the index of the newly inserted element.

int index( const T* )
Return the index of the given element. (If it exists in the array, else return -1.)

size_t cut( size_t count, size_t offset = 0 )
Remove array elements. count specifies the number of elements to remove, and offset specifies which elements to remove. By default elements are removed from the end of the array. The unused capacity grows by this amount. offset refers to the end of the array: the first removed element is located at index (length - offset - count). Returns the new length. Throws sxBoundsError if (offset+count) is greater than length.

void remove( size_t offset )
Removes the element specified by offset. This is basically a wrapper for the cut method
cut(1, length-offset-1)

void internalize( void )
Replace external pointers with internal copies of the referenced objects. class T must have well-defined copy semantics. Does nothing if already internal.

void externalize( void )
Change status of pointers to external. Beware that internalize does not undo this; once the pointers are designated external they cannot just be re-designated as internal. Confusion on this point will yield dangling pointers.

bool internal( void ) const
internal method: returns true if the pointers are internal

size_t increment_
linear growth increment

T** vector_
dynamic array of pointers


This class has no child classes.

alphabetic index hierarchy of classes


© Copyright The Johns Hopkins University 1999, All Rights Reserved.
Peter Z. Kunszt,

generated by doc++