From 5292e5831934dc719d1ac06332bd252abe4ac3bc Mon Sep 17 00:00:00 2001 From: David Date: Mon, 18 Jun 2007 19:41:34 +0000 Subject: david - writing code documentation... --- src/hash.h | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) (limited to 'src/hash.h') diff --git a/src/hash.h b/src/hash.h index 1bb25c9..6c4a443 100644 --- a/src/hash.h +++ b/src/hash.h @@ -71,6 +71,10 @@ namespace Bu bool bFilled; public: + /** + * Cast operator for HashProxy. + *@returns (value_type &) The value the HashProxy is pointing to. + */ operator _value &() { if( bFilled == false ) @@ -81,6 +85,10 @@ namespace Bu return *pValue; } + /** + * Direct function for retrieving a value out of the HashProxy. + *@returns (value_type &) The value pointed to by this HashProxy. + */ _value &value() { if( bFilled == false ) @@ -91,11 +99,17 @@ namespace Bu return *pValue; } + /** + * Whether this HashProxy points to something real or not. + */ bool isFilled() { return bFilled; } + /** + * Erase the data pointed to by this HashProxy. + */ void erase() { if( bFilled ) @@ -105,6 +119,10 @@ namespace Bu } } + /** + * Assign data to this point in the hash table. + *@param nval (value_type) the data to assign. + */ _value operator=( _value nval ) { if( bFilled ) @@ -122,6 +140,11 @@ namespace Bu return nval; } + /** + * Pointer extraction operator. Access to members of data pointed to + * by HashProxy. + *@returns (value_type *) + */ _value *operator->() { if( bFilled == false ) @@ -133,6 +156,15 @@ namespace Bu } }; + /** + * Libbu Template Hash Table + *@param key (typename) The datatype of the hashtable keys + *@param value (typename) The datatype of the hashtable data + *@param sizecalc (typename) Functor to compute new table size on rehash + *@param keyalloc (typename) Memory allocator for hashtable keys + *@param valuealloc (typename) Memory allocator for hashtable values + *@param challoc (typename) Byte allocator for bitflags + */ template class Hash { @@ -186,6 +218,10 @@ namespace Bu } } + /** + * Hashtable assignment operator. Clears this hashtable and + * copies RH into it. + */ Hash &operator=( const Hash &src ) { for( uint32_t j = 0; j < nCapacity; j++ ) @@ -244,26 +280,49 @@ namespace Bu ca.deallocate( aHashCodes, nCapacity ); } + /** + * Get the current hash table capacity. (Changes at re-hash) + *@returns (uint32_t) The current capacity. + */ uint32_t getCapacity() { return nCapacity; } + /** + * Get the number of hash locations spoken for. (Including + * not-yet-cleaned-up deleted items.) + *@returns (uint32_t) The current fill state. + */ uint32_t getFill() { return nFilled; } + /** + * Get the number of items stored in the hash table. + *@returns (uint32_t) The number of items stored in the hash table. + */ uint32_t size() { return nFilled-nDeleted; } + /** + * Get the number of items which have been deleted, but not yet + * cleaned up. + *@returns (uint32_t) The number of deleted items. + */ uint32_t getDeleted() { return nDeleted; } + /** + * Hash table index operator + *@param k (key_type) Key of data to be retrieved. + *@returns (HashProxy) Proxy pointing to the data. + */ virtual HashProxy operator[]( key k ) { uint32_t hash = __calcHashCode( k ); @@ -280,6 +339,11 @@ namespace Bu } } + /** + * Insert a value (v) under key (k) into the hash table + *@param k (key_type) Key to list the value under. + *@param v (value_type) Value to store in the hash table. + */ virtual void insert( key k, value v ) { uint32_t hash = __calcHashCode( k ); @@ -299,6 +363,10 @@ namespace Bu } } + /** + * Remove a value from the hash table. + *@param k (key_type) The data under this key will be erased. + */ virtual void erase( key k ) { uint32_t hash = __calcHashCode( k ); @@ -313,6 +381,11 @@ namespace Bu } struct iterator; + + /** + * Remove a value from the hash pointed to from an iterator. + *@param i (iterator &) The data to be erased. + */ virtual void erase( struct iterator &i ) { if( this != &i.hsh ) @@ -324,6 +397,9 @@ namespace Bu } } + /** + * Remove all data from the hash table. + */ virtual void clear() { for( uint32_t j = 0; j < nCapacity; j++ ) @@ -340,6 +416,11 @@ namespace Bu clearBits(); } + /** + * Get an item of data from the hash table. + *@param k (key_type) Key pointing to the data to be retrieved. + *@returns (value_type &) The data pointed to by (k). + */ virtual value &get( key k ) { uint32_t hash = __calcHashCode( k ); @@ -359,6 +440,12 @@ namespace Bu } } + /** + * Get a const item of data from the hash table. + *@param k (key_type) Key pointing to the data to be retrieved. + *@returns (const value_type &) A const version of the data pointed + * to by (k). + */ virtual const value &get( key k ) const { uint32_t hash = __calcHashCode( k ); @@ -378,6 +465,11 @@ namespace Bu } } + /** + * Does the hash table contain an item under key (k). + *@param k (key_type) The key to check. + *@returns (bool) Whether there was an item in the hash under key (k). + */ virtual bool has( key k ) { bool bFill; @@ -386,6 +478,9 @@ namespace Bu return bFill; } + /** + * Iteration structure for iterating through the hash. + */ typedef struct iterator { friend class Hash; @@ -410,6 +505,9 @@ namespace Bu bool bFinished; public: + /** + * Iterator incrementation operator. Move the iterator forward. + */ iterator operator++( int ) { if( bFinished == false ) @@ -418,6 +516,9 @@ namespace Bu return *this; } + /** + * Iterator incrementation operator. Move the iterator forward. + */ iterator operator++() { if( bFinished == false ) @@ -426,6 +527,9 @@ namespace Bu return *this; } + /** + * Iterator equality comparison operator. Iterators the same? + */ bool operator==( const iterator &oth ) { if( bFinished != oth.bFinished ) @@ -442,11 +546,17 @@ namespace Bu } } + /** + * Iterator not equality comparison operator. Not the same? + */ bool operator!=( const iterator &oth ) { return !(*this == oth ); } + /** + * Iterator assignment operator. + */ iterator operator=( const iterator &oth ) { if( &hsh != &oth.hsh ) @@ -456,32 +566,59 @@ namespace Bu bFinished = oth.bFinished; } + /** + * Iterator dereference operator... err.. get the value + *@returns (value_type &) The value behind this iterator. + */ value &operator *() { return hsh.getValueAtPos( nPos ); } + /** + * Get the key behind this iterator. + *@returns (key_type &) The key behind this iterator. + */ key &getKey() { return hsh.getKeyAtPos( nPos ); } + /** + * Get the value behind this iterator. + *@returs (value_type &) The value behind this iterator. + */ value &getValue() { return hsh.getValueAtPos( nPos ); } }; + /** + * Get an iterator pointing to the first item in the hash table. + *@returns (iterator) An iterator pointing to the first item in the + * hash table. + */ iterator begin() { return iterator( *this ); } + /** + * Get an iterator pointing to a point just past the last item in the + * hash table. + *@returns (iterator) An iterator pointing to a point just past the + * last item in the hash table. + */ iterator end() { return iterator( *this, true ); } + /** + * Get a list of all the keys in the hash table. + *@returns (std::list) The list of keys in the hash table. + */ std::list getKeys() { std::list lKeys; -- cgit v1.2.3