3080 lines
72 KiB
Plaintext
3080 lines
72 KiB
Plaintext
/*
|
|
* 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:
|
|
* headers/os/support/String.h rev 43319
|
|
* 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.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\class BString String.h
|
|
\ingroup support
|
|
\ingroup libbe
|
|
\brief String class supporting common string operations.
|
|
|
|
BString is a string allocation and manipulation class. The object
|
|
takes care to allocate and free memory for you, so it will always be
|
|
"big enough" to store your strings.
|
|
|
|
While BString is in essence a wrapper around a byte-array, which can always
|
|
be accessed with the BString::String() method, it does have some
|
|
understanding of UTF-8 and it can be used for the manipulation of UTF-8
|
|
strings. For all operations that perform on bytes, there is an equivalent
|
|
that operates on UTF-8 strings. See for example the BString::CopyInto() and
|
|
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 string.
|
|
|
|
\param string The \a string to copy from.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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)
|
|
\brief Creates and initializes a BString from a \a string up to
|
|
\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.
|
|
|
|
\param string The \a string data to initialize the BString to.
|
|
\param maxLength Maximum number of characters (bytes) to copy.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString::~BString()
|
|
\brief Free all resources associated with the object.
|
|
|
|
The destructor also frees the internal buffer associated with the string.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\name Access
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn const char* BString::String() const
|
|
\brief Return a pointer to the object string, \c NUL terminated.
|
|
|
|
The pointer to the object string is guaranteed to be \c NUL
|
|
terminated. You can't modify or free the pointer. Once the BString
|
|
object is deleted, the pointer becomes invalid.
|
|
|
|
If you want to manipulate the internal string of the object directly,
|
|
have a look at LockBuffer().
|
|
|
|
\return A pointer to the object string.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::Length() const
|
|
\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
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::CountChars() const
|
|
\brief Returns the length of the object measured in characters.
|
|
|
|
BString is somewhat aware of UTF-8 characters, so this method will count
|
|
the actual number of characters in the string.
|
|
|
|
\return An integer which is the number of characters in the string.
|
|
|
|
\sa Length()
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::CountBytes(int32 fromCharOffset, int32 charCount) const
|
|
\brief Count the number of bytes starting from a specified character
|
|
|
|
BString is somewhat aware of UTF-8 characters, which can take up more than
|
|
one byte. With this method you can count the number of bytes a subset of
|
|
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.
|
|
|
|
\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
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::IsEmpty() const
|
|
\brief Check whether the string is empty.
|
|
|
|
\return Returns \c true if the string is empty.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn uint32 BString::HashValue() const
|
|
\brief Return a hash value for the current string
|
|
|
|
\sa HashValue(const char*)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn static uint32 BString::HashValue(const char* string)
|
|
\brief Return the hash value of a specified \c string
|
|
|
|
This allows you to use the BString::HashValue() method on any arbitrary
|
|
\c string.
|
|
|
|
\param string The string that you want to have hashed.
|
|
|
|
\sa HashValue()
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\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
|
|
overloaded Adopt() methods to take over data from another object. Use
|
|
one of the assignment operators to copy data from another object, or
|
|
use one of the SetTo() methods for more advanced copying.
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator=(const BString& string)
|
|
\brief Re-initialize the object to a copy of the data of a BString.
|
|
|
|
\param string The \a string to copy.
|
|
|
|
\return The function always returns \c *this.
|
|
|
|
\sa Adopt(BString&)
|
|
\sa SetTo(const BString&, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator=(const char* str)
|
|
\brief Re-initialize the BString to a copy of the data of a string.
|
|
|
|
\param str The string data to re-initialize the BString to.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa SetTo(const char*, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator=(char c)
|
|
\brief Re-initialize the BString to a character.
|
|
|
|
\param c The \c char to re-initialize the BString to.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::SetTo(const char* str)
|
|
\brief Re-initialize the BString to a copy of the data of a string.
|
|
|
|
This method calls operator=(const char*).
|
|
|
|
\param str The string data to re-initialize the BString to.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa SetTo(const char*, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::SetTo(const char* str, int32 maxLength)
|
|
\brief Re-initialize the BString to a copy of the data of a string.
|
|
|
|
\param str The string data to re-initialize the BString to.
|
|
\param maxLength Maximum number of characters (bytes) to copy.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa operator=(const char*)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::SetTo(const BString& from)
|
|
\brief Re-initialize the BString to a copy of the data of a BString.
|
|
|
|
\param from The string data to re-initialize the BString to.
|
|
|
|
\return The function always returns \c *this.
|
|
|
|
\sa SetTo(const BString&, int32)
|
|
\sa Adopt(BString&)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 string data to re-initialize the BString to.
|
|
\param maxLength Maximum number of characters (bytes) to copy.
|
|
|
|
\return The function always returns \c *this.
|
|
|
|
\sa operator=(const BString&)
|
|
\sa Adopt(BString&, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Adopt(BString& from)
|
|
\brief Adopt the data of the given BString object.
|
|
|
|
This method adopts the data from a BString removing the data from \a from
|
|
and putting it into the BString.
|
|
|
|
\warning The object that is adopted from is not deleted, only its private
|
|
data is initialized to a \c NULL string. If the \a from object
|
|
was created on the heap you need to clean it up yourself.
|
|
|
|
\param from The string data to adopt.
|
|
|
|
\return The function always returns \c *this.
|
|
|
|
\sa operator=(const BString&)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Adopt(BString& from, int32 maxLength)
|
|
\brief Adopt the data of the given BString object up to \a maxLength
|
|
characters.
|
|
|
|
This method adopts the data from a BString removing the data from \a from
|
|
and putting it into the BString.
|
|
|
|
\param from The string object to adopt.
|
|
\param maxLength Maximum number of characters (bytes) to adopt.
|
|
|
|
\return The function always returns \c *this.
|
|
|
|
\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.
|
|
|
|
This method lets you specify the length of a string and what character
|
|
you want the string to contain repeatedly.
|
|
|
|
\param c The character you want to initialize the BString.
|
|
\param count The length of the string.
|
|
|
|
\return The function always returns \c *this.
|
|
|
|
\sa operator=(char c)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::SetToChars(const char* string, int32 charCount)
|
|
\brief UTF-8 aware version of SetTo(const char*, int32)
|
|
|
|
\param string The \a string to copy.
|
|
\param charCount The number of UTF-8 characters to copy.
|
|
|
|
\see SetTo(const char*, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::SetToChars(const BString& string, int32 charCount)
|
|
\brief UTF-8 aware version of SetTo(BString&, int32)
|
|
|
|
\param string The \a string to copy.
|
|
\param charCount The number of UTF-8 characters to copy.
|
|
|
|
\see SetTo(BString&, int32)
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::AdoptChars(BString& from, int32 charCount)
|
|
\brief UTF-8 aware version of Adopt(BString&, int32)
|
|
|
|
\param from The string data to start adopting from.
|
|
\param charCount Number of UTF-8 characters to adopt.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::SetToFormat(const char* format, ...)
|
|
\brief Sets the string to a formatted string ala <tt>sprintf()</tt>.
|
|
|
|
\param format The \a format string to use.
|
|
\param ... The rest of the parameters that are filled into \a format.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Substring Copying
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::CopyInto(BString& into, int32 fromOffset,
|
|
int32 length) const
|
|
\brief Copy the object's data (or part of it) into another BString.
|
|
|
|
This methods makes sure you don't copy more bytes than are available
|
|
in the string. If the length exceeds the length of the string, it only
|
|
copies the number of characters that are actually available.
|
|
|
|
\param into The BString to copy into.
|
|
\param fromOffset The (zero-based) offset where to begin the copy.
|
|
\param length The number of bytes to copy.
|
|
|
|
\return This method always returns a pointer to the string passed as the
|
|
\c into parameter.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BString::CopyInto(char* into, int32 fromOffset, int32 length) const
|
|
\brief Copy the BString data (or part of it) into the supplied buffer.
|
|
|
|
This methods makes sure you don't copy more bytes than are available
|
|
in the string. If the length exceeds the length of the string, it only
|
|
copies the number of characters that are actually available.
|
|
|
|
It's up to you to make sure your buffer is large enough.
|
|
|
|
\param into The buffer where to copy the object.
|
|
\param fromOffset The (zero-based) offset where to begin the copy.
|
|
\param length The number of bytes to copy.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::CopyCharsInto(BString& into, int32 fromOffset,
|
|
int32 charCount) const
|
|
\brief UTF-8 aware version of CopyInto(BString&, int32, int32) const.
|
|
|
|
\param into The BString to copy into.
|
|
\param fromOffset The (zero-based) offset in bytes where to begin the copy.
|
|
\param charCount The number of UTF-8 characters to copy.
|
|
|
|
\return This method always returns a pointer to the string passed as the
|
|
\c into parameter.
|
|
|
|
\see CopyInto(BString&, int32, int32) const
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::CopyCharsInto(char* into, int32* intoLength,
|
|
int32 fromCharOffset, int32 charCount) const
|
|
\brief UTF-8 aware version of CopyInto(char*, int32, int32) const.
|
|
|
|
\param into The buffer where to copy the object.
|
|
\param intoLength The length of \a into in bytes.
|
|
\param fromCharOffset The (zero-based) offset UTF-8 characters where to
|
|
begin the copy.
|
|
\param charCount The number of UTF-8 characters to copy.
|
|
|
|
\see CopyInto(char*, int32, int32) const
|
|
|
|
\return \c false if \a into was \c NULL, \c true otherwise.
|
|
|
|
\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
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Appending
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator+=(const BString& string)
|
|
\brief Append the given \a string to the end of the BString
|
|
|
|
\param string The string to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa Append(const BString&, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator+=(const char* str)
|
|
\brief Append the given string to the end of the BString.
|
|
|
|
\param str A pointer to the NULL-terminated string to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa Append(const char*, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator+=(char c)
|
|
\brief Append the given character to the end of the BString.
|
|
|
|
\param c The character to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa Append(char, int32)
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator+=(const BString& string)
|
|
\brief Append the given \a string to the end of the BString.
|
|
|
|
\param string The string to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa Append(const BString&, int32)
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Append(const BString& string)
|
|
\brief Append the given \a string to the end of the BString.
|
|
|
|
\param string The string to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa Append(const BString&, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Append(const char* str)
|
|
\brief Append the string data to the end of the BString.
|
|
|
|
This method calls operator+=(const char *str).
|
|
|
|
\sa Append(const char*, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Append(const BString& string, int32 length)
|
|
\brief Append a part of the given \a string to the end of the BString.
|
|
|
|
\param string The BString to append.
|
|
\param length The maximum number of bytes to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\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 end of the BString.
|
|
|
|
\param str A pointer to the string to append.
|
|
\param length The maximum number of bytes to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa operator+=(const char*)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Append(char c, int32 count)
|
|
\brief Append the given character repeatedly to the end of the BString.
|
|
|
|
\param c The character to append.
|
|
\param count The number of times this character should be appended.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa operator+=(char c)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::AppendChars(const BString& string, int32 charCount)
|
|
\brief UTF-8 aware version of Append(const BString&, int32).
|
|
|
|
\param string The \a string to append.
|
|
\param charCount The maximum number of UTF-8 characters to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see Append(const BString&, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::AppendChars(const char* string, int32 charCount)
|
|
\brief UTF-8 aware version of Append(const char*, int32).
|
|
|
|
\param string The \a string to append.
|
|
\param charCount The maximum number of UTF-8 characters to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see Append(const char*, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Prepending
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Prepend(const char* str)
|
|
\brief Prepend the given string to the beginning of the BString.
|
|
|
|
\param str The \a string to prepend.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa Prepend(const char*, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Prepend(const BString& string)
|
|
\brief Prepend the given BString to the beginning of the BString.
|
|
|
|
\param string The \a string to prepend.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa Prepend(const BString&, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Prepend(const char* str, int32 length)
|
|
\brief Prepend the given string to the beginning of the BString.
|
|
|
|
\param str The \a string to prepend.
|
|
\param length The maximum number of bytes to prepend.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa Prepend(const char*)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Prepend(const BString& string, int32 length)
|
|
\brief Prepend the given BString to the beginning of the BString.
|
|
|
|
\param string The \a string to prepend.
|
|
\param length The maximum number of bytes to prepend.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa Prepend(const BString&)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Prepend(char c, int32 count)
|
|
\brief Prepend the given character \a count times to the beginning of 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 UTF-8 aware version of Prepend(const char*, int32).
|
|
|
|
\param string The \a string to prepend.
|
|
\param charCount The maximum number of UTF-8 characters to prepend.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see Prepend(const char*, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::PrependChars(const BString& string, int32 charCount)
|
|
\brief UTF-8 aware version of Prepend(const BString&, int32).
|
|
|
|
\param string The \a string to prepend.
|
|
\param charCount The maximum number of UTF-8 characters to prepend.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see Prepend(const BString&, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Inserting
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Insert(const char* string, int32 position)
|
|
\brief Inserts the given string at the given position into the BString
|
|
data.
|
|
|
|
\param string The \a string to insert.
|
|
\param position The offset in bytes where to insert the \a string into
|
|
the BString's data.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\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)
|
|
\brief Inserts the given string at the given position into the BString
|
|
data.
|
|
|
|
\param string The \a string to insert.
|
|
\param length The number 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*, int32)
|
|
\sa Insert(const char*, int32, int32, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Insert(const char* string, int32 fromOffset,
|
|
int32 length, int32 position)
|
|
\brief Inserts the given string at the given position into the BString
|
|
data.
|
|
|
|
\param string The \a string to insert.
|
|
\param fromOffset The offset in bytes in the \a string to be inserted.
|
|
\param length The number 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*, int32)
|
|
\sa Insert(const char*, int32, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Insert(const BString& string, int32 position)
|
|
\brief Inserts the given BString at the given position into the BString
|
|
data.
|
|
|
|
\param string The \a string 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 BString&, int32, int32)
|
|
\sa Insert(const BString&, int32, int32, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Insert(const BString& string, int32 length, int32 position)
|
|
\brief Inserts the given BString at the given position into the BString
|
|
data.
|
|
|
|
\param string The \a string to insert.
|
|
\param length The number 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 BString&, int32)
|
|
\sa Insert(const BString&, int32, int32, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Insert(const BString& string, int32 fromOffset,
|
|
int32 length, int32 position)
|
|
\brief Inserts the given string at the given position into the BString
|
|
data.
|
|
|
|
\param string The \a string to insert.
|
|
\param fromOffset The offset in bytes of the string to be inserted.
|
|
\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 BString&, int32)
|
|
\sa Insert(const BString&, int32, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Insert(char c, int32 count, int32 pos)
|
|
\brief Inserts the given character repeatedly at the given position
|
|
into the BString 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 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 UTF-8 aware version of Insert(const char*, int32).
|
|
|
|
\param string The \a string to insert.
|
|
\param charPosition The offset in UTF-8 characters where to insert
|
|
the string into the data of the BString.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see Insert(const char*, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::InsertChars(const char* string, int32 charCount,
|
|
int32 charPosition)
|
|
\brief UTF-8 aware version of Insert(const char*, int32, int32).
|
|
|
|
\param string The \a string to insert.
|
|
\param charCount The number of UTF-8 characters to insert.
|
|
\param charPosition The offset in UTF-8 characters where to insert
|
|
the string into the data of the BString.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see Insert(const char*, int32, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::InsertChars(const char* string, int32 fromCharOffset,
|
|
int32 charCount, int32 charPosition)
|
|
\brief UTF-8 aware version of Insert(const char*, int32, int32, int32).
|
|
|
|
\param string The \a string to insert.
|
|
\param fromCharOffset The offset in UTF-8 characters of the string to be
|
|
inserted.
|
|
\param charCount The number of UTF-8 characters to insert.
|
|
\param charPosition The offset in UTF-8 characters where to insert
|
|
the string into the data of the BString.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see Insert(const char*, int32, int32, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::InsertChars(const BString& string, int32 charPosition)
|
|
\brief UTF-8 aware version of Insert(const BString&, int32).
|
|
|
|
\param string The \a string to insert.
|
|
\param charPosition The offset in UTF-8 characters where to insert
|
|
the string into the data of the BString.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see Insert(const BString&, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::InsertChars(const BString& string, int32 charCount,
|
|
int32 charPosition)
|
|
\brief UTF-8 aware version of Insert(const BString&, int32, int32).
|
|
|
|
\param string The \a string to insert.
|
|
\param charCount The number of UTF-8 characters to insert.
|
|
\param charPosition The offset in UTF-8 characters where to insert
|
|
the string into the data of the BString.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see Insert(const BString&, int32, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::InsertChars(const BString& string, int32 fromCharOffset,
|
|
int32 charCount, int32 charPosition)
|
|
\brief UTF-8 aware version of Insert(const BString&, int32, int32, int32).
|
|
|
|
\param string The \a string to insert.
|
|
\param fromCharOffset The offset in UTF-8 characters of the string to be
|
|
inserted.
|
|
\param charCount The number of UTF-8 characters to insert.
|
|
\param charPosition The offset in UTF-8 characters where to insert
|
|
the string into the data of the BString.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see Insert(const BString&, int32, int32, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Removing
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Trim()
|
|
\brief Removes spaces from the beginning and end of the string.
|
|
|
|
The definition of a space is set by the <tt>isspace()</tt> function.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Truncate(int32 newLength, bool lazy)
|
|
\brief Truncate the string to the new length.
|
|
|
|
\param newLength The new length of the string in bytes.
|
|
\param lazy If true, the memory-optimization is postponed until later.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::TruncateChars(int32 newCharCount, bool lazy)
|
|
\brief UTF-8 aware version of Truncate(int32, bool).
|
|
|
|
\param newCharCount The new length of the string in UTF-8 characters.
|
|
\param lazy If true, the memory-optimization is postponed until later.
|
|
|
|
\see Truncate(int32, bool)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Remove(int32 from, int32 length)
|
|
\brief Remove some bytes, starting at the given offset
|
|
|
|
\param from The offset in bytes to start removing.
|
|
\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 UTF-8 aware version of Remove(int32, int32).
|
|
|
|
\param fromCharOffset The offset in UTF-8 characters to start removing.
|
|
\param charCount The number of UTF-8 characters to remove.
|
|
|
|
\return This function always returns \c *this.
|
|
|
|
\see Remove(int32, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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)
|
|
\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)
|
|
\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)
|
|
\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)
|
|
\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)
|
|
\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)
|
|
\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 UTF-8 aware version of RemoveSet(const char*).
|
|
|
|
\param setOfCharsToRemove The set of characters to remove.
|
|
|
|
\return This function always returns \c *this.
|
|
|
|
\see RemoveSet(const char*)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 to move the string into.
|
|
\param from The offset (zero-based) in bytes where to begin the move.
|
|
\param length The number of bytes to move.
|
|
|
|
\return This method always returns \c into.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 to move the string into.
|
|
\param from The offset (zero-based) in bytes where to begin the move.
|
|
\param length The number of bytes to move.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::MoveCharsInto(BString& into, int32 fromCharOffset,
|
|
int32 charCount)
|
|
\brief UTF-8 aware version of MoveInto(BString&, int32, int32)
|
|
|
|
\param into The BString where to move the string into.
|
|
\param fromCharOffset The offset (zero-based) in UTF-8 characters where to
|
|
begin the move.
|
|
\param charCount The number of UTF-8 characters to move.
|
|
|
|
\see MoveInto(BString&, int32, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::MoveCharsInto(char* into, int32* intoLength,
|
|
int32 fromCharOffset, int32 charCount)
|
|
\brief UTF-8 aware version of MoveInto(char*, int32*, int32, int32).
|
|
|
|
\param into The buffer to move the string into.
|
|
\param intoLength The offset (zero-based) in bytes where to begin the move.
|
|
\param fromCharOffset The offset (zero-based) in UTF-8 characters where to
|
|
begin the move.
|
|
\param charCount The number of UTF-8 characters to move.
|
|
|
|
\returns \c false if \a into was \c NULL, \c true otherwise.
|
|
|
|
\see MoveInto(char*, int32*, int32, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Comparison
|
|
|
|
There are two different comparison methods. First of all there
|
|
is the whole range of operators that return a boolean value, secondly
|
|
there are methods that return an integer value, both case sensitive
|
|
and case insensitive.
|
|
|
|
There are also global comparison operators and global compare functions.
|
|
You might need these in case you have a sort routine that takes a generic
|
|
comparison function, such as BList::SortItems().
|
|
See the String.h documentation file to see the specifics, though basically
|
|
there are the same as implemented in this class.
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn bool BString::operator<(const BString& string) const
|
|
\brief Lexicographically compare if this BString is less than the given
|
|
\a string.
|
|
|
|
\param string The \a string to compare against.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 \a string to compare against.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::operator==(const BString& 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 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 \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 a given 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 not equal to a given
|
|
string.
|
|
|
|
\param string The \a string to compare against.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString::operator const char*() const
|
|
\brief Return an empty string.
|
|
|
|
\return An empty string.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int BString::Compare(const BString& string) const
|
|
\brief Lexicographically compare this BString to another \a string.
|
|
|
|
\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.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int BString::Compare(const char* string) const
|
|
\brief Lexicographically compare this BString to another \a string.
|
|
|
|
\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::Compare(const BString& 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 bytes 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.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 bytes 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 BString& string, int32 charCount) const
|
|
\brief UTF-8 aware version of Compare(const BString&, int32).
|
|
|
|
\param string The \a string to compare against.
|
|
\param charCount The number of UTF-8 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.
|
|
|
|
\see Compare(const BString&, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int BString::CompareChars(const char* string, int32 charCount) const
|
|
\brief UTF-8 aware version of Compare(const char*, int32).
|
|
|
|
\param string The \a string to compare against.
|
|
\param charCount The number of UTF-8 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.
|
|
|
|
\see Compare(const char*, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 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 BString& 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::ICompare(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
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Searching
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::FindFirst(const BString& string) const
|
|
\brief Find the first occurrence of the given \a string.
|
|
|
|
\param string The \a string to search for.
|
|
|
|
\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.
|
|
|
|
\sa IFindFirst(const BString&) const
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::FindFirst(const char* string) const
|
|
\brief Find the first occurrence of the given \a string.
|
|
|
|
\param string The \a string to search for.
|
|
|
|
\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.
|
|
|
|
\sa IFindFirst(const char*) const
|
|
\sa StartsWith(const char*) const
|
|
\sa StartsWith(const char*, int32) const
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 \a string to search for.
|
|
\param fromOffset The offset in bytes to start the search.
|
|
|
|
\return An integer which is 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.
|
|
|
|
\sa IFindFirst(const BString&, int32) const
|
|
\sa StartsWith(const char*, int32) const
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 \a string to search for.
|
|
\param fromOffset The offset in bytes to start the search.
|
|
|
|
\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.
|
|
|
|
\sa IFindFirst(const char*, int32) const
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::FindFirst(char c) const
|
|
\brief Find the first occurrence of the given character.
|
|
|
|
\param c The character to search for.
|
|
|
|
\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.
|
|
|
|
\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.
|
|
|
|
\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
|
|
was found, or \c B_ERROR if we could not find the character.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::FindFirstChars(const BString& string,
|
|
int32 fromCharOffset) const
|
|
\brief UTF-8 aware version of FindFirst(const BString&, int32).
|
|
|
|
\param string The \a string to search for.
|
|
\param fromCharOffset The offset in UTF-8 characters to start the search.
|
|
|
|
\return An integer which is 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.
|
|
|
|
\see FindFirst(const BString&, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::FindFirstChars(const char* string,
|
|
int32 fromCharOffset) const
|
|
\brief UTF-8 aware version of FindChars(const char*, int32).
|
|
|
|
\param string The \a string to search for.
|
|
\param fromCharOffset The offset in UTF-8 characters to start the search.
|
|
|
|
\see FindChars(const char*, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::FindLast(const BString& string) const
|
|
\brief Find the last occurrence of the given \a string.
|
|
|
|
\param string The \a string to search for.
|
|
|
|
\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.
|
|
|
|
\sa IFindLast(const BString&) const
|
|
\sa EndsWith(const BString&) const
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 in bytes (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.
|
|
|
|
\sa IFindLast(const char*) const
|
|
\sa EndsWith(const char*) const
|
|
\sa EndsWith(const char*, int32) const
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 in bytes to start the search.
|
|
|
|
\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.
|
|
|
|
\sa IFindLast(const BString&, int32) const
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 in bytes to start the search.
|
|
|
|
\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.
|
|
|
|
\sa IFindLast(const char*, int32) const
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::FindLast(char c) const
|
|
\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 BString
|
|
was found, or \c B_ERROR if we could not find the character.
|
|
|
|
\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 going backwards from the end.
|
|
|
|
\param c The character to search for.
|
|
\param beforeOffset The offset in bytes to start the search.
|
|
|
|
\return The offset (zero-based) into the data where the given character
|
|
was found, or \c B_ERROR Could not find the character.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::FindLastChars(const BString& string,
|
|
int32 beforeCharOffset) const
|
|
\brief UTF-8 aware version of FindLast(const BString&, int32).
|
|
|
|
\param string The BString to search for.
|
|
\param beforeCharOffset The offset in UTF-8 characters to start the search.
|
|
|
|
\return The offset in bytes (zero-based) into the data where the given
|
|
BString was found, or \c B_ERROR if we could not find the
|
|
\c string.
|
|
|
|
\see FindLast(const BString&, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::FindLastChars(const char* string,
|
|
int32 beforeCharOffset) const
|
|
\brief UTF-8 aware version of FindLast(const char*, int32).
|
|
|
|
\param string The string to search for.
|
|
\param beforeCharOffset The offset in UTF-8 characters to start the search.
|
|
|
|
\return The offset in bytes (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.
|
|
|
|
\see FindLast(const char*, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::IFindFirst(const BString& string) const
|
|
\brief Find the first occurrence of the given \a string case-insensitively.
|
|
|
|
\copydetails FindFirst(const BString&) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::IFindFirst(const char* string) const
|
|
\brief Find the first occurrence of the given \a string case-insensitively.
|
|
|
|
\param string The \a string to search for.
|
|
|
|
\copydetails FindFirst(const char*) 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.
|
|
|
|
\copydetails FindFirst(const BString&, int32) 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.
|
|
|
|
\copydetails FindFirst(const char*, int32) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::IFindLast(const BString& string) const
|
|
\brief Find the last occurrence of the given BString case-insensitively.
|
|
|
|
\copydetails FindLast(const BString&) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BString::IFindLast(const char* string) const
|
|
\brief Find the last occurrence of the given string case-insensitively.
|
|
|
|
\copydetails FindLast(const char*) 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 going backwards.
|
|
|
|
\copydetails FindLast(const BString&, int32) 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 going backwards.
|
|
|
|
\copydetails FindLast(const char*, int32) const
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::StartsWith(const BString& string) const
|
|
\brief Returns whether or not the BString starts with \a string.
|
|
|
|
\param string The \a string to search for.
|
|
|
|
\return \c true if the BString started with \a string, \c false otherwise.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::StartsWith(const char* string) const
|
|
\brief Returns whether or not the BString starts with \a string.
|
|
|
|
\param string The \a string to search for.
|
|
|
|
\return \c true if the BString started with \a string, \c false otherwise.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::StartsWith(const char* string, int32 length) const
|
|
\brief Returns whether or not the BString starts with \a length characters
|
|
of \a string.
|
|
|
|
\param string The \a string to search for.
|
|
\param length The number of characters (bytes) of \a string to search for.
|
|
|
|
\return \c true if the BString started with \a length characters of
|
|
\a string, \c false otherwise.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::EndsWith(const BString& string) const
|
|
\brief Returns whether or not the BString ends with \a string.
|
|
|
|
\param string The \a string to search for.
|
|
|
|
\return \c true if the BString ended with \a string, \c false otherwise.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::EndsWith(const char* string) const
|
|
\brief Returns whether or not the BString ends with \a string.
|
|
|
|
\param string The \a string to search for.
|
|
|
|
\return \c true if the BString ended with \a string, \c false otherwise.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::EndsWith(const char* string, int32 length) const
|
|
\brief Returns whether or not the BString ends with \a length characters
|
|
of \a string.
|
|
|
|
\param string The \a string to search for.
|
|
\param length The number of characters (bytes) of \a string to search for.
|
|
|
|
\return \c true if the BString ended with \a length characters of
|
|
\a string, \c false otherwise.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Replacing
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::ReplaceFirst(char replaceThis, char withThis)
|
|
\brief Replace the first occurrence of a character with another character.
|
|
|
|
\param replaceThis The character to replace.
|
|
\param withThis The character to put in its place.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa IReplaceFirst(char, char)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::ReplaceLast(char replaceThis, char withThis)
|
|
\brief Replace the last occurrence of a character with another character.
|
|
|
|
\param replaceThis The character to replace.
|
|
\param withThis The character to put in its place
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa IReplaceLast(char, char)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 its place
|
|
\param fromOffset The offset in bytes to start looking for the character.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa IReplaceAll(char, char, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::Replace(char replaceThis, char withThis,
|
|
int32 maxReplaceCount, int32 fromOffset)
|
|
\brief Replace a number of occurrences of a character with another
|
|
character.
|
|
|
|
\param replaceThis The character to replace.
|
|
\param withThis The character to put in its place
|
|
\param maxReplaceCount The maximum number of characters that should be
|
|
replaced.
|
|
\param fromOffset The offset in bytes to start looking for the character
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa IReplace(char, char, int32, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 its place
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa IReplaceFirst(const char*, const char*)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 its place
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa IReplaceLast(const char*, const char*)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 its place
|
|
\param fromOffset The offset in bytes to start looking for the string.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa IReplaceAll(const char*, const char*, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 its place
|
|
\param maxReplaceCount The maximum number of occurrences that should
|
|
be replaced.
|
|
\param fromOffset The offset in bytes to start looking for the string.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa IReplace(const char*, const char*, int32, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::ReplaceAllChars(const char* replaceThis,
|
|
const char* withThis, int32 fromCharOffset)
|
|
\brief UTF-8 aware version of ReplaceAll(const char*, const char*, int32).
|
|
|
|
\param replaceThis The string to replace.
|
|
\param withThis The string to put in its place
|
|
\param fromCharOffset The offset in UTF-8 characters to start looking for
|
|
the string.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see ReplaceAll(const char*, const char*, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::ReplaceChars(const char* replaceThis,
|
|
const char* withThis, int32 maxReplaceCount, int32 fromCharOffset)
|
|
\brief UTF-8 aware version of
|
|
ReplaceAll(const char*, const char*, int32, int32).
|
|
|
|
\param replaceThis The string to replace.
|
|
\param withThis The string to put in its place
|
|
\param maxReplaceCount The maximum number of occurrences that should
|
|
be replaced.
|
|
\param fromCharOffset The offset in UTF-8 characters to start looking for
|
|
the string.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\see ReplaceAll(const char*, const char*, int32, int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::IReplaceFirst(char replaceThis, char withThis)
|
|
\brief Replace the first occurrence of a character with another
|
|
character case-insensitively.
|
|
|
|
\param replaceThis The string to replace.
|
|
\param withThis The string to put in its place
|
|
|
|
\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-insensitively.
|
|
|
|
\param replaceThis The string to replace.
|
|
\param withThis The string to put in its place
|
|
|
|
\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-insensitively.
|
|
|
|
\param replaceThis The string to replace.
|
|
\param withThis The string to put in its place
|
|
\param fromOffset The offset where to start looking for the string
|
|
|
|
\sa ReplaceAll(char, char, int32)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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-insensitively.
|
|
|
|
\param replaceThis The char to replace.
|
|
\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, 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-insensitively.
|
|
|
|
\param replaceThis The string to replace.
|
|
\param withThis The string to put in its place.
|
|
|
|
\sa ReplaceFirst(const char*, const char*)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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 its place.
|
|
|
|
\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-insensitively.
|
|
|
|
\param replaceThis The string to replace.
|
|
\param withThis The string to put in its place.
|
|
\param fromOffset The offset where to start looking for the string.
|
|
|
|
\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-insensitively.
|
|
|
|
\param replaceThis The string to replace.
|
|
\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*, 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.
|
|
|
|
\param setOfBytes The set of characters that need to be replaced.
|
|
\param with The character to replace the occurrences with.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::ReplaceSet(const char* setOfBytes, const char* with)
|
|
\brief Replaces characters that are in a certain set with a chosen string.
|
|
|
|
\param setOfBytes The set of chars that need to be replaced.
|
|
\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,
|
|
const char* with)
|
|
\brief UTF-8 aware version of ReplaceSet(const char*, const char*)
|
|
|
|
\param setOfChars The set of UTF-8 characters that need to be replaced.
|
|
\param with The string to replace the occurrences with.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
// @}
|
|
|
|
|
|
/*!
|
|
\name Indexing
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn char& BString::operator[](int32 index)
|
|
\brief Return a reference to the data at the given offset.
|
|
|
|
This function can be used to read a byte.
|
|
There is no bounds checking though, so make sure the \c index
|
|
you supply is valid.
|
|
|
|
\param index The index (zero-based) of the byte to get.
|
|
|
|
\return Returns a reference to the specified byte.
|
|
|
|
\sa ByteAt(int32 index) for a safer version.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn char BString::operator[](int32 index) const
|
|
\brief Returns the character in the string at the given offset.
|
|
|
|
This function can be used to read a byte. There is no bound checking
|
|
though, use ByteAt() if you don't know if the \c index parameter is
|
|
valid.
|
|
|
|
\param index The index (zero-based) of the byte to get.
|
|
|
|
\return Returns a reference to the specified byte.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\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.
|
|
|
|
\param index The index (zero-based) of the byte to get.
|
|
|
|
\return A reference to the specified byte, if out of bounds return 0.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn const char* BString::CharAt(int32 charIndex, int32* bytes) const
|
|
\brief UTF-8 aware version of ByteAt(int32).
|
|
|
|
\param charIndex The index (zero-based) of the UTF-8 character to get.
|
|
\param bytes An int32 pointer to hold the UTF-8 character.
|
|
|
|
\return A reference to the specified UTF-8 character, if out of bounds
|
|
return 0.
|
|
|
|
\see ByteAt(int32)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BString::CharAt(int32 charIndex, char* buffer,
|
|
int32* bytes) const
|
|
\brief UTF-8 aware version of ByteAt(int32) with a \a buffer parameter.
|
|
|
|
\param charIndex The index (zero-based) of the UTF-8 character to get.
|
|
\param buffer Set to the position in the string where the character is
|
|
found.
|
|
\param bytes An int32 pointer to hold the UTF-8 character.
|
|
|
|
\see ByteAt(int32, char*, int32*)
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Low-Level Manipulation
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn char* BString::LockBuffer(int32 maxLength)
|
|
\brief Locks the buffer and return the internal string for manipulation.
|
|
|
|
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 in bytes. 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 to manipulate.
|
|
|
|
\sa UnlockBuffer()
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::UnlockBuffer(int32 length)
|
|
\brief Unlocks the buffer after you are done with low-level manipulation.
|
|
|
|
\param length The length in bytes to trim the string to in order to keep
|
|
the internal buffer sane. If you don't pass a value in it,
|
|
<tt>strlen()</tt> will be used to determine the length.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Case Manipulation
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::ToLower()
|
|
\brief Convert each of the characters in the BString to lowercase.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::ToUpper()
|
|
\brief Convert each of the characters in 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, and the 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, and the rest
|
|
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
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\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
|
|
escaping, where you place a character before the character that is
|
|
to be escaped, and not HTML style escaping, where certain characters
|
|
are replaced by something else.
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::CharacterEscape(const char* original,
|
|
const char* setOfCharsToEscape, char escapeWith)
|
|
\brief Escape selected characters on a given string.
|
|
|
|
This version sets itself to the string supplied in the \c original
|
|
parameter, and then escapes the selected characters with a supplied
|
|
character.
|
|
|
|
\param original The string to be escaped.
|
|
\param setOfCharsToEscape The set of characters that need to be escaped.
|
|
\param escapeWith The character to escape with.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa CharacterDeescape(char)
|
|
\sa CharacterDeescape(const char*, char)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::CharacterEscape(const char* setOfCharsToEscape,
|
|
char escapeWith)
|
|
\brief Escape selected characters of this string.
|
|
|
|
\param setOfCharsToEscape The set of characters that need to be escaped.
|
|
\param escapeWith The character to escape with.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa CharacterDeescape(char)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::CharacterDeescape(const char* original,
|
|
char escapeChar)
|
|
\brief Remove the character to escape with from a given string.
|
|
|
|
This version sets itself to the string supplied in the \c original
|
|
parameter, and then removes the escape characters.
|
|
|
|
\param original The string to be escaped.
|
|
\param escapeChar The character that was used to escape with.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa CharacterEscape(const char*, const char*, char)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::CharacterDeescape(char escapeChar)
|
|
\brief Remove the character to escape with from this string.
|
|
|
|
\param escapeChar The character that was used to escape with.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\sa CharacterEscape(const char*, char)
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name <tt>sprintf()</tt> Replacement Methods
|
|
|
|
These methods may be slower than <tt>sprintf()</tt>, but they are overflow safe.
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\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 \a string to the BString.
|
|
|
|
\param string The \a string to append.
|
|
|
|
\return This method always returns \c *this.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator<<(char c)
|
|
\brief Append \a c to the BString.
|
|
|
|
\param c The character to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator<<(bool value)
|
|
\brief Convert the \c bool \c value to a string and append it.
|
|
|
|
In case the \a value is true, the string "true" is appended to the string.
|
|
Otherwise, the string "false" is appended.
|
|
|
|
\param value The boolean \c value ("true" of "false") to append.
|
|
|
|
\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.
|
|
|
|
\param value The \c int \a value to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator<<(unsigned int value)
|
|
\brief Convert the <tt>unsigned int</tt> \a value to a string and append it.
|
|
|
|
\param value The <tt>unsigned int</tt> \a value to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator<<(unsigned long value)
|
|
\brief Convert the <tt>unsigned long</tt> \a value to a string and append it.
|
|
|
|
\param value The <tt>unsigned long</tt> \a value to append.
|
|
|
|
\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.
|
|
|
|
\param value The \c long \a value to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator<<(unsigned long long value)
|
|
\brief Convert the <tt>unsigned long long</tt> \a value to a string and
|
|
append it.
|
|
|
|
\param value The <tt>unsigned long long</tt> \a value to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator<<(long long value)
|
|
\brief Convert the <tt>long long</tt> \a value to a string and append it.
|
|
|
|
\param value The <tt>long long</tt> \a value to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator<<(float value)
|
|
\brief Convert the \c float \a value to a string and append it.
|
|
|
|
Using this operator will append using <tt>%.2f</tt> formatting.
|
|
|
|
\param value The \c float \a value to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BString& BString::operator<<(double value)
|
|
\brief Convert the \c double \a value to a string and append it.
|
|
|
|
Using this operator will append using <tt>%.2f</tt> formatting.
|
|
|
|
\param value The \c double \a value to append.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/************* end of BString class, start of general operators ************/
|
|
/*!
|
|
\addtogroup support_globals
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\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.
|
|
|
|
\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)
|
|
\brief Lexicographically compare if \c a is less 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.
|
|
|
|
\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 \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*) 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 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*) 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 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.
|
|
|
|
\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 \a b.
|
|
|
|
From String.h and in libbe.so.
|
|
|
|
\param a The first string to compare.
|
|
\param b The second string to compare.
|
|
|
|
\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)
|
|
\brief Lexicographically compare two strings.
|
|
|
|
This function is useful if you need a global compare function to feed to
|
|
BList::SortItems().
|
|
|
|
\param a The first string to compare.
|
|
\param b The second string to compare.
|
|
|
|
From String.h and in libbe.so.
|
|
|
|
\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)
|
|
\brief Lexicographically compare two strings case-insensitively.
|
|
|
|
This function is useful if you need a global compare function to feed to
|
|
BList::SortItems().
|
|
|
|
From String.h and in libbe.so.
|
|
|
|
\param a The first string to compare.
|
|
\param b The second string to compare.
|
|
|
|
\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)
|
|
\brief Lexicographically compare two strings.
|
|
|
|
This function is useful if you need a global compare function to feed to
|
|
BList::SortItems().
|
|
|
|
From String.h and in libbe.so.
|
|
|
|
\param a The first string to compare.
|
|
\param b The second string to compare.
|
|
|
|
\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)
|
|
\brief Lexicographically compare two strings case-insensitively.
|
|
|
|
This function is useful if you need a global compare function to feed to
|
|
BList::SortItems().
|
|
|
|
From String.h and in libbe.so.
|
|
|
|
\param a The first string to compare.
|
|
\param b The second string to compare.
|
|
|
|
\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
|
|
*/
|
|
|
|
|
|
//! @}
|