diff --git a/docs/user/book.dox b/docs/user/book.dox index 1e77ea8244..929567f195 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -15,3 +15,10 @@ \defgroup libbe (libbe.so) \defgroup libroot (libroot.so) */ + +// Subgroups + +/*! +\defgroup support_globals Global functions in the support kit +\ingroup support +*/ \ No newline at end of file diff --git a/docs/user/midi/midi1intro.dox b/docs/user/midi/midi1intro.dox index 1719629ffb..b2354206ae 100644 --- a/docs/user/midi/midi1intro.dox +++ b/docs/user/midi/midi1intro.dox @@ -35,14 +35,14 @@ To make MIDI data stream through your application, you create a "network" of BMidi-derived objects that send and receive MIDI messages. The old Midi Kit is slowly fading into obscurity. You may want to use the -\ref midi2 "new kit" instead. Also note that the OpenBeOS implementation +\ref midi2 "new kit" instead. Also note that the Haiku implementation of the kit sometimes behaves differently than the one from BeOS R5 or what -the BeBook says, but usually for the better ;-) +the BeBook says, but usually for the better. Especially the synth classes are not completely functional, but enough to play back General MIDI tunes. They should be backwards compatible with the majority of BeOS MIDI applications. Not all methods of BSynth, BMidiSynth, and BMidiSynthFile are implemented because some of them are rather obscure. -BSamples is a complete no-op; in other words, with the OpenBeOS Midi Kit +BSamples is a complete no-op; in other words, with the Haiku Midi Kit you cannot push waveform data into the output stream of the softsynth. */ diff --git a/docs/user/support/Autolock.dox b/docs/user/support/Autolock.dox new file mode 100644 index 0000000000..b93d7b2344 --- /dev/null +++ b/docs/user/support/Autolock.dox @@ -0,0 +1,103 @@ +/*! +\file Autolock.h +\brief Implements a handy locking utility. +*/ + +/*! +\class BAutolock +\ingroup support +\ingroup libbe +\brief Convenient utility to make parts of your code thread-safe easily. + +The autolocker uses a BLooper or a BLocker in order to protect a part +of your code. This class is usually used in combination with a BLocker +that protects a certain part of your code and data that are being +accessed by multiple threads. While BAutolock does not add any features +to locking, it provides a mechanism to easily lock and protect a part of your +code. + +Normally, when you need to protect data, you would have to make sure that +all your locks are paired with unlocks. Below is a simple example, but you +can imagine that there are more complex situations where you might spend a +lot of time debugging a hang because you didn't pair all the Lock()s with an +Unlock(). See the example: + +\code +status_t +Receiver::HandleCall(Call *call) +{ + ... work on call data ... + + fDataLocker->Lock() + + ... perform changes ... + + if (!success) + { + fDataLocker->Unlock(); + return B_ERROR; + } + + fDataLocker->Unlock() + return B_OK; +} +\endcode + +With the BAutolock this example can be rewritten as follows: +\code +status_t +Receiver::HandleCall(Call *call) +{ + ... work on call data ... + + BAutolock autolock(fDataLocker); + + ... perform changes ... + + if (!success) + return B_ERROR; + + return B_OK; +} +\endcode + +Since the object is created on stack, it is destroyed as soon as we leave +the function. Because the destruction of the object causes it to unlock +the BLocker or BLooper, you don't have to manually make sure that every +exit from the function is properly written. +*/ + +/*! +\fn BAutolock::BAutolock(BLooper *looper) +\brief Create an object and lock the BLooper +*/ + +/*! +\fn BAutolock::BAutolock(BLocker *locker) +\brief Create an object and lock the BLocker +*/ + +/*! +\fn BAutolock::BAutolock(BLocker &locker) +\brief Create an object and lock the BLocker +*/ + +/*! +\fn BAutolock::~BAutolock() +\brief Destroy the object and unlock the associated BLocker or BLooper +*/ + +/*! +\fn bool BAutolock::IsLocked(void) +\brief Verify whether the associated BLocker or BLooper are actually locked. + +Basically you may assume that when the object is created, you are +almost always sure the actual locking succeeds. It might fail if the +BLocker or BLooper are destroyed though. The semaphore will be +released and the Lock() call will fail. + +If you might get this behaviour, you can use this method to help you +protect yourself from it. +\retval true The lock was acquired. +\retval false Failed to acquire the lock. +*/ diff --git a/docs/user/support/BlockCache.dox b/docs/user/support/BlockCache.dox new file mode 100644 index 0000000000..13561aa61a --- /dev/null +++ b/docs/user/support/BlockCache.dox @@ -0,0 +1,108 @@ +/*! +\file BlockCache.h +\brief Implements a mechanism to store and retrieve memory blocks +*/ + +/*! +\var B_OBJECT_CACHE +\brief Used in the constructor of BBlockCache. Determines that objects will + be created using \c new[] and \c delete[]. +*/ + +/*! +\var B_MALLOC_CACHE +\brief Used in the constructor of BBlockCache. Determines that objects will + be created using \c malloc() and \c free(). +*/ + +/*! +\class BBlockCache +\ingroup support +\ingroup libbe +\brief A class that creates and maintains a pool of memory blocks. + +In some performance critical code there might come a time where you +require a lot of little blocks of memory that you want to access and +dispose of continuously. Since allocating and freeing memory are an +'expensive' operation, it's better to have a pool of memory blocks at +your disposal. Luckily, the Haiku API provides a class that will act +as the administrator of your memory pool, so you won't have to reinvent +the wheel. + +The principle is easy. The constructor takes the number of blocks you +want to create beforehand, the size of the blocks and the method of +allocation. This can either be #B_OBJECT_CACHE or #B_MALLOC_CACHE. +The first uses C++ operators \c new[] and \c delete[], the second uses +\c malloc() and \c free(). Unless you have specific demands on performance +or you want to take care of freeing the objects yourself, either use is fine. + +As soon as you have the memory pool, you can Get() blocks. If the +pre-allocated memory blocks run out, BBlockCache will allocate +new ones, so you won't have to worry about availability. As soon as +you're done, you can Save() the memory back into the pool, though +BBlockCache will make sure that there won't be more blocks saved +than the initial number you said when you created the object. + +As soon as you got a pointer from the Get() method, you own that +block of memory. This means that you have the liberty to dispose +of it yourself. It also means that when you delete your BBlockCache +instance, any blocks of memory that are checked out won't be destroyed. +In case you might want to delete your objects yourself, make sure you +use the proper way. If you created the object as #B_OBJECT_CACHE +use \c delete[] to free your object. If you created the object +as #B_MALLOC_CACHE, use \c free(). Please note that it defeats +the purpose of this class if your are going to free all the objects yourself, +since it basically means that when the pool runs out, Get() will be allocating +the objects itself. + +\note BBlockCache is thread-safe. +*/ + +/*! +\fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32 allocationType) +\brief Allocate a new memory pool. + +\param blockCount The number of free memory blocks you want to initially allocate. + This number is also used as a maximum number of free blocks that will be kept. +\param blockSize The size of the blocks. +\param allocationType Either #B_OBJECT_CACHE for using \c new[] and \c delete[] + or #B_MALLOC_CACHE for \c malloc() and \c free(). +*/ + +/*! +\fn BBlockCache::~BBlockCache() +\brief Destroy the empty blocks in the free list. + +Note that the blocks you checked out with Get() and not checked back in with +Save() will not be freed, since ownership belongs to you. Make sure you clean up +after yourself. +*/ + +/*! +\fn void *BBlockCache::Get(size_t blockSize) +\brief Get a block from the pool of free blocks. + +If the pool runs out of free blocks, a new one will be allocated. Please note that +if the size given in the \c blockSize parameter is different from the size given +in the constructor, that a new block of memory will be created. Only sizes that +match the blocks in the memory pool will come from the pool. + +\param blockSize The required size of the memory block. +\return Returns a pointer to a memory block, or \c NULL if locking the object +failed. +*/ + +/*! +\fn void BBlockCache::Save(void *pointer, size_t blockSize) +\brief Save a block of memory to the memory pool. + +The block of memory will only be added to the pool if the \c blockSize is equal +to the size the object was created with, and if the maximum number free blocks +in the list won't be passed. Else the memory will be freeed. + +Note that it is perfectly valid to pass objects other than you got from Get(), but +please note that the way it was created confirms with the way memory is allocated +and freed in this pool. Thus, only feed blocks that were created with \c new[] if +the allocation type is #B_OBJECT_CACHE, likewise use only objects allocated +with \c malloc() when the allocation type is #B_MALLOC_CACHE. +*/ diff --git a/docs/user/support/List.dox b/docs/user/support/List.dox new file mode 100644 index 0000000000..0d3402ff67 --- /dev/null +++ b/docs/user/support/List.dox @@ -0,0 +1,352 @@ +// Documentation by: +// Niels Sascha Reedijk +// Corresponds to: +// /trunk/headers/os/support/List.h rev 19972 +// /trunk/src/kits/support/List.cpp rev 18649 + +/*! +\file List.h +\brief Implements a list implementation. +*/ + +/*! +\class BList +\ingroup support +\ingroup libbe +\brief An ordered container that is designed to hold generic \c void * objects. + +This class is designed to be used for a variety of tasks. Unlike similar +implementations in other libraries, this class is not based on templates, +and as such is inherently not typed. So it will be the job of the coder to +make sure proper data will be entered, since the compiler cannot check this. + +BList contains a list of items that will grow and shrink depending on +how much items are in it. So you will not have to do any of the +memory management. Furthermore, it's ordered. Those properties make it +useful in a whole range of situations, for example in the interface kit in +the BListView class. + +A note on ownership of the objects might come in handy. BList at no time +assumes ownership of the objects, so removing items from the list will +only remove those items from the list, it will not delete the item. In the +same spirit you should also make sure that before you might delete an +object that's in a list, you will remove it from the list first. + +\warning This class is not thread-safe. + +The class implements methods to add and remove items, reorder items, +retrieve items, querying for items and some advanced methods which let +you perform a certain tasks to all the items of the list. +*/ + +/*! +\fn BList::BList(int32 count = 20) +\brief Create a new list with a number of empty slots. + +The memory management of this class allocates new memory per block. The +\c count parameter can be tweaked to determine the size of those blocks. +In general, if you know your list is only going to contain a fixed maximum +number of items, pass that value. If you expect your list to have very few items, +it's probably safe to choose a low number. This is as to prevent the list from +taking up unneccesary memory. If you expect the list to contain a large +number of items, choose a higher value, since every time the memory is full, all +the items have to be copied into a new piece of allocated memory which is +an expensive operation. + +If you are unsure, you don't have to break your head over this. As long as you +don't use a lot of lists or as long as the list isn't used in one of the +performance critical parts of the code, you are safe to go with the default +value. + +\param count The size of the blocks of memory allocated. +*/ + +/*! +\fn BList::BList(const BList& anotherList) +\brief Copy constructor, copies a complete list into this one. +*/ + +/*! +\fn BList::~BList() +\brief Destroy the list. + +Please note that as BList does not assume ownership of the objects, +only the list will be freed, not the objects that are held in it. +*/ + +/*! +\fn BList& BList::operator=(const BList &list) +\brief Copy another list into this object. +*/ + +/*! +\name Adding and removing items +*/ + +//! @{ + +/*! +\fn bool BList::AddItem(void *item, int32 index) +\brief Add an item at a certain position. + +\param item The item to add. +\param index The place in the list. +\retval true The item was added. +\retval false Item was not added. Either the index was negative or invalid, + or resizing the list failed. +\sa AddItem(void *item) +*/ + +/*! +\fn bool BList::AddItem(void *item) +\brief Append an item to the list. + +\param item The item to add. +\retval true The item was appended. +\retval true The item was added. +\retval false Item was not appended, since resizing the list failed. +\sa AddItem(void *item, int32 index) +*/ + +/*! +\fn bool BList::AddList(const BList *list, int32 index) +\brief Add items from another list to this list at a certain position. + +Note that the \c list parameter is \c const, so the original list will not be altered. + +\param list The list to be added. +\param index The position in the current list where the new item(s) should be put. +\retval true The list was added. +\retval false Failed to insert the list, due to the fact that resizing our list failed. +\sa AddList(const BList *list) +*/ + +/*! +\fn bool BList::AddList(const BList *list) +\brief Append a list to this list. + +Note that the \c list parameter is \c const, so the original list will not be altered. + +\param list The list to be appended. +\retval true The list was appended. +\retval false Failed to append the list, due to the fact that resizing our list failed. +\sa AddList(const BList *list, int32 index) +*/ + +/*! +\fn bool BList::RemoveItem(void *item) +\brief Remove an item from the list. + +\param item The item that should be removed. +\retval true The item was found and removed. +\retval false The item was not in this list and thus not removed. +\sa RemoveItem(int32 index) +*/ + +/*! +\fn void * BList::RemoveItem(int32 index) +\brief Remove the item at \c index from the list. + +\param index The item that should be removed. +\return The pointer to the item that was removed, or \c NULL in case the + index was invalid. +\sa RemoveItem(void *item) +*/ + +/*! +\fn bool BList::RemoveItems(int32 index, int32 count) +\brief Remove a number of items starting at a certain position. + +If the count parameter is larger than the number of items in the list, +all the items from the offset to the end will be removed. + +\param index The offset in the list where removal should start. +\param count The number of items to remove. +\retval true Removal succeeded. +\retval false Failed to remove the items because the index was invalid. +*/ + +/*! +\fn bool BList::ReplaceItem(int32 index, void *newItem) +\brief Replace a item with another one. + +\param index The offset in the list where to put the item. +\param newItem The new item to put in the list. +\retval true Item replaced. +\retval false The index was invalid. +*/ + +/*! +\fn void BList::MakeEmpty() +\brief Clear all the items from the list. + +Please note that this does not free the items. +*/ + +//! @} + +/*! +\name Reordering items +*/ + +//! @{ + +/*! +\fn void BList::SortItems(int (*compareFunc)(const void *, const void *)) +\brief Sort the items with the use of a supplied comparison function. + +The function should take two \c const pointers as arguments and should return an +integer. + +For an example, see the Compare(const BString *, const BString *) function. +*/ + +/*! +\fn bool BList::SwapItems(int32 indexA, int32 indexB) +\brief Swap two items. + +\param indexA The first item. +\param indexB The second item. +\retval true Swap succeeded. +\retval false Swap failed because one of the indexes were invalid. +*/ + +/*! +\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex) +\brief Move an item to a new place + +This moves a list item from posititon a to position b, moving the appropriate +block of list elements to make up for the move. For example, in the array: +\verbatim +A B C D E F G H I J +\endverbatim +Moveing 1(B)->6(G) would result in this: +\verbatim +A C D E F G B H I J +\endverbatim + +\param fromIndex The original location. +\param toIndex The new location. +\retval true Move succeeded. +\retval false Move failed since the indexes were invalid. +*/ + +//! @} + +/*! +\name Retrieving items +*/ + +//! @{ + +/*! +\fn void *BList::ItemAt(int32 index) const +\brief Get an item. + +\param index The item to retrieve. +\return A pointer to the item in that position, or \c NULL if the index is out of bounds. +\sa ItemAtFast(int32 index) const +*/ + +/*! +\fn void *BList::FirstItem() const +\brief Get the first item. +\return A pointer to the first item, or \c NULL if the list is empty. +*/ + +/*! +\fn void *BList::ItemAtFast(int32 index) const +\brief Get an item. + +This method does not performs any boundary checks when it retrieves an item. +Use this method in a performance critical area of your program where you are +sure you won't get an invalid item. + +\return A pointer to the item. +*/ + +/*! +\fn void *BList::LastItem() const +\brief Get the last item. +\return A pointer to the last item, or \c NULL if the list is empty. +*/ + +/*! +\fn void *BList::Items() const +\brief Return the internal list of objects. + +This method will return a pointer to the internal pointer list. This means you should be careful +what you are doing, since you are directly working with the internals of the class. + +It is definately not a good idea to make any changes to the list, since it will mess up +the internal consistency. + +\warning If there is anything you want for which you need the list of objects, please + realize that that probably means that what you want to do is a bad idea to begin with. + Avoid this method. The list of objects doesn't belong to you. Check if DoForEach() can + help you. +\return The internal list of pointers. +*/ + +//! @} + +/*! +\name Querying for items +*/ + +//! @{ + +/*! +\fn bool BList::HasItem(void *item) const +\brief Check if an item is in the list. +*/ + +/*! +\fn int32 BList::IndexOf(void *item) const +\brief Get the index of an item. + +\return The index of the item, or -1 when the item is not in the list. +*/ + +/*! +\fn int32 BList::CountItems() const +\brief Get the number of items in the list. +*/ + +/*! +\fn bool BList::IsEmpty() const +\brief Check if there are items in the list. +*/ + +//! @} + +/*! +\name Iterating over the list +*/ + +//! @{ + +/*! +\fn void BList::DoForEach(bool (*func)(void* item)) +\brief Perform an action on every item in the list. + +If one of the actions on the items fails, meaning that the \c func function +returned \c false, then the processing of the list will be stopped. + +\param func A function that takes a \c void * argument and returns a boolean. +*/ + +/*! +\fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2) +\brief Perform an action on every item in the list with an argument. + +If one of the actions on the items fails, meaning that the \c func function +returned \c false, then the processing of the list will be stopped. + +\param func A function with the first \c void * argument being the item, + and the second \c void * being the argument that you supply. It should + return a boolean value on whether it succeeded or not. +\param arg2 An argument to supply to \c func. +*/ + +//! @} diff --git a/docs/user/support/parsedate.dox b/docs/user/support/parsedate.dox index 7d8151a86b..44a501bba8 100644 --- a/docs/user/support/parsedate.dox +++ b/docs/user/support/parsedate.dox @@ -2,7 +2,7 @@ \file parsedate.h \ingroup support \ingroup libroot -\brief date parsing functions +\brief Date parsing functions This is a set a functions for parsing date strings in various formats. It's mostly tailored for parsing user given data, although originally, diff --git a/docs/user/support/stopwatch.dox b/docs/user/support/stopwatch.dox index 39efb3b6d1..05b40e464f 100644 --- a/docs/user/support/stopwatch.dox +++ b/docs/user/support/stopwatch.dox @@ -1,7 +1,5 @@ /*! \file StopWatch.h -\ingroup support -\ingroup libbe \brief Provides the BStopWatch class. */ diff --git a/docs/user/support/string.dox b/docs/user/support/string.dox index 96fe84d05f..f1b5bf455b 100644 --- a/docs/user/support/string.dox +++ b/docs/user/support/string.dox @@ -1,8 +1,12 @@ +// Documentation by: +// Niels Sascha Reedijk +// Corresponds to: +// /trunk/headers/os/support/String.h rev 19731 +// /trunk/src/kits/support/String.cpp rev 19731 + /*! \file String.h -\ingroup libbe -\ingroup support -\brief Implements the BString class. +\brief Implements the BString class and global operators and functions for handling strings. */ /*! @@ -21,30 +25,33 @@ takes care to allocate and free memory for you, so it will always be */ /*! -\var char* BString::_privateData +\var char* BString::fPrivateData \brief BString's storage for data + +If you are planning to derive from this object and you want to manipulate the raw +string data, please have a look at LockBuffer() and UnlockBuffer(). */ /*! \fn BString::BString() -\brief Creates an uninitialized BString. +\brief Create an uninitialized BString. */ /*! \fn BString::BString(const char* str) -\brief Creates a BString and initializes it to the given string. +\brief Create a BString and initializes it to the given string. \param str Pointer to a NULL terminated string. */ /*! \fn BString::BString(const BString &string) -\brief Creates a BString and makes it a copy of the supplied one. +\brief Create a BString and makes it a copy of the supplied one. \param string the BString object to be copied. */ /*! \fn BString::BString(const char *str, int32 maxLength) -\brief Creates a BString and initializes it to the given string. +\brief Create a BString and initializes it to the given string. \param str Pointer to a NULL terminated string. \param maxLength The amount of characters you want to copy from the original string. @@ -52,9 +59,9 @@ string. /*! \fn BString::~BString() -\brief Frees all resources associated with the object. +\brief Free all resources associated with the object. -Frees the memory allocated by the BString object. +The destructor frees the internal buffer associated with the string. */ @@ -66,27 +73,35 @@ Frees the memory allocated by the BString object. /*! \fn const char* BString::String() const -\brief Returns a pointer to the object string, NULL terminated. - -Returns a pointer to the object string, guaranteed to be NULL +\brief Return a pointer to the object string, NULL terminated. + +The pointer to the object string is guaranteed to be NULL terminated. You can't modify or free the pointer. Once the BString object is deleted, the pointer becomes invalid. + +If you want to manipulate the internal C-string of the object directly, have +a look at LockBuffer(). \return A pointer to the object string. */ /*! \fn int32 BString::Length() const -\brief Returns the length of the string, measured in bytes. -\return The length of the string, measured in bytes. +\brief Get the length of the string in bytes. + +\return An integer with the length of the string, measured in bytes. +\sa CountChars() */ /*! \fn int32 BString::CountChars() const \brief Returns the length of the object measured in characters. -Counts the number of UTF8 characters contained in the string. +BString is somewhat aware of UTF8 characters, so this method will count +the actual number of characters in the string. + \return An integer which is the number of characters in the string. +\sa Length() */ //! @} @@ -94,79 +109,121 @@ Counts the number of UTF8 characters contained in the string. /*! \name Assignment Methods + +To assign a string to the object, thus overriding the previous string +that was stored, there are different methods to use. Use one of the +overloaded Adopt() methods to take over data from another object. Use +one of the assignment operators to copy data from another object, or +use one of the SetTo() methods for more advanced copying. */ //! @{ /*! \fn BString& BString::operator=(const BString &string) -\brief Makes a copy of the given BString object. +\brief Re-initialize the object to a copy of the data of a BString. \param string The string object to copy. \return The function always returns \c *this . +\sa Adopt(BString &from) +\sa SetTo(const BString &string, int32 length) */ /*! \fn BString& BString::operator=(const char *str) -\brief Re-initializes the object to the given string. -\param str Pointer to a string. +\brief Re-initialize the object to a copy of the data of a C-string. +\param str Pointer to a C-string. \return The function always returns \c *this . +\sa SetTo(const char *str, int32 maxLength) */ /*! \fn BString& BString::operator=(char c) -\brief Re-initializes the object to the given character. +\brief Re-initialize the object to a character. \param c The character which you want to initialize the string to. \return The function always returns \c *this . */ /*! \fn BString& BString::SetTo(const char *str, int32 maxLength) -\brief Re-initializes the object to the given string. +\brief Re-initialize the object to a copy of the data of a C-string. \param str Pointer to a string. \param maxLength Amount of characters to copy from the original string. \return The function always returns \c *this . +\sa operator=(const char *str) */ /*! \fn BString& BString::SetTo(const BString &from) -\brief Makes a copy of the given BString object. +\brief Re-initialize the object to a copy of the data of a BString. \param from The string object to copy. \return The function always returns \c *this . +\sa SetTo(const BString &string, int32 length) +\sa Adopt(BString &from) +*/ + +/*! +\fn BString& BString::SetTo(const char *str) +\brief Re-initialize the object to a copy of the data of a C-string. + +This method calls operator=(const char *str). + +\param str Pointer to a C-string. +\return The function always returns \c *this . +\sa SetTo(const char *str, int32 maxLength) */ /*! \fn BString& BString::Adopt(BString &from) -\brief Adopt's data of the given BString object, freeing the original object. +\brief Adopt the data of the given BString object. + +This method adopts the data. Please note that the object that is adopted +from is not deleted, only its private data is initialized to a null +string. So if the from object was created on the heap, you need to +clean it up yourself. + \param from The string object to adopt. \return The function always returns \c *this . +\sa operator=(const BString &string) +\sa SetTo(const BString &string, int32 length) */ /*! \fn BString& BString::SetTo(const BString &string, int32 length) -\brief Makes a copy of the given BString object. +\brief Re-initialize the string to a copy of the given BString object. \param string The string object to copy. \param length Amount of characters to copy from the original BString. \return The function always returns \c *this . +\sa operator=(const BString &string) +\sa Adopt(BString &from, int32 length) */ /*! \fn BString& BString::Adopt(BString &from, int32 length) -\brief Adopt's data of the given BString object, freeing the original object. +\brief Adopt the data of the given BString object. + +This method adopts the data. Please note that the object that is adopted +from is not deleted, only its private data is initialized to a null +string. So if the from object was created on the heap, you need to +clean it up yourself. + \param from The string object to adopt. \param length Amount of characters to get from the original BString. \return The function always returns \c *this . +\sa operator=(const BString &string) +\sa SetTo(const BString &string, int32 length) */ /*! \fn BString& BString::SetTo(char c, int32 count) -\brief Initializes the object to a string composed by a character you specify. -\param c The character you want to initialize the BString. -\param count The number of characters you want the BString to be composed by. -\return The function always returns \c *this . -*/ +\brief Re-initialize the object to a string composed of a character you specify. -/*! -\fn BString &BString::SetTo(const char *str) +This method lets you specify the length of a string and what character you want the +string to contain repeatedly. + +\param c The character you want to initialize the BString. +\param count The length of the string. +\return The function always returns \c *this . +\sa operator=(char c) */ //! @} @@ -180,18 +237,30 @@ Counts the number of UTF8 characters contained in the string. /*! \fn BString &BString::CopyInto(BString &into, int32 fromOffset, int32 length) const -\brief Copy the BString data (or part of it) into another BString. -\param into The BString where to copy the object. -\param fromOffset The offset (zero based) where to begin the copy +\brief Copy the object's data (or part of it) into another BString. + +This methods makes sure you don't copy more bytes than are available in the string. If +the length exceeds the length of the string, it only copies the number of characters that +are actually available. + +\param into The BString to where to copy the object. +\param fromOffset The zero-based offset where to begin the copy. \param length The amount of bytes to copy. -\return This function always returns *this . +\return This method always returns a pointer to the string passed as the \c into parameter. */ /*! \fn void BString::CopyInto(char *into, int32 fromOffset, int32 length) const \brief Copy the BString data (or part of it) into the supplied buffer. + +This methods makes sure you don't copy more bytes than are available in the string. If +the length exceeds the length of the string, it only copies the number of characters that +are actually available. + +It's up to you to make sure your buffer is large enough. + \param into The buffer where to copy the object. -\param fromOffset The offset (zero based) where to begin the copy +\param fromOffset The zero-based offset where to begin the copy. \param length The amount of bytes to copy. */ @@ -205,52 +274,69 @@ Counts the number of UTF8 characters contained in the string. /*! \fn BString& BString::operator+=(const char *str) -\brief Appends the given string to the object. -\param str A pointer to the string to append. -\return This function always returns *this . +\brief Append the given string to the object. +\param str A pointer to the NULL-terminated C-string to append. +\return This method always returns \c *this . +\sa Append(const char *str, int32 length) */ /*! \fn BString& BString::operator+=(char c) -\brief Appends the given character to the object. +\brief Append the given character to the object. \param c The character to append. -\return This function always returns *this . +\return This method always returns \c *this . +\sa Append(char c, int32 count) */ /*! \fn BString & BString::operator+=(const BString &string) +\brief Append the given string to the object +\param string The string to append +\return This method always returns \c *this . +\sa Append(const BString &string, int32 length) */ /*! \fn BString &BString::Append(const BString &string) +\brief Append the given string to the object +\param string The string to append +\return This method always returns \c *this . +\sa Append(const BString &string, int32 length) */ /*! \fn BString &BString::Append(const char *str) +\brief Append the given string to the object. + +This method calls operator+=(const char *str). +\sa Append(const char *str, int32 length) */ /*! \fn BString& BString::Append(const BString &string, int32 length) -\brief Appends the given BString to the object. +\brief Append a part of the given BString to the object. \param string The BString to append. -\param length The maximum bytes to get from the original object. -\return This function always returns *this . +\param length The maximum number ofbytes to get from the original object. +\return This method always returns \c *this . +\sa operator+=(const BString &string) */ /*! \fn BString& BString::Append(const char *str, int32 length) -\brief Appends the given string to the object. +\brief Append a part of the given string to the object. \param str A pointer to the string to append. \param length The maximum bytes to get from the original string. -\return This function always returns *this . +\return This method always returns \c *this . +\sa operator+=(const char *str) */ /*! \fn BString& BString::Append(char c, int32 count) -\brief Appends the given character to the object. +\brief Append the given character repeatedly to the object. \param c The character to append. -\param count The number of characters to append. -\return This function always returns *this . +\param count The number of times this character should be appended. +\return This method always returns \c *this . +\sa operator+=(char c) */ //! @} @@ -264,40 +350,44 @@ Counts the number of UTF8 characters contained in the string. /*! \fn BString& BString::Prepend(const char *str) -\brief Prepends the given string to the object. +\brief Prepend the given string to the object. \param str A pointer to the string to prepend. -\return This function always returns *this . +\return This method always returns \c *this . +\sa Prepend(const char *str, int32 length) */ /*! \fn BString& BString::Prepend(const BString &string) -\brief Prepends the given BString to the object. +\brief Prepend the given BString to the object. \param string The BString object to prepend. -\return This function always returns *this . +\return This method always returns \c *this . +\sa Prepend(const BString &string, int32 len) */ /*! \fn BString& BString::Prepend(const char *str, int32 length) -\brief Prepends the given string to the object. +\brief Prepend the given string to the object. \param str A pointer to the string to prepend. \param length The maximum amount of bytes to get from the string. -\return This function always returns *this . +\return This method always returns \c *this . +\sa Prepend(const char *str) */ /*! \fn BString& BString::Prepend(const BString &string, int32 len) -\brief Prepends the given BString to the object. +\brief Prepend the given BString to the object. \param string The BString object to prepend. \param len The maximum amount of bytes to get from the BString. -\return This function always returns *this . +\return This method always returns \c *this . +\sa Prepend(const BString &string) */ /*! \fn BString& BString::Prepend(char c, int32 count) -\brief Prepends the given character to the object. +\brief Prepend the given character repeatedly to the object. \param c The character to prepend. -\param count The amount of characters to prepend. -\return This function always returns *this . +\param count The number of times this character should be prepended. +\return This method always returns \c *this . */ //! @} @@ -311,10 +401,12 @@ Counts the number of UTF8 characters contained in the string. /*! \fn BString& BString::Insert(const char *str, int32 pos) -\brief Inserts the given string at the given position into the object's data. +\brief Insert the given string at the given position into the object's data. \param str A pointer to the string to insert. -\param pos The offset into the BString's data where to insert the string. -\return This function always returns *this . +\param pos The offset in bytes into the BString's data where to insert the string. +\return This method always returns \c *this . +\sa Insert(const char *str, int32 length, int32 pos) +\sa Insert(const char *str, int32 fromOffset, int32 length, int32 pos) */ /*! @@ -322,54 +414,64 @@ Counts the number of UTF8 characters contained in the string. \brief Inserts the given string at the given position into the object's data. \param str A pointer to the string to insert. \param length The amount of bytes to insert. -\param pos The offset into the BString's data where to insert the string. -\return This function always returns *this . +\param pos The offset in bytes into the BString's data where to insert the string. +\return This method always returns \c *this . +\sa Insert(const char *str, int32 pos) +\sa Insert(const char *str, int32 fromOffset, int32 length, int32 pos) */ /*! \fn BString& BString::Insert(const char *str, int32 fromOffset, int32 length, int32 pos) -\brief Inserts the given string at the given position into the object's data. +\brief Insert the given string at the given position into the object's data. \param str A pointer to the string to insert. -\param fromOffset +\param fromOffset The offset in the string that is to be inserted \param length The amount of bytes to insert. -\param pos The offset into the BString's data where to insert the string. -\return This function always returns *this . +\param pos The offset in bytes into the BString's data where to insert the string. +\return This method always returns \c *this . +\sa Insert(const char *str, int32 pos) +\sa Insert(const char *str, int32 length, int32 pos) */ /*! \fn BString& BString::Insert(const BString &string, int32 pos) -\brief Inserts the given BString at the given position into the object's data. +\brief Insert the given BString at the given position into the object's data. \param string The BString object to insert. -\param pos The offset into the BString's data where to insert the string. -\return This function always returns *this . +\param pos The offset in bytes into the BString's data where to insert the string. +\return This method always returns \c *this . +\sa Insert(const BString &string, int32 length, int32 pos) +\sa Insert(const BString &string, int32 fromOffset, int32 length, int32 pos) */ /*! \fn BString& BString::Insert(const BString &string, int32 length, int32 pos) -\brief Inserts the given BString at the given position into the object's data. +\brief Insert the given BString at the given position into the object's data. \param string The BString object to insert. \param length The amount of bytes to insert. -\param pos The offset into the BString's data where to insert the string. -\return This function always returns *this . +\param pos The offset in bytes into the BString's data where to insert the string. +\return This method always returns \c *this . +\sa Insert(const BString &string, int32 pos) +\sa Insert(const BString &string, int32 fromOffset, int32 length, int32 pos) */ /*! \fn BString& BString::Insert(const BString &string, int32 fromOffset, int32 length, int32 pos) -\brief Inserts the given string at the given position into the object's data. +\brief Insert the given string at the given position into the object's data. \param string The BString object to insert. -\param fromOffset +\param fromOffset The offset in the string that is to be inserted \param length The amount of bytes to insert. -\param pos The offset into the BString's data where to insert the string. -\return This function always returns *this . +\param pos The offset in bytes into the BString's data where to insert the string. +\return This method always returns \c *this . +\sa Insert(const BString &string, int32 pos) +\sa Insert(const BString &string, int32 length, int32 pos) */ /*! \fn BString& BString::Insert(char c, int32 count, int32 pos) -\brief Inserts the given character at the given position into the object's data. +\brief Insert the given character repeatedly at the given position into the object's data. \param c The character to insert. -\param count The amount of bytes to insert. -\param pos The offset into the BString's data where to insert the string. -\return This function always returns *this . +\param count The number of times to insert the character. +\param pos The offset in bytes into the BString's data where to insert the string. +\return This method always returns \c *this . */ //! @} @@ -386,64 +488,64 @@ Counts the number of UTF8 characters contained in the string. \brief Truncate the string to the new length. \param newLength The new lenght of the string. \param lazy If true, the memory-optimisation is postponed to later -\return This function always returns *this . +\return This method always returns \c *this . */ /*! \fn BString& BString::Remove(int32 from, int32 length) -\brief Removes some bytes, starting at the given offset +\brief Remove some bytes, starting at the given offset \param from The offset from which you want to start removing \param length The number of bytes to remove -\return This function always returns *this . +\return This function always returns \c *this . */ /*! \fn BString& BString::RemoveFirst(const BString &string) -\brief Removes the first occurrence of the given BString. +\brief Remove the first occurrence of the given BString. \param string The BString to remove. -\return This function always returns *this . +\return This function always returns \c *this . */ /*! \fn BString& BString::RemoveLast(const BString &string) -\brief Removes the last occurrence of the given BString. +\brief Remove the last occurrence of the given BString. \param string The BString to remove. -\return This function always returns *this . +\return This function always returns \c *this . */ /*! \fn BString& BString::RemoveAll(const BString &string) -\brief Removes all occurrences of the given BString. +\brief Remove all occurrences of the given BString. \param string The BString to remove. -\return This function always returns *this . +\return This function always returns \c *this . */ /*! \fn BString& BString::RemoveFirst(const char *string) -\brief Removes the first occurrence of the given string. +\brief Remove the first occurrence of the given string. \param string A pointer to the string to remove. -\return This function always returns *this . +\return This function always returns \c *this . */ /*! \fn BString& BString::RemoveLast(const char *string) -\brief Removes the last occurrence of the given string. +\brief Remove the last occurrence of the given string. \param string A pointer to the string to remove. -\return This function always returns *this . +\return This function always returns \c *this . */ /*! \fn BString& BString::RemoveAll(const char *str) -\brief Removes all occurrences of the given string. +\brief Remove all occurrences of the given string. \param str A pointer to the string to remove. -\return This function always returns *this . +\return This function always returns \c *this . */ /*! \fn BString& BString::RemoveSet(const char *setOfCharsToRemove) -\brief Removes all the characters specified. +\brief Remove all the characters specified. \param setOfCharsToRemove The set of characters to remove. -\return This function always returns *this . +\return This function always returns \c *this . */ /*! @@ -452,7 +554,7 @@ Counts the number of UTF8 characters contained in the string. \param into The BString where to move the object. \param from The offset (zero based) where to begin the move \param length The amount of bytes to move. -\return This function always returns into. +\return This method always returns \c into . */ /*! @@ -468,88 +570,142 @@ Counts the number of UTF8 characters contained in the string. /*! \name Comparison Methods + +There are two different comparison methods. First of all there +is the whole range of operators that return a boolean value, secondly +there are methods that return an integer value, both case sensitive +and case insensitive. + +There are also global comparison operators and global compare functions. +You might need these in case you have a sort routine that takes a generic +comparison function, such as BList::SortItems(). +See the String.h documentation file to see the specifics, though basically +there are the same as implemented in this class. */ //! @{ /*! \fn bool BString::operator<(const char *string) const +\brief Lexographically compare if this string is less than a given string. */ /*! \fn bool BString::operator<(const BString &string) const +\brief Lexographically compare if this string is less than a given string. */ /*! \fn bool BString::operator<=(const char *string) const +\brief Lexographically compare if this string is less than or equal to a given string. */ /*! \fn bool BString::operator<=(const BString &string) const +\brief Lexographically compare if this string is less than or equal to a given string. */ /*! \fn bool BString::operator==(const char *string) const +\brief Lexographically compare if this string is equal to a given string. */ /*! \fn bool BString::operator==(const BString &string) const +\brief Lexographically compare if this string is equal to a given string. */ /*! \fn bool BString::operator>=(const char *string) const +\brief Lexographically compare if this string is more than or equal to a given string. */ /*! \fn bool BString::operator>=(const BString &string) const +\brief Lexographically compare if this string is more than or equal to a given string. */ /*! \fn bool BString::operator>(const char *string) const +\brief Lexographically compare if this string is more than a given string. */ /*! \fn bool BString::operator>(const BString &string) const +\brief Lexographically compare if this string is more than a given string. */ /*! \fn bool BString::operator!=(const BString &string) const +\brief Lexographically compare if this string is not equal to a given string. */ /*! \fn bool BString::operator!=(const char *str) const +\brief Lexographically compare if this string is not equal to a given string. */ /*! \fn int BString::Compare(const BString &string) const +\brief Lexographically compare this string to another. + +\param string The string to compare to. +\retval >0 The object sorts lexographically after \c string. +\retval =0 The object is equal to \c string. +\retval <0 The object sorts lexographically before \c string. */ /*! -\fn int BString::Compare(const char *string) const +\fn int BString::Compare(const char *str) const +\brief Lexographically compare this string to another. + +\sa Compare(const BString &string) const */ /*! \fn int BString::Compare(const BString &string, int32 n) const +\brief Lexographically compare a number of characters of this string to another. + +\param string The string to compare to. +\param n The number of characters to compare +\retval >0 The object sorts lexographically after \c string. +\retval =0 The object is equal to \c string. +\retval <0 The object sorts lexographically before \c string. */ /*! -\fn int BString::Compare(const char *string, int32 n) const +\fn int BString::Compare(const char *str, int32 n) const +\brief Lexographically compare a number of characters of this string to another. + +\sa Compare(const BString &string, int32 n) const */ /*! \fn int BString::ICompare(const BString &string) const +\brief Lexographically compare this string to another in a case-insensitive way. + +\sa Compare(const BString &string) const */ /*! \fn int BString::ICompare(const char *str) const +\brief Lexographically compare this string to another in a case-insensitive way. + +\sa Compare(const BString &string) const */ /*! \fn int BString::ICompare(const BString &string, int32 n) const +\brief Lexographically compare a number of characters of this string to another. + +\sa Compare(const BString &string, int32 n) const */ /*! \fn int BString::ICompare(const char *str, int32 n) const +\brief Lexographically compare a number of characters of this string to another. + +\sa Compare(const BString &string, int32 n) const */ //! @} @@ -565,16 +721,21 @@ Counts the number of UTF8 characters contained in the string. \fn int32 BString::FindFirst(const BString &string) const \brief Find the first occurrence of the given BString. \param string The BString to search for. -\return The offset(zero based) into the data +\return The offset(zero based) into the data where the given BString has been found. +\retval B_ERROR Could not find \c string. +\sa IFindFirst(const BString &string) const */ /*! -\fn int32 BString::FindFirst(const char *string) const +\fn int32 BString::FindFirst(const char *str) const \brief Find the first occurrence of the given string. -\param string The string to search for. +\param str The string to search for. \return The offset(zero based) into the data where the given string has been found. +\retval B_BAD_VALUE The \c str pointer is invalid. +\retval B_ERROR Could not find \c str. +\sa IFindFirst(const char *str) const */ /*! @@ -585,16 +746,21 @@ Counts the number of UTF8 characters contained in the string. \param fromOffset The offset where to start the search. \return An integer which is the offset(zero based) into the data where the given BString has been found. +\retval B_ERROR Could not find \c string. +\sa IFindFirst(const BString &string, int32 fromOffset) const */ /*! -\fn int32 BString::FindFirst(const char *string, int32 fromOffset) const +\fn int32 BString::FindFirst(const char *str, int32 fromOffset) const \brief Find the first occurrence of the given string, starting from the given offset. -\param string The string to search for. +\param str The string to search for. \param fromOffset The offset where to start the search. \return The offset(zero based) into the data where the given string has been found. +\retval B_BAD_VALUE The \c str pointer is invalid. +\retval B_ERROR Could not find \c str. +\sa IFindFirst(const char *str, int32 fromOffset) const */ /*! @@ -603,6 +769,7 @@ Counts the number of UTF8 characters contained in the string. \param c The character to search for. \return The offset(zero based) into the data where the given character has been found. +\retval B_ERROR Could not find \c c. */ /*! @@ -613,6 +780,7 @@ Counts the number of UTF8 characters contained in the string. \param fromOffset The offset where to start the search. \return The offset(zero based) into the data where the given character has been found. +\retval B_ERROR Could not find \c c. */ /*! @@ -621,15 +789,19 @@ Counts the number of UTF8 characters contained in the string. \param string The BString to search for. \return The offset(zero based) into the data where the given BString has been found. +\retval B_ERROR Could not find \c string. +\sa IFindLast(const BString &string) const */ /*! -\fn int32 BString::FindLast(const char *string) const +\fn int32 BString::FindLast(const char *str) const \brief Find the last occurrence of the given string. -\param string The string to search for. +\param str The string to search for. \return The offset(zero based) into the data where the given string has been found. -*/ +\retval B_BAD_VALUE The \c str pointer is invalid. +\retval B_ERROR Could not find \c str. +\sa IFindLast(const char *str) const /*! \fn int32 BString::FindLast(const BString &string, int32 beforeOffset) const @@ -639,16 +811,21 @@ Counts the number of UTF8 characters contained in the string. \param beforeOffset The offset where to start the search. \return An integer which is the offset(zero based) into the data where the given BString has been found. +\retval B_ERROR Could not find \c string. +\sa IFindLast(const BString &string, int32 beforeOffset) const */ /*! -\fn int32 BString::FindLast(const char *string, int32 beforeOffset) const +\fn int32 BString::FindLast(const char *str, int32 beforeOffset) const \brief Find the last occurrence of the given string, starting from the given offset, and going backwards. -\param string The string to search for. +\param str The string to search for. \param beforeOffset The offset where to start the search. \return The offset(zero based) into the data where the given string has been found. +\retval B_BAD_VALUE The \c str pointer is invalid. +\retval B_ERROR Could not find \c str. +\sa IFindLast(const char *str, int32 beforeOffset) const */ /*! @@ -657,6 +834,7 @@ Counts the number of UTF8 characters contained in the string. \param c The character to search for. \return The offset(zero based) into the data where the given character has been found. +\retval B_ERROR Could not find \c c. */ /*! @@ -667,38 +845,67 @@ Counts the number of UTF8 characters contained in the string. \param beforeOffset The offset where to start the search. \return The offset(zero based) into the data where the given character has been found. +\retval B_ERROR Could not find \c c. */ /*! \fn int32 BString::IFindFirst(const BString &string) const +\brief Find the first occurrence of the given BString case-insensitively. + +\sa FindFirst(const BString &string) const */ /*! -\fn int32 BString::IFindFirst(const char *string) const +\fn int32 BString::IFindFirst(const char *str) const +\brief Find the first occurrence of the given BString case-insensitively. + +\sa FindFirst(const char *str) const */ /*! \fn int32 BString::IFindFirst(const BString &string, int32 fromOffset) const +\brief Find the first occurrence of the given BString case-insensitively, + starting from the given offset. + +\sa FindFirst(const BString &string, int32 fromOffset) const */ /*! -\fn int32 BString::IFindFirst(const char *string, int32 fromOffset) const +\fn int32 BString::IFindFirst(const char *str, int32 fromOffset) const +\brief Find the first occurrence of the given string case-insensitively, + starting from the given offset. + +\sa FindFirst(const char *str, int32 fromOffset) const */ /*! \fn int32 BString::IFindLast(const BString &string) const +\brief Find the last occurrence of the given BString case-insensitively. + +\sa FindLast(const BString &string) const */ /*! -\fn int32 BString::IFindLast(const char *string) const +\fn int32 BString::IFindLast(const char *str) const +\brief Find the last occurrence of the given string case-insensitively. + +\sa FindLast(const char *str) const */ /*! \fn int32 BString::IFindLast(const BString &string, int32 beforeOffset) const +\brief Find the last occurrence of the given BString case-insensitively, + starting from the given offset, and going backwards. + +\sa FindLast(const BString &string, int32 beforeOffset) const */ /*! -\fn int32 BString::IFindLast(const char *string, int32 beforeOffset) const +\fn int32 BString::IFindLast(const char *str, int32 beforeOffset) const +\brief Find the last occurrence of the given string case-insensitively, + starting from the given offset, and going backwards. + +\sa FindLast(const char *str, int32 beforeOffset) const */ //! @} @@ -712,74 +919,151 @@ Counts the number of UTF8 characters contained in the string. /*! \fn BString& BString::ReplaceFirst(char replaceThis, char withThis) +\brief Replace the first occurance of a character with another character. +\param replaceThis The character to replace. +\param withThis The character to put in that place +\return This method always returns \c *this. +\sa IReplaceFirst(char replaceThis, char withThis) */ /*! \fn BString& BString::ReplaceLast(char replaceThis, char withThis) +\brief Replace the last occurance of a character with another character. +\param replaceThis The character to replace. +\param withThis The character to put in that place +\return This method always returns \c *this. +\sa ReplaceLast(char replaceThis, char withThis) */ /*! \fn BString& BString::ReplaceAll(char replaceThis, char withThis, int32 fromOffset) +\brief Replace all occurances of a character with another character. +\param replaceThis The character to replace. +\param withThis The character to put in that place +\param fromOffset The offset where to start looking for the character +\return This method always returns \c *this. +\sa IReplaceAll(char replaceThis, char withThis, int32 fromOffset) */ /*! \fn BString& BString::Replace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) +\brief Replace a number of occurances of a character with another character. +\param replaceThis The character to replace. +\param withThis The character to put in that place +\param maxReplaceCount The maximum number of characters that should be replaced. +\param fromOffset The offset where to start looking for the character +\return This method always returns \c *this. +\sa IReplace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) */ /*! \fn BString& BString::ReplaceFirst(const char *replaceThis, const char *withThis) +\brief Replace the first occurance of a string with another string. +\param replaceThis The C-string to replace. +\param withThis The C-string to put in that place +\return This method always returns \c *this. +\sa IReplaceFirst(const char *replaceThis, const char *withThis) */ /*! \fn BString& BString::ReplaceLast(const char *replaceThis, const char *withThis) +\brief Replace the last occurance of a string with another string. +\param replaceThis The C-string to replace. +\param withThis The C-string to put in that place +\return This method always returns \c *this. +\sa IReplaceLast(const char *replaceThis, const char *withThis) */ /*! \fn BString& BString::ReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) +\brief Replace all occurances of a string with another string. +\param replaceThis The string to replace. +\param withThis The string to put in that place +\param fromOffset The offset where to start looking for the string. +\return This method always returns \c *this. +\sa IReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) */ /*! \fn BString& BString::Replace(const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset) +\brief Replace a number of occurances of a string with another string. +\param replaceThis The string to replace. +\param withThis The string to put in that place +\param maxReplaceCount The maximum number of occurences that should be replaced. +\param fromOffset The offset where to start looking for the string +\return This method always returns \c *this. +\sa IReplace(const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset) */ /*! \fn BString& BString::IReplaceFirst(char replaceThis, char withThis) +\brief Replace the first occurance of a character with another character. Case insensitive. +\sa ReplaceFirst(char replaceThis, char withThis) */ /*! \fn BString& BString::IReplaceLast(char replaceThis, char withThis) +\brief Replace the last occurance of a character with another character. Case-insensitive. + +\sa ReplaceLast(char replaceThis, char withThis) */ /*! \fn BString& BString::IReplaceAll(char replaceThis, char withThis, int32 fromOffset) +\brief Replace all occurances of a character with another character. Case-insensitive. + +\sa ReplaceAll(char replaceThis, char withThis, int32 fromOffset) */ /*! \fn BString& BString::IReplace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) +\brief Replace a number of occurances of a character with another character. Case-insensive. + +\sa Replace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) */ /*! \fn BString& BString::IReplaceFirst(const char *replaceThis, const char *withThis) +\brief Replace the first occurance of a string with another string. Case-insensitive. + +\sa ReplaceFirst(const char *replaceThis, const char *withThis) */ /*! \fn BString& BString::IReplaceLast(const char *replaceThis, const char *withThis) +\brief Replace the last occurance of a string with another string. Case-insensitive. + +\sa ReplaceLast(const char *replaceThis, const char *withThis) */ /*! \fn BString& BString::IReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) +\brief Replace all occurances of a string with another string. Case-insensitive. + +\sa ReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) */ /*! \fn BString& BString::IReplace(const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset) +\brief Replace a number of occurances of a string with another string. Case-insensitive. + +\sa Replace(const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset) */ /*! \fn BString& BString::ReplaceSet(const char *setOfChars, char with) +\brief Replaces characters that are in a certain set with a chosen character. +\param setOfChars The set of characters that need to be replaced. +\param with The character to replace the occurences with. +\return This method always returns \c *this. */ /*! \fn BString& BString::ReplaceSet(const char *setOfChars, const char *with) +\brief Replaces characters that are in a certain set with a chosen string. +\param setOfChars The set of characters that need to be replaced. +\param with The string to replace the occurences with. +\return This method always returns \c *this. */ // @} @@ -793,13 +1077,14 @@ Counts the number of UTF8 characters contained in the string. /*! \fn char & BString::operator[](int32 index) -\brief Returns a reference to the data at the given offset. +\brief Return a reference to the data at the given offset. -This function can be used to read a byte or to change its value. +This function can be used to read a byte. There is no bounds checking though, so make sure the \c index you supply is valid. \param index The index (zero based) of the byte to get. \return Returns a reference to the specified byte. +\sa ByteAt(int32 index) for a safer version. */ /*! @@ -819,7 +1104,8 @@ valid. This function can be used to read a byte. \param index The index (zero based) of the byte to get. -\return Returns a reference to the specified byte. +\return Returns a reference to the specified byte. If you are out of bounds, + it will return 0. */ //! @} @@ -833,10 +1119,28 @@ This function can be used to read a byte. /*! \fn char* BString::LockBuffer(int32 maxLength) +\brief Locks the buffer and return the internal C-string for manipulation. + +If you want to do any lowlevel string manipulation on the internal buffer, +you should call this method. This method includes the possibility to grow the +buffer so that you don't have to worry about that yourself. + +Make sure you call UnlockBuffer() when you're done with the manipulation. + +\param maxLength The size of the buffer. If you don't want a bigger buffer, passing + anything under the length of the string will simply return it as is. +\return A pointer to the buffer you may manipulate. +\sa UnlockBuffer() */ /*! \fn BString& BString::UnlockBuffer(int32 length) +\brief Unlocks the buffer after you are done with lowlevel manipulation. + +\param length The length to trim the string to in order to keep the internal + buffer sane. If you don't pass a value in it, a \c strlen call will be used to + determine the length. +\return This method always returns \c *this. */ //! @} @@ -850,29 +1154,29 @@ This function can be used to read a byte. /*! \fn BString& BString::ToLower() -\brief Converts the BString to lowercase -\return This function always returns *this . +\brief Convert the BString to lowercase. +\return This method always returns \c *this . */ /*! \fn BString& BString::ToUpper() -\brief Converts the BString to uppercase -\return This function always returns *this . +\brief Convert the BString to uppercase. +\return This method always returns \c *this . */ /*! \fn BString& BString::Capitalize() -\brief Converts the first character to uppercase, rest to lowercase -\return This function always returns *this . +\brief Convert the first character to uppercase, rest to lowercase +\return This method always returns \c *this . */ /*! \fn BString& BString::CapitalizeEachWord() -\brief Converts the first character of every word to uppercase, rest to lowercase. +\brief Convert the first character of every word to uppercase, rest to lowercase. Converts the first character of every "word" (series of alpabetical characters separated by non alphabetical characters) to uppercase, and the rest to lowercase. -\return This function always returns *this . +\return This method always returns \c *this . */ //! @} @@ -880,24 +1184,58 @@ separated by non alphabetical characters) to uppercase, and the rest to lowercas /*! \name Escaping and Deescaping Methods + +This class contains some methods to help you with escaping and de-escaping +certain characters. Note that this is the C-style of escaping, where you place a character +before the character that is to be escaped, and not HTML style escaping, +where certain characters are replaced by something else. */ //! @{ /*! \fn BString& BString::CharacterEscape(const char *original, const char *setOfCharsToEscape, char escapeWith) +\brief Escape selected characters on a given string. + +This version sets itself to the string supplied in the \c original paramater, and +then escapes the selected characters with a supplied character. + +\param original The string to be escaped. +\param setOfCharsToEscape The set of characters that need to be escaped. +\param escapeWith The character to escape with. +\return This method always returns \c *this. +\sa CharacterDeescape(char escapeChar) +\sa CharacterDeescape(const char *original, char escapeChar) */ /*! \fn BString& BString::CharacterEscape(const char *setOfCharsToEscape, char escapeWith) +\brief Escape selected characters of this string. +\param setOfCharsToEscape The set of characters that need to be escaped. +\param escapeWith The character to escape with. +\return This method always returns \c *this. +\sa CharacterDeescape(char escapeChar) */ /*! \fn BString& BString::CharacterDeescape(const char *original, char escapeChar) +\brief Remove the character to escape with from a given string. + +This version sets itself to the string supplied in the \c original parameter, and +then removes the escape characters. + +\param original The string to be escaped. +\param escapeChar The character that was used to escape with. +\return This method always returns \c *this. +\sa CharacterEscape(const char *original, const char *setOfCharsToEscape, char escapeWith) */ /*! \fn BString& BString::CharacterDeescape(char escapeChar) +\brief Remove the character to escape with from this string. +\param escapeChar The character that was used to escape with. +\return This method always returns \c *this. +\sa CharacterEscape(const char *setOfCharsToEscape, char escapeWith) */ //! @} @@ -913,83 +1251,137 @@ These methods may be slower than sprintf(), but they are overflow safe. /*! \fn BString& BString::operator<<(const char *str) +\brief Append the string \c str to the object. */ /*! \fn BString& BString::operator<<(const BString &string) +\brief Append the string \c string to the object. */ /*! \fn BString& BString::operator<<(char c) +\brief Append the character \c c to the object. */ /*! \fn BString& BString::operator<<(int i) +\brief Convert the integer \c i to a string and append it to the object. */ /*! \fn BString& BString::operator<<(unsigned int i) +\brief Convert the unsigned integer \c i to a string and append it to the object. */ /*! \fn BString& BString::operator<<(uint32 i) +\brief Convert the unsigned integer \c i to a string and append it to the object. */ /*! \fn BString& BString::operator<<(int32 i) +\brief Convert the integer \c i to a string and append it to the object. */ /*! \fn BString& BString::operator<<(uint64 i) +\brief Convert the unsigned integer \c i to a string and append it to the object. */ /*! \fn BString& BString::operator<<(int64 i) +\brief Convert the integer \c i to a string and append it to the object. */ /*! \fn BString& BString::operator<<(float f) +\brief Convert the float \c f to a string and append it to the object. */ //! @} /************************ end of class BString, start of general operators ************/ +/*! +\addtogroup support_globals +@{ +*/ + + /*! \fn bool operator<(const char *str, const BString &string) +\brief Lexographically compare if \c str is less than a given BString. +\sa BString::operator<(const char *string) const */ /*! \fn bool operator<=(const char *str, const BString &string) +\brief Lexographically compare if \c str is less than or equal to a given BString. +\sa BString::operator<=(const char *string) const */ /*! \fn bool operator==(const char *str, const BString &string) +\brief Lexographically compare if \c str is equal to a given BString. +\sa BString::operator==(const char *string) const */ /*! \fn bool operator>(const char *str, const BString &string) +\brief Lexographically compare if \c str is more than a given BString. +\sa BString::operator>(const char *string) const */ /*! \fn bool operator>=(const char *str, const BString &string) +\brief Lexographically compare if \c str is more than or equal to a given BString. +\sa BString::operator>=(const char *string) const */ /*! \fn bool operator!=(const char *str, const BString &string) +\brief Lexographically compare if \c str is not equal to given BString. +\sa BString::operator!=(const char *string) const */ /*! \fn int Compare(const BString &, const BString &) +\brief Lexographically compare two strings. + +This function is useful if you need a global compare function to feed to +BList::SortItems() for example. + +\sa BString::Compare(const BString &string) const */ /*! \fn int ICompare(const BString &, const BString &) +\brief Lexographically compare two strings in a case insensitive way. + +This function is useful if you need a global compare function to feed to +BList::SortItems() for example. + +\sa BString::Compare(const BString &string) const */ /*! \fn int Compare(const BString *, const BString *) +\brief Lexographically compare two strings. + +This function is useful if you need a global compare function to feed to +BList::SortItems() for example. + +\sa BString::Compare(const BString &string) const */ /*! \fn int ICompare(const BString *, const BString *) + +This function is useful if you need a global compare function to feed to +BList::SortItems() for example. + +\brief Lexographically compare two strings in a case insensitive way. +\sa BString::Compare(const BString &string) const */ + +//! @} diff --git a/docs/user/support/support_intro.dox b/docs/user/support/support_intro.dox index 13615ad03a..654da4d0c9 100644 --- a/docs/user/support/support_intro.dox +++ b/docs/user/support/support_intro.dox @@ -9,7 +9,7 @@ use in your applications.
  • Threading utility classes:
  • Archiving and IO:
    • diff --git a/docs/user/support/typeconstants.dox b/docs/user/support/typeconstants.dox index 44c8fbd146..35c1cc7c07 100644 --- a/docs/user/support/typeconstants.dox +++ b/docs/user/support/typeconstants.dox @@ -58,7 +58,15 @@ \brief Represents a \c char type used for integer storage */ +/*! +\var B_ATOM_TYPE +\brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. +*/ +/*! +\var B_ATOMREF_TYPE +\brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. +*/ // Todo: the rest of the types