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/fstring.h | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ src/hash.h | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++ src/list.h | 15 ++++++ 3 files changed, 306 insertions(+) diff --git a/src/fstring.h b/src/fstring.h index 93a0042..9d88bd4 100644 --- a/src/fstring.h +++ b/src/fstring.h @@ -29,6 +29,11 @@ namespace Bu * almost no overhead in time or memory since a reference is created and no * data is actually copied. This also means that you never need to put any * FBasicString into a ref-counting container class. + * + *@param chr (typename) Type of character (i.e. char) + *@param nMinSize (int) Chunk size (default: 256) + *@param chralloc (typename) Memory Allocator for chr + *@param chunkalloc (typename) Memory Allocator for chr chunks */ template< typename chr, int nMinSize=256, typename chralloc=std::allocator, typename chunkalloc=std::allocator > > class FBasicString : public Archival @@ -113,6 +118,14 @@ namespace Bu clear(); } + /** + *@todo void append( const MyType & sData ) + */ + + /** + * Append data to your string. + *@param pData (const chr *) The data to append. + */ void append( const chr *pData ) { long nLen; @@ -126,6 +139,11 @@ namespace Bu appendChunk( pNew ); } + /** + * Append data to your string. + *@param pData (const chr *) The data to append. + *@param nLen (long) The length of the data to append. + */ void append( const chr *pData, long nLen ) { if( nLen == 0 ) @@ -138,16 +156,28 @@ namespace Bu appendChunk( pNew ); } + /** + * Append a single chr to your string. + *@param cData (const chr &) The character to append. + */ void append( const chr &cData ) { append( &cData, 1 ); } + /** + * Prepend another FString to this one. + *@param sData (MyType &) The FString to prepend. + */ void prepend( const MyType & sData ) { prepend( sData.getStr(), sData.getSize() ); } + /** + * Prepend data to your string. + *@param pData (const chr *) The data to prepend. + */ void prepend( const chr *pData ) { long nLen; @@ -159,6 +189,11 @@ namespace Bu prependChunk( pNew ); } + /** + * Prepend data to your string. + *@param pData (const chr *) The data to prepend. + *@param nLen (long) The length of the data to prepend. + */ void prepend( const chr *pData, long nLen ) { Chunk *pNew = newChunk( nLen ); @@ -168,11 +203,22 @@ namespace Bu prependChunk( pNew ); } + /** + *@todo void prepend( const chr &cData ) + */ + + /** + * Clear all data from the string. + */ void clear() { realClear(); } + /** + * Force the string to resize + *@param nNewSize (long) The new size of the string. + */ void resize( long nNewSize ) { if( nLength == nNewSize ) @@ -190,11 +236,19 @@ namespace Bu nLength = nNewSize; } + /** + * Get the current size of the string. + *@returns (long) The current size of the string. + */ long getSize() const { return nLength; } + /** + * Get a pointer to the string array. + *@returns (chr *) The string data. + */ chr *getStr() { if( pFirst == NULL ) @@ -204,6 +258,10 @@ namespace Bu return pFirst->pData; } + /** + * Get a const pointer to the string array. + *@returns (const chr *) The string data. + */ const chr *getStr() const { if( pFirst == NULL ) @@ -213,6 +271,10 @@ namespace Bu return pFirst->pData; } + /** + * (std::string compatability) Get a pointer to the string array. + *@returns (chr *) The string data. + */ chr *c_str() { if( pFirst == NULL ) @@ -222,6 +284,10 @@ namespace Bu return pFirst->pData; } + /** + * (std::string compatability) Get a const pointer to the string array. + *@returns (const chr *) The string data. + */ const chr *c_str() const { if( pFirst == NULL ) @@ -231,6 +297,10 @@ namespace Bu return pFirst->pData; } + /** + * Plus equals operator for FString. + *@param pData (const chr *) The data to append to your FString. + */ MyType &operator +=( const chr *pData ) { append( pData ); @@ -238,6 +308,10 @@ namespace Bu return (*this); } + /** + * Plus equals operator for FString. + *@param pData (const MyType &) The FString to append to your FString. + */ MyType &operator +=( const MyType &rSrc ) { if( rSrc.nLength == 0 ) @@ -248,6 +322,10 @@ namespace Bu return (*this); } + /** + * Plus equals operator for FString. + *@param pData (const chr) The character to append to your FString. + */ MyType &operator +=( const chr pData ) { append( &pData, 1 ); @@ -255,6 +333,11 @@ namespace Bu return (*this); } + /** + * Assignment operator. + *@param pData (const chr *) The character array to append to your + * FString. + */ MyType &operator =( const chr *pData ) { clear(); @@ -263,18 +346,31 @@ namespace Bu return (*this); } + /** + * Reset your FString to this character array. + *@param pData (const chr *) The character array to set your FString to. + */ void set( const chr *pData ) { clear(); append( pData ); } + /** + * Reset your FString to this character array. + *@param pData (const chr *) The character array to set your FString to. + *@param nSize (long) The length of the inputted character array. + */ void set( const chr *pData, long nSize ) { clear(); append( pData, nSize ); } + /** + * Assignment operator. + *@param rSrc (const MyType &) The FString to set your FString to. + */ MyType &operator =( const MyType &rSrc ) { //if( rSrc.isFlat() ) @@ -290,6 +386,11 @@ namespace Bu return (*this); } + /** + * Equals comparison operator. + *@param pData (const chr *) The character array to compare your FString + * to. + */ bool operator ==( const chr *pData ) const { if( pFirst == NULL ) { @@ -310,6 +411,10 @@ namespace Bu return true; } + /** + * Equals comparison operator. + *@param pData (const MyType &) The FString to compare your FString to. + */ bool operator ==( const MyType &pData ) const { if( pFirst == pData.pFirst ) @@ -330,16 +435,30 @@ namespace Bu return true; } + /** + * Not equals comparison operator. + *@param pData (const chr *) The character array to compare your FString + * to. + */ bool operator !=(const chr *pData ) const { return !(*this == pData); } + /** + * Not equals comparison operator. + *@param pData (const MyType &) The FString to compare your FString to. + */ bool operator !=(const MyType &pData ) const { return !(*this == pData); } + /** + * Indexing operator + *@param nIndex (long) The index of the character you want. + *@returns (chr &) The character at position (nIndex). + */ chr &operator[]( long nIndex ) { flatten(); @@ -347,6 +466,11 @@ namespace Bu return pFirst->pData[nIndex]; } + /** + * Const indexing operator + *@param nIndex (long) The index of the character you want. + *@returns (const chr &) The character at position (nIndex). + */ const chr &operator[]( long nIndex ) const { flatten(); @@ -354,6 +478,11 @@ namespace Bu return pFirst->pData[nIndex]; } + /** + * Is the character at index (nIndex) white space? + *@param nIndex (long) The index of the character you want to check. + *@returns (bool) Is it white space? + */ bool isWS( long nIndex ) const { flatten(); @@ -362,6 +491,11 @@ namespace Bu || pFirst->pData[nIndex]=='\r' || pFirst->pData[nIndex]=='\n'; } + /** + * Is the character at index (nIndex) a letter? + *@param nIndex (long) The index of the character you want to check. + *@returns (bool) Is it a letter? + */ bool isAlpha( long nIndex ) const { flatten(); @@ -370,6 +504,9 @@ namespace Bu || (pFirst->pData[nIndex] >= 'A' && pFirst->pData[nIndex] <= 'Z'); } + /** + * Convert your alpha characters to lower case. + */ void toLower() { flatten(); @@ -382,6 +519,9 @@ namespace Bu } } + /** + * Convert your alpha characters to upper case. + */ void toUpper() { flatten(); @@ -394,6 +534,11 @@ namespace Bu } } + /** + * Find the index of the first occurrance of (sText) + *@param sText (const char *) The string to search for. + *@returns (long) The index of the first occurrance. -1 for not found. + */ long find( const char *sText ) { long nTLen = strlen( sText ); @@ -406,6 +551,11 @@ namespace Bu return -1; } + /** + * Do a reverse search for (sText) + *@param sText (const char *) The string to search for. + *@returns (long) The index of the last occurrance. -1 for not found. + */ long rfind( const char *sText ) { long nTLen = strlen( sText ); @@ -418,6 +568,10 @@ namespace Bu return -1; } + /** + * Function the archiver calls to archive your FString. + *@param ar (Archive) The archive which is archiving your FString. + */ void archive( class Archive &ar ) { if( ar.isLoading() ) 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; diff --git a/src/list.h b/src/list.h index 4131987..9d1f904 100644 --- a/src/list.h +++ b/src/list.h @@ -21,6 +21,10 @@ namespace Bu * members are only accessable const. Third, erasing a location does not * invalidate the iterator, it simply points to the next valid location, or * end() if there are no more. + * + *@param value (typename) The type of data to store in your list + *@param valuealloc (typename) Memory Allocator for your value type + *@param linkalloc (typename) Memory Allocator for the list links. */ template, typename linkalloc=std::allocator > > class List @@ -53,6 +57,10 @@ namespace Bu clear(); } + /** + * Assignment operator. + *@param src (const MyType &) The list to assign to your list. + */ MyType &operator=( const MyType &src ) { clear(); @@ -62,6 +70,9 @@ namespace Bu } } + /** + * Clear the data from the list. + */ void clear() { Link *pCur = pFirst; @@ -79,6 +90,10 @@ namespace Bu nSize = 0; } + /** + * Append a value to the list. + *@param v (const value_type &) The value to append. + */ void append( const value &v ) { Link *pNew = la.allocate( 1 ); -- cgit v1.2.3