BString Class Reference

String class supporting common string operations. More...

#include <String.h>

Public Member Functions
	BString ()
	Creates an empty BString.
	BString (BString &&string) noexcept
	Move the data from the string to this object.
	BString (const BString &string)
	Creates and initializes a BString as a copy of another string.
	BString (const char *string)
	Creates and initializes a BString from string.
	BString (const char *string, int32 maxLength)
	Creates and initializes a BString from a string up to maxLength characters.
	~BString ()
	Free all resources associated with the object.
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.
BString &	operator= (const BString &string)
	Re-initialize the object to a copy of the data of a BString.
BString &	operator= (const char *string)
	Re-initialize the BString to a copy of the data of a string.
BString &	operator= (char c)
	Re-initialize the BString to a character.
BString &	operator= (BString &&string) noexcept
	Move the contents of string to this BString object.
BString &	SetTo (const char *string)
	Re-initialize the BString to a copy of the data of a string.
BString &	SetTo (const char *string, int32 maxLength)
	Re-initialize the BString to a copy of the data of a string.
BString &	SetTo (const BString &string)
	Re-initialize the BString to a copy of the data of a BString.
BString &	Adopt (BString &from)
	Adopt the data of the given BString object.
BString &	SetTo (const BString &string, int32 maxLength)
	Re-initialize the string to a copy of the given BString object.
BString &	Adopt (BString &from, int32 maxLength)
	Adopt the data of the given BString object up to maxLength characters.
BString &	SetTo (char c, int32 count)
	Re-initialize the object to a string composed of a character you specify.
BString &	SetToChars (const char *string, int32 charCount)
	UTF-8 aware version of SetTo(const char*, int32)
BString &	SetToChars (const BString &string, int32 charCount)
	UTF-8 aware version of SetTo(BString&, int32)
BString &	AdoptChars (BString &from, int32 charCount)
	UTF-8 aware version of Adopt(BString&, int32)
BString &	SetToFormat (const char *format,...)
	Sets the string to a formatted string ala sprintf().
BString &	SetToFormatVarArgs (const char *format, va_list args)
	Sets the string to a formatted string ala sprintf().
int	ScanWithFormat (const char *format,...)
	Parse a formatted string and save elements to variables ala scanf().
int	ScanWithFormatVarArgs (const char *format, va_list args)
	Parse a formatted string and save elements to variables ala scanf().
Substring Copying
BString &	CopyInto (BString &into, int32 fromOffset, int32 length) const
	Copy the object's data (or part of it) into another BString.
void	CopyInto (char *into, int32 fromOffset, int32 length) const
	Copy the BString data (or part of it) into the supplied buffer.
BString &	CopyCharsInto (BString &into, int32 fromCharOffset, int32 charCount) const
	UTF-8 aware version of CopyInto(BString&, int32, int32) const.
bool	CopyCharsInto (char *into, int32 *intoLength, int32 fromCharOffset, int32 charCount) const
	UTF-8 aware version of CopyInto(char*, int32, int32) const.
bool	Split (const char *separator, bool noEmptyStrings, BStringList &_list) const
	Split the string by the separator chars into _list.
Appending
BString &	operator+= (const BString &string)
	Append the given string to the end of the BString.
BString &	operator+= (const char *string)
	Append the given string to the end of the BString.
BString &	operator+= (char c)
	Append the given character to the end of the BString.
BString &	Append (const BString &string)
	Append the given string to the end of the BString.
BString &	Append (const char *string)
	Append the string data to the end of the BString.
BString &	Append (const BString &string, int32 length)
	Append a part of the given string to the end of the BString.
BString &	Append (const char *string, int32 length)
	Append a part of the given string to end of the BString.
BString &	Append (char c, int32 count)
	Append the given character repeatedly to the end of the BString.
BString &	AppendChars (const BString &string, int32 charCount)
	UTF-8 aware version of Append(const BString&, int32).
BString &	AppendChars (const char *string, int32 charCount)
	UTF-8 aware version of Append(const char*, int32).
Prepending
BString &	Prepend (const char *string)
	Prepend the given string to the beginning of the BString.
BString &	Prepend (const BString &string)
	Prepend the given BString to the beginning of the BString.
BString &	Prepend (const char *string, int32 length)
	Prepend the given string to the beginning of the BString.
BString &	Prepend (const BString &string, int32 length)
	Prepend the given BString to the beginning of the BString.
BString &	Prepend (char c, int32 count)
	Prepend the given character count times to the beginning of the BString.
BString &	PrependChars (const char *string, int32 charCount)
	UTF-8 aware version of Prepend(const char*, int32).
BString &	PrependChars (const BString &string, int32 charCount)
	UTF-8 aware version of Prepend(const BString&, int32).
Inserting
BString &	Insert (const char *string, int32 position)
	Inserts the given string at the given position into the BString data.
BString &	Insert (const char *string, int32 length, int32 position)
	Inserts the given string at the given position into the BString data.
BString &	Insert (const char *string, int32 fromOffset, int32 length, int32 position)
	Inserts the given string at the given position into the BString data.
BString &	Insert (const BString &string, int32 position)
	Inserts the given BString at the given position into the BString data.
BString &	Insert (const BString &string, int32 length, int32 position)
	Inserts the given BString at the given position into the BString data.
BString &	Insert (const BString &string, int32 fromOffset, int32 length, int32 position)
	Inserts the given string at the given position into the BString data.
BString &	Insert (char c, int32 count, int32 position)
	Inserts the given character repeatedly at the given position into the BString data.
BString &	InsertChars (const char *string, int32 charPosition)
	UTF-8 aware version of Insert(const char*, int32).
BString &	InsertChars (const char *string, int32 charCount, int32 charPosition)
	UTF-8 aware version of Insert(const char*, int32, int32).
BString &	InsertChars (const char *string, int32 fromCharOffset, int32 charCount, int32 charPosition)
	UTF-8 aware version of Insert(const char*, int32, int32, int32).
BString &	InsertChars (const BString &string, int32 charPosition)
	UTF-8 aware version of Insert(const BString&, int32).
BString &	InsertChars (const BString &string, int32 charCount, int32 charPosition)
	UTF-8 aware version of Insert(const BString&, int32, int32).
BString &	InsertChars (const BString &string, int32 fromCharOffset, int32 charCount, int32 charPosition)
	UTF-8 aware version of Insert(const BString&, int32, int32, int32).
Removing
BString &	Truncate (int32 newLength, bool lazy=true)
	Truncate the string to the new length.
BString &	TruncateChars (int32 newCharCount, bool lazy=true)
	UTF-8 aware version of Truncate(int32, bool).
BString &	Remove (int32 from, int32 length)
	Remove some bytes, starting at the given offset.
BString &	RemoveChars (int32 fromCharOffset, int32 charCount)
	UTF-8 aware version of Remove(int32, int32).
BString &	RemoveFirst (const BString &string)
	Remove the first occurrence of the given BString.
BString &	RemoveLast (const BString &string)
	Remove the last occurrence of the given BString.
BString &	RemoveAll (const BString &string)
	Remove all occurrences of the given BString.
BString &	RemoveFirst (const char *string)
	Remove the first occurrence of the given string.
BString &	RemoveLast (const char *string)
	Remove the last occurrence of the given string.
BString &	RemoveAll (const char *string)
	Remove all occurrences of the given string.
BString &	RemoveSet (const char *setOfBytesToRemove)
	Remove all the characters specified.
BString &	RemoveCharsSet (const char *setOfCharsToRemove)
	UTF-8 aware version of RemoveSet(const char*).
BString &	MoveInto (BString &into, int32 from, int32 length)
	Move the BString data (or part of it) into another BString.
void	MoveInto (char *into, int32 from, int32 length)
	Move the BString data (or part of it) into the given buffer.
BString &	MoveCharsInto (BString &into, int32 fromCharOffset, int32 charCount)
	UTF-8 aware version of MoveInto(BString&, int32, int32)
bool	MoveCharsInto (char *into, int32 *intoLength, int32 fromCharOffset, int32 charCount)
	UTF-8 aware version of MoveInto(char*, int32*, int32, int32).
BString &	Trim ()
	Removes spaces from the beginning and end of the string.
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.
bool	operator< (const BString &string) const
	Lexicographically compare if this BString is less than the given string.
bool	operator<= (const BString &string) const
	Lexicographically compare if this BString is less than or equal to the given string.
bool	operator== (const BString &string) const
	Lexicographically compare if this BString is equal to the given string.
bool	operator>= (const BString &string) const
	Lexicographically compare if this BString is greater than or equal to the given string.
bool	operator> (const BString &string) const
	Lexicographically compare if this BString is greater than the given string.
bool	operator!= (const BString &string) const
	Lexicographically compare if this BString is not equal to the given string.
bool	operator< (const char *string) const
	Lexicographically compare if this BString is less than the given string.
bool	operator<= (const char *string) const
	Lexicographically compare if this BString is less than or equal to the given string.
bool	operator== (const char *string) const
	Lexicographically compare if this BString is equal to the given string.
bool	operator>= (const char *string) const
	Lexicographically compare if this string is more than or equal to a given string.
bool	operator> (const char *string) const
	Lexicographically compare if this string is more than a given string.
bool	operator!= (const char *string) const
	Lexicographically compare if this string is not equal to a given string.
	operator const char * () const
	Return an empty string.
int	Compare (const BString &string) const
	Lexicographically compare this BString to another string.
int	Compare (const char *string) const
	Lexicographically compare this BString to another string.
int	Compare (const BString &string, int32 length) const
	Lexicographically compare length characters of this BString to another string.
int	Compare (const char *string, int32 length) const
	Lexicographically compare length characters of this BString to another string.
int	CompareAt (size_t offset, const BString &string, int32 length) const
	Lexicographically compare length of characters of this BString to another string, starting at offset.
int	CompareChars (const BString &string, int32 charCount) const
	UTF-8 aware version of Compare(const BString&, int32).
int	CompareChars (const char *string, int32 charCount) const
	UTF-8 aware version of Compare(const char*, int32).
int	ICompare (const BString &string) const
	Lexicographically compare this BString to another string case-insensitively.
int	ICompare (const char *string) const
	Lexicographically compare this BString to another string case-insensitively.
int	ICompare (const BString &string, int32 length) const
	Lexicographically compare length characters of this BString to another string.
int	ICompare (const char *string, int32 length) const
	Lexicographically compare length characters of this BString to another string.
Searching
int32	FindFirst (const BString &string) const
	Find the first occurrence of the given string.
int32	FindFirst (const char *string) const
	Find the first occurrence of the given string.
int32	FindFirst (const BString &string, int32 fromOffset) const
	Find the first occurrence of the given string starting from the given offset.
int32	FindFirst (const char *string, int32 fromOffset) const
	Find the first occurrence of the given string, starting from the given offset.
int32	FindFirst (char c) const
	Find the first occurrence of the given character.
int32	FindFirst (char c, int32 fromOffset) const
	Find the first occurrence of the given character, starting from the given offset.
int32	FindFirstChars (const BString &string, int32 fromCharOffset) const
	UTF-8 aware version of FindFirst(const BString&, int32).
int32	FindFirstChars (const char *string, int32 fromCharOffset) const
	UTF-8 aware version of FindFirst(const char*, int32).
int32	FindLast (const BString &string) const
	Find the last occurrence of the given string.
int32	FindLast (const char *string) const
	Find the last occurrence of the given string.
int32	FindLast (const BString &string, int32 beforeOffset) const
	Find the last occurrence of the given BString, starting from the given offset, and going backwards.
int32	FindLast (const char *string, int32 beforeOffset) const
	Find the last occurrence of the given string, starting from the given offset, and going backwards.
int32	FindLast (char c) const
	Find the last occurrence of the given character.
int32	FindLast (char c, int32 beforeOffset) const
	Find the last occurrence of the given character, starting from the given offset going backwards from the end.
int32	FindLastChars (const BString &string, int32 beforeCharOffset) const
	UTF-8 aware version of FindLast(const BString&, int32).
int32	FindLastChars (const char *string, int32 beforeCharOffset) const
	UTF-8 aware version of FindLast(const char*, int32).
int32	IFindFirst (const BString &string) const
	Find the first occurrence of the given string case-insensitively.
int32	IFindFirst (const char *string) const
	Find the first occurrence of the given string case-insensitively.
int32	IFindFirst (const BString &string, int32 fromOffset) const
	Find the first occurrence of the given BString case-insensitively, starting from the given offset.
int32	IFindFirst (const char *string, int32 fromOffset) const
	Find the first occurrence of the given string case-insensitively, starting from the given offset.
int32	IFindLast (const BString &string) const
	Find the last occurrence of the given BString case-insensitively.
int32	IFindLast (const char *string) const
	Find the last occurrence of the given string case-insensitively.
int32	IFindLast (const BString &string, int32 beforeOffset) const
	Find the last occurrence of the given BString case-insensitively, starting from the given offset going backwards.
int32	IFindLast (const char *string, int32 beforeOffset) const
	Find the last occurrence of the given string case-insensitively, starting from the given offset going backwards.
bool	StartsWith (const BString &string) const
	Returns whether or not the BString starts with string.
bool	StartsWith (const char *string) const
	Returns whether or not the BString starts with string.
bool	StartsWith (const char *string, int32 length) const
	Returns whether or not the BString starts with length characters of string.
bool	IStartsWith (const BString &string) const
	Returns whether or not the BString starts with string case-insensitively.
bool	IStartsWith (const char *string) const
	Returns whether or not the BString starts with string case-insensitively.
bool	IStartsWith (const char *string, int32 length) const
	Returns whether or not the BString starts with length characters of string case-insensitively.
bool	EndsWith (const BString &string) const
	Returns whether or not the BString ends with string.
bool	EndsWith (const char *string) const
	Returns whether or not the BString ends with string.
bool	EndsWith (const char *string, int32 length) const
	Returns whether or not the BString ends with length characters of string.
bool	IEndsWith (const BString &string) const
	Returns whether or not the BString ends with string case-insensitively.
bool	IEndsWith (const char *string) const
	Returns whether or not the BString ends with string case-insensitively.
bool	IEndsWith (const char *string, int32 length) const
	Returns whether or not the BString ends with length characters of string case-insensitively.
Replacing
BString &	ReplaceFirst (char replaceThis, char withThis)
	Replace the first occurrence of a character with another character.
BString &	ReplaceLast (char replaceThis, char withThis)
	Replace the last occurrence of a character with another character.
BString &	ReplaceAll (char replaceThis, char withThis, int32 fromOffset=0)
	Replace all occurrences of a character with another character.
BString &	Replace (char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset=0)
	Replace a number of occurrences of a character with another character.
BString &	ReplaceFirst (const char *replaceThis, const char *withThis)
	Replace the first occurrence of a string with another string.
BString &	ReplaceLast (const char *replaceThis, const char *withThis)
	Replace the last occurrence of a string with another string.
BString &	ReplaceAll (const char *replaceThis, const char *withThis, int32 fromOffset=0)
	Replace all occurrences of a string with another string.
BString &	Replace (const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset=0)
	Replace a number of occurrences of a string with another string.
BString &	ReplaceAllChars (const char *replaceThis, const char *withThis, int32 fromCharOffset)
	UTF-8 aware version of ReplaceAll(const char*, const char*, int32).
BString &	ReplaceChars (const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromCharOffset)
	UTF-8 aware version of ReplaceAll(const char*, const char*, int32, int32).
BString &	IReplaceFirst (char replaceThis, char withThis)
	Replace the first occurrence of a character with another character case-insensitively.
BString &	IReplaceLast (char replaceThis, char withThis)
	Replace the last occurrence of a character with another character case-insensitively.
BString &	IReplaceAll (char replaceThis, char withThis, int32 fromOffset=0)
	Replace all occurrences of a character with another character case-insensitively.
BString &	IReplace (char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset=0)
	Replace a number of occurrences of a character with another character case-insensitively.
BString &	IReplaceFirst (const char *replaceThis, const char *withThis)
	Replace the first occurrence of a string with another string case-insensitively.
BString &	IReplaceLast (const char *replaceThis, const char *withThis)
	Replace the last occurrence of a string with another string. Case-insensitive.
BString &	IReplaceAll (const char *replaceThis, const char *withThis, int32 fromOffset=0)
	Replace all occurrences of a string with another string case-insensitively.
BString &	IReplace (const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset=0)
	Replace a number of occurrences of a string with another string case-insensitively.
BString &	ReplaceSet (const char *setOfBytes, char with)
	Replaces characters that are in a certain set with a chosen character.
BString &	ReplaceSet (const char *setOfBytes, const char *with)
	Replaces characters that are in a certain set with a chosen string.
BString &	ReplaceCharsSet (const char *setOfChars, const char *with)
	UTF-8 aware version of ReplaceSet(const char*, const char*)
Indexing
char	operator[] (int32 index) const
	Returns the character in the string at the given offset.
char	ByteAt (int32 index) const
	Returns the character in the string at the given offset.
const char *	CharAt (int32 charIndex, int32 *bytes=NULL) const
	UTF-8 aware version of ByteAt(int32).
bool	CharAt (int32 charIndex, char *buffer, int32 *bytes) const
	UTF-8 aware version of ByteAt(int32) with a buffer parameter.
Low-Level Manipulation
char *	LockBuffer (int32 maxLength)
	Locks the buffer and return the internal string for manipulation.
BString &	UnlockBuffer (int32 length=-1)
	Unlocks the buffer after you are done with low-level manipulation.
BString &	SetByteAt (int32 pos, char to)
	Set a byte at position pos to character to.
Case Manipulation
BString &	ToLower ()
	Convert each of the characters in the BString to lowercase.
BString &	ToUpper ()
	Convert each of the characters in the BString to uppercase.
BString &	Capitalize ()
	Convert the first character to uppercase, and the rest to lowercase.
BString &	CapitalizeEachWord ()
	Convert the first character of every word to uppercase, and the rest to lowercase.
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.
BString &	CharacterEscape (const char *original, const char *setOfCharsToEscape, char escapeWith)
	Escape selected characters on a given string.
BString &	CharacterEscape (const char *setOfCharsToEscape, char escapeWith)
	Escape selected characters of this string.
BString &	CharacterDeescape (const char *original, char escapeChar)
	Remove the character to escape with from a given string.
BString &	CharacterDeescape (char escapeChar)
	Remove the character to escape with from this string.
sprintf() Replacement Methods
These methods may be slower than sprintf(), but they are overflow safe.
BString &	operator<< (const char *string)
	Append string to the BString.
BString &	operator<< (const BString &string)
	Append string to the BString.
BString &	operator<< (char c)
	Append c to the BString.
BString &	operator<< (bool value)
	Convert the bool value to a string and append it.
BString &	operator<< (int value)
	Convert the int value to a string and append it.
BString &	operator<< (unsigned int value)
	Convert the unsigned int value to a string and append it.
BString &	operator<< (unsigned long value)
	Convert the unsigned long value to a string and append it.
BString &	operator<< (long value)
	Convert the long value to a string and append it.
BString &	operator<< (unsigned long long value)
	Convert the unsigned long long value to a string and append it.
BString &	operator<< (long long value)
	Convert the long long value to a string and append it.
BString &	operator<< (float value)
	Convert the float value to a string and append it.
BString &	operator<< (double value)
	Convert the double value to a string and append it.

Access
const char *	String () const
	Return a pointer to the object string, NUL terminated.
int32	Length () const
	Get the length of the string in bytes.
int32	CountChars () const
	Returns the length of the object measured in characters.
int32	CountBytes (int32 fromCharOffset, int32 charCount) const
	Count the number of bytes starting from a specified character.
bool	IsEmpty () const
	Check whether the string is empty.
uint32	HashValue () const
	Return a hash value for the current string.
static uint32	HashValue (const char *string)
	Return the hash value of a specified string.

Detailed Description

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

Constructor & Destructor Documentation

BString() [1/5]

BString::BString

(

)

Creates an empty BString.

Since

BeOS R5

BString() [2/5]

BString::BString

(

const char *

string

)

Creates and initializes a BString from string.

Parameters

string

The string to copy from.

Since

BeOS R5

BString() [3/5]

BString::BString

(

const BString &

string

)

Creates and initializes a BString as a copy of another string.

Parameters

string

The BString object to copy from.

Since

BeOS R5

BString() [4/5]

BString::BString	(	const char *	string,
		int32	maxLength
	)

Creates and initializes a BString from a string up to maxLength characters.

If maxLength is greater than the length of the source string then the entire source string is copied. If maxLength is less than or equal to 0 then the result is an empty BString.

Warning

In BeOS R5 passing in a negative maxLength argument will copy the entire string.

Parameters

string	The string data to initialize the BString to.
maxLength	Maximum number of characters (bytes) to copy.

Since

BeOS R5

BString() [5/5]

BString::BString ( BString &&  string )

noexcept

Move the data from the string to this object.

Create a new string object with the data of another string. The string will no longer point to the same contents.

Note

This constructor is only available for modern C++ (C++11 or later).

Since

Haiku R1

~BString()

BString::~BString

(

)

Free all resources associated with the object.

The destructor also frees the internal buffer associated with the string.

Since

BeOS R5

Member Function Documentation

Adopt() [1/2]

BString & BString::Adopt

(

BString &

from

)

Adopt the data of the given BString object.

This method adopts the data from a BString removing the data from 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 NULL string. If the from object was created on the heap you need to clean it up yourself.

Parameters

from	The string data to adopt.

Returns

The function always returns *this.

See also

operator=(const BString&)

Since

BeOS R5

Adopt() [2/2]

BString & BString::Adopt	(	BString &	from,
		int32	maxLength
	)

Adopt the data of the given BString object up to maxLength characters.

This method adopts the data from a BString removing the data from from and putting it into the BString.

Parameters

from	The string object to adopt.
maxLength	Maximum number of characters (bytes) to adopt.

Returns

The function always returns *this.

See also

SetTo(const BString&, int32)

Since

BeOS R5

AdoptChars()

BString & BString::AdoptChars	(	BString &	from,
		int32	charCount
	)

UTF-8 aware version of Adopt(BString&, int32)

Parameters

from	The string data to start adopting from.
charCount	Number of UTF-8 characters to adopt.

Returns

This method always returns *this.

Since

Haiku R1

Append() [1/5]

BString & BString::Append	(	char	c,
		int32	count
	)

Append the given character repeatedly to the end of the BString.

Parameters

c	The character to append.
count	The number of times this character should be appended.

Returns

This method always returns *this.

See also

operator+=(char c)

Since

BeOS R5

Append() [2/5]

BString & BString::Append ( const BString &  string )

inline

Append the given string to the end of the BString.

Parameters

string

The string to append.

Returns

This method always returns *this.

See also

Append(const BString&, int32)

Since

BeOS R5

References Length(), and String().

Append() [3/5]

BString & BString::Append	(	const BString &	string,
		int32	length
	)

Append a part of the given string to the end of the BString.

Parameters

string	The BString to append.
length	The maximum number of bytes to append.

Returns

This method always returns *this.

See also

operator+=(const BString&)

Since

BeOS R5

Append() [4/5]

BString & BString::Append ( const char *  str )

inline

Append the string data to the end of the BString.

This method calls operator+=(const char *str).

See also

Append(const char*, int32)

Since

BeOS R5

References operator+=().

Append() [5/5]

BString & BString::Append	(	const char *	str,
		int32	length
	)

Append a part of the given string to end of the BString.

Parameters

str	A pointer to the string to append.
length	The maximum number of bytes to append.

Returns

This method always returns *this.

See also

operator+=(const char*)

Since

BeOS R5

AppendChars() [1/2]

BString & BString::AppendChars	(	const BString &	string,
		int32	charCount
	)

UTF-8 aware version of Append(const BString&, int32).

Parameters

string	The string to append.
charCount	The maximum number of UTF-8 characters to append.

Returns

This method always returns *this.

See also

Append(const BString&, int32)

Since

Haiku R1

AppendChars() [2/2]

BString & BString::AppendChars	(	const char *	string,
		int32	charCount
	)

UTF-8 aware version of Append(const char*, int32).

Parameters

string	The string to append.
charCount	The maximum number of UTF-8 characters to append.

Returns

This method always returns *this.

See also

Append(const char*, int32)

Since

Haiku R1

ByteAt()

char BString::ByteAt ( int32  index ) const

inline

Returns the character in the string at the given offset.

This function can be used to read a single byte.

Parameters

index

The index (zero-based) of the byte to get.

Returns

A reference to the specified byte, if out of bounds return 0.

Since

BeOS R5

References Length().

Capitalize()

BString & BString::Capitalize

(

)

Convert the first character to uppercase, and the rest to lowercase.

Returns

This method always returns *this.

Since

BeOS R5

CapitalizeEachWord()

BString & BString::CapitalizeEachWord

(

)

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.

Returns

This method always returns *this.

Since

BeOS R5

CharacterDeescape() [1/2]

BString & BString::CharacterDeescape

(

char

escapeChar

)

Remove the character to escape with from this string.

Parameters

escapeChar

The character that was used to escape with.

Returns

This method always returns *this.

See also

CharacterEscape(const char*, char)

CharacterDeescape() [2/2]

BString & BString::CharacterDeescape	(	const char *	original,
		char	escapeChar
	)

Remove the character to escape with from a given string.

This version sets itself to the string supplied in the original parameter, and then removes the escape characters.

Parameters

original	The string to be escaped.
escapeChar	The character that was used to escape with.

Returns

This method always returns *this.

See also

CharacterEscape(const char*, const char*, char)

Since

BeOS R5

CharacterEscape() [1/2]

BString & BString::CharacterEscape	(	const char *	original,
		const char *	setOfCharsToEscape,
		char	escapeWith
	)

Escape selected characters on a given string.

This version sets itself to the string supplied in the original parameter, and then escapes the selected characters with a supplied character.

Parameters

original	The string to be escaped.
setOfCharsToEscape	The set of characters that need to be escaped.
escapeWith	The character to escape with.

Returns

This method always returns *this.

See also

CharacterDeescape(char)

CharacterDeescape(const char*, char)

Since

BeOS R5

CharacterEscape() [2/2]

BString & BString::CharacterEscape	(	const char *	setOfCharsToEscape,
		char	escapeWith
	)

Escape selected characters of this string.

Parameters

setOfCharsToEscape	The set of characters that need to be escaped.
escapeWith	The character to escape with.

Returns

This method always returns *this.

See also

CharacterDeescape(char)

Since

BeOS R5

CharAt() [1/2]

bool BString::CharAt	(	int32	charIndex,
		char *	buffer,
		int32 *	bytes
	)		const

UTF-8 aware version of ByteAt(int32) with a buffer parameter.

Parameters

charIndex	The index (zero-based) of the UTF-8 character to get.
buffer	Set to the position in the string where the character is found.
bytes	An int32 pointer to hold the UTF-8 character.

See also

ByteAt(int32, char*, int32*)

Since

Haiku R1

CharAt() [2/2]

const char * BString::CharAt	(	int32	charIndex,
		int32 *	bytes = NULL
	)		const

UTF-8 aware version of ByteAt(int32).

Parameters

charIndex	The index (zero-based) of the UTF-8 character to get.
bytes	An int32 pointer to hold the UTF-8 character.

Returns

A reference to the specified UTF-8 character, if out of bounds return 0.

See also

ByteAt(int32)

Since

Haiku R1

Compare() [1/4]

int BString::Compare

(

const BString &

string

)

const

Lexicographically compare this BString to another string.

Parameters

string

The string to compare against.

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

Since

BeOS R5

Compare() [2/4]

int BString::Compare	(	const BString &	string,
		int32	length
	)		const

Lexicographically compare length characters of this BString to another string.

Parameters

string	The string to compare against.
length	The number of bytes to compare.

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

Since

BeOS R5

Compare() [3/4]

int BString::Compare

(

const char *

string

)

const

Lexicographically compare this BString to another string.

Parameters

string

The string to compare against.

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

See also

Compare(const BString&) const

Since

BeOS R5

Compare() [4/4]

int BString::Compare	(	const char *	string,
		int32	length
	)		const

Lexicographically compare length characters of this BString to another string.

Parameters

string	The string to compare against.
length	The number of bytes to compare.

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

See also

Compare(const BString&, int32) const

Since

BeOS R5

CompareAt()

int BString::CompareAt	(	size_t	offset,
		const BString &	string,
		int32	length
	)		const

Lexicographically compare length of characters of this BString to another string, starting at offset.

Parameters

offset	The offset (in bytes) to start comparison.
string	The string to compare against.
length	The number of bytes to compare.

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

See also

Compare(const BString&, int32) const

Since

Haiku R1

CompareChars() [1/2]

int BString::CompareChars	(	const BString &	string,
		int32	charCount
	)		const

UTF-8 aware version of Compare(const BString&, int32).

Parameters

string	The string to compare against.
charCount	The number of UTF-8 characters to compare.

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

See also

Compare(const BString&, int32)

Since

Haiku R1

CompareChars() [2/2]

int BString::CompareChars	(	const char *	string,
		int32	charCount
	)		const

UTF-8 aware version of Compare(const char*, int32).

Parameters

string	The string to compare against.
charCount	The number of UTF-8 characters to compare.

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

See also

Compare(const char*, int32)

Since

Haiku R1

CopyCharsInto() [1/2]

BString & BString::CopyCharsInto	(	BString &	into,
		int32	fromOffset,
		int32	charCount
	)		const

UTF-8 aware version of CopyInto(BString&, int32, int32) const.

Parameters

into	The BString to copy into.
fromOffset	The (zero-based) offset in bytes where to begin the copy.
charCount	The number of UTF-8 characters to copy.

Returns

This method always returns a pointer to the string passed as the into parameter.

See also

CopyInto(BString&, int32, int32) const

Since

Haiku R1

CopyCharsInto() [2/2]

bool BString::CopyCharsInto	(	char *	into,
		int32 *	intoLength,
		int32	fromCharOffset,
		int32	charCount
	)		const

UTF-8 aware version of CopyInto(char*, int32, int32) const.

Parameters

into	The buffer where to copy the object.
intoLength	The length of into in bytes.
fromCharOffset	The (zero-based) offset UTF-8 characters where to begin the copy.
charCount	The number of UTF-8 characters to copy.

See also

CopyInto(char*, int32, int32) const

Returns

false if into was NULL, true otherwise.

Since

Haiku R1

CopyInto() [1/2]

BString & BString::CopyInto	(	BString &	into,
		int32	fromOffset,
		int32	length
	)		const

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.

Parameters

into	The BString to copy into.
fromOffset	The (zero-based) offset where to begin the copy.
length	The number of bytes to copy.

Returns

This method always returns a pointer to the string passed as the into parameter.

Since

BeOS R5

CopyInto() [2/2]

void BString::CopyInto	(	char *	into,
		int32	fromOffset,
		int32	length
	)		const

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.

Parameters

into	The buffer where to copy the object.
fromOffset	The (zero-based) offset where to begin the copy.
length	The number of bytes to copy.

Since

BeOS R5

CountBytes()

int32 BString::CountBytes	(	int32	fromCharOffset,
		int32	charCount
	)		const

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.

Parameters

fromCharOffset	The index of the character (not the byte!) from which to start the count
charCount	The number of characters to count

Returns

An integer with the number of bytes.

Since

Haiku R1

CountChars()

int32 BString::CountChars

(

)

const

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.

Returns

An integer which is the number of characters in the string.

See also

Length()

Since

BeOS R5

EndsWith() [1/3]

bool BString::EndsWith

(

const BString &

string

)

const

Returns whether or not the BString ends with string.

Parameters

string

The string to search for.

Returns

true if the BString ended with string, false otherwise.

Since

Haiku R1

EndsWith() [2/3]

bool BString::EndsWith

(

const char *

string

)

const

Returns whether or not the BString ends with string.

Parameters

string

The string to search for.

Returns

true if the BString ended with string, false otherwise.

Since

Haiku R1

EndsWith() [3/3]

bool BString::EndsWith	(	const char *	string,
		int32	length
	)		const

Returns whether or not the BString ends with length characters of string.

Parameters

string	The string to search for.
length	The number of characters (bytes) of string to search for.

Returns

true if the BString ended with length characters of string, false otherwise.

Since

Haiku R1

FindFirst() [1/6]

int32 BString::FindFirst

(

char

c

)

const

Find the first occurrence of the given character.

Parameters

c	The character to search for.

Returns

The offset (zero-based) into the data where the given character was found, or B_ERROR if we could not find the character.

Since

BeOS R5

FindFirst() [2/6]

int32 BString::FindFirst	(	char	c,
		int32	fromOffset
	)		const

Find the first occurrence of the given character, starting from the given offset.

Parameters

c	The character to search for.
fromOffset	The offset where to start the search.

Returns

The offset (zero-based) into the data where the given character was found, or B_ERROR if we could not find the character.

Since

BeOS R5

FindFirst() [3/6]

int32 BString::FindFirst

(

const BString &

string

)

const

Find the first occurrence of the given string.

Parameters

string

The string to search for.

Returns

The offset (zero-based) into the data where the given BString was found or B_ERROR if we could not find string.

See also

IFindFirst(const BString&) const

Since

BeOS R5

FindFirst() [4/6]

int32 BString::FindFirst	(	const BString &	string,
		int32	fromOffset
	)		const

Find the first occurrence of the given string starting from the given offset.

Parameters

string	The string to search for.
fromOffset	The offset in bytes to start the search.

Returns

An integer which is the offset (zero-based) into the data where the given BString was found or B_ERROR if we could not find the string.

See also

IFindFirst(const BString&, int32) const

StartsWith(const char*, int32) const

Since

BeOS R5

FindFirst() [5/6]

int32 BString::FindFirst

(

const char *

string

)

const

Find the first occurrence of the given string.

Parameters

string

The string to search for.

Returns

The offset (zero-based) into the data where the given string was found, B_BAD_VALUE if the string pointer is invalid, or B_ERROR if we could not find string.

See also

IFindFirst(const char*) const

StartsWith(const char*) const

StartsWith(const char*, int32) const

Since

BeOS R5

FindFirst() [6/6]

int32 BString::FindFirst	(	const char *	string,
		int32	fromOffset
	)		const

Find the first occurrence of the given string, starting from the given offset.

Parameters

string	The string to search for.
fromOffset	The offset in bytes to start the search.

Returns

The offset (zero-based) into the data where the given string was found, B_BAD_VALUE if the string pointer is invalid, or B_ERROR if we could not find the string.

See also

IFindFirst(const char*, int32) const

Since

BeOS R5

FindFirstChars() [1/2]

int32 BString::FindFirstChars	(	const BString &	string,
		int32	fromCharOffset
	)		const

UTF-8 aware version of FindFirst(const BString&, int32).

Parameters

string	The string to search for.
fromCharOffset	The offset in UTF-8 characters to start the search.

Returns

An integer which is the offset (zero-based) into the data where the given BString was found or B_ERROR if we could not find the string.

See also

FindFirst(const BString&, int32)

Since

Haiku R1

FindFirstChars() [2/2]

int32 BString::FindFirstChars	(	const char *	string,
		int32	fromCharOffset
	)		const

UTF-8 aware version of FindFirst(const char*, int32).

Parameters

string	The string to search for.
fromCharOffset	The offset in UTF-8 characters to start the search.

See also

FindChars(const char*, int32)

Since

Haiku R1

FindLast() [1/6]

int32 BString::FindLast

(

char

c

)

const

Find the last occurrence of the given character.

Parameters

c	The character to search for.

Returns

The offset (zero-based) into the data where the given BString was found, or B_ERROR if we could not find the character.

Since

BeOS R5

FindLast() [2/6]

int32 BString::FindLast	(	char	c,
		int32	beforeOffset
	)		const

Find the last occurrence of the given character, starting from the given offset going backwards from the end.

Parameters

c	The character to search for.
beforeOffset	The offset in bytes to start the search.

Returns

The offset (zero-based) into the data where the given character was found, or B_ERROR Could not find the character.

Since

BeOS R5

FindLast() [3/6]

int32 BString::FindLast

(

const BString &

string

)

const

Find the last occurrence of the given string.

Parameters

string

The string to search for.

Returns

The offset (zero-based) into the data where the given BString was found, or B_ERROR if we could not find the string.

See also

IFindLast(const BString&) const

EndsWith(const BString&) const

Since

BeOS R5

FindLast() [4/6]

int32 BString::FindLast	(	const BString &	string,
		int32	beforeOffset
	)		const

Find the last occurrence of the given BString, starting from the given offset, and going backwards.

Parameters

string	The BString to search for.
beforeOffset	The offset in bytes to start the search.

Returns

The offset (zero-based) into the data where the given BString was found, or B_ERROR if we could not find the string.

See also

IFindLast(const BString&, int32) const

Since

BeOS R5

FindLast() [5/6]

int32 BString::FindLast

(

const char *

string

)

const

Find the last occurrence of the given string.

Parameters

string

The string to search for.

Returns

The offset in bytes (zero-based) into the data where the given string was found, B_BAD_VALUE if the string pointer is invalid, or B_ERROR if we could not find the string.

See also

IFindLast(const char*) const

EndsWith(const char*) const

EndsWith(const char*, int32) const

Since

BeOS R5

FindLast() [6/6]

int32 BString::FindLast	(	const char *	string,
		int32	beforeOffset
	)		const

Find the last occurrence of the given string, starting from the given offset, and going backwards.

Parameters

string	The string to search for.
beforeOffset	The offset in bytes to start the search.

Returns

The offset (zero-based) into the data where the given string was found, B_BAD_VALUE if the string pointer is invalid, or B_ERROR if we could not find the string.

See also

IFindLast(const char*, int32) const

Since

BeOS R5

FindLastChars() [1/2]

int32 BString::FindLastChars	(	const BString &	string,
		int32	beforeCharOffset
	)		const

UTF-8 aware version of FindLast(const BString&, int32).

Parameters

string	The BString to search for.
beforeCharOffset	The offset in UTF-8 characters to start the search.

Returns

The offset in bytes (zero-based) into the data where the given BString was found, or B_ERROR if we could not find the string.

See also

FindLast(const BString&, int32)

Since

Haiku R1

FindLastChars() [2/2]

int32 BString::FindLastChars	(	const char *	string,
		int32	beforeCharOffset
	)		const

UTF-8 aware version of FindLast(const char*, int32).

Parameters

string	The string to search for.
beforeCharOffset	The offset in UTF-8 characters to start the search.

Returns

The offset in bytes (zero-based) into the data where the given string was found, B_BAD_VALUE if the string pointer is invalid, or B_ERROR if we could not find the string.

See also

FindLast(const char*, int32)

Since

Haiku R1

HashValue() [1/2]

uint32 BString::HashValue ( ) const

inline

Return a hash value for the current string.

See also

HashValue(const char*)

Since

Haiku R1

References HashValue(), and String().

Referenced by HashValue().

HashValue() [2/2]

static uint32 BString::HashValue ( const char *  string )

static

Return the hash value of a specified string.

This allows you to use the BString::HashValue() method on any arbitrary string.

Parameters

string

The string that you want to have hashed.

See also

HashValue()

Since

Haiku R1

ICompare() [1/4]

int BString::ICompare

(

const BString &

string

)

const

Lexicographically compare this BString to another string case-insensitively.

Parameters

string

The string to compare against.

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

See also

Compare(const BString&) const

Since

BeOS R5

ICompare() [2/4]

int BString::ICompare	(	const BString &	string,
		int32	length
	)		const

Lexicographically compare length characters of this BString to another string.

Parameters

string	The string to compare against.
length	The number of characters to compare.

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

See also

Compare(const BString&, int32) const

Since

BeOS R5

ICompare() [3/4]

int BString::ICompare

(

const char *

string

)

const

Lexicographically compare this BString to another string case-insensitively.

Parameters

string

The string to compare against.

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

See also

Compare(const BString&) const

Since

BeOS R5

ICompare() [4/4]

int BString::ICompare	(	const char *	string,
		int32	length
	)		const

Lexicographically compare length characters of this BString to another string.

Parameters

string	The string to compare against.
length	The number of characters to compare

Returns

An int representing the strings relationship to each other.

Return values

>0	The BString sorts lexicographically after string.
=0	The BString is equal to string.
<0	The BString sorts lexicographically before string.

See also

Compare(const BString&, int32) const

Since

BeOS R5

IEndsWith() [1/3]

bool BString::IEndsWith

(

const BString &

string

)

const

Returns whether or not the BString ends with string case-insensitively.

Parameters

string

The string to search for.

Returns

true if the BString ended with string case-insensitively, false otherwise.

Since

Haiku R1

IEndsWith() [2/3]

bool BString::IEndsWith

(

const char *

string

)

const

Returns whether or not the BString ends with string case-insensitively.

Parameters

string

The string to search for.

Returns

true if the BString ended with string case-insensitively, false otherwise.

Since

Haiku R1

IEndsWith() [3/3]

bool BString::IEndsWith	(	const char *	string,
		int32	length
	)		const

Returns whether or not the BString ends with length characters of string case-insensitively.

Parameters

string	The string to search for.
length	The number of characters (bytes) of string to search for.

Returns

true if the BString ended with length characters of string case-insensitively, false otherwise.

Since

Haiku R1

IFindFirst() [1/4]

int32 BString::IFindFirst

(

const BString &

string

)

const

Find the first occurrence of the given string case-insensitively.

Parameters

string

The string to search for.

Returns

The offset (zero-based) into the data where the given BString was found or B_ERROR if we could not find string.

See also

IFindFirst(const BString&) const

Since

BeOS R5

IFindFirst() [2/4]

int32 BString::IFindFirst	(	const BString &	string,
		int32	fromOffset
	)		const

Find the first occurrence of the given BString case-insensitively, starting from the given offset.

Parameters

string	The string to search for.
fromOffset	The offset in bytes to start the search.

Returns

An integer which is the offset (zero-based) into the data where the given BString was found or B_ERROR if we could not find the string.

See also

IFindFirst(const BString&, int32) const

StartsWith(const char*, int32) const

Since

BeOS R5

IFindFirst() [3/4]

int32 BString::IFindFirst

(

const char *

string

)

const

Find the first occurrence of the given string case-insensitively.

Parameters

string

The string to search for.

Returns

The offset (zero-based) into the data where the given string was found, B_BAD_VALUE if the string pointer is invalid, or B_ERROR if we could not find string.

See also

IFindFirst(const char*) const

StartsWith(const char*) const

StartsWith(const char*, int32) const

Since

BeOS R5

IFindFirst() [4/4]

int32 BString::IFindFirst	(	const char *	string,
		int32	fromOffset
	)		const

Find the first occurrence of the given string case-insensitively, starting from the given offset.

Parameters

string	The string to search for.
fromOffset	The offset in bytes to start the search.

Returns

The offset (zero-based) into the data where the given string was found, B_BAD_VALUE if the string pointer is invalid, or B_ERROR if we could not find the string.

See also

IFindFirst(const char*, int32) const

Since

BeOS R5

IFindLast() [1/4]

int32 BString::IFindLast

(

const BString &

string

)

const

Find the last occurrence of the given BString case-insensitively.

Parameters

string

The string to search for.

Returns

The offset (zero-based) into the data where the given BString was found, or B_ERROR if we could not find the string.

See also

IFindLast(const BString&) const

EndsWith(const BString&) const

Since

BeOS R5

IFindLast() [2/4]

int32 BString::IFindLast	(	const BString &	string,
		int32	beforeOffset
	)		const

Find the last occurrence of the given BString case-insensitively, starting from the given offset going backwards.

Parameters

string	The BString to search for.
beforeOffset	The offset in bytes to start the search.

Returns

The offset (zero-based) into the data where the given BString was found, or B_ERROR if we could not find the string.

See also

IFindLast(const BString&, int32) const

Since

BeOS R5

IFindLast() [3/4]

int32 BString::IFindLast

(

const char *

string

)

const

Find the last occurrence of the given string case-insensitively.

Parameters

string

The string to search for.

Returns

The offset in bytes (zero-based) into the data where the given string was found, B_BAD_VALUE if the string pointer is invalid, or B_ERROR if we could not find the string.

See also

IFindLast(const char*) const

EndsWith(const char*) const

EndsWith(const char*, int32) const

Since

BeOS R5

IFindLast() [4/4]

int32 BString::IFindLast	(	const char *	string,
		int32	beforeOffset
	)		const

Find the last occurrence of the given string case-insensitively, starting from the given offset going backwards.

Parameters

string	The string to search for.
beforeOffset	The offset in bytes to start the search.

Returns

The offset (zero-based) into the data where the given string was found, B_BAD_VALUE if the string pointer is invalid, or B_ERROR if we could not find the string.

See also

IFindLast(const char*, int32) const

Since

BeOS R5

Insert() [1/7]

BString & BString::Insert	(	char	c,
		int32	count,
		int32	pos
	)

Inserts the given character repeatedly at the given position into the BString data.

Parameters

c	The character to insert.
count	The number of times to insert the character.
pos	The offset in bytes into the data of the BString where to insert the string.

Returns

This method always returns *this.

Since

BeOS R5

Insert() [2/7]

BString & BString::Insert	(	const BString &	string,
		int32	fromOffset,
		int32	length,
		int32	position
	)

Inserts the given string at the given position into the BString data.

Parameters

string	The string to insert.
fromOffset	The offset in bytes of the string to be inserted.
length	The amount of bytes to insert.
position	The offset in bytes into the data of the BString where to insert the string.

Returns

This method always returns *this.

See also

Insert(const BString&, int32)

Insert(const BString&, int32, int32)

Since

BeOS R5

Insert() [3/7]

BString & BString::Insert	(	const BString &	string,
		int32	length,
		int32	position
	)

Inserts the given BString at the given position into the BString data.

Parameters

string	The string to insert.
length	The number of bytes to insert.
position	The offset in bytes into the data of the BString where to insert the string.

Returns

This method always returns *this.

See also

Insert(const BString&, int32)

Insert(const BString&, int32, int32, int32)

Since

BeOS R5

Insert() [4/7]

BString & BString::Insert	(	const BString &	string,
		int32	position
	)

Inserts the given BString at the given position into the BString data.

Parameters

string	The string to insert.
position	The offset in bytes into the data of the BString where to insert the string.

Returns

This method always returns *this.

See also

Insert(const BString&, int32, int32)

Insert(const BString&, int32, int32, int32)

Since

BeOS R5

Insert() [5/7]

BString & BString::Insert	(	const char *	string,
		int32	fromOffset,
		int32	length,
		int32	position
	)

Inserts the given string at the given position into the BString data.

Parameters

string	The string to insert.
fromOffset	The offset in bytes in the string to be inserted.
length	The number of bytes to insert.
position	The offset in bytes into the data of the BString where to insert the string.

Returns

This method always returns *this.

See also

Insert(const char*, int32)

Insert(const char*, int32, int32)

Since

BeOS R5

Insert() [6/7]

BString & BString::Insert	(	const char *	string,
		int32	length,
		int32	position
	)

Inserts the given string at the given position into the BString data.

Parameters

string	The string to insert.
length	The number of bytes to insert.
position	The offset in bytes into the data of the BString where to insert the string.

Returns

This method always returns *this.

See also

Insert(const char*, int32)

Insert(const char*, int32, int32, int32)

Since

BeOS R5

Insert() [7/7]

BString & BString::Insert	(	const char *	string,
		int32	position
	)

Inserts the given string at the given position into the BString data.

Parameters

string	The string to insert.
position	The offset in bytes where to insert the string into the BString's data.

Returns

This method always returns *this.

See also

Insert(const char*, int32, int32)

Insert(const char*, int32, int32, int32)

Since

BeOS R5

InsertChars() [1/6]

BString & BString::InsertChars	(	const BString &	string,
		int32	charCount,
		int32	charPosition
	)

UTF-8 aware version of Insert(const BString&, int32, int32).

Parameters

string	The string to insert.
charCount	The number of UTF-8 characters to insert.
charPosition	The offset in UTF-8 characters where to insert the string into the data of the BString.

Returns

This method always returns *this.

See also

Insert(const BString&, int32, int32)

Since

Haiku R1

InsertChars() [2/6]

BString & BString::InsertChars	(	const BString &	string,
		int32	charPosition
	)

UTF-8 aware version of Insert(const BString&, int32).

Parameters

string	The string to insert.
charPosition	The offset in UTF-8 characters where to insert the string into the data of the BString.

Returns

This method always returns *this.

See also

Insert(const BString&, int32)

Since

Haiku R1

InsertChars() [3/6]

BString & BString::InsertChars	(	const BString &	string,
		int32	fromCharOffset,
		int32	charCount,
		int32	charPosition
	)

UTF-8 aware version of Insert(const BString&, int32, int32, int32).

Parameters

string	The string to insert.
fromCharOffset	The offset in UTF-8 characters of the string to be inserted.
charCount	The number of UTF-8 characters to insert.
charPosition	The offset in UTF-8 characters where to insert the string into the data of the BString.

Returns

This method always returns *this.

See also

Insert(const BString&, int32, int32, int32)

Since

Haiku R1

InsertChars() [4/6]

BString & BString::InsertChars	(	const char *	string,
		int32	charCount,
		int32	charPosition
	)

UTF-8 aware version of Insert(const char*, int32, int32).

Parameters

string	The string to insert.
charCount	The number of UTF-8 characters to insert.
charPosition	The offset in UTF-8 characters where to insert the string into the data of the BString.

Returns

This method always returns *this.

See also

Insert(const char*, int32, int32)

Since

Haiku R1

InsertChars() [5/6]

BString & BString::InsertChars	(	const char *	string,
		int32	charPosition
	)

UTF-8 aware version of Insert(const char*, int32).

Parameters

string	The string to insert.
charPosition	The offset in UTF-8 characters where to insert the string into the data of the BString.

Returns

This method always returns *this.

See also

Insert(const char*, int32)

Since

Haiku R1

InsertChars() [6/6]

BString & BString::InsertChars	(	const char *	string,
		int32	fromCharOffset,
		int32	charCount,
		int32	charPosition
	)

UTF-8 aware version of Insert(const char*, int32, int32, int32).

Parameters

string	The string to insert.
fromCharOffset	The offset in UTF-8 characters of the string to be inserted.
charCount	The number of UTF-8 characters to insert.
charPosition	The offset in UTF-8 characters where to insert the string into the data of the BString.

Returns

This method always returns *this.

See also

Insert(const char*, int32, int32, int32)

Since

Haiku R1

IReplace() [1/2]

BString & BString::IReplace	(	char	replaceThis,
		char	withThis,
		int32	maxReplaceCount,
		int32	fromOffset = 0
	)

Replace a number of occurrences of a character with another character case-insensitively.

Parameters

replaceThis	The char to replace.
withThis	The char to put in its place
maxReplaceCount	The maximum number of occurrences that should be replaced.
fromOffset	The offset where to start looking for the string

See also

Replace(char, char, int32, int32)

Since

BeOS R5

IReplace() [2/2]

BString & BString::IReplace	(	const char *	replaceThis,
		const char *	withThis,
		int32	maxReplaceCount,
		int32	fromOffset = 0
	)

Replace a number of occurrences of a string with another string case-insensitively.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place
maxReplaceCount	The maximum number of occurrences that should be replaced.
fromOffset	The offset where to start looking for the string

See also

Replace(const char*, const char*, int32, int32)

Since

BeOS R5

IReplaceAll() [1/2]

BString & BString::IReplaceAll	(	char	replaceThis,
		char	withThis,
		int32	fromOffset = 0
	)

Replace all occurrences of a character with another character case-insensitively.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place
fromOffset	The offset where to start looking for the string

See also

ReplaceAll(char, char, int32)

Since

BeOS R5

IReplaceAll() [2/2]

BString & BString::IReplaceAll	(	const char *	replaceThis,
		const char *	withThis,
		int32	fromOffset = 0
	)

Replace all occurrences of a string with another string case-insensitively.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place.
fromOffset	The offset where to start looking for the string.

See also

ReplaceAll(const char*, const char*, int32)

Since

BeOS R5

IReplaceFirst() [1/2]

BString & BString::IReplaceFirst	(	char	replaceThis,
		char	withThis
	)

Replace the first occurrence of a character with another character case-insensitively.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place

See also

ReplaceFirst(char, char)

Since

BeOS R5

IReplaceFirst() [2/2]

BString & BString::IReplaceFirst	(	const char *	replaceThis,
		const char *	withThis
	)

Replace the first occurrence of a string with another string case-insensitively.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place.

See also

ReplaceFirst(const char*, const char*)

Since

BeOS R5

IReplaceLast() [1/2]

BString & BString::IReplaceLast	(	char	replaceThis,
		char	withThis
	)

Replace the last occurrence of a character with another character case-insensitively.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place

See also

ReplaceLast(char, char)

Since

BeOS R5

IReplaceLast() [2/2]

BString & BString::IReplaceLast	(	const char *	replaceThis,
		const char *	withThis
	)

Replace the last occurrence of a string with another string. Case-insensitive.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place.

See also

ReplaceLast(const char*, const char*)

Since

BeOS R5

IsEmpty()

bool BString::IsEmpty ( ) const

inline

Check whether the string is empty.

Returns

Returns true if the string is empty.

Since

Haiku R1

References Length().

IStartsWith() [1/3]

bool BString::IStartsWith

(

const BString &

string

)

const

Returns whether or not the BString starts with string case-insensitively.

Parameters

string

The string to search for.

Returns

true if the BString started with string case-insensitively, false otherwise.

Since

Haiku R1

IStartsWith() [2/3]

bool BString::IStartsWith

(

const char *

string

)

const

Returns whether or not the BString starts with string case-insensitively.

Parameters

string

The string to search for.

Returns

true if the BString started with string case-insensitively, false otherwise.

Since

Haiku R1

IStartsWith() [3/3]

bool BString::IStartsWith	(	const char *	string,
		int32	length
	)		const

Returns whether or not the BString starts with length characters of string case-insensitively.

Parameters

string	The string to search for.
length	The number of characters (bytes) of string to search for.

Returns

true if the BString started with length characters of string case-insensitively, false otherwise.

Since

Haiku R1

Length()

int32 BString::Length ( ) const

inline

Get the length of the string in bytes.

Returns

An integer with the length of the string, measured in bytes.

See also

CountChars()

Since

BeOS R5

Referenced by Append(), ByteAt(), IsEmpty(), and operator+=().

LockBuffer()

char * BString::LockBuffer

(

int32

maxLength

)

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.

Parameters

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.

Returns

A pointer to the buffer to manipulate.

See also

UnlockBuffer()

Since

BeOS R5

MoveCharsInto() [1/2]

BString & BString::MoveCharsInto	(	BString &	into,
		int32	fromCharOffset,
		int32	charCount
	)

UTF-8 aware version of MoveInto(BString&, int32, int32)

Parameters

into	The BString where to move the string into.
fromCharOffset	The offset (zero-based) in UTF-8 characters where to begin the move.
charCount	The number of UTF-8 characters to move.

See also

MoveInto(BString&, int32, int32)

Since

Haiku R1

MoveCharsInto() [2/2]

bool BString::MoveCharsInto	(	char *	into,
		int32 *	intoLength,
		int32	fromCharOffset,
		int32	charCount
	)

UTF-8 aware version of MoveInto(char*, int32*, int32, int32).

Parameters

into	The buffer to move the string into.
intoLength	The offset (zero-based) in bytes where to begin the move.
fromCharOffset	The offset (zero-based) in UTF-8 characters where to begin the move.
charCount	The number of UTF-8 characters to move.

Returns

false if into was NULL, true otherwise.

See also

MoveInto(char*, int32*, int32, int32)

Since

Haiku R1

MoveInto() [1/2]

BString & BString::MoveInto	(	BString &	into,
		int32	from,
		int32	length
	)

Move the BString data (or part of it) into another BString.

Parameters

into	The BString to move the string into.
from	The offset (zero-based) in bytes where to begin the move.
length	The number of bytes to move.

Returns

This method always returns into.

Since

BeOS R5

MoveInto() [2/2]

void BString::MoveInto	(	char *	into,
		int32	from,
		int32	length
	)

Move the BString data (or part of it) into the given buffer.

Parameters

into	The buffer to move the string into.
from	The offset (zero-based) in bytes where to begin the move.
length	The number of bytes to move.

Since

BeOS R5

operator const char *()

BString::operator const char * ( ) const

inline

Return an empty string.

Returns

An empty string.

Since

Haiku R1

operator!=() [1/2]

bool BString::operator!= ( const BString &  string ) const

inline

Lexicographically compare if this BString is not equal to the given string.

Parameters

string

The string to compare against.

Since

BeOS R5

References String().

operator!=() [2/2]

bool BString::operator!= ( const char *  string ) const

inline

Lexicographically compare if this string is not equal to a given string.

Parameters

string

The string to compare against.

Since

BeOS R5

References operator==().

operator+=() [1/3]

BString & BString::operator+=

(

char

c

)

Append the given character to the end of the BString.

Parameters

c	The character to append.

Returns

This method always returns *this.

See also

Append(char, int32)

operator+=() [2/3]

BString & BString::operator+= ( const BString &  string )

inline

Append the given string to the end of the BString.

Parameters

string

The string to append.

Returns

This method always returns *this.

See also

Append(const BString&, int32)

Since

BeOS R5

References Length(), and String().

Referenced by Append().

operator+=() [3/3]

BString & BString::operator+=

(

const char *

str

)

Append the given string to the end of the BString.

Parameters

str	A pointer to the NULL-terminated string to append.

Returns

This method always returns *this.

See also

Append(const char*, int32)

Since

BeOS R5

operator<() [1/2]

bool BString::operator< ( const BString &  string ) const

inline

Lexicographically compare if this BString is less than the given string.

Parameters

string

The string to compare against.

Since

BeOS R5

References String().

operator<() [2/2]

bool BString::operator<

(

const char *

string

)

const

Lexicographically compare if this BString is less than the given string.

Parameters

string

The string to compare against.

Since

BeOS R5

operator<<() [1/12]

BString & BString::operator<<

(

bool

value

)

Convert the bool value to a string and append it.

In case the value is true, the string "true" is appended to the string. Otherwise, the string "false" is appended.

Parameters

value

The boolean value ("true" of "false") to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<<() [2/12]

BString & BString::operator<<

(

char

c

)

Append c to the BString.

Parameters

c	The character to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<<() [3/12]

BString & BString::operator<<

(

const BString &

string

)

Append string to the BString.

Parameters

string

The string to append.

Returns

This method always returns *this.

operator<<() [4/12]

BString & BString::operator<<

(

const char *

string

)

Append string to the BString.

Parameters

string

The string to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<<() [5/12]

BString & BString::operator<<

(

double

value

)

Convert the double value to a string and append it.

Using this operator will append using %.2f formatting.

Parameters

value

The double value to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<<() [6/12]

BString & BString::operator<<

(

float

value

)

Convert the float value to a string and append it.

Using this operator will append using %.2f formatting.

Parameters

value

The float value to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<<() [7/12]

BString & BString::operator<<

(

int

value

)

Convert the int value to a string and append it.

Parameters

value

The int value to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<<() [8/12]

BString & BString::operator<<

(

long long

value

)

Convert the long long value to a string and append it.

Parameters

value

The long long value to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<<() [9/12]

BString & BString::operator<<

(

long

value

)

Convert the long value to a string and append it.

Parameters

value

The long value to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<<() [10/12]

BString & BString::operator<<

(

unsigned int

value

)

Convert the unsigned int value to a string and append it.

Parameters

value

The unsigned int value to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<<() [11/12]

BString & BString::operator<<

(

unsigned long long

value

)

Convert the unsigned long long value to a string and append it.

Parameters

value

The unsigned long long value to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<<() [12/12]

BString & BString::operator<<

(

unsigned long

value

)

Convert the unsigned long value to a string and append it.

Parameters

value

The unsigned long value to append.

Returns

This method always returns *this.

Since

BeOS R5

operator<=() [1/2]

bool BString::operator<= ( const BString &  string ) const

inline

Lexicographically compare if this BString is less than or equal to the given string.

Parameters

string

The string to compare against.

Since

BeOS R5

References String().

operator<=() [2/2]

bool BString::operator<=

(

const char *

string

)

const

Lexicographically compare if this BString is less than or equal to the given string.

Parameters

string

The string to compare against.

Since

BeOS R5

operator=() [1/4]

BString & BString::operator= ( BString &&  string )

noexcept

Move the contents of string to this BString object.

The string will no longer point to the same contents.

Note

This method is only available for modern C++ (C++11 or later).

Returns

This method always returns *this.

Since

Haiku R1

operator=() [2/4]

BString & BString::operator=

(

char

c

)

Re-initialize the BString to a character.

Parameters

c	The char to re-initialize the BString to.

Returns

This method always returns *this.

Since

BeOS R5

operator=() [3/4]

BString & BString::operator=

(

const BString &

string

)

Re-initialize the object to a copy of the data of a BString.

Parameters

string

The string to copy.

Returns

The function always returns *this.

See also

Adopt(BString&)

SetTo(const BString&, int32)

Since

BeOS R5

Referenced by SetTo().

operator=() [4/4]

BString & BString::operator=

(

const char *

str

)

Re-initialize the BString to a copy of the data of a string.

Parameters

str	The string data to re-initialize the BString to.

Returns

This method always returns *this.

See also

SetTo(const char*, int32)

Since

BeOS R5

operator==() [1/2]

bool BString::operator== ( const BString &  string ) const

inline

Lexicographically compare if this BString is equal to the given string.

Parameters

string

The string to compare against.

Since

BeOS R5

References String().

Referenced by operator!=().

operator==() [2/2]

bool BString::operator==

(

const char *

string

)

const

Lexicographically compare if this BString is equal to the given string.

Parameters

string

The string to compare against.

Since

BeOS R5

operator>() [1/2]

bool BString::operator> ( const BString &  string ) const

inline

Lexicographically compare if this BString is greater than the given string.

Parameters

string

The string to compare against.

Since

BeOS R5

References String().

operator>() [2/2]

bool BString::operator>

(

const char *

string

)

const

Lexicographically compare if this string is more than a given string.

Parameters

string

The string to compare against.

Since

BeOS R5

operator>=() [1/2]

bool BString::operator>= ( const BString &  string ) const

inline

Lexicographically compare if this BString is greater than or equal to the given string.

Parameters

string

The string to compare against.

Since

BeOS R5

References String().

operator>=() [2/2]

bool BString::operator>=

(

const char *

string

)

const

Lexicographically compare if this string is more than or equal to a given string.

Parameters

string

The string to compare against.

Since

BeOS R5

operator[]()

char BString::operator[] ( int32  index ) const

inline

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 index parameter is valid.

Parameters

index

The index (zero-based) of the byte to get.

Returns

Returns a reference to the specified byte.

Since

BeOS R5

Prepend() [1/5]

BString & BString::Prepend	(	char	c,
		int32	count
	)

Prepend the given character count times to the beginning of the BString.

Parameters

c	The character to prepend.
count	The number of times this character should be prepended.

Returns

This method always returns *this.

Since

BeOS R5

Prepend() [2/5]

BString & BString::Prepend

(

const BString &

string

)

Prepend the given BString to the beginning of the BString.

Parameters

string

The string to prepend.

Returns

This method always returns *this.

See also

Prepend(const BString&, int32)

Since

BeOS R5

Prepend() [3/5]

BString & BString::Prepend	(	const BString &	string,
		int32	length
	)

Prepend the given BString to the beginning of the BString.

Parameters

string	The string to prepend.
length	The maximum number of bytes to prepend.

Returns

This method always returns *this.

See also

Prepend(const BString&)

Since

BeOS R5

Prepend() [4/5]

BString & BString::Prepend

(

const char *

str

)

Prepend the given string to the beginning of the BString.

Parameters

str	The string to prepend.

Returns

This method always returns *this.

See also

Prepend(const char*, int32)

Since

BeOS R5

Prepend() [5/5]

BString & BString::Prepend	(	const char *	str,
		int32	length
	)

Prepend the given string to the beginning of the BString.

Parameters

str	The string to prepend.
length	The maximum number of bytes to prepend.

Returns

This method always returns *this.

See also

Prepend(const char*)

Since

BeOS R5

PrependChars() [1/2]

BString & BString::PrependChars	(	const BString &	string,
		int32	charCount
	)

UTF-8 aware version of Prepend(const BString&, int32).

Parameters

string	The string to prepend.
charCount	The maximum number of UTF-8 characters to prepend.

Returns

This method always returns *this.

See also

Prepend(const BString&, int32)

Since

Haiku R1

PrependChars() [2/2]

BString & BString::PrependChars	(	const char *	string,
		int32	charCount
	)

UTF-8 aware version of Prepend(const char*, int32).

Parameters

string	The string to prepend.
charCount	The maximum number of UTF-8 characters to prepend.

Returns

This method always returns *this.

See also

Prepend(const char*, int32)

Since

Haiku R1

Remove()

BString & BString::Remove	(	int32	from,
		int32	length
	)

Remove some bytes, starting at the given offset.

Parameters

from	The offset in bytes to start removing.
length	The number of bytes to remove.

Returns

This function always returns *this.

Since

BeOS R5

RemoveAll() [1/2]

BString & BString::RemoveAll

(

const BString &

string

)

Remove all occurrences of the given BString.

Parameters

string

The BString to remove.

Returns

This function always returns *this.

Since

BeOS R5

RemoveAll() [2/2]

BString & BString::RemoveAll

(

const char *

str

)

Remove all occurrences of the given string.

Parameters

str	A pointer to the string to remove.

Returns

This function always returns *this.

Since

BeOS R5

RemoveChars()

BString & BString::RemoveChars	(	int32	fromCharOffset,
		int32	charCount
	)

UTF-8 aware version of Remove(int32, int32).

Parameters

fromCharOffset	The offset in UTF-8 characters to start removing.
charCount	The number of UTF-8 characters to remove.

Returns

This function always returns *this.

See also

Remove(int32, int32)

Since

Haiku R1

RemoveCharsSet()

BString & BString::RemoveCharsSet

(

const char *

setOfCharsToRemove

)

UTF-8 aware version of RemoveSet(const char*).

Parameters

setOfCharsToRemove

The set of characters to remove.

Returns

This function always returns *this.

See also

RemoveSet(const char*)

Since

Haiku R1

RemoveFirst() [1/2]

BString & BString::RemoveFirst

(

const BString &

string

)

Remove the first occurrence of the given BString.

Parameters

string

The BString to remove.

Returns

This function always returns *this.

Since

BeOS R5

RemoveFirst() [2/2]

BString & BString::RemoveFirst

(

const char *

string

)

Remove the first occurrence of the given string.

Parameters

string

A pointer to the string to remove.

Returns

This function always returns *this.

Since

BeOS R5

RemoveLast() [1/2]

BString & BString::RemoveLast

(

const BString &

string

)

Remove the last occurrence of the given BString.

Parameters

string

The BString to remove.

Returns

This function always returns *this.

Since

BeOS R5

RemoveLast() [2/2]

BString & BString::RemoveLast

(

const char *

string

)

Remove the last occurrence of the given string.

Parameters

string

A pointer to the string to remove.

Returns

This function always returns *this.

Since

BeOS R5

RemoveSet()

BString & BString::RemoveSet

(

const char *

setOfCharsToRemove

)

Remove all the characters specified.

Parameters

setOfCharsToRemove

The set of characters to remove.

Returns

This function always returns *this.

Since

BeOS R5

Replace() [1/2]

BString & BString::Replace	(	char	replaceThis,
		char	withThis,
		int32	maxReplaceCount,
		int32	fromOffset = 0
	)

Replace a number of occurrences of a character with another character.

Parameters

replaceThis	The character to replace.
withThis	The character to put in its place
maxReplaceCount	The maximum number of characters that should be replaced.
fromOffset	The offset in bytes to start looking for the character

Returns

This method always returns *this.

See also

IReplace(char, char, int32, int32)

Since

BeOS R5

Replace() [2/2]

BString & BString::Replace	(	const char *	replaceThis,
		const char *	withThis,
		int32	maxReplaceCount,
		int32	fromOffset = 0
	)

Replace a number of occurrences of a string with another string.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place
maxReplaceCount	The maximum number of occurrences that should be replaced.
fromOffset	The offset in bytes to start looking for the string.

Returns

This method always returns *this.

See also

IReplace(const char*, const char*, int32, int32)

Since

BeOS R5

ReplaceAll() [1/2]

BString & BString::ReplaceAll	(	char	replaceThis,
		char	withThis,
		int32	fromOffset = 0
	)

Replace all occurrences of a character with another character.

Parameters

replaceThis	The character to replace.
withThis	The character to put in its place
fromOffset	The offset in bytes to start looking for the character.

Returns

This method always returns *this.

See also

IReplaceAll(char, char, int32)

Since

BeOS R5

ReplaceAll() [2/2]

BString & BString::ReplaceAll	(	const char *	replaceThis,
		const char *	withThis,
		int32	fromOffset = 0
	)

Replace all occurrences of a string with another string.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place
fromOffset	The offset in bytes to start looking for the string.

Returns

This method always returns *this.

See also

IReplaceAll(const char*, const char*, int32)

Since

BeOS R5

ReplaceAllChars()

BString & BString::ReplaceAllChars	(	const char *	replaceThis,
		const char *	withThis,
		int32	fromCharOffset
	)

UTF-8 aware version of ReplaceAll(const char*, const char*, int32).

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place
fromCharOffset	The offset in UTF-8 characters to start looking for the string.

Returns

This method always returns *this.

See also

ReplaceAll(const char*, const char*, int32)

Since

Haiku R1

ReplaceChars()

BString & BString::ReplaceChars	(	const char *	replaceThis,
		const char *	withThis,
		int32	maxReplaceCount,
		int32	fromCharOffset
	)

UTF-8 aware version of ReplaceAll(const char*, const char*, int32, int32).

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place
maxReplaceCount	The maximum number of occurrences that should be replaced.
fromCharOffset	The offset in UTF-8 characters to start looking for the string.

Returns

This method always returns *this.

See also

ReplaceAll(const char*, const char*, int32, int32)

Since

Haiku R1

ReplaceCharsSet()

BString & BString::ReplaceCharsSet	(	const char *	setOfChars,
		const char *	with
	)

UTF-8 aware version of ReplaceSet(const char*, const char*)

Parameters

setOfChars	The set of UTF-8 characters that need to be replaced.
with	The string to replace the occurrences with.

Returns

This method always returns *this.

Since

Haiku R1

ReplaceFirst() [1/2]

BString & BString::ReplaceFirst	(	char	replaceThis,
		char	withThis
	)

Replace the first occurrence of a character with another character.

Parameters

replaceThis	The character to replace.
withThis	The character to put in its place.

Returns

This method always returns *this.

See also

IReplaceFirst(char, char)

Since

BeOS R5

ReplaceFirst() [2/2]

BString & BString::ReplaceFirst	(	const char *	replaceThis,
		const char *	withThis
	)

Replace the first occurrence of a string with another string.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place

Returns

This method always returns *this.

See also

IReplaceFirst(const char*, const char*)

Since

BeOS R5

ReplaceLast() [1/2]

BString & BString::ReplaceLast	(	char	replaceThis,
		char	withThis
	)

Replace the last occurrence of a character with another character.

Parameters

replaceThis	The character to replace.
withThis	The character to put in its place

Returns

This method always returns *this.

See also

IReplaceLast(char, char)

Since

BeOS R5

ReplaceLast() [2/2]

BString & BString::ReplaceLast	(	const char *	replaceThis,
		const char *	withThis
	)

Replace the last occurrence of a string with another string.

Parameters

replaceThis	The string to replace.
withThis	The string to put in its place

Returns

This method always returns *this.

See also

IReplaceLast(const char*, const char*)

Since

BeOS R5

ReplaceSet() [1/2]

BString & BString::ReplaceSet	(	const char *	setOfBytes,
		char	with
	)

Replaces characters that are in a certain set with a chosen character.

Parameters

setOfBytes	The set of characters that need to be replaced.
with	The character to replace the occurrences with.

Returns

This method always returns *this.

Since

BeOS R5

ReplaceSet() [2/2]

BString & BString::ReplaceSet	(	const char *	setOfBytes,
		const char *	with
	)

Replaces characters that are in a certain set with a chosen string.

Parameters

setOfBytes	The set of chars that need to be replaced.
with	The string to replace the occurrences with.

Returns

This method always returns *this.

Since

BeOS R5

ScanWithFormat()

int BString::ScanWithFormat	(	const char *	format,
			...
	)

Parse a formatted string and save elements to variables ala scanf().

Parameters

format	The format string to use.
...	The parameters that you want to store the parsed data into.

Returns

This method returns the number of items that were parsed.

Since

Haiku R1

ScanWithFormatVarArgs()

int BString::ScanWithFormatVarArgs	(	const char *	format,
		va_list	args
	)

Parse a formatted string and save elements to variables ala scanf().

Parameters

format	The format string to use.
args	The parameters that you want to store the parsed data into.

Returns

This method returns the number of items that were parsed.

Since

Haiku R1

SetByteAt()

BString & BString::SetByteAt	(	int32	pos,
		char	to
	)

Set a byte at position pos to character to.

Parameters

pos	The index of the byte to replace.
to	The new value that should replace the previous byte.

Returns

This method always returns *this.

Since

Haiku R1

SetTo() [1/5]

BString & BString::SetTo	(	char	c,
		int32	count
	)

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.

Parameters

c	The character you want to initialize the BString.
count	The length of the string.

Returns

The function always returns *this.

See also

operator=(char c)

Since

BeOS R5

SetTo() [2/5]

BString & BString::SetTo

(

const BString &

from

)

Re-initialize the BString to a copy of the data of a BString.

Parameters

from	The string data to re-initialize the BString to.

Returns

The function always returns *this.

See also

SetTo(const BString&, int32)

Adopt(BString&)

Since

BeOS R5

SetTo() [3/5]

BString & BString::SetTo	(	const BString &	string,
		int32	maxLength
	)

Re-initialize the string to a copy of the given BString object.

Parameters

string	The string data to re-initialize the BString to.
maxLength	Maximum number of characters (bytes) to copy.

Returns

The function always returns *this.

See also

operator=(const BString&)

Adopt(BString&, int32)

Since

BeOS R5

SetTo() [4/5]

BString & BString::SetTo ( const char *  str )

inline

Re-initialize the BString to a copy of the data of a string.

This method calls operator=(const char*).

Parameters

str	The string data to re-initialize the BString to.

Returns

This method always returns *this.

See also

SetTo(const char*, int32)

Since

BeOS R5

References operator=().

SetTo() [5/5]

BString & BString::SetTo	(	const char *	str,
		int32	maxLength
	)

Re-initialize the BString to a copy of the data of a string.

Parameters

str	The string data to re-initialize the BString to.
maxLength	Maximum number of characters (bytes) to copy.

Returns

This method always returns *this.

See also

operator=(const char*)

Since

BeOS R5

SetToChars() [1/2]

BString & BString::SetToChars	(	const BString &	string,
		int32	charCount
	)

UTF-8 aware version of SetTo(BString&, int32)

Parameters

string	The string to copy.
charCount	The number of UTF-8 characters to copy.

See also

SetTo(BString&, int32)

Returns

This method always returns *this.

Since

Haiku R1

SetToChars() [2/2]

BString & BString::SetToChars	(	const char *	string,
		int32	charCount
	)

UTF-8 aware version of SetTo(const char*, int32)

Parameters

string	The string to copy.
charCount	The number of UTF-8 characters to copy.

See also

SetTo(const char*, int32)

Since

Haiku R1

SetToFormat()

BString & BString::SetToFormat	(	const char *	format,
			...
	)

Sets the string to a formatted string ala sprintf().

Parameters

format	The format string to use.
...	The rest of the parameters that are filled into format.

Returns

This method always returns *this.

Since

Haiku R1

SetToFormatVarArgs()

BString & BString::SetToFormatVarArgs	(	const char *	format,
		va_list	args
	)

Sets the string to a formatted string ala sprintf().

Parameters

format	The format string to use.
args	The rest of the parameters that are filled into format.

Returns

This method always returns *this.

Since

Haiku R1

Split()

bool BString::Split	(	const char *	separator,
		bool	noEmptyStrings,
		BStringList &	_list
	)		const

Split the string by the separator chars into _list.

Parameters

separator	The list of separator characters to split on.
noEmptyStrings	If true, do not add empty strings to _list.
_list	The BStringList to add the strings into.

Since

Haiku R1

StartsWith() [1/3]

bool BString::StartsWith

(

const BString &

string

)

const

Returns whether or not the BString starts with string.

Parameters

string

The string to search for.

Returns

true if the BString started with string, false otherwise.

Since

Haiku R1

StartsWith() [2/3]

bool BString::StartsWith

(

const char *

string

)

const

Returns whether or not the BString starts with string.

Parameters

string

The string to search for.

Returns

true if the BString started with string, false otherwise.

Since

Haiku R1

StartsWith() [3/3]

bool BString::StartsWith	(	const char *	string,
		int32	length
	)		const

Returns whether or not the BString starts with length characters of string.

Parameters

string	The string to search for.
length	The number of characters (bytes) of string to search for.

Returns

true if the BString started with length characters of string, false otherwise.

Since

Haiku R1

String()

const char * BString::String ( ) const

inline

Return a pointer to the object string, NUL terminated.

The pointer to the object string is guaranteed to be 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().

Returns

A pointer to the object string.

Since

BeOS R5

Referenced by Append(), HashValue(), operator!=(), operator+=(), operator<(), operator<=(), operator==(), operator>(), and operator>=().

ToLower()

BString & BString::ToLower

(

)

Convert each of the characters in the BString to lowercase.

Returns

This method always returns *this.

Since

BeOS R5

ToUpper()

BString & BString::ToUpper

(

)

Convert each of the characters in the BString to uppercase.

Returns

This method always returns *this.

Since

BeOS R5

Trim()

BString & BString::Trim

(

)

Removes spaces from the beginning and end of the string.

The definition of a space is set by the isspace() function.

Returns

This method always returns *this.

Since

Haiku R1

Truncate()

BString & BString::Truncate	(	int32	newLength,
		bool	lazy = true
	)

Truncate the string to the new length.

Parameters

newLength	The new length of the string in bytes.
lazy	If true, the memory-optimization is postponed until later.

Returns

This method always returns *this.

Since

BeOS R5

TruncateChars()

BString & BString::TruncateChars	(	int32	newCharCount,
		bool	lazy = true
	)

UTF-8 aware version of Truncate(int32, bool).

Parameters

newCharCount	The new length of the string in UTF-8 characters.
lazy	If true, the memory-optimization is postponed until later.

See also

Truncate(int32, bool)

Since

Haiku R1

UnlockBuffer()

BString & BString::UnlockBuffer

(

int32

length = -1

)

Unlocks the buffer after you are done with low-level manipulation.

Parameters

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, strlen() will be used to determine the length.

Returns

This method always returns *this.

Since

BeOS R5