From 4e86c50016ecfea40a72930cdd0460143f9edf4a Mon Sep 17 00:00:00 2001 From: Mike Buland Date: Sun, 9 Aug 2009 05:30:34 +0000 Subject: Really, just a lot of documenting. --- src/bitstring.h | 51 ------------------------------------- src/crypt.cpp | 7 +++++ src/crypt.h | 11 ++++++-- src/doxy/formatting.dox | 35 +++++++++++++++++++++++++ src/doxy/groups.dox | 10 ++++---- src/doxy/main.dox | 1 + src/doxy/streams.dox | 13 +++++----- src/fbasicstring.h | 35 ++++++++++++++++++------- src/hash.h | 16 +++++++++--- src/ito.h | 2 +- src/list.h | 2 +- src/set.h | 3 +-- src/tests/console.cpp | 36 ++++++++++++++++++++++++++ src/util.h | 68 ++++++++++++++++++++++++++++++++++++++++++++++--- 14 files changed, 205 insertions(+), 85 deletions(-) create mode 100644 src/doxy/formatting.dox create mode 100644 src/tests/console.cpp (limited to 'src') diff --git a/src/bitstring.h b/src/bitstring.h index 35f854f..b5f1ada 100644 --- a/src/bitstring.h +++ b/src/bitstring.h @@ -202,57 +202,6 @@ namespace Bu */ long toLong( long iStart = 0, long iSize = 32 ); - /** - * Converts the data into a human-readable SString object. SString is - * used to make transport of the string and management very simple. - * Since BitStrings will generally be longer than your average strip of - * ints a faculty is included and turned on by default that will insert - * spacers into the output text every 8 places. For debugging work, - * this is definately reccomended. - *@param bAddSpacers Leave set to true in order to have the output - * broken into logical groupings of 8 bits per block. Set to off to - * have a harder - * to read solid block of bits. - *@returns A SString object containing the produced string. - */ - //std::string toString( bool bAddSpacers = true ); - - // Utility - /** - * Converts the given number of bits into the smallest allocatable unit, - * which is bytes in C and on most systems nowadays. This is the - * minimum number of bytes needed to contain the given number of bits, - * so there is generally some slop if they are not evenly divisible. - *@param iBits The number of bits you wish to use. - *@returns The number of bytes you will need to contain the given number - * of bits. - */ - //static long bitsToBytes( long iBits ); - - /** - * Writes all data in the BitString, including a small header block - * describing the number of bits in the BitString to the file described - * by the given file descriptor. The data writen is purely sequential - * and probably not too easy to read by other mechanisms, although the - * readFromFile function should always be able to do it. This function - * does not open nor close the file pointed to by fh. - *@param fh The file descriptor of the file to write the data to. - *@returns true if the operation completed without error, false - * otherwise. - */ - //bool writeToFile( FILE *fh ); - - /** - * Reads data formatted by writeToFile and clears out any data that may - * have been in the BitString. This function preserves nothing in the - * original BitString that it may be replacing. This function does not - * open nor close the file pointed to by fh. - *@param fh The file descriptor to try to read the data from. - *@returns true if the operation completed without error, false - * otherwise. - */ - //bool readFromFile( FILE *fh ); - //operators BitString &operator=( const BitString &xSrc ); BitString operator~(); diff --git a/src/crypt.cpp b/src/crypt.cpp index 9111cda..dbf90ab 100644 --- a/src/crypt.cpp +++ b/src/crypt.cpp @@ -1,3 +1,10 @@ +/* + * Copyright (C) 2007-2008 Xagasoft, All rights reserved. + * + * This file is part of the libbu++ library and is released under the + * terms of the license contained in the file LICENSE. + */ + #include "bu/crypt.h" #include "bu/md5.h" #include "bu/base64.h" diff --git a/src/crypt.h b/src/crypt.h index 1ea1b85..a38ff52 100644 --- a/src/crypt.h +++ b/src/crypt.h @@ -1,3 +1,10 @@ +/* + * Copyright (C) 2007-2008 Xagasoft, All rights reserved. + * + * This file is part of the libbu++ library and is released under the + * terms of the license contained in the file LICENSE. + */ + #ifndef BU_CRYPT_H #define BU_CRYPT_H @@ -5,8 +12,8 @@ namespace Bu { - FString cryptPass( const FString &sPass, const FString &sSalt ); - FString cryptPass( const FString &sPass ); + FString cryptPass( const Bu::FString &sPass, const Bu::FString &sSalt ); + FString cryptPass( const Bu::FString &sPass ); }; #endif diff --git a/src/doxy/formatting.dox b/src/doxy/formatting.dox new file mode 100644 index 0000000..7b440cb --- /dev/null +++ b/src/doxy/formatting.dox @@ -0,0 +1,35 @@ +/* + * Copyright (C) 2007-2008 Xagasoft, All rights reserved. + * + * This file is part of the libbu++ library and is released under the + * terms of the license contained in the file LICENSE. + */ + +/** + *@page howto_formatting Formatting data for streams and the console. + * + * Libbu++ provides a powerful and flexible interface for writing formatted + * data easily to any Stream. This is implemented as a seperate set of + * classes from the basic Stream system in order to simplify both systems and + * provide additional flexibility and organization. + * + *@section secBasics The Basics: Writing to the console (standard i/o) + * Libbu++ provides the global variable Bu::sio already instantiated and ready + * to be used to access the standard input and output via the Bu::Formatter + * class. If you are familiar with the STL cout then you're practically done. + * A quick example may be best. + *@code +#include +using namespace Bu; + +int main() +{ + int i = 47; + + sio << "Hello, world." << sio.nl + << "Here is a number: " << i << sio.nl; + + return 0; +} +@endcode + */ diff --git a/src/doxy/groups.dox b/src/doxy/groups.dox index 9b54950..285923c 100644 --- a/src/doxy/groups.dox +++ b/src/doxy/groups.dox @@ -6,26 +6,26 @@ */ /** - *@defgroup Threading + *@defgroup Threading Threading * Threads are awesome. */ /** - *@defgroup Serving + *@defgroup Serving Serving * Serving data is pretty cool too. */ /** - *@defgroup Containers + *@defgroup Containers Containers * Containers for data. */ /** - *@defgroup Taf + *@defgroup Taf Taf * Taf is the best! */ /** - *@defgroup Streams + *@defgroup Streams Streams * Streams are for data. */ diff --git a/src/doxy/main.dox b/src/doxy/main.dox index 6030f0c..5e822e1 100644 --- a/src/doxy/main.dox +++ b/src/doxy/main.dox @@ -18,6 +18,7 @@ * comprehensive guides and API reference, but doesn't yet. For now check out * these sections: * - @ref howto_streams + * - @ref howto_formatting * - @ref howto_archives * - @ref howto_threading * - @ref howto_servers diff --git a/src/doxy/streams.dox b/src/doxy/streams.dox index 8217210..9655743 100644 --- a/src/doxy/streams.dox +++ b/src/doxy/streams.dox @@ -44,11 +44,10 @@ * data. * *@section difference How are libbu++ streams different form stl streams? - * While not globally true, many stl streams are designed for formatting the - * data that flows through the stream, that means that when you attempt to - * write a uint32_t into a standard stream it can be difficult to predict what - * the result will be, will it be the binary representation or a textual - * conversion? + * The most basic difference is that libbu++ streams are geared more towards a + * lower level feel, giving you easy and more direct access to many features, + * while seperating all of the formatting code used for console I/O and number + * to text conversion, etc, in a seperate place. * * Libbu++ streams are very direct about how the data is handled. All end-point * streams will always handle the data that you provide or request without any @@ -59,8 +58,8 @@ * easy as possible to write general code that was as easy as possible to * extend, and as clear as possible. We have accomplished this by making * streams simple, yet flexible, with a clear API and a flexible filter system - * that something geared towards more general formatting, conversion, and - * operator-only access can't touch. + * that something geared towards more general formatting, conversion can't + * touch. * *@section usage Using streams directly * To create a stream depends on the type of stream that you're interested in, diff --git a/src/fbasicstring.h b/src/fbasicstring.h index b9e4871..fbfc5ef 100644 --- a/src/fbasicstring.h +++ b/src/fbasicstring.h @@ -706,6 +706,7 @@ namespace Bu /** * Append another FString to this one. *@param sData (MyType &) The FString to append. + *@param nStart Start position in sData to start copying from. *@param nLen How much data to append. */ void append( const MyType & sData, long nStart, long nLen ) @@ -715,6 +716,11 @@ namespace Bu append( sData.getStr(), nStart, nLen ); } + /** + * Append data to this FString using the passed in iterator as a base. + * The iterator is const, it is not changed. + *@param s Iterator from any compatible FBasicString to copy data from. + */ void append( const const_iterator &s ) { if( !s.isValid() ) @@ -731,11 +737,24 @@ namespace Bu } } + /** + * Append data to this FString using the passed in iterator as a base. + * The iterator is const, it is not changed. + *@param s Iterator from any compatible FBasicString to copy data from. + */ void append( const iterator &s ) // I get complainst without this one { append( const_iterator( s ) ); } + /** + * Append data to this FString using the passed in iterator as a base, + * and copy data until the ending iterator is reached. The character + * at the ending iterator is not copied. + * The iterators are const, they are not changed. + *@param s Iterator from any compatible FBasicString to copy data from. + *@param e Iterator to stop copying at. + */ void append( const const_iterator &s, const const_iterator &e ) { if( !s.isValid() ) @@ -884,10 +903,6 @@ namespace Bu pFirst->nLength -= nLen; } - /** - *@todo void prepend( const chr &cData ) - */ - /** * Clear all data from the string. */ @@ -1079,7 +1094,7 @@ namespace Bu /** * Plus equals operator for FString. - *@param pData (const MyType &) The FString to append to your FString. + *@param rSrc (const MyType &) The FString to append to your FString. */ MyType &operator+=( const MyType &rSrc ) { @@ -1093,7 +1108,7 @@ namespace Bu /** * Plus equals operator for FString. - *@param pData (const chr) The character to append to your FString. + *@param cData (const chr) The character to append to your FString. */ MyType &operator+=( const chr cData ) { @@ -1603,7 +1618,8 @@ namespace Bu /** * Find the index of the first occurrance of cChar - *@param sText (const chr *) The string to search for. + *@param cChar The character to search for. + *@param iStart The position in the string to start searching from. *@returns (long) The index of the first occurrance. -1 for not found. */ long findIdx( const chr cChar, long iStart=0 ) const @@ -1619,8 +1635,9 @@ namespace Bu /** * Find the index of the first occurrance of sText - *@param cChar (const chr) The character to search for. - *@returns (long) The index of the first occurrance. -1 for not found. + *@param sText The null-terminated string to search for. + *@param iStart The position in the string to start searching from. + *@returns The index of the first occurrance. -1 for not found. */ long findIdx( const chr *sText, long iStart=0 ) const { diff --git a/src/hash.h b/src/hash.h index 3868a4e..50a35b8 100644 --- a/src/hash.h +++ b/src/hash.h @@ -17,8 +17,8 @@ #include "bu/exceptionbase.h" #include "bu/list.h" #include "bu/util.h" -///#include "archival.h" -///#include "archive.h" +//#include "archival.h" +//#include "archive.h" #define bitsToBytes( n ) (n/32+(n%32>0 ? 1 : 0)) @@ -37,6 +37,14 @@ namespace Bu template bool __cmpHashKeys( const T &a, const T &b ); + /** + * Default functor used to compute the size of hash tables. This version + * effectively doubles the size of the table when space is low, ensuring + * that you always wind up with an odd number for the table size. A + * better but slower option is to always find the next prime number that's + * above double your current table size, but that has the potential to be + * slower. + */ struct __calcNextTSize_fast { uint32_t operator()( uint32_t nCapacity, uint32_t, uint32_t nDeleted ) const @@ -677,7 +685,7 @@ namespace Bu /** * Get the value behind this iterator. - *@returs (value_type &) The value behind this iterator. + *@returns (value_type &) The value behind this iterator. */ value &getValue() { @@ -804,7 +812,7 @@ namespace Bu /** * Get the value behind this iterator. - *@returs (value_type &) The value behind this iterator. + *@returns (value_type &) The value behind this iterator. */ const value &getValue() const { diff --git a/src/ito.h b/src/ito.h index 9829d28..3539929 100644 --- a/src/ito.h +++ b/src/ito.h @@ -94,7 +94,7 @@ namespace Bu * the function that actually makes up the thread, it simply calls the * run member function in an OO-friendly way. This is what allows us to * use member variables from within the thread itself. - *@param Should always be this. + *@param pThread Should always be this. *@returns This is specified by posix, I'm not sure yet. */ static void *threadRunner( void *pThread ); diff --git a/src/list.h b/src/list.h index c517a9e..934766b 100644 --- a/src/list.h +++ b/src/list.h @@ -611,7 +611,7 @@ namespace Bu /** * Erase an item from the list if you already know the item. - *@param ob The item to find and erase. + *@param v The item to find and erase. */ void erase( const value &v ) { diff --git a/src/set.h b/src/set.h index a25b0bf..aec5781 100644 --- a/src/set.h +++ b/src/set.h @@ -184,9 +184,8 @@ namespace Bu } /** - * Insert a value (v) under key (k) into the hash table + * Insert key (k) into the set *@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 ) { diff --git a/src/tests/console.cpp b/src/tests/console.cpp new file mode 100644 index 0000000..628482b --- /dev/null +++ b/src/tests/console.cpp @@ -0,0 +1,36 @@ +#include +using namespace Bu; + +#include +using namespace std; + +typedef struct Counter +{ + Counter() : i( 0 ) + { + } + + int get() + { + i++; + return i-1; + } + + int i; +} Counter; + +template +void runtest( a &out ) +{ + Counter c; + out << c.get() << ", " << c.get() << ", " << c.get() << ", " << c.get() << ", " << c.get() << "\n"; +} + +int main() +{ + runtest( cout ); + runtest( sio ); + + return 0; +} + diff --git a/src/util.h b/src/util.h index efbfb26..ea107ee 100644 --- a/src/util.h +++ b/src/util.h @@ -19,6 +19,12 @@ namespace Bu { + /** + * Swap the value of two variables, uses references, so it's pretty safe. + * Objects passed in must support a basic assignemnt operator (=); + *@param a Variable to recieve the value of parameter b + *@param b Variable to recieve the value of parameter a + */ template void swap( item &a, item &b ) { @@ -27,36 +33,78 @@ namespace Bu b = tmp; } + /** + * Finds the lesser of the two objects, objects passed in must be + * less-than-comparable. + *@param a A value to test. + *@param b Another value to test. + *@returns A reference to the lesser of a or b. + */ template const item &min( const item &a, const item &b ) { return a item &min( item &a, item &b ) { return a const item &max( const item &a, const item &b ) { - return a>b?a:b; + return b item &max( item &a, item &b ) { - return a>b?a:b; + return b const item &mid( const item &a, const item &b, const item &c ) { return min( max( a, b ), c ); } - + + /** + * Given three objects this finds the one between the other two. + *@param a A value to test. + *@param b Another value to test. + *@param c Yet another value to test. + *@returns A reference to the mid-value of a, b, and c. + */ template item &mid( item &a, item &b, item &c ) { @@ -66,6 +114,10 @@ namespace Bu // // Basic comparison functors // + /** + * Simple less-than comparison functor. Objects being used should be + * less-than-comparable. + */ template struct __basicLTCmp { @@ -75,6 +127,10 @@ namespace Bu } }; + /** + * Simple greater-than comparison functor. Objects being used should be + * greater-than-comparable. + */ template struct __basicGTCmp { @@ -84,6 +140,9 @@ namespace Bu } }; + /** + * As __basicLTCmp but dereferences the passed in pointers before comparing. + */ template struct __basicPtrLTCmp { @@ -93,6 +152,9 @@ namespace Bu } }; + /** + * As __basicGTCmp but dereferences the passed in pointers before comparing. + */ template struct __basicPtrGTCmp { -- cgit v1.2.3