From c4b9309a9964a8bf18a834cf41aa97f1172bab0d Mon Sep 17 00:00:00 2001 From: John Scipione Date: Tue, 24 Jun 2014 19:25:43 -0400 Subject: [PATCH] Update Support Kit docs, add \since Also add preliminary documentation for BObjectList. --- docs/user/support/Architecture.dox | 51 +- docs/user/support/Archivable.dox | 281 +++-- docs/user/support/Autolock.dox | 83 +- docs/user/support/Beep.dox | 16 +- docs/user/support/BlockCache.dox | 36 +- docs/user/support/BufferIO.dox | 109 +- docs/user/support/DataIO.dox | 214 +++- docs/user/support/Flattenable.dox | 104 +- docs/user/support/List.dox | 363 +++++-- docs/user/support/Locker.dox | 134 ++- docs/user/support/ObjectList.dox | 509 +++++++++ docs/user/support/StopWatch.dox | 22 +- docs/user/support/String.dox | 1516 +++++++++++++++++---------- docs/user/support/SupportDefs.dox | 124 ++- docs/user/support/TLS.dox | 41 +- docs/user/support/TypeConstants.dox | 69 +- docs/user/support/parsedate.dox | 103 +- 17 files changed, 2695 insertions(+), 1080 deletions(-) create mode 100644 docs/user/support/ObjectList.dox diff --git a/docs/user/support/Architecture.dox b/docs/user/support/Architecture.dox index 699beac1b2..8b7c38a333 100644 --- a/docs/user/support/Architecture.dox +++ b/docs/user/support/Architecture.dox @@ -1,13 +1,14 @@ /* - * Copyright 2013, Haiku, Inc. All rights reserved. + * Copyright 2013-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Documentation by: + * John Scipione, jscipione@gmail.com * Ingo Weinhold, ingo_weinhold@gmx.de * * Corresponds to: - * headers/os/storage/PathFinder.h hrev46390 - * src/kits/storage/PathFinder.cpp hrev46390 + * headers/os/support/Architecture.h hrev47419 + * src/kits/support/Architecture.cpp hrev47419 */ @@ -16,7 +17,7 @@ \ingroup support \ingroup libbe \brief Provides functions for getting the primary and secondary - architectures of the system. + architectures of the system. */ @@ -30,6 +31,8 @@ \return The name of the caller's architecture. \see get_primary_architecture() + + \since Haiku R1 */ @@ -40,6 +43,8 @@ This is the packaging architecture the main system has been built for. \return The name of the system's primary architecture. + + \since Haiku R1 */ @@ -56,12 +61,15 @@ if it would be possible to install the support for gcc 4. \param architectures A pre-allocated array of size \a count where the names - of the secondary architectures will be stored. Can be \c NULL, if - \a count is 0. + of the secondary architectures will be stored. Can be \c NULL, if + \a count is 0. \param count The size of the \a architectures array. + \return The actual number of secondary architectures. May be greater than - \a count, but at most \a count names will be written to - \a architectures. + \a count, but at most \a count names will be written to + \a architectures. + + \since Haiku R1 */ @@ -75,13 +83,16 @@ Note that this version can fail when running out of memory. \param _architectures Reference to a BStringList that will be set to the - list of names of secondary architectures. On error the list will be - emptied. + list of names of secondary architectures. On error the list will be + emptied. + \return A status code. \retval B_OK Everything went fine. \retval B_NO_MEMORY A memory allocation failed. \see get_secondary_architectures(const char**,size_t) + + \since Haiku R1 */ @@ -89,24 +100,24 @@ \fn size_t get_architectures(const char** architectures, size_t count) \brief Returns the names of the system's primary and secondary - architectures. + architectures. This is a convenience function that returns both the primary architecture as returned by get_primary_architecture() and the secondary architectures as returned by get_secondary_architectures() in the provided array. \param architectures A pre-allocated array of size \a count where the names - of the architectures will be stored. Can be \c NULL, if \a count is 0. + of the architectures will be stored. Can be \c NULL if \a count is 0. \param count The size of the \a architectures array. \return The actual number of architectures. May be greater than \a count, - but at most \a count names will be written to \a architectures. + but at most \a count names will be written to \a architectures. */ /*! \fn status_t get_architectures(BStringList& _architectures) \brief Returns the names of the system's primary and secondary - architectures. + architectures. This is a C++ interface similar to get_architectures(const char**,size_t). Instead of returning the @@ -114,13 +125,16 @@ Note that this version can fail when running out of memory. \param _architectures Reference to a BStringList that will be set to the - list of names of primary and secondary architectures. On error the list - will be emptied. + list of names of primary and secondary architectures. On error the + list will be emptied. + \return A status code. \retval B_OK Everything went fine. \retval B_NO_MEMORY A memory allocation failed. \see get_architectures(const char**,size_t) + + \since Haiku R1 */ @@ -135,6 +149,9 @@ inconclusive the name of the primary architecture is returned. \param path The path to be analyzed. It doesn't necessarily have to point to - an existing file or directory. + an existing file or directory. + \return The name of the architecture determined from \a path. + + \since Haiku R1 */ diff --git a/docs/user/support/Archivable.dox b/docs/user/support/Archivable.dox index e11b97fa86..b8db3c2b51 100644 --- a/docs/user/support/Archivable.dox +++ b/docs/user/support/Archivable.dox @@ -5,6 +5,7 @@ * Authors: * Niels Sascha Reedijk, niels.reedijk@gmail.com * Alex Wilson, yourpalal2@gmail.com + * John Scipione, jscipione@gmail.com * * Proofreader: * David Weizades, ddewbofh@hotmail.com @@ -21,7 +22,7 @@ \ingroup support \ingroup libbe \brief Provides the BArchivable interface and declares the BArchiver and - BUnarchiver classes. + BUnarchiver classes. */ @@ -64,6 +65,8 @@ You should also consider implementing the AllArchived() and AllUnarchived() methods, which were designed to ease archiving and unarchiving in such a situation. + + \since BeOS R3 */ @@ -76,36 +79,43 @@ that takes one BMessage argument. In that constructor, you should call your parent class' archive constructor (even if your parent class is BArchivable). + + \since BeOS R3 */ /*! \fn BArchivable::BArchivable() \brief Constructor. Does nothing. + + \since BeOS R3 */ /*! \fn BArchivable::~BArchivable() \brief Destructor. Does nothing. + + \since BeOS R3 */ /*! - \fn virtual status_t BArchivable::Archive(BMessage* into, - bool deep = true) const + \fn virtual status_t BArchivable::Archive(BMessage* into, bool deep) const \brief Archive the object into a BMessage. - + You should call this method from your derived implementation as it adds the data needed to instantiate your object to the message. - + \param into The message you store your object in. \param deep If \c true, all children of this object should be archived as - well. + well. \retval B_OK The archive operation was successful. \retval B_BAD_VALUE \c NULL \a archive message. \retval B_ERROR The archive operation failed. + + \since BeOS R3 */ @@ -117,17 +127,22 @@ your class. The automatic functions, such as #instantiate_object() and BUnarchiver::InstantiateObject() will not choose the wrong class but manual calls to this member might be faulty. You can verify that \c archive - stores an object of your calss with the validate_instantiation() function. + stores an object of your class with the validate_instantiation() function. \param archive The message with the data of the object to restore. + + \return A pointer to a BArchivable object. \retval You should return a pointer to the object you create with - \c archive, or \c NULL if unarchival fails. + \c archive, or \c NULL if the unarchival fails. + \warning The default implementation will always return \c NULL. Even though it is possible to store plain BArchivable objects, it is impossible to - restore them. + restore them. - \see instantiate_object(BMessage *from) + \see instantiate_object(BMessage*) \see BUnarchiver::InstantiateObject() + + \since BeOS R3 */ @@ -137,13 +152,16 @@ compatibility purposes). \internal This method is defined for binary compatibility purposes, it is - used to ensure that the correct AllUnarchived() and AllArchived() - methods are called for objects, as those methods are new to Haiku. + used to ensure that the correct AllUnarchived() and AllArchived() + methods are called for objects, as those methods are new to + Haiku. \param d The perform code. \param arg A pointer to store some data. \returns A status code. + + \since Haiku R1 */ @@ -158,10 +176,12 @@ their parent class, the same as for the Archive() method. \warning To guarantee that your AllUnarchived() method will be called - during unarchival, you must create a BUnarchiver object in your - archive constructor. + during unarchival, you must create a BUnarchiver object in your + archive constructor. \see BUnarchiver, BUnarchiver::Finish() + + \since Haiku R1 */ @@ -184,6 +204,8 @@ method implementation, and \b NOT your AllArchived() method. \see BArchiver BArchiver::Finish() + + \since Haiku R1 */ @@ -195,7 +217,7 @@ \ingroup support \ingroup libbe \brief A class that simplifies the archiving of complicated BArchivable - hierarchies. + hierarchies. The BArchiver class is a small class that is used for archiving of complicated BArchivable hierarchies. Such a hierarchy may include @@ -208,19 +230,25 @@ present in your original hierarchy. The objects you archive can be retrieved using a BUnarchiver object. + + \since Haiku R1 */ /*! \fn BArchiver::BArchiver(BMessage* archive) \brief Constructs a BArchiver object that manages \c archive. + + \since Haiku R1 */ /*! \fn BArchiver::~BArchiver() \brief Destroys a BArchiver object. If the BArchiver object has not had its - Finish() method called, this will be done now. + Finish() method called, this will be done now. + + \since Haiku R1 */ @@ -228,12 +256,12 @@ \fn status_t BArchiver::AddArchivable(const char* name, BArchivable* archivable, bool deep = true) \brief Adds a reference to \c archivable to the archive used to - construct this BArchiver. May call \c archivable's Archive() method. + construct this BArchiver. May call \c archivable's Archive() method. \param name Where this reference will be stored in the archive. \param archivable The BArchivable* object that to reference. \param deep Passed to \c archivable->Archive() if \c archivable must - be archived. + be archived. Adds a reference to \c archivable to your archive. If \c archivable has not yet been archived, then its Archive() method is called. BArchiver @@ -241,9 +269,11 @@ method or the GetTokenForArchivable() methods. \warning If you manually archive an object, and then pass it to - AddArchivable() or GetTokenForArchivable(), it will be archived again, - and when unarchived you will end up with two different BArchivable - objects. + AddArchivable() or GetTokenForArchivable(), it will be archived + again, and when unarchived you will end up with two different + BArchivable objects. + + \since Haiku R1 */ @@ -251,12 +281,12 @@ \fn status_t BArchiver::GetTokenForArchivable(BArchivable* archivable, bool deep, int32& _token); \brief Get a token representing a BArchivable object for this archiving - session. + session. \param archivable The BArchivable object for which you wish to get a - token. + token. \param deep Controls how \c archivable will be archived, if it has not yet - been archived in this session. + been archived in this session. \param[out] _token The token representing \c archivable is stored here. Retrieves or creates a token to represent \c archivable in this archiving @@ -265,8 +295,10 @@ Archive() method. \warning If you manually archive an object, and then pass it to - GetTokenForArchivable(), it will be archived again, and when unarchived - you will end up with two different BArchivable objects. + GetTokenForArchivable(), it will be archived again, and when + unarchived you will end up with two different BArchivable objects. + + \since Haiku R1 */ @@ -274,46 +306,58 @@ \fn status_t BArchiver::GetTokenForArchivable(BArchivable* archivable, int32 &_token) \brief Equivalent to calling the expanded GetTokenForArchivable( - BArchivable*, bool, int32&), with the deep parameter equal to true. + BArchivable*, bool, int32&), with the deep parameter equal to + \c true. \see GetTokenForArchivable(BArchivable*, bool, int32&) + + \since Haiku R1 */ /*! \fn bool BArchiver::IsArchived(BArchivable* archivable); \brief Returns whether \c archivable has already been archived in this - session. + session. + \return Whether or not the object has already been archived. \retval true \c archivable has been archived in this archiving session. \retval false \c archivable has not been archived in this archiving session. + + \since Haiku R1 */ /*! \fn status_t BArchiver::Finish(status_t err = B_OK); \brief Report any archiving errors and possibly complete the archiving - session. - \return The first error reported in this archiving session, or B_OK. + session. This method may finish an archiving session (triggering the call of all archived objects' AllArchived() methods) if the following conditions are true: - \li No errors have been reported to this or any other BArchiver object - within this session. - \li This is the last remaining BArchiver that has not had its Finish() - method invoked. + - No errors have been reported to this or any other BArchiver object + within this session. + - This is the last remaining BArchiver that has not had its Finish() + method invoked. + If you call this method with an error code not equal to B_OK, then this archiving session has failed, archived objects will not have their AllArchived() methods called, and any subsequent calls to this method on any BArchiver objects in this session will return your error code. + + \return The first error reported in this archiving session, or \c B_OK. + + \since Haiku R1 */ /*! - \fn const BMessage* BArchiver::ArchiveMessage() const + \fn const BMessage* BArchiver::ArchiveMessage() const \brief Returns the BMessage* used to construct this BArchiver. This is - the archive that AddArchivable() modifies. + the archive that AddArchivable() modifies. + + \since Haiku R1 */ @@ -325,7 +369,7 @@ \ingroup support \ingroup libbe \brief A class that simplifies the unarchiving of complicated BArchivable - hierarchies. + hierarchies. The BUnarchiver class is a small class used to recover BArchivable objects that have been archived with the BArchiver class. It also provides ownership @@ -343,9 +387,11 @@ BUnarchiver helper classes, and want to maintain backwards compatibility with old archive, this can be done using the IsArchiveManaged() method. - \warning Calling methods on your BUnarchiver with a legacy archive (one that - was not managed by a BArchiver during archival) will result in a - call to debugger(). + \warning Calling methods on your BUnarchiver with a legacy archive (one + that was not managed by a BArchiver during archival) will result + in a call to debugger(). + + \since Haiku R1 */ @@ -354,15 +400,18 @@ \brief Constructs a BUnarchiver object to manage \c archive. \note To guarantee that your AllUnarchived() method will be called during - archival, you must create a BUnarchiver object in your archive - constructor. It is necessary to do this even if you won't use the - BUnarchiver object in your archive constructor. + archival, you must create a BUnarchiver object in your archive + constructor. It is necessary to do this even if you won't use the + BUnarchiver object in your archive constructor. \warning Do not construct a BUnarchiver object without first calling - BUnarchiver::PrepareArchive() on \c archive. It is only safe to build a - BUnarchiver without this call in your AllUnarchived() implementation. + BUnarchiver::PrepareArchive() on \c archive. It is only safe to + build a BUnarchiver without this call in your AllUnarchived() + implementation. \see BUnarchiver::PrepareArchive() + + \since Haiku R1 */ @@ -371,17 +420,21 @@ \brief Destroys a BUnarchiver object. Calls this objects Finish() method, if it has not yet been called. + + \since Haiku R1 */ /*! \fn status_t BUnarchiver::EnsureUnarchived(int32 token) \brief Ensure the object represented by \a token is unarchived and - instantiated. + instantiated. \param token the object \a token \returns A status code. + + \since Haiku R1 */ @@ -389,35 +442,41 @@ \fn status_t BUnarchiver::EnsureUnarchived(const char* name, int32 index = 0) \brief Ensure the object archived under \a name at \a index is unarchived - and instantiated. + and instantiated. \param name The archive \a name. \param index The archive \a index. \returns A status code. + + \since Haiku R1 */ /*! \fn bool BUnarchiver::IsInstantiated(int32 token) \brief Checks whether the object represented by \c token has been - instantiated in this session. + instantiated in this session. \param token The object \a token. \returns \c true if instantiated, \c false otherwise + + \since Haiku R1 */ /*! \fn bool BUnarchiver::IsInstantiated(const char* name, int32 index = 0) \brief Checks whether the object archived under \a name at \a index has been - instantiated in this session. + instantiated in this session. \param name The archive \a name. \param index The arcive \a token. \returns \c true if instantiated, \c false otherwise. + + \since Haiku R1 */ @@ -431,18 +490,20 @@ If the retrieved object is not of the type T, then this method will fail. If this method fails, you will not receive ownership of the object, no matter what you specified in \c owning. - + \tparam T The type of \a object you wish to find. \param token The \a token you got for this object from - BArchiver::GetTokenForArchivable() during archival. + BArchiver::GetTokenForArchivable() during archival. \param owning Whether or not you wish to take ownership of the - retrieved object. + retrieved object. \param object Return parameter for the retrieved object of type T. \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. + + \since Haiku R1 */ @@ -456,12 +517,14 @@ \tparam T The type of \a object you wish to find. \param token The \a token you got for this object from - BArchiver::GetTokenForArchivable() during archival. + BArchiver::GetTokenForArchivable() during archival. \param object The return parameter for the retrieved object of type T. \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. + + \since Haiku R1 */ @@ -469,7 +532,7 @@ \fn template status_t BUnarchiver::FindObject(const char* name, int32 index, ownership_policy owning, T*& object) \brief Recover an object that had previously been archived using - the BArchiver::AddArchivable() method. + the BArchiver::AddArchivable() method. If the object has not yet been instantiated, and this request is not coming from an AllUnarchived() implementation, the object will be @@ -478,20 +541,22 @@ If the retrieved object is not of the type T, then this method will fail. If this method fails, you will not receive ownership of the object, no matter what you specified in \c owning. - + \tparam T The type of object you wish to find. \param name The name that was passed to BArchiver::AddArchivable() when - adding this object. + adding this object. \param index The index of the object you wish to recover (\c 0-based, - like BMessage::FindData(). + like BMessage::FindData(). \param owning Dictates whether or not you wish to take ownership of the - retrieved object. + retrieved object. \param object Return parameter for the retrieved object of type T. \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. + + \since Haiku R1 */ @@ -499,19 +564,21 @@ \fn template status_t BUnarchiver::FindObject(const char* name, int32 index, T*& object) \brief Recover and take ownership of an object that had previously been - archived using the BArchiver::AddArchivable() method. + archived using the BArchiver::AddArchivable() method. \tparam T The type of object you wish to find. \param name The name that was passed to BArchiver::AddArchivable() when - adding this object. + adding this object. \param index The index of the object you wish to recover (\c 0-based, - like #BMessage::FindData(). + like #BMessage::FindData(). \param object Return parameter for the retrieved object of type T. \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. + + \since Haiku R1 */ @@ -519,21 +586,23 @@ \fn template status_t BUnarchiver::FindObject(const char* name, ownership_policy owning, T*& object) \brief Recover an object at index \c 0 that had previously been - archived using the BArchiver::AddArchivable() method. + archived using the BArchiver::AddArchivable() method. Equivalent to calling FindObject(name, \c 0, owning, object). \tparam T The type of \a object you wish to find. \param name The name that was passed to BArchiver::AddArchivable() when - adding this object. + adding this object. \param owning Dictates whether or not you wish to take ownership of the - retrieved object. + retrieved object. \param object Return parameter for the retrieved object of type T. \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. + + \since Haiku R1 */ @@ -544,33 +613,35 @@ previously been archived using the BArchiver::AddArchivable() method. Equivalent to calling FindObject(name, \c 0, - BUnarchiver::B_ASSUME_OWNERSHIP, object). + BUnarchiver::B_ASSUME_OWNERSHIP, object). \tparam T The type of \a object you wish to find. \param name The name that was passed to BArchiver::AddArchivable() when - adding this object. + adding this object. \param object Return parameter for the retrieved \a object of type T. \returns A status code. \retval B_OK The \a object retrieved was of type T. \retval B_BAD_TYPE The \a object retrieved was not of type T. + + \since Haiku R1 */ /*! \fn status_t BUnarchiver::Finish(status_t err = B_OK); \brief Report any unarchiving errors and possibly complete the archiving - session. + session. This method may finish an unarchiving session (triggering the call of all instantiated objects' AllUnarchived() methods) if the following conditions are true: - \li No errors have been reported to this or any other BUnarchiver - object within this session. - \li This is the last remaining BUnarchiver that has not had its - Finish() method invoked. + - No errors have been reported to this or any other BUnarchiver + object within this session. + - This is the last remaining BUnarchiver that has not had its + Finish() method invoked. If you call this method with an error code not equal to B_OK, then this unarchiving session has failed, instantiated objects will not have their @@ -581,11 +652,13 @@ the root object). \return The first error reported in this unarchiving session, or \c B_OK. + + \since Haiku R1 */ /*! - \fn const BMessage* BUnarchiver::ArchiveMessage() const + \fn const BMessage* BUnarchiver::ArchiveMessage() const \brief Returns the BMessage* used to construct this BUnarchiver. This is the archive that FindObject() uses. @@ -623,6 +696,8 @@ MyArchivableClas::MyArchivableClass(BMessage* archive) \returns Whether \a archive was managed by a BArchiver object. \retval true if \a archive was managed by a BArchiver object. \retval false otherwise. + + \since Haiku R1 */ @@ -650,6 +725,8 @@ MyArchivableClas::MyArchivableClas(BMessage* archive) \param archive The archive you wish to have prepared. \return The same #BMessage as is passed in. + + \since Haiku R1 */ @@ -661,16 +738,20 @@ MyArchivableClas::MyArchivableClas(BMessage* archive) \a archivable. \param archivable The \a archivable object. + + \since Haiku R1 */ /*! \fn void BUnarchiver::RelinquishOwnership(BArchivable* archivable) \brief Relinquish ownership of \a archivable. If \a archivable remains - unclaimed at the end of the unarchiving session, it will be deleted - (unless it is the root object). + unclaimed at the end of the unarchiving session, it will be deleted + (unless it is the root object). \param archivable The \a archivable object. + + \since Haiku R1 */ @@ -678,7 +759,7 @@ MyArchivableClas::MyArchivableClas(BMessage* archive) \fn template status_t BUnarchiver::InstantiateObject( BMessage* from, T*& object) \brief Attempt to instantiate an object of type T from BMessage* - \a from. + \a from. If the instantiated object is not of type T, then it will be deleted, and this method will return \c B_BAD_TYPE. This method is similar to @@ -691,6 +772,8 @@ MyArchivableClas::MyArchivableClas(BMessage* archive) \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. + + \since Haiku R1 */ @@ -708,45 +791,55 @@ MyArchivableClas::MyArchivableClas(BMessage* archive) /*! \typedef typedef BArchivable* (*instantiation_func)(BMessage*) \brief Internal definition of a function that can instantiate objects that - have been created with the BArchivable API. + have been created with the BArchivable API. + + \since BeOS R3 */ /*! \fn BArchivable* instantiate_object(BMessage *from, image_id *id) \brief Instantiate an archived object with the object being defined in a - different application or library. - + different application or library. + This function is similar to instantiate_object(BMessage *from), except that it takes the \a id argument referring to an image where the object might be - stored. - + stored. + \note Images are names for executable files. Image id's refer to these - executable files that have been loaded by your application. Have a look - at the kernel API for further information. + executable files that have been loaded by your application. Have a + look at the kernel API for further information. + + \since BeOS R3 */ /*! \fn BArchivable* instantiate_object(BMessage *from) \brief Instantiate an archived object. - + This global function will determine the base class, based on the \a from argument, and it will call the Instantiate() function of that object to - restore it. - + restore it. + \param from The archived object. + \return The object returns a pointer to the instantiated object, or \c NULL - if the instantiation failed. The global \c errno variable will contain - the reason why it failed. + if the instantiation failed. The global \c errno variable will + contain the reason why it failed. + \see instantiate_object(BMessage *from, image_id *id) + + \since BeOS R3 */ /*! \fn bool validate_instantiation(BMessage* from, const char* className) \brief Internal function that checks if the \a className is the same as the - one stored in the \a from message. + one stored in the \a from message. + + \since BeOS R3 */ @@ -754,21 +847,27 @@ MyArchivableClas::MyArchivableClas(BMessage* archive) \fn instantiation_func find_instantiation_func(const char* className, const char* signature) \brief Internal function that searches for the instantiation func with a - specific signature. Use instantiate_object() instead. + specific signature. Use instantiate_object() instead. + + \since Haiku R1 */ /*! \fn instantiation_func find_instantiation_func(const char* className) \brief Internal function that searches for the instantiation func of a - specific class. Use instantiate_object() instead. + specific class. Use instantiate_object() instead. + + \since BeOS R3 */ /*! \fn instantiation_func find_instantiation_func(BMessage* archive) \brief Internal function that searches for the instantiation func that - works on the specified \a archive. Use instantiate_object() instead. + works on the specified \a archive. Use instantiate_object() instead. + + \since BeOS R3 */ diff --git a/docs/user/support/Autolock.dox b/docs/user/support/Autolock.dox index fb7f3c63a3..a63b58cc48 100644 --- a/docs/user/support/Autolock.dox +++ b/docs/user/support/Autolock.dox @@ -1,9 +1,10 @@ /* - * Copyright 2007-2013 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Corresponds to: * headers/os/support/Autolock.h rev 33370 @@ -41,35 +42,38 @@ 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; + ... 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: + 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; + ... work on call data ... + + BAutolock autolock(fDataLocker); + + ... perform changes ... + + if (!success) + return B_ERROR; + + return B_OK; } \endcode @@ -77,37 +81,47 @@ Receiver::HandleCall(Call *call) 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 unlocked. + + \since BeOS R3 */ /*! - \fn BAutolock::BAutolock(BLooper *looper) + \fn BAutolock::BAutolock(BLooper* looper) \brief Create an object and lock the BLooper + + \since BeOS R3 */ /*! - \fn BAutolock::BAutolock(BLocker *locker) + \fn BAutolock::BAutolock(BLocker* locker) \brief Create an object and lock the BLocker + + \since BeOS R3 */ /*! - \fn BAutolock::BAutolock(BLocker &locker) + \fn BAutolock::BAutolock(BLocker& locker) \brief Create an object and lock the BLocker + + \since BeOS R3 */ /*! \fn BAutolock::~BAutolock() \brief Destroy the object and unlock the associated BLocker or BLooper + + \since BeOS R3 */ /*! \fn bool BAutolock::IsLocked() - \brief Verify whether the associated BLocker or BLooper are actually - locked. + \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 @@ -116,27 +130,36 @@ Receiver::HandleCall(Call *call) If you expect this to happen, you can use this method to help you protect yourself from any harm. + + \return Whether or not the BLocker or BLooper is locked. \retval true The lock was acquired. \retval false Failed to acquire the lock. + + \since BeOS R3 */ /*! \fn bool BAutolock::Lock() \brief Lock the BAutolock if it has not already happened - + Note that unlike BLocker, the object is not locked with lock count. That means that if the lock is already taken, this method returns \c true without any action. + \return Whether or not the BLocker or BLooper was locked. \retval true The lock was acquired (or had already been acquired). \retval false Failed to acquire the lock. + + \since Haiku R1 */ /*! \fn void BAutolock::Unlock() - \brief Unlock the BAutolock if the lock is being held + \brief Unlock the BAutolock if the lock is being held. If the lock is not held, the method does nothing. + + \since Haiku R1 */ \ No newline at end of file diff --git a/docs/user/support/Beep.dox b/docs/user/support/Beep.dox index 95a629fb5f..73a9722b08 100644 --- a/docs/user/support/Beep.dox +++ b/docs/user/support/Beep.dox @@ -1,9 +1,10 @@ /* - * Copyright 2007 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Corresponds to: * headers/os/support/Beep.h rev 19972 @@ -21,6 +22,8 @@ \ingroup support \ingroup libbe \brief Functions to generate sounds from the computer. + + \since BeOS R3 */ @@ -35,26 +38,37 @@ /*! \fn status_t beep() \brief Invoke the standard system beep to alert users. + From Beep.h and in libbe.so. + \see system_beep() and add_system_beep_event() + + \since BeOS R3 */ /*! \fn status_t system_beep(const char* eventName) \brief Invokes the sound for event \a eventName. + You can add the events using add_system_beep_event(). From Beep.h and in libbe.so. + + \since BeOS R5 */ /*! \fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0) \brief Adds an event to the media server. + Call this method to add a specific event to the media server. From Beep.h and in libbe.so. + \param eventName The name of the event. \param flags Currently unused. Pass \c 0. + + \since BeOS R5 */ diff --git a/docs/user/support/BlockCache.dox b/docs/user/support/BlockCache.dox index a474542364..6b4e1e4b3d 100644 --- a/docs/user/support/BlockCache.dox +++ b/docs/user/support/BlockCache.dox @@ -1,9 +1,10 @@ /* - * Copyright 2007 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Proofreading: * David Weizades, ddewbofh@hotmail.com @@ -15,7 +16,7 @@ */ - /*! +/*! \file BlockCache.h \ingroup support \ingroup libbe @@ -26,14 +27,18 @@ /*! \var B_OBJECT_CACHE \brief Used in the constructor of BBlockCache. Determines that objects will - be created using \c new[] and \c delete[]. + be created using \c new[] and \c delete[]. + + \since BeOS R3 */ /*! \var B_MALLOC_CACHE \brief Used in the constructor of BBlockCache. Determines that objects will - be created using \c malloc() and \c free(). + be created using \c malloc() and \c free(). + + \since BeOS R3 */ @@ -77,6 +82,8 @@ Get() will be allocating the objects by itself. \note BBlockCache is thread-safe. + + \since BeOS R3 */ @@ -86,11 +93,13 @@ \brief Allocate a new memory pool. \param blockCount The number of free memory blocks you want to allocate - initially. This number is also used as the maximum number of free blocks - that will be kept. + initially. This number is also used as the 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(). + \c delete[] or #B_MALLOC_CACHE for \c malloc() and \c free(). + + \since BeOS R3 */ @@ -101,11 +110,13 @@ 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. + + \since BeOS R3 */ /*! - \fn void *BBlockCache::Get(size_t blockSize) + \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 @@ -114,13 +125,16 @@ 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. + object failed. + + \since BeOS R3 */ /*! - \fn void BBlockCache::Save(void *pointer, size_t blockSize) + \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 @@ -134,4 +148,6 @@ were created with \c new[] if the allocation type is #B_OBJECT_CACHE. Likewise, you should only use objects allocated with \c malloc() when the allocation type is #B_MALLOC_CACHE. + + \since BeOS R3 */ diff --git a/docs/user/support/BufferIO.dox b/docs/user/support/BufferIO.dox index ff03d222ed..bf87f32a8f 100644 --- a/docs/user/support/BufferIO.dox +++ b/docs/user/support/BufferIO.dox @@ -1,10 +1,11 @@ /* - * Copyright 2007,Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * Stefano Ceccherini, burton666@libero.it * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Corresponds to: * headers/os/support/BufferIO.h rev 38225 @@ -47,15 +48,18 @@ done with it will also flush the stream and update the original stream. \note This class is not meant to be used in cases where the - original stream requires to be in a consistent state. Neither should - this class be used as a way to perform 'atomic' writes, because the - object might need to do partial writes if it needs to 'move' the - buffer. This happens for instance if the original stream is bigger - than the buffer. + original stream requires to be in a consistent state. Neither should + this class be used as a way to perform 'atomic' writes, because the + object might need to do partial writes if it needs to 'move' the + buffer. This happens for instance if the original stream is bigger + than the buffer. + + \since Haiku R1 */ + /*! - \fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize, + \fn BBufferIO::BBufferIO(BPositionIO* stream, size_t bufferSize, bool ownsStream) \brief Initialize a BBufferIO object. @@ -64,11 +68,14 @@ \param stream A pointer to a BPositionIO object. \param bufferSize The size of the buffer that the object will allocate and - use. + use. \param ownsStream Specifies if the object will delete the stream on - destruction. + destruction. + + \since Haiku R1 */ + /*! \fn BBufferIO::~BBufferIO() \brief Free the resources allocated by the object @@ -76,11 +83,13 @@ Flush pending changes to the stream and free the allocated memory. If the \c owns_stream property is \c true, the destructor also deletes the stream associated with the BBufferIO object. + + \since Haiku R1 */ -/*! - \fn ssize_t BBufferIO::ReadAt(off_t pos, void *buffer, size_t size) +/*! + \fn ssize_t BBufferIO::ReadAt(off_t pos, void* buffer, size_t size) \brief Read the specified amount of bytes at the given position. \param pos The offset into the stream where to read. @@ -89,11 +98,14 @@ \return The amount of bytes actually read, or an error code. \retval B_NO_INIT The object is not associated with a valid BPositionIO - stream. + stream. \retval B_BAD_VALUE The \c buffer parameter is not valid. + + \since Haiku R1 */ -/*! + +/*! \fn ssize_t BBufferIO::WriteAt(off_t pos, const void *buffer, size_t size) \brief Write the specified amount of bytes at the given position. @@ -103,11 +115,14 @@ \return The amount of bytes actually written, or an error code. \retval B_NO_INIT The object is not associated with a valid BPositionIO - stream. + stream. \retval B_BAD_VALUE The \c buffer parameter is not valid. + + \since Haiku R1 */ -/*! + +/*! \fn off_t BBufferIO::Seek(off_t position, uint32 seekMode) \brief Set the position in the stream. @@ -117,22 +132,25 @@ \param position The position where you want to seek. \param seekMode Can have three values: - - \c SEEK_SET The position passed is an offset from the beginning of - the stream; in other words, the current position is set to - position. For this mode, position should be a positive value. - - \c SEEK_CUR The position argument is an offset from the current - position; the value of the argument is added to the current - position. - - \c SEEK_END. The position argument is an offset from the end of the - stream. In this mode the position argument should be negative - (or zero). + - \c SEEK_SET The position passed is an offset from the beginning + of the stream; in other words, the current position is set to + position. For this mode, position should be a positive value. + - \c SEEK_CUR The position argument is an offset from the current + position; the value of the argument is added to the current + position. + - \c SEEK_END. The position argument is an offset from the end of + the stream. In this mode the position argument should be negative + (or zero). \return The current position as an offset in bytes from the beginning of - the stream. + the stream. \retval B_NO_INIT The object is not associated with a valid BPositionIO - stream. + stream. + + \since Haiku R1 */ + /*! \fn off_t BBufferIO::Position() const \brief Return the current position in the stream. @@ -140,9 +158,12 @@ \return The current position as an offset in bytes from the beginning of the stream. \retval B_NO_INIT The object is not associated with a valid BPositionIO - stream. + stream. + + \since Haiku R1 */ + /*! \fn status_t BBufferIO::SetSize(off_t size) \brief Call the SetSize() function of the assigned BPositionIO stream. @@ -152,23 +173,30 @@ \returns A status code. \retval B_OK The stream is resized. \retval B_NO_INIT The object is not associated with a valid BPositionIO - stream. + stream. + + \since Haiku R1 */ + /*! \fn status_t BBufferIO::Flush() \brief Write pending modifications to the stream. - \return The amount of bytes written, or if it failed it will return an error - code. + \return The amount of bytes written, or if it failed it will return an + error code. + + \since Haiku R1 */ -/*! - \fn BPositionIO *BBufferIO::Stream() const +/*! + \fn BPositionIO* BBufferIO::Stream() const \brief Return a pointer to the stream specified on construction. \return A pointer to the BPositionIO stream specified on construction. + + \since Haiku R1 */ @@ -177,18 +205,23 @@ \brief Return the size of the internal buffer. \return The size of the buffer allocated by the object. + + \since Haiku R1 */ /*! \fn bool BBufferIO::OwnsStream() const - \brief Tell if the BBufferIO object "owns" the specified stream. + \brief Return whether or not the BBufferIO object "owns" the stream. + \return Whether or not the BBufferIO object "owns" the stream. \retval true The object "owns" the stream and will destroy it upon - destruction. + destruction. \retval false The object does not own the stream. \see SetOwnsStream() + + \since Haiku R1 */ @@ -197,11 +230,15 @@ \brief Set the \c owns_stream property of the object. \param owns_stream If you pass \c true, the object will delete the stream - upon destruction, if you pass \c false it will not. + upon destruction, if you pass \c false it will not. + + \since Haiku R1 */ /*! \fn void BBufferIO::PrintToStream() const - \brief Print the object to stdout. + \brief Print the object to standard output. + + \since Haiku R1 */ diff --git a/docs/user/support/DataIO.dox b/docs/user/support/DataIO.dox index 7885975cba..7a2f382385 100644 --- a/docs/user/support/DataIO.dox +++ b/docs/user/support/DataIO.dox @@ -5,10 +5,11 @@ * Authors: * Stefano Ceccherini, burton666@libero.it * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/support/DataIO.h rev 38226 - * src/kits/support/DataIO.cpp rev 42177 + * headers/os/support/DataIO.h hrev47418 + * src/kits/support/DataIO.cpp hrev47418 */ @@ -16,13 +17,14 @@ \file DataIO.h \ingroup support \ingroup libbe - \brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes. + \brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO + and BMemoryIO classes. - Pure virtual BDataIO and BPositioIO classes provide - the protocol for Read()/Write()/Seek(). + Pure virtual BDataIO and BPositioIO classes provide the protocol for + Read(), Write(), and Seek(). - BMallocIO and BMemoryIO classes implement the protocol, - as does BFile in the Storage Kit. + BMallocIO and BMemoryIO classes implement the protocol, as does BFile in + the Storage Kit. */ @@ -34,7 +36,7 @@ \ingroup support \ingroup libbe \brief Abstract interface for objects that provide read and write access to - data. + data. The interface provided by this class applies to objects or data that are limited to reading and writing data. Classes derived from this class should @@ -46,23 +48,29 @@ Objects and data that support more advanced operations like seeking or reading at writing at defined positions should derive their classes from BPositionIO, which inherits this class. + + \since BeOS R3 */ /*! \fn BDataIO::BDataIO() \brief This constructor does nothing. + + \since BeOS R3 */ /*! \fn BDataIO::~BDataIO() \brief This destructor does nothing. + + \since BeOS R3 */ /*! - \fn virtual ssize_t BDataIO::Read(void *buffer, size_t size) + \fn virtual ssize_t BDataIO::Read(void* buffer, size_t size) \brief Reads data from the object into a buffer. Your implementation should copy data into \c buffer, with the maximum size @@ -71,26 +79,31 @@ The default implementation is a no-op returning \c B_NOT_SUPPORTED. \return You should return the amount of bytes actually read, or an error - code in case of failure. + code in case of failure. + + \since BeOS R3 */ /*! - \fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size) + \fn virtual ssize_t BDataIO::Write(const void* buffer, size_t size) \brief Writes data from a buffer to the object. Your implementation should copy data from \c buffer, with the maximum size - of \c size. + of \c size. The default implementation is a no-op returning \c B_NOT_SUPPORTED. - \return You should return the amount of bytes actually written, or an error - code in case of failure. + \return You should return the amount of bytes actually written, or an error + code in case of failure. + + \since BeOS R3 */ /*! - \fn virtual status_t BDataIO::ReadExactly(void* buffer, size_t size, size_t* _bytesRead) + \fn virtual status_t BDataIO::ReadExactly(void* buffer, size_t size, + size_t* _bytesRead) \brief Reads an exact amount of data from the object into a buffer. This is a convenience wrapper method for Read() for code that expects the @@ -99,21 +112,25 @@ read any more data (i.e. returns 0). \param buffer Pointer to pre-allocated storage of at least \a size bytes - into which the data shall be read. Won't be dereferenced, when \a size - is 0. + into which the data shall be read. Won't be dereferenced, when + \a size is 0. \param size The number of bytes to be read. \param _bytesRead Optional pointer to a pre-allocated size_t into which the - number of bytes actually read will be written. When the method returns - \c B_OK this will always be \a size. Can be \c NULL. - \return An error code indicated whether the method succeeded. + number of bytes actually read will be written. When the method + returns \c B_OK this will always be \a size. Can be \c NULL. + + \return An error code indicating whether or not the method succeeded. \retval B_OK All data have been read. \retval B_PARTIAL_READ Read() didn't fail, but couldn't provide as many - bytes as requested. + bytes as requested. + + \since Haiku R1 */ /*! - \fn virtual status_t BDataIO::WriteExactly(const void* buffer, size_t size, size_t* _bytesWritten) + \fn virtual status_t BDataIO::WriteExactly(const void* buffer, size_t size, + size_t* _bytesWritten) \brief Writes an exact amount of data from a buffer to the object. This is a convenience wrapper method for Write() for code that expects the @@ -122,15 +139,18 @@ write any more data (i.e. returns 0). \param buffer Pointer to a buffer of at least \a size bytes containing the - data to be written. Won't be dereferenced, when \a size is 0. + data to be written. Won't be dereferenced, when \a size is 0. \param size The number of bytes to be written. \param _bytesWritten Optional pointer to a pre-allocated size_t into which - the number of bytes actually written will be written. When the method - returns \c B_OK this will always be \a size. Can be \c NULL. + the number of bytes actually written will be written. When the + method returns \c B_OK this will always be \a size. Can be \c NULL. + \return An error code indicated whether the method succeeded. \retval B_OK All data have been written. \retval B_PARTIAL_READ Write() didn't fail, but couldn't write as many - bytes as provided. + bytes as provided. + + \since Haiku R1 */ @@ -142,7 +162,7 @@ \ingroup support \ingroup libbe \brief Abstract interface that provides advanced read, write and seek access - to data. + to data. The interface of this object applies to objects or data that allows position-aware reading and writing of data. Classes that derive from this @@ -158,29 +178,37 @@ default implementation is to read or write the data at the current position indicated by Position(). Re-implement the methods if you require a different behavior. + + \since Haiku R1 */ /*! \fn BPositionIO::BPositionIO() \brief This constructor does nothing. + + \since Haiku R1 */ /*! \fn virtual BPositionIO::~BPositionIO() \brief This destructor does nothing. + + \since Haiku R1 */ /*! - \fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size) + \fn virtual ssize_t BPositionIO::Read(void* buffer, size_t size) \brief Read data from current position. This method is derived from BDataIO. The default implementation reads data from the current position of the cursor, pointed at by Position(). If you require different behaviour, please look at BDataIO::Read() for what is expected of this method. + + \since BeOS R3 */ @@ -192,28 +220,36 @@ to the current position of the cursor, pointed at by Position(). If you require different behaviour, please look at BDataIO::Write() for what is expected of this method. + + \since BeOS R3 */ /*! - \fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0 + \fn virtual ssize_t BPositionIO::ReadAt(off_t position, void* buffer, + size_t size) = 0 \brief Pure virtual to read data from a certain position. Your implementation should copy data from the position indicated by \a position into the \a buffer with the maximum size of \a size. \return The amount of bytes actually read, or an error code. + + \since BeOS R3 */ /*! - \fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0 + \fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, + size_t size) = 0 \brief Pure virtual to write data to a certain position. Your implementation should copy data from \a buffer to the position indicated by \a buffer with the maximum size of \a size. \return The amount of bytes actually written, or an error code. + + \since BeOS R3 */ @@ -226,11 +262,15 @@ \param position An integer that defines a position. \param seekMode You will get one of the following values: - - \c SEEK_SET Set the cursor to the position indicated by \c position. - - \c SEEK_END Set the cursor to the end of the buffer, and go - \c position beyond that. - - \c SEEK_CUR Set the cursor the the current position plus \c position. + - \c SEEK_SET Set the cursor to the position indicated by + \c position. + - \c SEEK_END Set the cursor to the end of the buffer, and go + \c position beyond that. + - \c SEEK_CUR Set the cursor the the current position plus + \c position. \return The new position. + + \since BeOS R3 */ @@ -239,6 +279,8 @@ \brief Pure virtual to return the current position of the cursor. \return Your implementation should return the current position of the cursor. + + \since BeOS R3 */ @@ -250,7 +292,9 @@ the size to be changed, reimplement this method. \return Return \c B_OK if everything succeeded, else return the appropriate - error code. + error code. + + \since BeOS R3 */ @@ -266,8 +310,13 @@ your class. \param[out] size The size of the object is put into this parameter. + \return This method returns \c B_OK on success or an error code on error. + + \see SetSize() \see Seek() + + \since BeOS R3 */ @@ -291,6 +340,8 @@ This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and Position() interface from BPositionIO. + + \since BeOS R3 */ @@ -300,8 +351,11 @@ \param data A pointer to the buffer to adopt. \param length The size of the buffer. + \see BMemoryIO(const void *buffer, size_t length) for a read-only - implementation. + implementation. + + \since BeOS R3 */ @@ -311,13 +365,18 @@ \param buffer A pointer to the \c const (read-only) buffer to adopt. \param length The size of the buffer. + \see BMemoryIO(void *buffer, size_t length) for a read-write implementation. + + \since BeOS R3 */ /*! \fn BMemoryIO::~BMemoryIO() \brief The destructor does nothing. + + \since BeOS R3 */ @@ -328,9 +387,12 @@ \param[in] pos The offset where to start reading data. \param[out] buffer The buffer to copy the read bytes into. \param[in] size The size of the \a buffer. + \return The amount of read bytes or an error code. \retval B_BAD_VALUE The position is less than zero or the buffer given on - construction is invalid. + construction is invalid. + + \since BeOS R3 */ @@ -341,10 +403,13 @@ \param pos The offset to write to. \param buffer The buffer to copy the bytes from. \param size The number of bytes to write. + \return The amount of bytes written or an error code. \retval B_NOT_ALLOWED The object is constructed as a read-only object. \retval B_BAD_VALUE The position is less than zero or the buffer given on - construction is invalid. + construction is invalid. + + \since BeOS R3 */ @@ -353,20 +418,27 @@ \brief Move the cursor to a given position. \param position The position to move the cursor to. - \param seek_mode The mode determines where the cursor is placed. - Possibilities: - - \c SEEK_SET The cursor is set to \a position. - - \c SEEK_CUR The \a position is added to the current position of the - cursor. - - \c SEEK_END The cursor is put at the end of the data, plus - \a position added to it. + \param seek_mode The mode determines where the cursor is placed. + Possibilities include: + - \c SEEK_SET The cursor is set to \a position. + - \c SEEK_CUR The \a position is added to the current position of + the cursor. + - \c SEEK_END The cursor is put at the end of the data, plus + \a position added to it. + \return The new position. + + \since BeOS R3 */ /*! \fn off_t BMemoryIO::Position() const \brief Return the current position. + + \return The current position as an off_t. + + \since BeOS R3 */ @@ -387,6 +459,8 @@ \retval B_OK The buffer is resized. \retval B_NOT_ALLOWED The buffer is read-only. \retval B_ERROR The \c size is larger than the size of the buffer. + + \since BeOS R3 */ @@ -415,19 +489,26 @@ If you require a BPositionIO derived object that works on buffers you provide, have a look at BMemoryIO. + + \since BeOS R3 */ /*! \fn BMallocIO::BMallocIO() \brief Create a new memory buffer with block size 256. + \see SetBlockSize() + + \since BeOS R3 */ /*! \fn BMallocIO::~BMallocIO() \brief Destroy the object and free the internal buffer. + + \since BeOS R3 */ @@ -438,8 +519,11 @@ \param[in] pos Offset into the data where to read from. \param[out] buffer The buffer to copy the read bytes in. \param [in] size Size of the buffer. + \return The number of read bytes, or \c B_BAD_VALUE if - the provided \a buffer is invalid. + the provided \a buffer is invalid. + + \since BeOS R3 */ @@ -450,8 +534,11 @@ \param pos Offset into the data where to write to. \param buffer The buffer to copy from. \param size The size of the buffer. + \return The number of bytes written or \c B_BAD_VALUE if the provided. - \a buffer is invalid. + \a buffer is invalid. + + \since BeOS R3 */ @@ -461,18 +548,23 @@ \param position The position to move the cursor to. \param seekMode The mode determines where the cursor is placed. Possibilities: - - \c SEEK_SET The cursor is set to \a position. - - \c SEEK_CUR The \c position is added to the current position of the - cursor. - - \c SEEK_END The cursor is put at the end of the data, plus - \a position added to it. - \return The new position. + - \c SEEK_SET The cursor is set to \a position. + - \c SEEK_CUR The \c position is added to the current position of the + cursor. + - \c SEEK_END The cursor is put at the end of the data, plus + \a position added to it. + + \return The new position as an off_t. + + \since BeOS R3 */ /*! \fn off_t BMallocIO::Position() const \brief Return the position of the cursor. + + \since BeOS R3 */ @@ -484,8 +576,12 @@ than the current size, the data will be cleared. \param size The new size of the buffer. + + \return A status code. \retval B_OK Resizing the data succeeded. \retval B_NO_MEMORY Failed to allocate the necessary memory. + + \since BeOS R3 */ @@ -493,21 +589,25 @@ \fn void BMallocIO::SetBlockSize(size_t blockSize) \brief Change the block size to a certain value. - This class allocates memory in blocks. If you are in performance-critical + This class allocates memory in blocks. If you are in performance-critical code you might want to tweak this setting to create a better performance in - case you know you are going to allocate more than the default blocksize of + case you know you are going to allocate more than the default block size of 256. \param blockSize The new block size. + + \since BeOS R3 */ /*! - \fn const void *BMallocIO::Buffer() const + \fn const void* BMallocIO::Buffer() const \brief Return a pointer to the internal buffer. As with any pointer to internal buffers the Haiku API exposes, make sure you don't change anything since it doesn't belong to you. + + \since BeOS R3 */ @@ -518,4 +618,6 @@ This number doesn't have to be the same size as the buffer is. Because memory is allocated in blocks the actual size of the buffer may be greater, but this method only returns the number of bytes that are actually used. + + \since BeOS R3 */ diff --git a/docs/user/support/Flattenable.dox b/docs/user/support/Flattenable.dox index 94d1026ada..34c267e720 100644 --- a/docs/user/support/Flattenable.dox +++ b/docs/user/support/Flattenable.dox @@ -1,9 +1,10 @@ /* - * Copyright 2007 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: - * Niels Sascha Reedijk + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Corresponds to: * headers/os/support/Flattenable.h rev 39675 @@ -24,21 +25,21 @@ \ingroup support \ingroup libbe \brief Interface for classes that can flatten and unflatten themselves to - a stream of bytes. + a stream of bytes. It is convenient that objects can be stored as a flat stream of bytes. In this way, they can be written to disk, exchanged between applications or send - over networks. This ability, which is known in many other programming - languages as marshalling, is not native in C++. The Haiku API has created a - universal interface that classes have if they are able to be flattened. This + over networks. This ability, known as marshaling in many other programming + languages, is not native to C++. The Haiku API has created a universal + interface that classes have if they are able to be flattened. This class defines the interface. This class does nothing on its own, and - therefore contains pure virtuals. By inheriting this class and inmplementing - the methods in your own class, you will be able to use your objects as - flattenable objects throughout the Haiku API. + therefore contains pure virtual functions. By inheriting this class and + implementing the methods in your own class, you will be able to use your + objects as flattenable objects throughout the Haiku API. Flattened objects can be used for example when sending messages within an application or between applications. The BMessage class uses the interface - to store and transmit custom classes. + to store and transmit custom classes. If you want to be able to flatten your objects, you will need to implement various methods. Flatten() and Unflatten() are where the magic happen. These @@ -56,33 +57,37 @@ \code type_code CUSTOM_STRING_TYPE = 'CUST'; -class CustomString : public BFlattenable -{ +class CustomString : public BFlattenable { public: - char data[100]; + char data[100]; - // From BFlattenable - bool IsFixedSize() const { return false; }; - type_code TypeCode() const { return CUSTOM_STRING_TYPE; }; - ssize_t FlattenedSize() const { return strlen(data); }; + // from BFlattenable + bool IsFixedSize() const { return false; }; + type_code TypeCode() const { return CUSTOM_STRING_TYPE; }; + ssize_t FlattenedSize() const { return strlen(data); }; - status_t Flatten(void* buffer, ssize_t size) const - { - if ((strlen(data) + 1) < size) - return B_BAD_VALUE; - memcpy(buffer, data, size); - return B_OK; - }; + status_t Flatten(void* buffer, ssize_t size) const + { + if ((strlen(data) + 1) < size) + return B_BAD_VALUE; - status_t Unflatten(type_code code, const void* buffer, ssize_t size) - { - if (code != CUSTOM_STRING_TYPE) - return B_BAD_TYPE; - if (size > 100) - return B_NO_MEMORY; - memcpy(data, buffer, size); - return B_OK; - }; + memcpy(buffer, data, size); + + return B_OK; + }; + + status_t Unflatten(type_code code, const void* buffer, ssize_t size) + { + if (code != CUSTOM_STRING_TYPE) + return B_BAD_TYPE; + + if (size > 100) + return B_NO_MEMORY; + + memcpy(data, buffer, size); + + return B_OK; + }; }; \endcode @@ -102,13 +107,20 @@ public: to disk. Another example is BPath. Because of that you can store paths and send them over via messages. Throughout the Haiku API you will find classes that provide the flattening interface. + + \since BeOS R3 */ /*! \fn virtual bool BFlattenable::IsFixedSize() const - \brief Pure virtual that should return whether or not flattened objects of - this type always have a fixed size. + \brief Pure virtual that should return whether or not flattened objects of + this type always have a fixed size. + + \return Should return whether or not the flattened objects of this type + always have a fixed size. + + \since BeOS R3 */ @@ -117,22 +129,26 @@ public: \brief Pure virtual that returns the type_code this class flattens to. \return Either one of the existing typecodes found in TypeConstants.h - if your class actually is compatible to those formats, or a - custom four-byte integer constant if not. + if your class actually is compatible to those formats, or a + custom four-byte integer constant if not. + + \since BeOS R3 */ /*! \fn virtual ssize_t BFlattenable::FlattenedSize() const \brief Pure virtual that should return the size of the flattened object in - bytes. + bytes. + + \since BeOS R3 */ /*! \fn virtual status_t BFlattenable::Flatten(void* buffer, ssize_t size) const \brief Pure virtual that should flatten the object into the supplied - \a buffer. + \a buffer. Please make sure that you check that the supplied buffer is not a \c NULL pointer. Also make sure that the size of the flattened object does isn't @@ -144,6 +160,8 @@ public: \retval B_OK The object was flattened. \retval B_NO_MEMORY The buffer was smaller than required. \retval B_BAD_VALUE The buffer was a \c NULL pointer. + + \since BeOS R3 */ @@ -159,6 +177,8 @@ public: \returns Whether or not the supplied type_code is supported. \retval true The type_code is supported. \retval false The type_code is not supported. + + \since BeOS R3 */ @@ -166,7 +186,7 @@ public: \fn virtual status_t BFlattenable::Unflatten(type_code code, const void* buffer, ssize_t size) \brief Pure virtual that should unflatten the buffer and put the contents - into the current object. + into the current object. Make sure that the supplied buffer is not \c NULL and that you actually support the typecode. @@ -179,10 +199,14 @@ public: \retval B_OK The object is unflattened. \retval B_BAD_VALUE The \a buffer pointer is \c NULL or the data is invalid. \retval B_BAD_TYPE You don't support data with this \a code. + + \since BeOS R3 */ /*! \fn virtual BFlattenable::~BFlattenable() \brief Destructor. Does nothing. + + \since Haiku R1 */ diff --git a/docs/user/support/List.dox b/docs/user/support/List.dox index b545e70cd2..b8cb9eedff 100644 --- a/docs/user/support/List.dox +++ b/docs/user/support/List.dox @@ -1,9 +1,10 @@ /* - * Copyright 2007 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Proofreading: * David Weizades, ddewbofh@hotmail.com @@ -11,8 +12,8 @@ * John Drinkwater, jdrinkwater@gmail.com * * Corresponds to: - * headers/os/support/List.h rev 34520 - * src/kits/support/List.cpp rev 34520 + * headers/os/support/List.h hrev47418 + * src/kits/support/List.cpp hrev47418 */ @@ -29,7 +30,7 @@ \ingroup support \ingroup libbe \brief An ordered container that is designed to hold generic \c void* - objects. + 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 @@ -54,8 +55,14 @@ The class implements methods to add, remove, reorder, retrieve, and query items as well as some advanced methods which let you perform a task on all the items in the list. + + \see BObjectList for a templated version of BList that adds type safety, + optional object ownership, search, and insert operations. + + \since BeOS R3 */ + /*! \fn BList::BList(int32 count = 20) \brief Create a new list with a number of empty slots. @@ -76,104 +83,186 @@ values. \param count The size of the blocks allocated in memory. + + \since BeOS R3 */ + /*! - \fn BList::BList(const BList& anotherList) + \fn BList::BList(const BList& other) \brief Copy constructor. Copy a complete list into this one. + + \param other The list to copy from. + + \since BeOS R3 */ + /*! \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. + + \since BeOS R3 */ + /*! - \fn BList& BList::operator=(const BList &list) - \brief Copy another list into this object. + \name Operators */ + +//! @{ + + +/*! + \fn BList& BList::operator=(const BList &other) + \brief Copy another list into this object. + + \since BeOS R3 +*/ + + +/*! + \fn bool BList::operator==(const BList& other) const + \brief Returns whether or not the BList and \a other are equal. + + Equal means that they are the same object or their contents are the same. + + \return \c true if the lists are equal, \c false if they are NOT equal. + + \since Haiku R1 +*/ + + +/*! + \fn bool BList::operator!=(const BList& other) const + \brief Returns whether or not the BList and \a other are NOT equal. + + \return \c true if the lists are NOT equal, \c false if they are equal. + + \since Haiku R1 +*/ + + +//! @} + + /*! \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. +/*! + \fn bool BList::AddItem(void* item, int32 index) + \brief Add \a item at the specified \a index. + + \param item The \a item to add. + \param index The place in the list to add the \a item. + + \return Whether or not the item was added. \retval true The item was added. \retval false Item was not added. Either the index is negative or invalid, - or resizing the list failed. - \see AddItem(void *item) + or resizing the list failed. + + \see AddItem(void*) + + \since BeOS R3 */ -/*! - \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 false Item was not appended, since resizing the list failed. - \see AddItem(void *item, int32 index) +/*! + \fn bool BList::AddItem(void* item) + \brief Append the \a item to the end of the list. + + \param item The item to append. + + \return Whether or not the \a item was appended. + \retval true The \a item was appended. + \retval false \a item was not appended, since resizing the BList failed. + + \see AddItem(void*, int32) + + \since BeOS R3 */ + /*! - \fn bool BList::AddList(const BList *list, int32 index) - \brief Add items from another list to this list at a certain position. + \fn bool BList::AddList(const BList* list, int32 index) + \brief Add a \a list of items to this list at the specified \a index. Note that the \a 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. - \see AddList(const BList *list) + \param list The \a list to be added. + \param index The position in the current \a list where the new item(s) + are added. + + \return Whether or not the \a list was added. + \retval true The \a list was added. + \retval false Failed to insert the \a list resizing failed. + + \see AddList(const BList*) + + \since BeOS R3 */ + /*! - \fn bool BList::AddList(const BList *list) - \brief Append a list to this list. + \fn bool BList::AddList(const BList* list) + \brief Append a \a list of items to this list. Note that the \a list parameter is a \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 of - our list failed. - \see AddList(const BList *list, int32 index) + \param list The \a list to be added. + + \return Whether or not the \a list was added. + \retval true The \a list was appended. + \retval false Failed to append the list, resizing failed. + + \see AddList(const BList*, int32) + + \since BeOS R3 */ -/*! - \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. - \see RemoveItem(int32 index) +/*! + \fn bool BList::RemoveItem(void* item) + \brief Remove \a item from the list. + + \param item The \a item to be removed. + + \return Whether or not the \a item was removed. + \retval true The \a item was found and removed. + \retval false The \a item was not in this list and thus not removed. + + \see RemoveItem(int32) + + \since BeOS R3 */ + /*! - \fn void * BList::RemoveItem(int32 index) + \fn void* BList::RemoveItem(int32 index) \brief Remove the item at \a 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. - \see RemoveItem(void *item) + \param index The \a index of the item to be removed. + + \return The pointer to the item that was removed, or \c NULL if the + \a index was invalid. + + \see RemoveItem(void*) + + \since BeOS R3 */ + /*! \fn bool BList::RemoveItems(int32 index, int32 count) \brief Remove a number of items starting at a certain position. @@ -183,122 +272,171 @@ \param index The offset in the list where removal should start. \param count The number of items to remove. + + \return Whether or not the items were removed. \retval true Removal succeeded. \retval false Failed to remove the items because the index was invalid. + + \since BeOS R3 */ + /*! - \fn bool BList::ReplaceItem(int32 index, void *newItem) + \fn bool BList::ReplaceItem(int32 index, void* item) \brief Replace an 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. + \param index The offset in the list where to put the \a item. + \param item The new \a item to put in the list. + + \return Whether or not the item was replaced. + \retval true The item was replaced. + \retval false The \a index was invalid. + + \since Haiku R1 */ + /*! \fn void BList::MakeEmpty() \brief Clear all the items from the list. - Please note that this does not free the items. + \note This does not free the items. + + \since BeOS R3 */ + //! @} + /*! \name Reordering Items */ + //! @{ + /*! - \fn void BList::SortItems(int (*compareFunc)(const void *, const void *)) + \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. + + \since BeOS R3 */ + /*! \fn bool BList::SwapItems(int32 indexA, int32 indexB) - \brief Swap two items. + \brief Swap the items at \a indexA and \a indexB. \param indexA The first item. \param indexB The second item. + + \return Whether or not the items were swapped. \retval true Swap succeeded. \retval false Swap failed because one of the indexes was invalid. + + \since Haiku R1 */ + /*! \fn bool BList::MoveItem(int32 fromIndex, int32 toIndex) - \brief Move an item to a new place + \brief Move the item at \a fromIndex to the position of \a toIndex. This moves a list item from position A to position B, moving the appropriate block of list elements to make up for the move. For example, in the array: - \verbatim +\verbatim A B C D E F G H I J - \endverbatim +\endverbatim Moving 1(B)->6(G) would result in this: - \verbatim +\verbatim A C D E F G B H I J - \endverbatim +\endverbatim \param fromIndex The original location. \param toIndex The new location. + + \return Whether or not the items were moved. \retval true Move succeeded. \retval false Move failed due to the indexes being invalid. + + \since Haiku R1 */ + //! @} + /*! \name Retrieving Items */ + //! @{ + /*! - \fn void *BList::ItemAt(int32 index) const - \brief Get an item. + \fn void* BList::ItemAt(int32 index) const + \brief Return a pointer to the item at the given \a index. \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. + + \return A pointer to the item in that position, or \c NULL if the + \a index is out of bounds. + \see ItemAtFast(int32 index) const + + \since BeOS R3 */ + /*! - \fn void *BList::FirstItem() const - \brief Get the first item. + \fn void* BList::FirstItem() const + \brief Return a pointer to the first item in the list. \return A pointer to the first item or \c NULL if the list is empty. + \see LastItem() const + + \since BeOS R3 */ + /*! - \fn void *BList::ItemAtFast(int32 index) const - \brief Get an item. + \fn void* BList::ItemAtFast(int32 index) const + \brief Return a pointer to the item at \a index. This method does not perform any boundary checks when it retrieves an item. Use this method in a performance critical area of your program where you are sure you will not get an invalid item. \return A pointer to the item. + + \since Haiku R1 */ + /*! - \fn void *BList::LastItem() const - \brief Get the last item. + \fn void* BList::LastItem() const + \brief Return a pointer to the last item in the list. + \return A pointer to the last item or \c NULL if the list is empty. + \see FirstItem() const + + \since BeOS R3 */ + /*! - \fn void *BList::Items() const + \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 @@ -309,51 +447,80 @@ A C D E F G B H I J 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 and that you should avoid this method. - The list of objects does not belong to you. See also DoForEach() for an - alternate method. + objects, please realize that that probably means that what you + want to do is a bad idea to begin with and that you should avoid + this method. The list of objects does not belong to you. + \return The internal list of pointers. + + \sa DoForEach() for an alternate method. + + \since BeOS R3 */ + //! @} + /*! - \name Querying for Items + \name Querying 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. + \fn bool BList::HasItem(void* item) const + \brief Return whether or not \a item is in the list. + + \return \c true if the \a item was in the list, \c false otherwise. + + \since BeOS R3 +*/ + + +/*! + \fn int32 BList::IndexOf(void* item) const + \brief Return the index of \a item. \return The index of the item, or -1 when the item is not in the list. + + \since BeOS R3 */ + /*! \fn int32 BList::CountItems() const - \brief Get the number of items in the list. + \brief Returns the number of items in the list. + + \return The number of items in the list as an int32. + + \since BeOS R3 */ + /*! \fn bool BList::IsEmpty() const - \brief Check if there are items in the list. + \brief Return whether or not there are items in the list. + + \return \c true if the list was empty, \c false otherwise. + + \since BeOS R3 */ + //! @} + /*! - \name Iterating over the List + \name Iterating Over Items */ + //! @{ + /*! \fn void BList::DoForEach(bool (*func)(void* item)) \brief Perform an action on every item in the list. @@ -361,23 +528,31 @@ A C D E F G B H I J If one of the actions on the items fails it means that the \a func function returned \c false and the processing of the list will be stopped. - \param func A function that takes a \c void* argument and returns a - boolean. - \see DoForEach(bool (*func)(void* item, void* arg2), void *arg2) + \param func A pointer to a function that takes a \c void* argument and + returns a bool. + + \see DoForEach(bool (*func)(void*, void*), void*) + + \since BeOS R3 */ + /*! - \fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2) + \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 it means that the \a func function returned \c false and 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. + 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 \a func. - \see DoForEach(bool (*func)(void* item)) + + \see DoForEach(bool (*func)(void*)) + + \since BeOS R3 */ + //! @} diff --git a/docs/user/support/Locker.dox b/docs/user/support/Locker.dox index 84169516a6..5521b11580 100644 --- a/docs/user/support/Locker.dox +++ b/docs/user/support/Locker.dox @@ -1,15 +1,17 @@ /* - * Copyright 2007-2013 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Corresponds to: * headers/os/support/Locker.h rev 36218 * src/kits/support/Locker.cpp rev 32758 */ + /*! \file Locker.h \ingroup support @@ -25,7 +27,7 @@ \brief Semaphore-type class for thread safety. The BLocker interface is not merely a wrapper around a semaphore, but it - also has two advantages. First of all, it implements a benaphore. + also has two advantages. First of all, it implements a benaphore. A benaphore is in some ways more speed efficient, because before it uses the internal semaphore, it first checks against a variable that is only operated on with atomic operations. Setting a variable @@ -38,7 +40,7 @@ semaphore. You can imagine that in many cases where you protect of data that \em might be accessed by two or more concurrent threads, but the chances of it happening being very small, the benaphore benefits the - most from it's speed. + most from it's speed. The other feature of BLocker that improves basic semaphore handling is that it allows for recursive locks. The following piece of code works with a @@ -53,9 +55,8 @@ Flower::Grow(int length) fLength += length; fLock->Unlock(); return B_OK; - } else { + } else return B_ERROR; - } } status_t @@ -65,9 +66,8 @@ Flower::Water(int amount) status_t status = Grow(amount * 2); fLock->Unlock(); return status; - } else { + } else return B_ERROR; - } } \endcode @@ -75,71 +75,81 @@ Flower::Water(int amount) requests from the same thread. A normal semaphore would block in \c Grow() because the semaphore would be acquired already. Please do make sure you pair every Lock() with an Unlock() though, or you'll create a deadlock. + + \sa BAutolock + + \since BeOS R3 */ /*! \fn BLocker::BLocker() - \brief Constructor. + \brief Create a new BLocker with the default name "some BLocker" and + benaphore-style locking. - Create a new BLocker with the default name of some BLocker. This - BLocker will use the benaphore-style locking. + This BLocker will use the benaphore-style locking. \note For debugging purposes, it's extremely convenient to actually give a - name to the object. In case of a deadlock, it's easier to track down which - BLocker object might have caused the problems. + name to the object. In case of a deadlock, it's easier to track down + which BLocker object might have caused the problems. - \see BLocker(const char* name, bool benaphoreStyle) for all the options. + \see BLocker(const char*, bool) for all the options. + + \since BeOS R3 */ /*! \fn BLocker::BLocker(const char* name) - \brief Constructor. - - Create a new BLocker with benaphore-style locking. + \brief Creates a new BLocker with the given \a name and benaphore-style + locking. \param name A NULL-terminated string that contains the name of the - semaphore. Note that the length of the names are limited to - \c B_OS_NAME_LENGTH constant, which includes the \c \\0 - character. + semaphore. Note that the length of the names are limited to + \c B_OS_NAME_LENGTH constant, which includes the \c \\0 + character. \see BLocker(const char* name, bool benaphoreStyle) for all the options. + + \since BeOS R3 */ /*! \fn BLocker::BLocker(bool benaphoreStyle) - \brief Constructor. - - Creates a BLocker with the default name of some BLocker. + \brief Creates a BLocker with the default name "some BLocker" and the given + locking style. \note For debugging purposes, it's extremely convenient to actually give a - name to the object. In case of a deadlock, it's easier to track down - which BLocker object might have caused the problems. + name to the object. In case of a deadlock, it's easier to track down + which BLocker object might have caused the problems. \param benaphoreStyle If you pass \c true, the locker will be in benaphore - style (which is the default option for other constructors). If you - pass \c false, the object will completely rely on semaphores for - it's functioning. + style (which is the default option for other constructors). If you + pass \c false, the object will completely rely on semaphores for + it's functioning. \see BLocker(const char* name, bool benaphoreStyle) if you also want - to set a name. + to set a name. + + \since BeOS R4 */ /*! \fn BLocker::BLocker(const char* name, bool benaphoreStyle) - \brief Constructor. + \brief Creates a new BLocker with the given \a name and locking style. \param name A NULL-terminated string that contains the name of the - semaphore. Note that the length of the names are limited to - \c B_OS_NAME_LENGTH constant, which includes the \c \\0 - character. + semaphore. Note that the length of the names are limited to + \c B_OS_NAME_LENGTH constant, which includes the \c \\0 + character. \param benaphoreStyle If you pass \c true, the locker will be in benaphore - style (which is the default option for other constructors). If - you pass \c false, the object will completely rely on semaphores - for its functioning. + style (which is the default option for other constructors). If + you pass \c false, the object will completely rely on semaphores + for its functioning. + + \since BeOS R4 */ @@ -150,16 +160,20 @@ Flower::Water(int amount) Release the internal semaphore. Because of this, any pending Lock() calls from other threads be cancelled. The return code will be \c false for those calls. + + \since BeOS R3 */ /*! \fn status_t BLocker::InitCheck() const \brief Check whether the locker has properly initialized - - \retval B_OK The semaphore has been properly initialized - \retval (negative) Any other error value that is related to semaphore - initialization + + \return A status code, \c B_OK if the semaphore has been properly + initialized or any other error (negative) value related + to semaphore initialization. + + \since Haiku R1 */ @@ -169,10 +183,12 @@ Flower::Water(int amount) \retval true Lock acquired successfully. \retval false Failed to acquire the lock. Most probable cause is that the - object is deleted. This frees the semaphore and releases the - pending Lock() requests. + object is deleted. This frees the semaphore and releases the + pending Lock() requests. \see LockWithTimeout(bigtime_t timeout), Unlock() + + \since BeOS R3 */ @@ -181,22 +197,28 @@ Flower::Water(int amount) \brief Add a lock request and block until we get it or until it times out. \param timeout This is a timeout in microseconds (one millionth of a - second) relative to now. + second) relative to now. \see Lock(), Unlock() + + \since BeOS R3 */ /*! \fn void BLocker::Unlock(void) \brief Release the lock that's currently held. + + \since BeOS R3 */ /*! \fn thread_id BLocker::LockingThread(void) const \brief Return the \c thread_id of the thread that's currently holding the - lock. + lock. + + \since BeOS R3 */ @@ -204,21 +226,32 @@ Flower::Water(int amount) \fn bool BLocker::IsLocked(void) const \brief Check if the calling thread is actually holding the lock. + \return Whether or not the calling thread is holding the lock. \retval true The thread from which this method is called from is currently - holding the lock. + holding the lock. \retval false The object is unlocked or the lock is held by another thread. + + \since BeOS R3 */ /*! \fn int32 BLocker::CountLocks(void) const \brief Return the number of recursive locks that are currently held. + + \return the number of currently held recursive locks as an int32. + + \since BeOS R3 */ /*! - \fn nt32 BLocker::CountLockRequests(void) const + \fn int32 BLocker::CountLockRequests(void) const \brief Return the number of threads with a pending lock request. + + \return The number of threads with a pending lock request as an int32. + + \since BeOS R3 */ @@ -227,7 +260,12 @@ Flower::Water(int amount) \brief Return the sem_id of the semaphore this object holds. \warning Like any other internal objects that the Haiku API might expose, - this semaphore id should in general be left alone. You should not use any - of the public low-level semaphore functions on this semaphore, because it - will harm the internal consistency of the object. + this semaphore id should in general be left alone. You should not + use any of the public low-level semaphore functions on this + semaphore, because it will harm the internal consistency of the + object. + + \return The sem_id of the semaphore this object holds. + + \since BeOS R3 */ diff --git a/docs/user/support/ObjectList.dox b/docs/user/support/ObjectList.dox new file mode 100644 index 0000000000..871136f88f --- /dev/null +++ b/docs/user/support/ObjectList.dox @@ -0,0 +1,509 @@ +/* + * Copyright 2014 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * headers/os/support/ObjectList.h hrev40252 + */ + + +/*! + \file ObjectList.h + \ingroup support + \ingroup libbe + \brief Defines the BObjectList class. +*/ + + +/*! + \class BObjectList + \ingroup support + \ingroup libbe + \brief BObjectList is a wrapper around BList that adds type safety, + optional object ownership, search, and insert operations. + + \since Haiku R1 +*/ + + +/*! + \fn template BObjectList::BObjectList(int32 itemsPerBlock, + bool owning) + \brief Creates a new BObjectList. + + \param itemsPerBlock The number of items per block to allocate. + \param owning Whether or not the BObjectList deletes its items when + it is emptied or deleted. + + \since Haiku R1 +*/ + + +/*! + \fn template BObjectList::BObjectList( + const BObjectList& list) + \brief Creates a new BObjectList as a copy of another \a list. + + \param list The \a list to copy from. + + \since Haiku R1 +*/ + + +/*! + \fn template BObjectList::~BObjectList() + \brief Deletes the list. + + If the list owns its items they are deleted too. + + \since Haiku R1 +*/ + + +/*! + \name Operators +*/ + + +//! @{ + + +/*! + \fn template BObjectList& BObjectList::operator=( + const BObjectList& list) + \brief Creates a new BObjectList as a copy of another \a list by + overloading the = operator. + + \param list The \a list to copy from. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \name Adding and Removing Items +*/ + + +//! @{ + + +/*! + \fn template bool BObjectList::AddItem(T* item) + \brief Append the \a item to the end of the list. + + \param item The \a item to append. + + \return Whether or not the \a item was appended. + \retval true The \a item was appended. + \retval false \a item was not appended, since resizing the BObjectList + failed. + + \since Haiku R1 +*/ + + +/*! + \fn template bool BObjectList::AddItem(T* item, int32 index) + \brief Add \a item at the specified \a index. + + \param item The \a item to add. + \param index The place in the list to add the \a item. + + \return Whether or not the item was added. + \retval true The item was added. + \retval false Item was not added. Either the index is negative or invalid, + or resizing the BObjectList failed. + + \since Haiku R1 +*/ + + +/*! + \fn template bool BObjectList::AddList(BObjectList* list) + \brief Append a \a list of items to this list. + + The original list is not altered. + + \param list The \a list to be added. + + \return Whether or not the \a list was added. + \retval true The \a list was added. + \retval false Failed to append the list, resizing failed. + + \since Haiku R1 +*/ + + +/*! + \fn template bool BObjectList::AddList(BObjectList* list, + int32 index) + \brief Add a \a list of items to this list at the specified \a index. + + The original list is not altered. + + \param list The \a list to be added. + \param index The position in the current \a list where the new item(s) are + added. + + \return Whether or not the \a list was added. + \retval true The \a list was added. + \retval false Failed to insert the \a list resizing failed. + + \since Haiku R1 +*/ + + +/*! + \fn template bool BObjectList::RemoveItem(T* item, + bool deleteIfOwning) + \brief Remove \a item from the list. + + \param item The \a item to be removed. + \param deleteIfOwning Also delete the \a item if owned. + + \return Whether or not the \a item was removed. + \retval true The \a item was found and removed. + \retval false The \a item was not in this list and thus not removed. + + \since Haiku R1 +*/ + + +/*! + \fn template T* BObjectList::RemoveItemAt(int32 index) + \brief Remove the item at \a index from the list. + + \param index The \a index of the item to be removed. + + \return The pointer to the item that was removed, or \c NULL if the + \a index was invalid. + + \since Haiku R1 +*/ + + +/*! + \fn template inline T* BObjectList::ItemAt(int32 index) const + \brief Return a pointer to the item at the given \a index. + + \param index The item to retrieve. + + \return A pointer to the item in that position, or \c NULL if the + \a index is out of bounds. + + \since Haiku R1 +*/ + + +/*! + \fn template bool BObjectList::ReplaceItem(int32 index, T* item) + \brief Replace an item with another one. + + \param index The offset in the list where to put the \a item. + \param item The new \a item to put in the list. + + \return Whether or not the item was replaced. + \retval true The item was replaced. + \retval false The \a index was invalid. + + \since Haiku R1 +*/ + + +/*! + \fn template void BObjectList::MakeEmpty(bool deleteIfOwning) + \brief Clear all the items from the list. + + \param deleteIfOwning Also deletes items if owned. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \name Reordering Items +*/ + + +//! @{ + + +/*! + \fn template T* BObjectList::SwapWithItem(int32 index, T* item) + \brief Swap the \a item with the item at \a index. + + \param index The offset in the list where to put the \a item. + \param item The new \a item to put in the list. + + \return A pointer to the item in that position, or \c NULL if the + \a index is out of bounds. + + \since Haiku R1 +*/ + + +/*! + \fn template bool BObjectList::MoveItem(int32 from, int32 to) + \brief Move the item at \a from to the position of \a to. + + \param from The index to move the item \a from. + \param to The index to move the item \a to. + + \return Whether or not the items were moved. + \retval true The items were moved. + \retval false The \a from or \a to index was invalid. + + \see BList::MoveItem() + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \name Querying Items +*/ + + +//! @{ + + +/*! + \fn template int32 BObjectList::IndexOf(const T* item) const + \brief Return the index of \a item. + + \return The index of the item, or -1 when the item is not in the list. + + \since Haiku R1 +*/ + + +/*! + \fn template T* BObjectList::FirstItem() const + \brief Return a pointer to the first item in the list. + + \return A pointer to the first item or \c NULL if the list is empty. + + \see BObjectList::LastItem() const + + \since Haiku R1 +*/ + + +/*! + \fn template T* BObjectList::LastItem() const + \brief Return a pointer to the last item in the list. + + \return A pointer to the last item or \c NULL if the list is empty. + + \see BObjectList::FirstItem() const + + \since Haiku R1 +*/ + + +/*! + \fn template bool BObjectList::HasItem(const T* item) const + \brief Return whether or not \a item is in the list. + + \return \c true if the \a item was in the list, \c false otherwise. + + \since Haiku R1 +*/ + + +/*! + \fn template bool BObjectList::IsEmpty() const + \brief Return whether or not there are items in the list. + + \return \c true if the list was empty, \c false otherwise. + + \since Haiku R1 +*/ + + +/*! + \fn template int32 BObjectList::CountItems() const + \brief Returns the number of items in the list. + + \return The number of items in the list as an int32. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \name Iterating Over Items +*/ + + +//! @{ + + +/*! + \fn template T* BObjectList::EachElement(EachFunction func, + void* params) + \brief Perform an action on each item in the list. + + \param func A function that takes a \c void* argument and returns a + boolean. + \param params parameters for \a func. + + \return A pointer to the item. + + \since Haiku R1 +*/ + + +/*! + \fn template const T* BObjectList::EachElement( + ConstEachFunction func, void* params) const + \brief Perform an action on each item in the list. + + \param func A function that takes a \c void* argument and returns a + boolean. + \param params parameters for \a func. + + \return A pointer to the item. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \name Finding Items +*/ + + +//! @{ + + +/*! + \fn template const T* BObjectList::FindIf( + const UnaryPredicate& predicate) const + \brief Find items that match \a predicate. + + \return A const pointer to T. + + \since Haiku R1 +*/ + + +/*! + \fn template T* BObjectList::FindIf( + const UnaryPredicate& predicate) + \brief Find items that match \a predicate. + + \return A pointer to T. + + \since Haiku R1 +*/ + + +/*! + \fn template T* BObjectList::BinarySearch(const T& key, + CompareFunction func) const + \brief Search for \a key in the list of items using the supplied comparison + function via a binary search algorithm. + + \param key The \a key to search for. + \param func The comparison function to use. + + \return A pointer to T. + + \since Haiku R1 +*/ + + +/*! + \fn template T* BObjectList::BinarySearch(const T& key, + CompareFunctionWithState func, void* state) const + \brief Search for \a key in the list of items using the supplied comparison + function via a binary search algorithm. + + \param key The \a key to search for. + \param func The comparison function to use. + \param state Additional information used to search for the item. + + \return A pointer to T. + + \since Haiku R1 +*/ + + +//! @} + + +/*! + \name Reordering Items +*/ + + +//! @{ + + +/*! + \fn template void BObjectList::SortItems( + CompareFunction function) + \brief Sort the items with the use of a supplied comparison \a function. + + \param function The \a function used to sort the items. + + \since Haiku R1 +*/ + + +/*! + \fn template void BObjectList::SortItems( + CompareFunctionWithState function, void* state) + \brief Sort the items with the use of a supplied comparison \a function and + addtional \a state. + + \param function The \a function used to sort the items. + \param state Additional information used to sort the items. + + \since Haiku R1 +*/ + + +/*! + \fn template void BObjectList::HSortItems( + CompareFunction function) + \brief Sort the items with the use of a supplied comparison \a function. + + \param function The \a function used to sort the items. + + \since Haiku R1 +*/ + + +/* + \fn template void BObjectList::HSortItems( + CompareFunctionWithState function, void* state) + + \param function The \a function used to sort the items. + \param state Additional information used to sort the items. + + \since Haiku R1 +*/ + + +//! @} diff --git a/docs/user/support/StopWatch.dox b/docs/user/support/StopWatch.dox index 1974a49080..9db21df0cb 100644 --- a/docs/user/support/StopWatch.dox +++ b/docs/user/support/StopWatch.dox @@ -1,5 +1,5 @@ /* - * Copyright 2007 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Documentation written by: @@ -37,11 +37,13 @@ Reset() to reset the timer back to 0 clearing all lap info. When the object is destroyed the timing information is streamed to standard out unless you set the \a silent parameter to \c true in the constructor. + + \since BeOS R3 */ /*! - \fn BStopWatch::BStopWatch(const char *name, bool silent) + \fn BStopWatch::BStopWatch(const char* name, bool silent) \brief Constructs a BStopWatch object and starts the timer. This method creates a new BStopWatch object. As soon as the object is @@ -55,6 +57,8 @@ anonymous stop watch. \param silent Pass \c true to suppress time information from streaming to standard output when the object is destroyed. + + \since BeOS R3 */ @@ -64,6 +68,8 @@ If \a silent was set to \c false in the constructor then this method will print elapsed time information to standard output. + + \since BeOS R3 */ @@ -72,6 +78,8 @@ \brief Resume the timer from a suspended state. \see Suspend() + + \since BeOS R3 */ @@ -80,6 +88,8 @@ \brief Suspend the timer. \see Resume() + + \since BeOS R3 */ @@ -97,6 +107,8 @@ the time that has passed since the last lap). Any call to Lap() beyond the 10th lap will overwrite the last value. Calling Lap() while the timer is suspended does nothing and returns 0. + + \since BeOS R3 */ @@ -105,6 +117,8 @@ \brief Gets the elapsed time the object has counted. \return The elapsed time in microseconds. + + \since BeOS R3 */ @@ -114,6 +128,8 @@ Resets the stop watch clearing the start time and stored laps and restarts the timer. + + \since BeOS R3 */ @@ -125,4 +141,6 @@ string. \return the name of the stop watch set in the constructor. + + \since BeOS R3 */ diff --git a/docs/user/support/String.dox b/docs/user/support/String.dox index 327ae4dc93..935ded3554 100644 --- a/docs/user/support/String.dox +++ b/docs/user/support/String.dox @@ -1,11 +1,12 @@ /* - * Copyright 2007-2011 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * Stefano Ceccherini, burton666@freemail.it * Marc Flerackers, mflerackers@androme.be * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * Oliver Tappe, openbeos@hirschaefer.de * * Corresponds to: @@ -13,14 +14,16 @@ * src/kits/support/String.cpp rev 42682 */ + /*! \file String.h \ingroup support \ingroup libbe \brief Defines the BString class and global operators and functions for - handling strings. + handling strings. */ + /*! \class BString String.h \ingroup support @@ -39,38 +42,52 @@ BString::CopyCharsInto() methods. The main difference is that if there are any position argumens, the regular method counts the bytes and the Chars methods counts characters. + + \since BeOS R5 */ /*! \fn BString::BString() \brief Creates an empty BString. + + \since BeOS R5 */ /*! \fn BString::BString(const char* string) - \brief Creates and initializes a BString from a \a string. + \brief Creates and initializes a BString from \a string. + + \param string The \a string to copy from. + + \since BeOS R5 */ /*! - \fn BString::BString(const BString &string) - \brief Creates and initializes a BString from another BString. + \fn BString::BString(const BString& string) + \brief Creates and initializes a BString as a copy of another \a string. + + \param string The BString object to copy from. + + \since BeOS R5 */ /*! - \fn BString::BString(const char *string, int32 maxLength) + \fn BString::BString(const char* string, int32 maxLength) \brief Creates and initializes a BString from a \a string up to - \a maxLength characters. + \a maxLength characters. If \a maxLength is greater than the length of the source \a string then the entire source \a string is copied. If \a maxLength is less than or equal to 0 then the result is an empty BString. \warning In BeOS R5 passing in a negative \a maxLength argument will copy - the entire \a string. + the entire \a string. + + \since BeOS R5 */ @@ -79,11 +96,13 @@ \brief Free all resources associated with the object. The destructor also frees the internal buffer associated with the string. + + \since BeOS R5 */ /*! - \name Access Methods + \name Access */ @@ -102,6 +121,8 @@ have a look at LockBuffer(). \return A pointer to the object string. + + \since BeOS R5 */ @@ -110,7 +131,10 @@ \brief Get the length of the string in bytes. \return An integer with the length of the string, measured in bytes. + \sa CountChars() + + \since BeOS R5 */ @@ -122,7 +146,10 @@ the actual number of characters in the string. \return An integer which is the number of characters in the string. + \sa Length() + + \since BeOS R5 */ @@ -135,13 +162,15 @@ the string contains. \warning This method does not check whether the input is outside of the - boundaries, so make sure that you check your input values. + boundaries, so make sure that you check your input values. - \param fromCharOffset The index of the character (not the byte!) from - which to start the count + \param fromCharOffset The index of the character (not the byte!) from + which to start the count \param charCount The number of characters to count \return An integer with the number of bytes. + + \since Haiku R1 */ @@ -150,6 +179,8 @@ \brief Check whether the string is empty. \return Returns \c true if the string is empty. + + \since Haiku R1 */ @@ -157,7 +188,9 @@ \fn uint32 BString::HashValue() const \brief Return a hash value for the current string - \sa HashValue(const char *string) + \sa HashValue(const char*) + + \since Haiku R1 */ @@ -171,6 +204,8 @@ \param string The string that you want to have hashed. \sa HashValue() + + \since Haiku R1 */ @@ -178,7 +213,7 @@ /*! - \name Assignment Methods + \name Assignment 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 @@ -192,23 +227,27 @@ /*! - \fn BString& BString::operator=(const BString &string) + \fn BString& BString::operator=(const BString& string) \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) + \sa Adopt(BString&) + \sa SetTo(const BString&, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::operator=(const char *str) + \fn BString& BString::operator=(const char* str) \brief Re-initialize the object to a copy of the data of a string. - \sa SetTo(const char *str, int32 maxLength) + \sa SetTo(const char*, int32) + + \since BeOS R5 */ @@ -217,48 +256,56 @@ \brief Re-initialize the object to a character. \param c The character which you want to initialize the string to. + + \since BeOS R5 */ /*! - \fn BString& BString::SetTo(const char *str) + \fn BString& BString::SetTo(const char* str) \brief Re-initialize the object to a copy of the data of a string. - This method calls operator=(const char *str). + This method calls operator=(const char*). - \sa SetTo(const char *str, int32 maxLength) + \sa SetTo(const char*, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::SetTo(const char *str, int32 maxLength) + \fn BString& BString::SetTo(const char* str, int32 maxLength) \brief Re-initialize the object to a copy of the data of a string. \param str The string to copy. \param maxLength Amount of characters to copy from the string. - \sa operator=(const char *str) + \sa operator=(const char*) + + \since BeOS R5 */ /*! - \fn BString& BString::SetTo(const BString &from) + \fn BString& BString::SetTo(const BString& from) \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) + \sa SetTo(const BString&, int32) + \sa Adopt(BString&) + + \since BeOS R5 */ /*! - \fn BString& BString::Adopt(BString &from) + \fn BString& BString::Adopt(BString& from) \brief Adopt the data of the given BString object. - This method adopts the data from a BString. + This method adopts the data from a BString. \note The object that is adopted from is not deleted, only its private data is initialized to a \c NULL string. So if the from object was @@ -268,12 +315,14 @@ \return The function always returns \c *this. - \sa operator=(const BString &string) + \sa operator=(const BString&) + + \since BeOS R5 */ /*! - \fn BString& BString::SetTo(const BString &string, int32 maxLength) + \fn BString& BString::SetTo(const BString& string, int32 maxLength) \brief Re-initialize the string to a copy of the given BString object. \param string The BString object to copy. @@ -281,29 +330,33 @@ \return The function always returns \c *this. - \sa operator=(const BString &string) - \sa Adopt(BString &from, int32 maxLength) + \sa operator=(const BString&) + \sa Adopt(BString&, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::Adopt(BString &from, int32 maxLength) + \fn BString& BString::Adopt(BString& from, int32 maxLength) \brief Adopt the data of the given BString object up to \a maxLength - characters. + characters. \param from The string object to adopt. \param maxLength Number of characters to adopt from the original BString. \return The function always returns \c *this. - \sa SetTo(const BString &string, int32 maxLength) + \sa SetTo(const BString&, int32) + + \since BeOS R5 */ /*! \fn BString& BString::SetTo(char c, int32 count) \brief Re-initialize the object to a string composed of a character you - specify. + specify. This method lets you specify the length of a string and what character you want the string to contain repeatedly. @@ -314,30 +367,40 @@ \return The function always returns \c *this. \sa operator=(char c) + + \since BeOS R5 */ /*! - \fn BString& BString::SetToChars(const char *string, int32 charCount) - \brief Undocumented + \fn BString& BString::SetToChars(const char* string, int32 charCount) + \brief Undocumented. + + \since Haiku R1 */ /*! \fn BString& BString::SetToChars(const BString& string, int32 charCount) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! \fn BString& BString::AdoptChars(BString& from, int32 charCount) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! - \fn BString& BString::SetToFormat(const char *format, ...) - \brief Undocumented + \fn BString& BString::SetToFormat(const char* format, ...) + \brief Undocumented. + + \since Haiku R1 */ @@ -353,7 +416,7 @@ /*! - \fn BString &BString::CopyInto(BString &into, int32 fromOffset, + \fn BString& BString::CopyInto(BString& into, int32 fromOffset, int32 length) const \brief Copy the object's data (or part of it) into another BString. @@ -366,12 +429,14 @@ \param length The amount of bytes to copy. \return This method always returns a pointer to the string passed as the - \c into parameter. + \c into parameter. + + \since BeOS R5 */ /*! - \fn void BString::CopyInto(char *into, int32 fromOffset, int32 length) const + \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 @@ -383,20 +448,39 @@ \param into The buffer where to copy the object. \param fromOffset The (zero-based) offset where to begin the copy. \param length The amount of bytes to copy. + + \since BeOS R5 */ /*! \fn BString& BString::CopyCharsInto(BString& into, int32 fromOffset, int32 charCount) const - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! \fn bool BString::CopyCharsInto(char* into, int32* intoLength, int32 fromCharOffset, int32 charCount) const - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 +*/ + + +/*! + \fn bool BString::Split(const char* separator, bool noEmptyStrings, + BStringList& _list) const + \brief Split the string by the \a separator chars into \a _list. + + \param separator The list of \a separator characters to split on. + \param noEmptyStrings If \c true, do not add empty strings to \a _list. + \param _list The BStringList to add the strings into. + + \since Haiku R1 */ @@ -404,7 +488,7 @@ /*! - \name Appending Methods + \name Appending */ @@ -412,26 +496,30 @@ /*! - \fn BString & BString::operator+=(const BString &string) + \fn BString& BString::operator+=(const BString& string) \brief Append the given string to the object - \param string The string to append + \param string The string to append. \return This method always returns \c *this. - \sa Append(const BString &string, int32 length) + \sa Append(const BString&, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::operator+=(const char *str) + \fn BString& BString::operator+=(const char* str) \brief Append the given string to the object. \param str A pointer to the NULL-terminated string to append. \return This method always returns \c *this. - \sa Append(const char *str, int32 length) + \sa Append(const char*, int32) + + \since BeOS R5 */ @@ -443,67 +531,75 @@ \return This method always returns \c *this. - \sa Append(char c, int32 count) + \sa Append(char, int32) */ /*! - \fn BString & BString::operator+=(const BString &string) - \brief Append the given string to the object + \fn BString& BString::operator+=(const BString& string) + \brief Append the given string to the object. - \param string The string to append + \param string The string to append. \return This method always returns \c *this. - \sa Append(const BString &string, int32 length) + \sa Append(const BString&, int32) */ /*! - \fn BString &BString::Append(const BString &string) - \brief Append the given string to the object + \fn BString& BString::Append(const BString&) + \brief Append the given string to the object. - \param string The string to append + \param string The string to append. \return This method always returns \c *this. - \sa Append(const BString &string, int32 length) + \sa Append(const BString&, int32) + + \since BeOS R5 */ /*! - \fn BString &BString::Append(const char *str) + \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) + \sa Append(const char*, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::Append(const BString &string, int32 length) + \fn BString& BString::Append(const BString& string, int32 length) \brief Append a part of the given BString to the object. \param string The BString to append. - \param length The maximum number ofbytes to get from the original object. + \param length The maximum number of bytes to get from the original. \return This method always returns \c *this. - \sa operator+=(const BString &string) + \sa operator+=(const BString&) + + \since BeOS R5 */ /*! - \fn BString& BString::Append(const char *str, int32 length) - \brief Append a part of the given string to the object. + \fn BString& BString::Append(const char* str, int32 length) + \brief Append a part of the given string to the BString. \param str A pointer to the string to append. \param length The maximum bytes to get from the original string. \return This method always returns \c *this. - \sa operator+=(const char *str) + \sa operator+=(const char*) + + \since BeOS R5 */ @@ -517,18 +613,24 @@ \return This method always returns \c *this. \sa operator+=(char c) + + \since BeOS R5 */ /*! \fn BString& BString::AppendChars(const BString& string, int32 charCount) - \brief undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! - \fn BString& BString::AppendChars(const char *string, int32 charCount) - \brief undocumented + \fn BString& BString::AppendChars(const char* string, int32 charCount) + \brief Undocumented. + + \since Haiku R1 */ @@ -536,7 +638,7 @@ /*! - \name Prepending Methods + \name Prepending */ @@ -544,75 +646,89 @@ /*! - \fn BString& BString::Prepend(const char *str) - \brief Prepend the given string to the object. + \fn BString& BString::Prepend(const char* str) + \brief Prepend the given string to the BString. \param str A pointer to the string to prepend. \return This method always returns \c *this. - \sa Prepend(const char *str, int32 length) + \sa Prepend(const char*, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::Prepend(const BString &string) + \fn BString& BString::Prepend(const BString& string) \brief Prepend the given BString to the object. \param string The BString object to prepend. \return This method always returns \c *this. - \sa Prepend(const BString &string, int32 len) + \sa Prepend(const BString&, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::Prepend(const char *str, int32 length) - \brief Prepend the given string to the object. + \fn BString& BString::Prepend(const char* str, int32 length) + \brief Prepend the given string to the BString. \param str A pointer to the string to prepend. \param length The maximum amount of bytes to get from the string. \return This method always returns \c *this. - \sa Prepend(const char *str) + \sa Prepend(const char*) + + \since BeOS R5 */ /*! - \fn BString& BString::Prepend(const BString &string, int32 length) + \fn BString& BString::Prepend(const BString& string, int32 length) \brief Prepend the given BString to the object. - \param string The BString object to prepend. + \param string The BString to prepend. \param length The maximum amount of bytes to get from the BString. \return This method always returns \c *this. - \sa Prepend(const BString &string) + \sa Prepend(const BString&) + + \since BeOS R5 */ /*! \fn BString& BString::Prepend(char c, int32 count) - \brief Prepend the given character repeatedly to the object. + \brief Prepend the given character \a count times to the BString. \param c The character to prepend. \param count The number of times this character should be prepended. \return This method always returns \c *this. + + \since BeOS R5 */ /*! - \fn BString& BString::PrependChars(const char *string, int32 charCount) - \brief undocumented + \fn BString& BString::PrependChars(const char* string, int32 charCount) + \brief Undocumented. + + \since Haiku R1 */ /*! \fn BString& BString::PrependChars(const BString& string, int32 charCount) - \brief undocumented + \brief Undocumented. + + \since Haiku R1 */ @@ -620,7 +736,7 @@ /*! - \name Inserting Methods + \name Inserting */ @@ -628,158 +744,186 @@ /*! - \fn BString& BString::Insert(const char *string, int32 position) + \fn BString& BString::Insert(const char* string, int32 position) \brief Insert the given string at the given position into the object's - data. + data. \param string A pointer to the string to insert. \param position The offset in bytes into the BString's data where to insert - the string. + the string. \return This method always returns \c *this. - \sa Insert(const char *string, int32 length, int32 position) - \sa Insert(const char *string, int32 fromOffset, int32 length, int32 position) + \sa Insert(const char*, int32, int32) + \sa Insert(const char*, int32, int32, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::Insert(const char *string, int32 length, int32 position) + \fn BString& BString::Insert(const char* string, int32 length, + int32 position) \brief Inserts the given string at the given position into the object's - data. + data. \param string A pointer to the string to insert. - \param length The amount of bytes to insert. - \param position The offset in bytes into the BString's data where to insert - the string. + \param length The amount of bytes to insert. + \param position The offset in bytes into the data of the BString where to + insert the string. \return This method always returns \c *this. - \sa Insert(const char *string, int32 position) - \sa Insert(const char *string, int32 fromOffset, int32 length, int32 position) + \sa Insert(const char*, int32) + \sa Insert(const char*, int32, int32, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::Insert(const char *string, int32 fromOffset, + \fn BString& BString::Insert(const char* string, int32 fromOffset, int32 length, int32 position) \brief Insert the given string at the given position into the object's - data. + data. \param string A pointer to the string to insert. \param fromOffset The offset in the string that is to be inserted - \param length The amount of bytes to insert. - \param position The offset in bytes into the BString's data where to insert - the string. + \param length The amount of bytes to insert. + \param position The offset in bytes into the data of the BString where to + insert the string. \return This method always returns \c *this. - \sa Insert(const char *string, int32 position) - \sa Insert(const char *string, int32 length, int32 position) + \sa Insert(const char*, int32) + \sa Insert(const char*, int32, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::Insert(const BString &string, int32 position) + \fn BString& BString::Insert(const BString& string, int32 position) \brief Insert the given BString at the given position into the object's - data. + data. + \param string The BString object to insert. - \param position The offset in bytes into the BString's data where to insert - the string. + \param position The offset in bytes into the data of the BString where to + insert the string. \return This method always returns \c *this. - \sa Insert(const BString &string, int32 length, int32 position) - \sa Insert(const BString &string, int32 fromOffset, int32 length, int32 position) + \sa Insert(const BString&, int32, int32) + \sa Insert(const BString&, int32, int32, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::Insert(const BString &string, int32 length, int32 position) + \fn BString& BString::Insert(const BString& string, int32 length, int32 position) \brief Insert the given BString at the given position into the object's - data. + data. \param string The BString object to insert. \param length The amount of bytes to insert. - \param position The offset in bytes into the BString's data where to insert - the string. + \param position The offset in bytes into the data of the BString where to + insert the string. \return This method always returns \c *this. - \sa Insert(const BString &string, int32 position) - \sa Insert(const BString &string, int32 fromOffset, int32 length, int32 position) + \sa Insert(const BString&, int32) + \sa Insert(const BString&, int32, int32, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::Insert(const BString &string, int32 fromOffset, + \fn BString& BString::Insert(const BString& string, int32 fromOffset, int32 length, int32 position) \brief Insert the given string at the given position into the object's - data. + data. \param string The BString object to insert. \param fromOffset The offset in the string that is to be inserted \param length The amount of bytes to insert. - \param position The offset in bytes into the BString's data where to insert - the string. + \param position The offset in bytes into the data of the BString where to + insert the string. \return This method always returns \c *this. - \sa Insert(const BString &string, int32 position) - \sa Insert(const BString &string, int32 length, int32 position) + \sa Insert(const BString&, int32) + \sa Insert(const BString&, int32, int32) + + \since BeOS R5 */ /*! \fn BString& BString::Insert(char c, int32 count, int32 pos) - \brief Insert the given character repeatedly 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 number of times to insert the character. - \param pos The offset in bytes into the BString's data where to insert - the string. + \param pos The offset in bytes into the data of the BString where to + insert the string. \return This method always returns \c *this. + + \since BeOS R5 */ /*! - \fn BString& BString::InsertChars(const char *string, int32 charPosition) - \brief Undocumented + \fn BString& BString::InsertChars(const char* string, int32 charPosition) + \brief Undocumented. + + \since Haiku R1 */ /*! \fn BString& BString::InsertChars(const char* string, int32 charCount, int32 charPosition) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! \fn BString& BString::InsertChars(const char* string, int32 fromCharOffset, int32 charCount, int32 charPosition) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! \fn BString& BString::InsertChars(const BString& string, int32 charPosition) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! \fn BString& BString::InsertChars(const BString& string, int32 charCount, int32 charPosition) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! \fn BString& BString::InsertChars(const BString& string, int32 fromCharOffset, int32 charCount, int32 charPosition) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ @@ -787,7 +931,7 @@ /*! - \name Removing Methods + \name Removing */ @@ -802,12 +946,16 @@ \param lazy If true, the memory-optimization is postponed to later \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::TruncateChars(int32 newCharCount, bool lazy) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ @@ -819,124 +967,152 @@ \param length The number of bytes to remove \return This function always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::RemoveChars(int32 fromCharOffset, int32 charCount) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! - \fn BString& BString::RemoveFirst(const BString &string) + \fn BString& BString::RemoveFirst(const BString& string) \brief Remove the first occurrence of the given BString. \param string The BString to remove. \return This function always returns \c *this. + + \since BeOS R5 */ /*! - \fn BString& BString::RemoveLast(const BString &string) + \fn BString& BString::RemoveLast(const BString& string) \brief Remove the last occurrence of the given BString. \param string The BString to remove. \return This function always returns \c *this. + + \since BeOS R5 */ /*! - \fn BString& BString::RemoveAll(const BString &string) + \fn BString& BString::RemoveAll(const BString& string) \brief Remove all occurrences of the given BString. \param string The BString to remove. \return This function always returns \c *this. + + \since BeOS R5 */ /*! - \fn BString& BString::RemoveFirst(const char *string) + \fn BString& BString::RemoveFirst(const char* string) \brief Remove the first occurrence of the given string. \param string A pointer to the string to remove. \return This function always returns \c *this. + + \since BeOS R5 */ /*! - \fn BString& BString::RemoveLast(const char *string) + \fn BString& BString::RemoveLast(const char* string) \brief Remove the last occurrence of the given string. \param string A pointer to the string to remove. \return This function always returns \c *this. + + \since BeOS R5 */ /*! - \fn BString& BString::RemoveAll(const char *str) + \fn BString& BString::RemoveAll(const char* str) \brief Remove all occurrences of the given string. \param str A pointer to the string to remove. \return This function always returns \c *this. + + \since BeOS R5 */ /*! - \fn BString& BString::RemoveSet(const char *setOfCharsToRemove) + \fn BString& BString::RemoveSet(const char* setOfCharsToRemove) \brief Remove all the characters specified. \param setOfCharsToRemove The set of characters to remove. \return This function always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::RemoveCharsSet(const char*setOfCharsToRemove) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! - \fn BString& BString::MoveInto(BString &into, int32 from, int32 length) + \fn BString& BString::MoveInto(BString& into, int32 from, int32 length) \brief Move the BString data (or part of it) into another BString. - \param into The BString where to move the object. + \param into The BString where to move the string into. \param from The offset (zero-based) where to begin the move. - \param length The amount of bytes to move. + \param length The number of bytes to move. - \return This method always returns \c into . + \return This method always returns \c into. + + \since BeOS R5 */ /*! - \fn void BString::MoveInto(char *into, int32 from, int32 length) + \fn void BString::MoveInto(char* into, int32 from, int32 length) \brief Move the BString data (or part of it) into the given buffer. - \param into The buffer where to move the object. + \param into The buffer where to move the string into. \param from The offset (zero-based) where to begin the move. - \param length The amount of bytes to move. + \param length The number of bytes to move. + + \since BeOS R5 */ /*! - \fn BString& BString::MoveCharsInto(BString &into, int32 fromCharOffset, + \fn BString& BString::MoveCharsInto(BString& into, int32 fromCharOffset, int32 charCount) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! \fn bool BString::MoveCharsInto(char* into, int32* intoLength, int32 fromCharOffset, int32 charCount) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ @@ -944,7 +1120,7 @@ /*! - \name Comparison Methods + \name Comparison There are two different comparison methods. First of all there is the whole range of operators that return a boolean value, secondly @@ -963,242 +1139,299 @@ /*! - \fn bool BString::operator<(const BString &string) const - \brief Lexicographically compare if this string is less than a given string. + \fn bool BString::operator<(const BString& string) const + \brief Lexicographically compare if this BString is less than the given + \a string. - \param string The string to compare with. + \param string The \a string to compare against. + + \since BeOS R5 */ /*! - \fn bool BString::operator<=(const BString &string) const - \brief Lexicographically compare if this string is less than or equal to - a given string. + \fn bool BString::operator<=(const BString& string) const + \brief Lexicographically compare if this BString is less than or equal to + the given \a string. - \param string The string to compare with. + \param string The \a string to compare against. + + \since BeOS R5 */ /*! - \fn bool BString::operator==(const BString &string) const - \brief Lexicographically compare if this string is equal to a given string. + \fn bool BString::operator==(const BString& string) const + \brief Lexicographically compare if this BString is equal to the given + \a string. - \param string The string to compare with. + \param string The \a string to compare against. + + \since BeOS R5 */ /*! - \fn bool BString::operator>=(const BString &string) const + \fn bool BString::operator>=(const BString& string) const + \brief Lexicographically compare if this BString is greater than or equal + to the given \a string. + + \param string The string to compare against. + + \since BeOS R5 +*/ + + +/*! + \fn bool BString::operator>(const BString& string) const + \brief Lexicographically compare if this BString is greater than the given + \a string. + + \param string The string to compare against. + + \since BeOS R5 +*/ + + +/*! + \fn bool BString::operator!=(const BString& string) const + \brief Lexicographically compare if this BString is not equal to the given + \a string. + + \param string The string to compare against. + + \since BeOS R5 +*/ + + +/*! + \fn bool BString::operator<(const char* string) const + \brief Lexicographically compare if this BString is less than the given + \a string. + + \param string The string to compare against. + + \since BeOS R5 +*/ + + +/*! + \fn bool BString::operator<=(const char* string) const + \brief Lexicographically compare if this BString is less than or equal to + the given \a string. + + \param string The \a string to compare against. + + \since BeOS R5 +*/ + + +/*! + \fn bool BString::operator==(const char* string) const + \brief Lexicographically compare if this BString is equal to the given + \a string. + + \param string The \a string to compare against. + + \since BeOS R5 +*/ + + +/*! + \fn bool BString::operator>=(const char* string) const \brief Lexicographically compare if this string is more than or equal - to a given string. + to a given \a string. - \param string The string to compare with. + \param string The \a string to compare against. + + \since BeOS R5 */ /*! - \fn bool BString::operator>(const BString &string) const + \fn bool BString::operator>(const char* string) const \brief Lexicographically compare if this string is more than a given string. - \param string The string to compare with. + \param string The \a string to compare against. + + \since BeOS R5 */ /*! - \fn bool BString::operator!=(const BString &string) const + \fn bool BString::operator!=(const char* string) const \brief Lexicographically compare if this string is not equal to a given - string. + string. - \param string The string to compare with. -*/ + \param string The \a string to compare against. - -/*! - \fn bool BString::operator<(const char *string) const - \brief Lexicographically compare if this string is less than a given string. - - \param string The string to compare with. -*/ - - -/*! - \fn bool BString::operator<=(const char *string) const - \brief Lexicographically compare if this string is less than or equal to - a given string. - - \param string The string to compare with. -*/ - - -/*! - \fn bool BString::operator==(const char *string) const - \brief Lexicographically compare if this string is equal to a given string. - - \param string The string to compare with. -*/ - - -/*! - \fn bool BString::operator>=(const char *string) const - \brief Lexicographically compare if this string is more than or equal - to a given string. - - \param string The string to compare with. -*/ - - -/*! - \fn bool BString::operator>(const char *string) const - \brief Lexicographically compare if this string is more than a given string. - - \param string The string to compare with. -*/ - - -/*! - \fn bool BString::operator!=(const char *string) const - \brief Lexicographically compare if this string is not equal to a given - string. - - \param string The string to compare with. + \since BeOS R5 */ /*! \fn BString::operator const char*() const - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! - \fn int BString::Compare(const BString &string) const - \brief Lexicographically compare this string to another. + \fn int BString::Compare(const BString& string) const + \brief Lexicographically compare this BString to another \a string. - \param string The string to compare to. + \param string The \a string to compare against. - \retval >0 The object sorts lexicographically after \c string. - \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexicographically before \c string. + \return An int representing the strings relationship to each other. + \retval >0 The BString sorts lexicographically after \a string. + \retval =0 The BString is equal to \a string. + \retval <0 The BString sorts lexicographically before \a string. + + \since BeOS R5 */ /*! - \fn int BString::Compare(const char *string) const - \brief Lexicographically compare this string to another. + \fn int BString::Compare(const char* string) const + \brief Lexicographically compare this BString to another \a string. - \param string The string to compare to. + \param string The \a string to compare against. - \retval >0 The object sorts lexicographically after \c string. - \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexicographically before \c string. + \return An int representing the strings relationship to each other. + \retval >0 The BString sorts lexicographically after \a string. + \retval =0 The BString is equal to \a string. + \retval <0 The BString sorts lexicographically before \a string. - \sa Compare(const BString &string) const + \sa Compare(const BString&) const + + \since BeOS R5 */ /*! - \fn int BString::Compare(const BString &string, int32 length) const - \brief Lexicographically compare a number of characters of a string to - another. + \fn int BString::Compare(const BString& string, int32 length) const + \brief Lexicographically compare \a length characters of this BString to + another \a string. - \param string The string to compare to. - \param length The number of characters to compare - - \retval >0 The object sorts lexicographically after \c string. - \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexicographically before \c string. -*/ - - -/*! - \fn int BString::Compare(const char *string, int32 length) const - \brief Lexicographically compare a number of characters of a string to - another. - - \param string The string to compare to. + \param string The \a string to compare against. \param length The number of characters to compare. - \retval >0 The object sorts lexicographically after \c string. - \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexicographically before \c string. + \return An int representing the strings relationship to each other. + \retval >0 The BString sorts lexicographically after \a string. + \retval =0 The BString is equal to \a string. + \retval <0 The BString sorts lexicographically before \a string. - \sa Compare(const BString &string, int32 n) const + \since BeOS R5 */ /*! - \fn int BString::CompareChars(const BString& string, - int32 charCount) const - \brief Undocumented + \fn int BString::Compare(const char* string, int32 length) const + \brief Lexicographically compare \a length characters of this BString to + another \a string. + + \param string The \a string to compare against. + \param length The number of characters to compare. + + \return An int representing the strings relationship to each other. + \retval >0 The BString sorts lexicographically after \a string. + \retval =0 The BString is equal to \a string. + \retval <0 The BString sorts lexicographically before \a string. + + \sa Compare(const BString&, int32) const + + \since BeOS R5 */ /*! - \fn int BString::CompareChars(const char *string, - int32 charCount) const - \brief Undocumented + \fn int BString::CompareChars(const BString& string, int32 charCount) const + \brief Undocumented. + + \since Haiku R1 */ /*! - \fn int BString::ICompare(const BString &string) const - \brief Lexicographically compare a string to another in a - case-insensitive way. + \fn int BString::CompareChars(const char* string, int32 charCount) const + \brief Undocumented. - \param string The string to compare to. + \since Haiku R1 +*/ - \retval >0 The object sorts lexicographically after \c string. - \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexicographically before \c string. - \sa Compare(const BString &string) const +/*! + \fn int BString::ICompare(const BString& string) const + \brief Lexicographically compare this BString to another \a string + case-insensitively. + + \param string The \a string to compare against. + + \return An int representing the strings relationship to each other. + \retval >0 The BString sorts lexicographically after \a string. + \retval =0 The BString is equal to \a string. + \retval <0 The BString sorts lexicographically before \a string. + + \sa Compare(const BString&) const + + \since BeOS R5 */ /*! \fn int BString::ICompare(const char* string) const - \brief Lexicographically compare this string to another in a - case-insensitive way. + \brief Lexicographically compare this BString to another \a string + case-insensitively. - \param string The string to compare to. + \param string The \a string to compare against. - \retval >0 The object sorts lexicographically after \c string. - \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexicographically before \c string. + \return An int representing the strings relationship to each other. + \retval >0 The BString sorts lexicographically after \a string. + \retval =0 The BString is equal to \a string. + \retval <0 The BString sorts lexicographically before \a string. - \sa Compare(const BString &string) const + \sa Compare(const BString&) const + + \since BeOS R5 */ /*! \fn int BString::ICompare(const BString& string, int32 length) const - \brief Lexicographically compare a number of characters of this string - to another. + \brief Lexicographically compare \a length characters of this BString + to another \a string. - \param string The string to compare to. - \param length The number of characters to compare + \param string The \a string to compare against. + \param length The number of characters to compare. - \retval >0 The object sorts lexicographically after \c string. - \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexicographically before \c string. + \return An int representing the strings relationship to each other. + \retval >0 The BString sorts lexicographically after \a string. + \retval =0 The BString is equal to \a string. + \retval <0 The BString sorts lexicographically before \a string. - \sa Compare(const BString &string, int32 length) const + \sa Compare(const BString&, int32) const + + \since BeOS R5 */ /*! \fn int BString::ICompare(const char* string, int32 length) const - \brief Lexicographically compare a number of characters of this string - to another. + \brief Lexicographically compare \a length characters of this BString + to another \a string. - \param string The string to compare to. + \param string The \a string to compare against. \param length The number of characters to compare - \retval >0 The object sorts lexicographically after \c string. - \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexicographically before \c string. + \return An int representing the strings relationship to each other. + \retval >0 The BString sorts lexicographically after \a string. + \retval =0 The BString is equal to \a string. + \retval <0 The BString sorts lexicographically before \a string. - \sa Compare(const BString &string, int32 length) const + \sa Compare(const BString&, int32) const + + \since BeOS R5 */ @@ -1206,7 +1439,7 @@ /*! - \name Searching Methods + \name Searching */ @@ -1214,68 +1447,69 @@ /*! - \fn int32 BString::FindFirst(const BString &string) const - \brief Find the first occurrence of the given BString. + \fn int32 BString::FindFirst(const BString& string) const + \brief Find the first occurrence of the given \a string. - \param string The BString to search for. + \param string The \a string to search for. - \return The offset (zero-based) into the data where the given BString - has been found. + \return The offset (zero-based) into the data where the given BString + was found or \c B_ERROR if we could not find \c string. - \retval B_ERROR Could not find \c string. + \sa IFindFirst(const BString&) const - \sa IFindFirst(const BString &string) const + \since BeOS R5 */ /*! - \fn int32 BString::FindFirst(const char *string) const - \brief Find the first occurrence of the given string. + \fn int32 BString::FindFirst(const char* string) const + \brief Find the first occurrence of the given \a string. - \param string The string to search for. + \param string The \a string to search for. - \return The offset (zero-based) into the data where the given string - has been found. + \return The offset (zero-based) into the data where the given string + was found, \c B_BAD_VALUE if the \c string pointer is invalid, + or \c B_ERROR if we could not find \c string. - \retval B_BAD_VALUE The \c string pointer is invalid. - \retval B_ERROR Could not find \c string. + \sa IFindFirst(const char*) const - \sa IFindFirst(const char *string) const + \since BeOS R5 */ /*! - \fn int32 BString::FindFirst(const BString &string, int32 fromOffset) const - \brief Find the first occurrence of the given BString, starting from - the given offset. + \fn int32 BString::FindFirst(const BString& string, int32 fromOffset) const + \brief Find the first occurrence of the given \a string starting from + the given offset. - \param string The BString to search for. + \param string The \a string to search for. \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. + where the given BString was found or \c B_ERROR if we could + not find the \c string. - \retval B_ERROR Could not find \c string. + \sa IFindFirst(const BString&, int32) const - \sa IFindFirst(const BString &string, int32 fromOffset) const + \since BeOS R5 */ /*! - \fn int32 BString::FindFirst(const char *string, int32 fromOffset) const - \brief Find the first occurrence of the given string, - starting from the given offset. + \fn int32 BString::FindFirst(const char* string, int32 fromOffset) const + \brief Find the first occurrence of the given \a string, starting from the + given offset. - \param string The string to search for. + \param string The \a 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. + \return The offset (zero-based) into the data where the given string + was found, \c B_BAD_VALUE if the \c string pointer is invalid, + or \c B_ERROR if we could not find the \c string. - \retval B_BAD_VALUE The \c string pointer is invalid. - \retval B_ERROR Could not find \c string. + \sa IFindFirst(const char*, int32) const - \sa IFindFirst(const char *string, int32 fromOffset) const + \since BeOS R5 */ @@ -1285,104 +1519,109 @@ \param c The character to search for. - \return The offset (zero-based) into the data - where the given character has been found. + \return The offset (zero-based) into the data where the given character + was found, or \c B_ERROR if we could not find the character. - \retval B_ERROR Could not find \c c. + \since BeOS R5 */ /*! \fn int32 BString::FindFirst(char c, int32 fromOffset) const - \brief Find the first occurrence of the given character, - starting from the given offset. + \brief Find the first occurrence of the given character, starting from the + given offset. \param c The character to search for. \param fromOffset The offset where to start the search. - \return The offset (zero-based) into the data - where the given character has been found. + \return The offset (zero-based) into the data where the given character + was found, or \c B_ERROR if we could not find the character. - \retval B_ERROR Could not find \c c. + \since BeOS R5 */ /*! \fn int32 BString::FindFirstChars(const BString& string, int32 fromCharOffset) const - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! - \fn int32 BString::FindFirstChars(const char *string, + \fn int32 BString::FindFirstChars(const char* string, int32 fromCharOffset) const - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! - \fn int32 BString::FindLast(const BString &string) const - \brief Find the last occurrence of the given BString. + \fn int32 BString::FindLast(const BString& string) const + \brief Find the last occurrence of the given \a string. - \param string The BString to search for. + \param string The \a string to search for. \return The offset (zero-based) into the data where the given BString - has been found. + was found, or \c B_ERROR if we could not find the \c string. - \retval B_ERROR Could not find \c string. - \sa IFindLast(const BString &string) const + \sa IFindLast(const BString&) const + + \since BeOS R5 */ /*! - \fn int32 BString::FindLast(const char *string) const + \fn int32 BString::FindLast(const char* string) const \brief Find the last occurrence of the given string. \param string The string to search for. \return The offset (zero-based) into the data where the given string - has been found. + was found, \c B_BAD_VALUE if the \c string pointer is invalid, + or \c B_ERROR if we could not find the \c string. - \retval B_BAD_VALUE The \c string pointer is invalid. - \retval B_ERROR Could not find \c string. + \sa IFindLast(const char*) const - \sa IFindLast(const char *string) const -/*! + \since BeOS R5 +*/ /*! - \fn int32 BString::FindLast(const BString &string, int32 beforeOffset) const + \fn int32 BString::FindLast(const BString& string, int32 beforeOffset) const \brief Find the last occurrence of the given BString, starting from the given offset, and going backwards. \param string The BString to search for. \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. + \return The offset (zero-based) into the data where the given BString + was found, or \c B_ERROR if we could not find the \c string. - \retval B_ERROR Could not find \c string. + \sa IFindLast(const BString&, int32) const - \sa IFindLast(const BString &string, int32 beforeOffset) const + \since BeOS R5 */ /*! - \fn int32 BString::FindLast(const char *string, int32 beforeOffset) const + \fn int32 BString::FindLast(const char* string, 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 beforeOffset The offset where to start the search. - \return The offset (zero-based) into the data - where the given string has been found. + \return The offset (zero-based) into the data where the given string + was found, \c B_BAD_VALUE if the \c string pointer is invalid, + or \c B_ERROR if we could not find the \c string. - \retval B_BAD_VALUE The \c string pointer is invalid. - \retval B_ERROR Could not find \c string. + \sa IFindLast(const char*, int32) const - \sa IFindLast(const char *string, int32 beforeOffset) const + \since BeOS R5 */ @@ -1391,107 +1630,115 @@ \brief Find the last occurrence of the given character. \param c The character to search for. - \return The offset (zero-based) into the data where the given character - has been found. + \return The offset (zero-based) into the data where the given BString + was found, or \c B_ERROR if we could not find the character. - \retval B_ERROR Could not find \c c. + \since BeOS R5 */ /*! \fn int32 BString::FindLast(char c, int32 beforeOffset) const \brief Find the last occurrence of the given character, - starting from the given offset and going backwards. + starting from the given offset going backwards from the end. \param c The character to search for. \param beforeOffset The offset where to start the search. \return The offset (zero-based) into the data where the given character - has been found. + was found, or \c B_ERROR Could not find the character. - \retval B_ERROR Could not find \c c. + \since BeOS R5 */ /*! \fn int32 BString::FindLastChars(const BString& string, int32 beforeCharOffset) const - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 + + \since BeOS R5 */ /*! - \fn int32 BString::FindLastChars(const char *string, + \fn int32 BString::FindLastChars(const char* string, int32 beforeCharOffset) const - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! - \fn int32 BString::IFindFirst(const BString &string) const - \brief Find the first occurrence of the given BString case-insensitively. + \fn int32 BString::IFindFirst(const BString& string) const + \brief Find the first occurrence of the given \a string case-insensitively. - \sa FindFirst(const BString &string) const + \copydetails FindFirst(const BString&) const */ /*! - \fn int32 BString::IFindFirst(const char *string) const - \brief Find the first occurrence of the given BString case-insensitively. + \fn int32 BString::IFindFirst(const char* string) const + \brief Find the first occurrence of the given \a string case-insensitively. - \sa FindFirst(const char *string) const + \param string The \a string to search for. + + \copydetails FindFirst(const char*) const */ /*! - \fn int32 BString::IFindFirst(const BString &string, int32 fromOffset) 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. + starting from the given offset. - \sa FindFirst(const BString &string, int32 fromOffset) const + \copydetails FindFirst(const BString&, int32) const */ /*! - \fn int32 BString::IFindFirst(const char *string, int32 fromOffset) const + \fn int32 BString::IFindFirst(const char* string, int32 fromOffset) const \brief Find the first occurrence of the given string case-insensitively, - starting from the given offset. + starting from the given offset. - \sa FindFirst(const char *string, int32 fromOffset) const + \copydetails FindFirst(const char*, int32) const */ /*! - \fn int32 BString::IFindLast(const BString &string) 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 + \copydetails FindLast(const BString&) const */ /*! - \fn int32 BString::IFindLast(const char *string) const + \fn int32 BString::IFindLast(const char* string) const \brief Find the last occurrence of the given string case-insensitively. - \sa FindLast(const char *string) const + \copydetails FindLast(const char*) const */ /*! - \fn int32 BString::IFindLast(const BString &string, int32 beforeOffset) 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. + starting from the given offset going backwards. - \sa FindLast(const BString &string, int32 beforeOffset) const + \copydetails FindLast(const BString&, int32) const */ /*! - \fn int32 BString::IFindLast(const char *string, int32 beforeOffset) const + \fn int32 BString::IFindLast(const char* string, int32 beforeOffset) const \brief Find the last occurrence of the given string case-insensitively, - starting from the given offset, and going backwards. + starting from the given offset going backwards. - \sa FindLast(const char *string, int32 beforeOffset) const + \copydetails FindLast(const char*, int32) const */ @@ -1499,7 +1746,7 @@ /*! - \name Replacing Methods + \name Replacing */ @@ -1511,11 +1758,13 @@ \brief Replace the first occurrence of a character with another character. \param replaceThis The character to replace. - \param withThis The character to put in that place + \param withThis The character to put in its place. \return This method always returns \c *this. - \sa IReplaceFirst(char replaceThis, char withThis) + \sa IReplaceFirst(char, char) + + \since BeOS R5 */ @@ -1524,26 +1773,30 @@ \brief Replace the last occurrence of a character with another character. \param replaceThis The character to replace. - \param withThis The character to put in that place + \param withThis The character to put in its place \return This method always returns \c *this. - \sa ReplaceLast(char replaceThis, char withThis) + \sa IReplaceLast(char, char) + + \since BeOS R5 */ /*! - \fn BString& BString::ReplaceAll(char replaceThis, char withThis, + \fn BString& BString::ReplaceAll(char replaceThis, char withThis, int32 fromOffset) \brief Replace all occurrences of a character with another character. \param replaceThis The character to replace. - \param withThis The character to put in that place + \param withThis The character to put in its 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) + \sa IReplaceAll(char, char, int32) + + \since BeOS R5 */ @@ -1554,129 +1807,142 @@ character. \param replaceThis The character to replace. - \param withThis The character to put in that place + \param withThis The character to put in its place \param maxReplaceCount The maximum number of characters that should be - replaced. + 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) + \sa IReplace(char, char, int32, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::ReplaceFirst(const char *replaceThis, - const char *withThis) + \fn BString& BString::ReplaceFirst(const char* replaceThis, + const char* withThis) \brief Replace the first occurrence of a string with another string. \param replaceThis The string to replace. - \param withThis The string to put in that place + \param withThis The string to put in its place \return This method always returns \c *this. - \sa IReplaceFirst(const char *replaceThis, const char *withThis) + \sa IReplaceFirst(const char*, const char*) + + \since BeOS R5 */ /*! - \fn BString& BString::ReplaceLast(const char *replaceThis, - const char *withThis) + \fn BString& BString::ReplaceLast(const char* replaceThis, + const char* withThis) \brief Replace the last occurrence of a string with another string. \param replaceThis The string to replace. - \param withThis The string to put in that place + \param withThis The string to put in its place \return This method always returns \c *this. - \sa IReplaceLast(const char *replaceThis, const char *withThis) + \sa IReplaceLast(const char*, const char*) + + \since BeOS R5 */ /*! - \fn BString& BString::ReplaceAll(const char *replaceThis, - const char *withThis, int32 fromOffset) + \fn BString& BString::ReplaceAll(const char* replaceThis, + const char* withThis, int32 fromOffset) \brief Replace all occurrences of a string with another string. \param replaceThis The string to replace. - \param withThis The string to put in that place + \param withThis The string to put in its 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) + \sa IReplaceAll(const char*, const char*, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::Replace(const char *replaceThis, - const char *withThis, int32 maxReplaceCount, int32 fromOffset) + \fn BString& BString::Replace(const char* replaceThis, + const char* withThis, int32 maxReplaceCount, int32 fromOffset) \brief Replace a number of occurrences 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 withThis The string to put in its place + \param maxReplaceCount The maximum number of occurrences 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) + \sa IReplace(const char*, const char*, int32, int32) + + \since BeOS R5 */ /*! \fn BString& BString::ReplaceAllChars(const char* replaceThis, const char* withThis, int32 fromCharOffset) - \brief Undocumented + \brief Undocumented. */ /*! - \fn BString& BString::ReplaceChars(const char* replaceThis, const char* withThis, - int32 maxReplceCount, int32 fromCharOffset) - \brief Undocumented + \fn BString& BString::ReplaceChars(const char* replaceThis, + const char* withThis, int32 maxReplceCount, int32 fromCharOffset) + \brief Undocumented. */ /*! \fn BString& BString::IReplaceFirst(char replaceThis, char withThis) \brief Replace the first occurrence of a character with another - character. Case insensitive. + character case-insensitively. \param replaceThis The string to replace. - \param withThis The string to put in that place + \param withThis The string to put in its place - \sa ReplaceFirst(char replaceThis, char withThis) + \sa ReplaceFirst(char, char) + + \since BeOS R5 */ /*! \fn BString& BString::IReplaceLast(char replaceThis, char withThis) \brief Replace the last occurrence of a character with another - character. Case-insensitive. + character case-insensitively. \param replaceThis The string to replace. - \param withThis The string to put in that place + \param withThis The string to put in its place - \sa ReplaceLast(char replaceThis, char withThis) + \sa ReplaceLast(char, char) + + \since BeOS R5 */ /*! \fn BString& BString::IReplaceAll(char replaceThis, char withThis, - int32 fromOffset) - \brief Replace all occurrences of a character with another character. - Case-insensitive. + int32 fromOffset) + \brief Replace all occurrences of a character with another character + case-insensitively. \param replaceThis The string to replace. - \param withThis The string to put in that place + \param withThis The string to put in its place \param fromOffset The offset where to start looking for the string - \sa ReplaceAll(char replaceThis, char withThis, int32 fromOffset) + \sa ReplaceAll(char, char, int32) + + \since BeOS R5 */ @@ -1684,84 +1950,94 @@ \fn BString& BString::IReplace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) \brief Replace a number of occurrences of a character with another - character. Case-insensive. + character case-insensitively. \param replaceThis The char to replace. - \param withThis The char to put in that place - \param maxReplaceCount The maximum number of occurences that should - be replaced. + \param withThis The char to put in its place + \param maxReplaceCount The maximum number of occurrences that should + be replaced. \param fromOffset The offset where to start looking for the string - \sa Replace(char replaceThis, char withThis, int32 maxReplaceCount, - int32 fromOffset) + \sa Replace(char, char, int32, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::IReplaceFirst(const char *replaceThis, - const char *withThis) - \brief Replace the first occurrence of a string with another string. - Case-insensitive. + \fn BString& BString::IReplaceFirst(const char* replaceThis, + const char* withThis) + \brief Replace the first occurrence of a string with another string + case-insensitively. \param replaceThis The string to replace. - \param withThis The string to put in that place + \param withThis The string to put in its place. - \sa ReplaceFirst(const char *replaceThis, const char *withThis) + \sa ReplaceFirst(const char*, const char*) + + \since BeOS R5 */ /*! - \fn BString& BString::IReplaceLast(const char *replaceThis, - const char *withThis) + \fn BString& BString::IReplaceLast(const char* replaceThis, + const char* withThis) \brief Replace the last occurrence of a string with another string. Case-insensitive. \param replaceThis The string to replace. - \param withThis The string to put in that place + \param withThis The string to put in its place. - \sa ReplaceLast(const char *replaceThis, const char *withThis) + \sa ReplaceLast(const char*, const char*) + + \since BeOS R5 */ /*! - \fn BString& BString::IReplaceAll(const char *replaceThis, - const char *withThis, int32 fromOffset) - \brief Replace all occurrences of a string with another string. - Case-insensitive. + \fn BString& BString::IReplaceAll(const char* replaceThis, + const char* withThis, int32 fromOffset) + \brief Replace all occurrences of a string with another string + case-insensitively. \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 + \param withThis The string to put in its place. + \param fromOffset The offset where to start looking for the string. - \sa ReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) + \sa ReplaceAll(const char*, const char*, int32) + + \since BeOS R5 */ /*! - \fn BString& BString::IReplace(const char *replaceThis, - const char *withThis, int32 maxReplaceCount, int32 fromOffset) - \brief Replace a number of occurrences of a string with another string. - Case-insensitive. + \fn BString& BString::IReplace(const char* replaceThis, + const char* withThis, int32 maxReplaceCount, int32 fromOffset) + \brief Replace a number of occurrences of a string with another string + case-insensitively. \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 withThis The string to put in its place + \param maxReplaceCount The maximum number of occurrences that should + be replaced. \param fromOffset The offset where to start looking for the string - \sa Replace(const char *replaceThis, const char *withThis, - int32 maxReplaceCount, int32 fromOffset) + \sa Replace(const char*, const char*, int32, int32) + + \since BeOS R5 */ /*! \fn BString& BString::ReplaceSet(const char* setOfBytes, char with) \brief Replaces characters that are in a certain set with a chosen - character. + character. \param setOfBytes The set of characters that need to be replaced. - \param with The character to replace the occurences with. + \param with The character to replace the occurrences with. \return This method always returns \c *this. + + \since BeOS R5 */ @@ -1770,16 +2046,20 @@ \brief Replaces characters that are in a certain set with a chosen string. \param setOfBytes The set of characters that need to be replaced. - \param with The string to replace the occurences with. + \param with The string to replace the occurrences with. \return This method always returns \c *this. + + \since BeOS R5 */ /*! - \fn BString& BString::ReplaceCharsSet(const char* setOfChars, + \fn BString& BString::ReplaceCharsSet(const char* setOfChars, const char* with) - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ @@ -1787,7 +2067,7 @@ /*! - \name Character Access + \name Indexing */ @@ -1807,6 +2087,8 @@ \return Returns a reference to the specified byte. \sa ByteAt(int32 index) for a safer version. + + \since BeOS R5 */ @@ -1821,6 +2103,8 @@ \param index The index (zero-based) of the byte to get. \return Returns a reference to the specified byte. + + \since BeOS R5 */ @@ -1828,25 +2112,31 @@ \fn char BString::ByteAt(int32 index) const \brief Returns the character in the string at the given offset. - This function can be used to read a single byte. + This function can be used to read a single byte. \param index The index (zero-based) of the byte to get. - \return Returns a reference to the specified byte. If you are out of - bounds, it will return 0. + \return A reference to the specified byte, if we are out of bounds + it will return 0. + + \since BeOS R5 */ /*! \fn const char* BString::CharAt(int32 charIndex, int32* bytes) const - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ /*! - \fn bool BString::CharAt(int32 charIndex, char* buffer, + \fn bool BString::CharAt(int32 charIndex, char* buffer, int32* bytes) const - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ @@ -1865,31 +2155,35 @@ \fn char* BString::LockBuffer(int32 maxLength) \brief Locks the buffer and return the internal string for manipulation. - If you want to do any lowlevel string manipulation on the internal buffer, + If you want to do any low-level 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 biggerx - buffer, passing anything under the length of the string will simply - return it as is. + \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() + + \since BeOS R5 */ /*! \fn BString& BString::UnlockBuffer(int32 length) - \brief Unlocks the buffer after you are done with lowlevel manipulation. + \brief Unlocks the buffer after you are done with low-level 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. + internal buffer sane. If you don't pass a value in it, \c strlen() + will be used to determine the length. \return This method always returns \c *this. + + \since BeOS R5 */ @@ -1907,34 +2201,45 @@ /*! \fn BString& BString::ToLower() \brief Convert the BString to lowercase. + \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::ToUpper() \brief Convert the BString to uppercase. + \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::Capitalize() \brief Convert the first character to uppercase, rest to lowercase + \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::CapitalizeEachWord() \brief Convert the first character of every word to uppercase, rest - to lowercase. + to lowercase. Converts the first character of every "word" (series of alphabetical characters separated by non alphabetical characters) to uppercase, and the rest to lowercase. \return This method always returns \c *this. + + \since BeOS R5 */ @@ -1942,7 +2247,7 @@ /*! - \name Escaping and De-escaping Methods + \name Escaping and De-escaping This class contains some methods to help you with escaping and de-escaping certain characters. Note that this is the C-style of @@ -1970,8 +2275,10 @@ \return This method always returns \c *this. - \sa CharacterDeescape(char escapeChar) - \sa CharacterDeescape(const char *original, char escapeChar) + \sa CharacterDeescape(char) + \sa CharacterDeescape(const char*, char) + + \since BeOS R5 */ @@ -1985,7 +2292,9 @@ \return This method always returns \c *this. - \sa CharacterDeescape(char escapeChar) + \sa CharacterDeescape(char) + + \since BeOS R5 */ @@ -2002,8 +2311,9 @@ \return This method always returns \c *this. - \sa CharacterEscape(const char *original, const char *setOfCharsToEscape, - char escapeWith) + \sa CharacterEscape(const char*, const char*, char) + + \since BeOS R5 */ @@ -2015,7 +2325,7 @@ \return This method always returns \c *this. - \sa CharacterEscape(const char *setOfCharsToEscape, char escapeWith) + \sa CharacterEscape(const char*, char) */ @@ -2023,7 +2333,7 @@ /*! - \name Trimming methods + \name Trimming */ @@ -2032,7 +2342,9 @@ /*! \fn BString& BString::Trim() - \brief Undocumented + \brief Undocumented. + + \since Haiku R1 */ @@ -2040,9 +2352,9 @@ /*! - \name Simple sprintf Replacement Methods + \name sprintf() Replacement Methods - These methods may be slower than sprintf(), but they are overflow safe. + These methods may be slower than \c sprintf(), but they are overflow safe. */ @@ -2050,66 +2362,106 @@ /*! - \fn BString& BString::operator<<(const char *string) - \brief Append the string \a string. + \fn BString& BString::operator<<(const char* string) + \brief Append \a string to the BString. + + \param string The \a string to append. + + \return This method always returns \c *this. + + \since BeOS R5 */ /*! - \fn BString& BString::operator<<(const BString &string) - \brief Append the BString \a string. + \fn BString& BString::operator<<(const BString& string) + \brief Append \a string to the BString. + + \return This method always returns \c *this. */ /*! \fn BString& BString::operator<<(char c) - \brief Append the \c char \a c. + \brief Append \a c to the BString. + + \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::operator<<(bool value) - \brief Append the boolean \c value to the string. + \brief Convert the \c bool \c value to a string and append it. In case the \a value is true, the string \c true is appended to the string. Otherwise, the string \c false is appended. + + \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::operator<<(int value) \brief Convert the \c int \a value to a string and append it. + + \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::operator<<(unsigned int value) - \brief Convert the \c unsigned \c int \a value to a string and append it. + \brief Convert the unsigned int \a value to a string and append it. + + \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::operator<<(unsigned long value) - \brief Convert the \c unsigned \c long \a value to a string and append it. + \brief Convert the unsigned long \a value to a string and append it. + + \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::operator<<(long value) \brief Convert the \c long \a value to a string and append it. + + \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::operator<<(unsigned long long value) - \brief Convert the \c unsigned \c long \c long \a value to a string and - append it. + \brief Convert the unsigned long long \a value to a string and + append it. + + \return This method always returns \c *this. + + \since BeOS R5 */ /*! \fn BString& BString::operator<<(long long value) - \brief Convert the \c long \c long \a value to a string and append it. + \brief Convert the long long \a value to a string and append it. + + \return This method always returns \c *this. + + \since BeOS R5 */ @@ -2117,7 +2469,11 @@ \fn BString& BString::operator<<(float value) \brief Convert the \c float \a value to a string and append it. - Using this operator will append in the \c %.2f style formatting. + Using this operator will append in the %.2f style formatting. + + \return This method always returns \c *this. + + \since BeOS R5 */ @@ -2126,6 +2482,10 @@ \brief Convert the \c double \a value to a string and append it. Using this operator will append in the \c %.2f style formatting. + + \return This method always returns \c *this. + + \since BeOS R5 */ @@ -2142,146 +2502,200 @@ /*! - \fn bool operator<(const char *a, const BString &b) - \brief Lexicographically compare if \c a is less than a given BString. + \fn bool operator<(const char* a, const BString& b) + \brief Lexicographically compare if \c a is less than the given BString \a b. From String.h and in libbe.so. \param a The first string to compare. \param b The second string to compare. - \sa BString::operator<(const char *string) const + \return \c true if \a a is less than \a b, \c false otherwise. + + \sa BString::operator<(const char*) const + + \since BeOS R5 */ /*! - \fn bool operator<=(const char *a, const BString &b) + \fn bool operator<=(const char* a, const BString& b) \brief Lexicographically compare if \c a is less than or equal to a - given BString. + given BString \a b. From String.h and in libbe.so. \param a The first string to compare. \param b The second string to compare. - \sa BString::operator<=(const char *string) const + \return \c true if \a a is less than or equal to \a b, + \c false otherwise. + + \sa BString::operator<=(const char*) const + + \since BeOS R5 */ /*! - \fn bool operator==(const char *a, const BString &b) - \brief Lexicographically compare if \c a is equal to a given BString. + \fn bool operator==(const char* a, const BString& b) + \brief Lexicographically compare if \c a is equal to a given BString \a b. From String.h and in libbe.so. \param a The first string to compare. \param b The second string to compare. - \sa BString::operator==(const char *string) const + \sa BString::operator==(const char*) const + + \return \c true if \a a is equal to \a b, \c false otherwise. + + \since BeOS R5 */ /*! - \fn bool operator>(const char *a, const BString &b) - \brief Lexicographically compare if \c a is more than a given BString. + \fn bool operator>(const char* a, const BString& b) + \brief Lexicographically compare if \c a is greater than a given BString \a b. From String.h and in libbe.so. \param a The first string to compare. \param b The second string to compare. - \sa BString::operator>(const char *string) const + \sa BString::operator>(const char*) const + + \return \c true if \a a is greater than \a b, \c false otherwise. + + \since BeOS R5 */ /*! - \fn bool operator>=(const char *a, const BString &b) - \brief Lexicographically compare if \c a is more than or equal to a - given BString. + \fn bool operator>=(const char* a, const BString& b) + \brief Lexicographically compare if \c a is greater than or equal to a + given BString \a b. From String.h and in libbe.so. \param a The first string to compare. \param b The second string to compare. - \sa BString::operator>=(const char *string) const + \return \c true if \a a is greater than or equal to \a b, + \c false otherwise. + + \sa BString::operator>=(const char*) const + + \since BeOS R5 */ /*! - \fn bool operator!=(const char *a, const BString &b) - \brief Lexicographically compare if \c a is not equal to given BString. + \fn bool operator!=(const char* a, const BString& b) + \brief Lexicographically compare if \c a is not equal to given BString \a b. From String.h and in libbe.so. \param a The first string to compare. \param b The second string to compare. - \sa BString::operator!=(const char *string) const + \return \c true if \a a is NOT equal to \a b, \c false otherwise. + + \sa BString::operator!=(const char*) const + + \since BeOS R5 */ /*! - \fn int Compare(const BString &a, const BString &b) + \fn int Compare(const BString& a, const BString& b) \brief Lexicographically compare two strings. This function is useful if you need a global compare function to feed to - BList::SortItems() for example. + BList::SortItems(). \param a The first string to compare. \param b The second string to compare. From String.h and in libbe.so. - \sa BString::Compare(const BString &string) const + \return An int representing the strings relationship to each other. + \retval >0 \a a sorts lexicographically after \a b. + \retval =0 \a a is equal to \a b. + \retval <0 \a a sorts lexicographically before \a b. + + \sa BString::Compare(const BString&) const + + \since BeOS R5 */ /*! - \fn int ICompare(const BString &a, const BString &b) + \fn int ICompare(const BString& a, const BString& b) \brief Lexicographically compare two strings case-insensitively. This function is useful if you need a global compare function to feed to - BList::SortItems() for example. + BList::SortItems(). From String.h and in libbe.so. \param a The first string to compare. \param b The second string to compare. - \sa BString::Compare(const BString &string) const + \return An int representing the strings relationship to each other. + \retval >0 \a a sorts lexicographically after \a b. + \retval =0 \a a is equal to \a b. + \retval <0 \a a sorts lexicographically before \a b. + + \sa BString::Compare(const BString&) const + + \since BeOS R5 */ /*! - \fn int Compare(const BString *a, const BString *b) + \fn int Compare(const BString* a, const BString* b) \brief Lexicographically compare two strings. This function is useful if you need a global compare function to feed to - BList::SortItems() for example. + BList::SortItems(). From String.h and in libbe.so. \param a The first string to compare. \param b The second string to compare. - \sa BString::Compare(const BString &string) const + \return An int representing the strings relationship to each other. + \retval >0 \a a sorts lexicographically after \a b. + \retval =0 \a a is equal to \a b. + \retval <0 \a a sorts lexicographically before \a b. + + \sa BString::Compare(const BString&) const + + \since BeOS R5 */ /*! - \fn int ICompare(const BString *a, const BString *b) + \fn int ICompare(const BString* a, const BString* b) \brief Lexicographically compare two strings case-insensitively. This function is useful if you need a global compare function to feed to - BList::SortItems() for example. + BList::SortItems(). From String.h and in libbe.so. \param a The first string to compare. \param b The second string to compare. - \sa BString::Compare(const BString &string) const + \return An int representing the strings relationship to each other. + \retval >0 \a a sorts lexicographically after \a b. + \retval =0 \a a is equal to \a b. + \retval <0 \a a sorts lexicographically before \a b. + + \sa BString::Compare(const BString&) const + + \since BeOS R5 */ diff --git a/docs/user/support/SupportDefs.dox b/docs/user/support/SupportDefs.dox index 962a9ccfc6..e70960068a 100644 --- a/docs/user/support/SupportDefs.dox +++ b/docs/user/support/SupportDefs.dox @@ -1,9 +1,10 @@ /* - * Copyright 2007 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Corresponds to: * headers/os/support/SupportDefs.h rev 35018 @@ -202,13 +203,17 @@ /*! \typedef typedef int32 status_t - \brief Represents one of the status codes defined in Error.h + \brief Represents one of the status codes defined in Error.h. + + \since BeOS R3 */ /*! \typedef typedef int64 bigtime_t \brief Represents time. The unit depends on the context of the function. + + \since BeOS R3 */ @@ -221,7 +226,9 @@ /*! \typedef typedef uint32 type_code \brief Represents a certain type of data. See TypeConstants.h for - possible values. + possible values. + + \since Haiku R1 */ @@ -230,11 +237,13 @@ \brief Defined to support 'hidden' commands or extensions to classes. The Haiku API has none of these. + + \since Haiku R1 */ - + //! @} - + /*! \name Format strings for printf() and scanf() @@ -547,7 +556,7 @@ */ -/*! +/*! \def B_PRIdDEV \brief dev_t */ @@ -571,7 +580,7 @@ */ -/*! +/*! \def B_PRIdTIME \brief time_t */ @@ -588,10 +597,12 @@ //////////////// Odds and ends - + /*! - \var const char *B_EMPTY_STRING + \var const char* B_EMPTY_STRING \brief Defines an empty string. Currently defined as the string "". + + \since BeOS R3 */ @@ -599,8 +610,10 @@ \def min_c(a,b) \brief Returns the minimum of the values a and b. - \note When including this header in a C file, use the C equivalent called - \c min(a,b). + \note When including this header in a C file, use the C equivalent called + \c min(a,b). + + \since Haiku R1 */ @@ -608,14 +621,18 @@ \def max_c(a,b) \brief Returns the maximum of values a and b. - \note When including this header in a C file, use the C equivalent called - \c max(a,b). + \note When including this header in a C file, use the C equivalent called + \c max(a,b). + + \since Haiku R1 */ /*! \def NULL \brief Defines the constant \c NULL if it hasn't already been defined. + + \since BeOS R3 */ @@ -627,7 +644,8 @@ //! @{ -/*! \fn void atomic_set(int32* value, int32 newValue) +/*! + \fn void atomic_set(int32* value, int32 newValue) \brief Atomically set the variable \a value to \a newvalue. This is a thread-safe way of performing the \c *value \c = \c newValue @@ -641,17 +659,19 @@ \sa atomic_and() \sa atomic_or(), \sa atomic_get() + + \since Haiku R1 */ /*! \fn int32 atomic_get_and_set(int32* value, int32 newValue) \brief Atomically set the variable \a value to \a newvalue and return the - old value. + old value. This is a thread-safe way of performing the \c *value \c = \c newValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a - mutex in this case. + mutex in this case. \return The original value of \c value. @@ -662,18 +682,20 @@ \sa atomic_and() \sa atomic_or(), \sa atomic_get() + + \since Haiku R1 */ /*! \fn int32 atomic_test_and_set(int32* value, int32 newValue, int32 testAgainst) \brief Atomically set the variable \a value to \a newValue if the current - value is \a testAgainst. - - This is a thread-safe way of conditionally performing the \c *value \c += + value is \a testAgainst. + + This is a thread-safe way of conditionally performing the \c *value \c += \c newValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use - a semaphore or a mutex in this case. + a semaphore or a mutex in this case. \return The original value of \c value. @@ -684,6 +706,8 @@ \sa atomic_and() \sa atomic_or() \sa atomic_get() + + \since Haiku R1 */ @@ -694,7 +718,7 @@ This is a thread-safe way of performing the \c *value \c += \c addValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a - mutex in this case. + mutex in this case. \return The original value of \c value. @@ -705,17 +729,19 @@ \sa atomic_and() \sa atomic_or() \sa atomic_get() + + \since BeOS R3 */ /*! \fn int32 atomic_and(int32* value, int32 andValue) - \brief Atomically perform a bitwise AND operation of \a andValue to the + \brief Atomically perform a bitwise AND operation of \a andValue to the variable \a andValue. This is a thread-safe way of performing the \c *value \c &= \c andValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a - mutex in this case. + mutex in this case. \return The original value of \c value. @@ -726,19 +752,20 @@ \sa atomic_add() \sa atomic_or() \sa atomic_get() -*/ + \since BeOS R3 +*/ /*! \fn int32 atomic_or(int32* value, int32 orValue) - \brief Atomically perform a bitwise OR operation of \a orValue to the - variable \a andValue. + \brief Atomically perform a bitwise OR operation of \a orValue to the + variable \a andValue. This is a thread-safe way of performing the \c *value \c |= \c orValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a - mutex in this case. + mutex in this case. \return The original value of \c value. @@ -749,6 +776,8 @@ \sa atomic_add() \sa atomic_and() \sa atomic_get() + + \since BeOS R3 */ @@ -770,6 +799,8 @@ \sa atomic_add() \sa atomic_and() \sa atomic_or() + + \since Haiku R1 */ @@ -789,18 +820,20 @@ \sa atomic_and64() \sa atomic_or64() \sa atomic_get64() + + \since Haiku R1 */ /*! \fn int64 atomic_get_and_set64(int64* value, int64 newValue) \brief Atomically set the variable \a value to \a newvalue and return - the old value. + the old value. This is a thread-safe way of performing the \c *value \c = \c newValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a - mutex in this case. + mutex in this case. \return The original value of \c value. @@ -811,6 +844,8 @@ \sa atomic_and64() \sa atomic_or64() \sa atomic_get64() + + \since Haiku R1 */ @@ -818,12 +853,12 @@ \fn int64 atomic_test_and_set64(int64* value, int64 newValue, int64 testAgainst) \brief Atomically set the variable \a value to \a newValue if the current - value is \a testAgainst. + value is \a testAgainst. This is a thread-safe way of conditionally performing the \c *value \c += \c newValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't - have to use a semaphore or a mutex in this case. + have to use a semaphore or a mutex in this case. \return The original value of \c value. @@ -834,6 +869,8 @@ \sa atomic_and64() \sa atomic_or64() \sa atomic_get64() + + \since Haiku R1 */ @@ -844,8 +881,8 @@ This is a thread-safe way of performing the \c *value \c += \c addValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a - mutex in this case. - + mutex in this case. + \return The original value of \c value. \sa atomic_add() for a version that works on an \c int32. @@ -855,13 +892,15 @@ \sa atomic_and64() \sa atomic_or64() \sa atomic_get64() + + \since Haiku R1 */ /*! \fn int64 atomic_and64(int64* value, int64 andValue) \brief Atomically perform a bitwise AND operation of \a andValue to the - variable \a andValue. + variable \a andValue. This is a thread-safe way of performing the \c *value \c &= \c andValue operation. You should use these function when two or more threads might @@ -877,17 +916,20 @@ \sa atomic_add64() \sa atomic_or64() \sa atomic_get64() + + \since Haiku R1 */ -/*! \fn int64 atomic_or64(int64* value, int64 orValue) +/*! + \fn int64 atomic_or64(int64* value, int64 orValue) \brief Atomically perform a bitwise OR operation of \a orValue to the - variable \a andValue. + variable \a andValue. This is a thread-safe way of performing the \c *value \c |= \c orValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a - mutex in this case. + mutex in this case. \return The original value of \c value. @@ -898,6 +940,8 @@ \sa atomic_add64() \sa atomic_and64() \sa atomic_get64() + + \since Haiku R1 */ @@ -919,6 +963,8 @@ \sa atomic_add64() \sa atomic_and64() \sa atomic_or64() + + \since Haiku R1 */ @@ -943,12 +989,16 @@ /*! \def FALSE \brief Obsolete. Use \c false. + + \since BeOS R3 */ /*! \def TRUE \brief Obsolete. Use \c true. + + \since BeOS R3 */ diff --git a/docs/user/support/TLS.dox b/docs/user/support/TLS.dox index 75068553cd..c25af3f6b8 100644 --- a/docs/user/support/TLS.dox +++ b/docs/user/support/TLS.dox @@ -1,9 +1,10 @@ /* - * Copyright 2007 Haiku Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Corresponds to: * headers/os/support/TLS.h rev 19972 @@ -64,18 +65,22 @@ public: \note -# It is impossible to get data other than from your thread. -# There is a limit to the number of TLS variables you can allocate. This - limit is define by #TLS_MAX_KEYS, but do realize that you share this - limit with all the libraries your application is linked to. + limit is define by #TLS_MAX_KEYS, but do realize that you share this + limit with all the libraries your application is linked to. -# The actual global variables, in the example \c gThreadName and - \c gThreadData, are only indexes. You cannot use these variables to - access data without the TLS API. + \c gThreadData, are only indexes. You cannot use these variables to + access data without the TLS API. + + \since BeOS R5 */ /*! \def TLS_MAX_KEYS \brief The maximum number of thread local storage variables. This number is - process wide. + process wide. + + \since BeOS R5 */ @@ -87,42 +92,50 @@ public: you can reuse in every thread. \return A unique index to which you can associate per thread data. If we - overrun the maximum number of keys, as defined by #TLS_MAX_KEYS, - the function will return \c B_NO_MEMORY. + overrun the maximum number of keys, as defined by #TLS_MAX_KEYS, + the function will return \c B_NO_MEMORY. \sa tls_get() \sa tls_set() \sa tls_address() + + \since BeOS R5 */ /*! - \fn void *tls_get(int32 index) + \fn void* tls_get(int32 index) \brief Retrieve the data stored for this thread at the provided \a index. \param index The \a index that you retrieved with tls_allocate(). \return The data you set using tls_set() for this thread, or \c NULL if there - is no data set, or the \a index is invalid. + is no data set, or the \a index is invalid. \sa tls_allocate() \sa tls_set() + + \since BeOS R5 */ /*! - \fn void **tls_address(int32 index) + \fn void** tls_address(int32 index) \brief Retrieve the pointer that refers to the data of this thread at the provided \a index. You can use this pointer to directly manipulate your thread data. \param index The \a index that you retrieved with tls_allocate(). + \return The pointer to where your thread's data is, or \c NULL if the index - is invalid. + is invalid. + \sa tls_allocate() \sa tls_set() \sa tls_get() + + \since BeOS R5 */ @@ -135,8 +148,10 @@ public: \param index The \a index that you retrieved with tls_allocate(). \param value The data that should be associated with the index for this - thread. + thread. \sa tls_allocate() \sa tls_get() + + \since BeOS R5 */ diff --git a/docs/user/support/TypeConstants.dox b/docs/user/support/TypeConstants.dox index 8a1d7fcbd9..b73e4aba42 100644 --- a/docs/user/support/TypeConstants.dox +++ b/docs/user/support/TypeConstants.dox @@ -1,9 +1,10 @@ /* - * Copyright 2007 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * Corresponds to: * headers/os/support/TypeConstants.h rev 43506 @@ -14,10 +15,10 @@ \file TypeConstants.h \ingroup support \ingroup libbe - \brief Represents typecodes that are used in various part of the Haiku API. + \brief Represents type codes that are used in various part of the Haiku API. The type codes all refer to a specified type, except one. B_ANY_TYPE can - refer to literaly any type. This type could be used in case you send or receive + refer to literally any type. This type could be used in case you send or receive data of which you don't know the type, but you want to send or receive it anyway. */ @@ -26,6 +27,8 @@ /*! \var B_ANY_TYPE \brief General type when the exact contents is not yet known. + + \since Haiku R1 */ @@ -34,6 +37,8 @@ \brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. + + \since Haiku R1 */ @@ -42,102 +47,136 @@ \brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. + + \since Haiku R1 */ /*! \var B_BOOL_TYPE \brief Boolean value. + + \since Haiku R1 */ /*! \var B_CHAR_TYPE \brief Represents the \c char type. + + \since Haiku R1 */ /*! \var B_COLOR_8_BIT_TYPE \brief Represents a one-byte color. + + \since Haiku R1 */ /*! \var B_DOUBLE_TYPE \brief Represents the \c double type. + + \since Haiku R1 */ /*! \var B_FLOAT_TYPE \brief Represents the \c float type. + + \since Haiku R1 */ /*! \var B_GRAYSCALE_8_BIT_TYPE \brief Represents a byte-long grayscale value. + + \since Haiku R1 */ /*! \var B_INT16_TYPE \brief Represents a \c short type. + + \since Haiku R1 */ /*! \var B_INT32_TYPE \brief Represents a \c long type. + + \since Haiku R1 */ /*! \var B_INT64_TYPE \brief Represents a \c long \c long type. + + \since Haiku R1 */ /*! \var B_INT8_TYPE \brief Represents a \c char type used for integer storage. + + \since Haiku R1 */ /*! \var B_LARGE_ICON_TYPE \brief Represents a large icon. + + \since Haiku R1 */ /*! \var B_MEDIA_PARAMETER_GROUP_TYPE \brief Represents the BParameterGroup type from the media kit. + + \since Haiku R1 */ /*! \var B_MEDIA_PARAMETER_TYPE \brief Represents the BParameter type from the media kit. + + \since Haiku R1 */ /*! \var B_MEDIA_PARAMETER_WEB_TYPE \brief Represents the BParameterWeb type from the media kit. + + \since Haiku R1 */ /*! \var B_MESSAGE_TYPE \brief Represents a BMessage type. + + \since Haiku R1 */ /*! \var B_MESSENGER_TYPE \brief Represents a BMessenger type. + + \since Haiku R1 */ @@ -155,72 +194,96 @@ /*! \var B_URL_HTTP \brief application/x-vnd.Be.URL.http + + \since Haiku R1 */ /*! \var B_URL_HTTPS \brief application/x-vnd.Be.URL.https + + \since Haiku R1 */ /*! \var B_URL_FTP \brief application/x-vnd.Be.URL.ftp + + \since Haiku R1 */ /*! \var B_URL_GOPHER \brief application/x-vnd.Be.URL.gopher + + \since Haiku R1 */ /*! \var B_URL_MAILTO \brief application/x-vnd.Be.URL.mailto + + \since Haiku R1 */ /*! \var B_URL_NEWS \brief application/x-vnd.Be.URL.news + + \since Haiku R1 */ /*! \var B_URL_NNTP \brief application/x-vnd.Be.URL.nntp + + \since Haiku R1 */ /*! \var B_URL_TELNET \brief application/x-vnd.Be.URL.telnet + + \since Haiku R1 */ /*! \var B_URL_RLOGIN \brief application/x-vnd.Be.URL.rlogin + + \since Haiku R1 */ /*! \var B_URL_TN3270 \brief application/x-vnd.Be.URL.tn3270 + + \since Haiku R1 */ /*! \var B_URL_WAIS \brief application/x-vnd.Be.URL.wais + + \since Haiku R1 */ /*! \var B_URL_FILE \brief application/x-vnd.Be.URL.file + + \since Haiku R1 */ diff --git a/docs/user/support/parsedate.dox b/docs/user/support/parsedate.dox index 5ec8a538ff..9750ba2e5e 100644 --- a/docs/user/support/parsedate.dox +++ b/docs/user/support/parsedate.dox @@ -1,12 +1,13 @@ /* - * Copyright 2007 Haiku, Inc. All rights reserved. + * Copyright 2007-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: - * Axel Dörfler + * Axel Dörfler + * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/support/parsedate.h rev 19972 + * headers/os/support/parsedate.h rev 19972 */ @@ -36,20 +37,20 @@ Here are some examples of input strings that parsedate() will be able to convert along with some notes: - "last friday", "this wednesday", "next July" - "last", "next", and "this" refer to the week or year (depending - on the context). So "last friday" means last week's friday. - "This wednesday" is referring to this week's wednesday, no matter - if it has already passed or not. - "Next July" refers to next year's July. All of these dates are - parsed relative to the specified time (usually "now"), and will - be set to the first moment of that time span: "next monday" is - monday, 0:00:00, midnight. + "last", "next", and "this" refer to the week or year (depending + on the context). So "last friday" means last week's friday. + "This wednesday" is referring to this week's wednesday, no matter + if it has already passed or not. + "Next July" refers to next year's July. All of these dates are + parsed relative to the specified time (usually "now"), and will + be set to the first moment of that time span: "next monday" is + monday, 0:00:00, midnight. - "now" just returns the time all calculations are relative to. - "next 5 minutes", "5 minutes", "+5 mins" all mean the same thing, - that is, current time plus exactly 5 minutes. + that is, current time plus exactly 5 minutes. - "5 weeks" means in 5 weeks from now on. - "8/5/2003", "5.8.2003", "2003-08-05" are all referring to August - 5th, 2003, again at 0:00 midnight. + 5th, 2003, again at 0:00 midnight. - "Thursday 3:00" means this week's thursday, at 3 o'clock. \anchor parsedateFormats @@ -84,8 +85,8 @@ not a valid meridian specifier), or "4:66" (minutes out of range). \note At the time of this writing, the parsedate() functions are not - localized and will only recognize English time specifications - following the examples above. + localized and will only recognize English time specifications + following the examples above. */ @@ -129,15 +130,15 @@ \fn time_t parsedate(const char *dateString, time_t relativeTo) \brief Parses \a dateString relative to \a relativeTo - Parses the given \a dateString relative to the time - specified by \a relativeTo using the internal formats - table. + Parses the given \a dateString relative to the time specified by + \a relativeTo using the internal formats table. \param dateString the date that should be parsed, i.e. "next thursday". \param relativeTo all relative dates will be relative to this time, if -1 - is passed, the current time will be used. - \return the parsed time value or -1 if the \a dateString - could not be parsed. + is passed, the current time will be used. + + \return The parsed time value or -1 if the \a dateString could not be + parsed. */ @@ -145,55 +146,55 @@ \fn time_t parsedate_etc(const char *dateString, time_t relativeTo, int *_storedFlags) \brief Parses dateString relative to - relativeTo + relativeTo This does basically the same as parsedate(), but will set the following flags in _storedFlags: - \htmlonly - - - - - - - - - - - -
ConstantMeaning
PARSEDATE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly -
PARSEDATE_DAY_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly -
PARSEDATE_MINUTE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly -
PARSEDATE_INVALID_DATE - \endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly - This flag will only be set if the function returns -1. -
- \endhtmlonly +\htmlonly + + + + + + + + + + + +
ConstantMeaning
PARSEDATE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly +
PARSEDATE_DAY_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly +
PARSEDATE_MINUTE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly +
PARSEDATE_INVALID_DATE + \endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly + This flag will only be set if the function returns -1. +
+\endhtmlonly */ /*! - \fn void set_dateformats(const char *formatTable[]) + \fn void set_dateformats(const char* formatTable[]) \brief sets the internal format table for parsedate() This function let you set the format table which is used by parsedate(). - When formatTable is NULL, the standard built-in format table will be set again. - \param formatTable the NULL terminated formats list. This list must stay - valid when using parsedate() - it is not copied, but directly used. + When formatTable is NULL, the standard built-in + format table will be set again. - \see - \ref parsedateFormats Format! + \param formatTable the NULL terminated formats list. This list must stay + valid when using parsedate() - it is not copied, but directly used. + + \see \ref parsedateFormats Format! */ /*! - \fn const char **get_dateformats(void) + \fn const char** get_dateformats(void) \brief returns the internal format table currently used by parsedate() Returns the internal format table currently used by parsedate() - this is either a pointer to the built-in one, or one that you have previously set using set_dateformats(). - \see - \ref set_dateformats() + \see \ref set_dateformats() */