• 
• 
• 
• 

BString Class Reference
[Support Kit, (libbe.so)]

String class supporting common string operations. More...

List of all members.

Public Member Functions
	BString (const char *string, int32 maxLength)
	Create a BString and initializes it to the given string.
	BString (const BString &string)
	Create a BString and makes it a copy of the supplied one.
	BString (const char *string)
	Create a BString and initializes it to the given string.
	BString ()
	Create an uninitialized BString.
	~BString ()
	Free all resources associated with the object.
Assignment Methods
To assign a string to the object, thus overriding the previous string that was stored, there are different methods to use. Use one of the overloaded Adopt() methods to take over data from another object. Use one of the assignment operators to copy data from another object, or use one of the SetTo() methods for more advanced copying.
BString &	Adopt (BString &from, int32 maxLength)
	Adopt the data of the given BString object.
BString &	Adopt (BString &from)
	Adopt the data of the given BString object.
BString &	operator= (char c)
	Re-initialize the object to a character.
BString &	operator= (const char *string)
	Re-initialize the object to a copy of the data of a C-string.
BString &	operator= (const BString &string)
	Re-initialize the object to a copy of the data of a BString.
BString &	SetTo (char c, int32 count)
	Re-initialize the object to a string composed of a character you specify.
BString &	SetTo (const BString &string, int32 maxLength)
	Re-initialize the string to a copy of the given BString object.
BString &	SetTo (const BString &string)
	Re-initialize the object to a copy of the data of a BString.
BString &	SetTo (const char *string, int32 maxLength)
	Re-initialize the object to a copy of the data of a C-string.
BString &	SetTo (const char *string)
	Re-initialize the object to a copy of the data of a C-string.
Appending Methods
BString &	Append (char c, int32 count)
	Append the given character repeatedly to the object.
BString &	Append (const char *string, int32 length)
	Append a part of the given string to the object.
BString &	Append (const BString &string, int32 length)
	Append a part of the given BString to the object.
BString &	Append (const char *string)
	Append the given string to the object.
BString &	Append (const BString &string)
	Append the given string to the object.
BString &	operator+= (char c)
	Append the given character to the object.
BString &	operator+= (const char *string)
	Append the given string to the object.
BString &	operator+= (const BString &string)
	Append the given string to the object.
Character Access
char	ByteAt (int32 index) const
	Returns the character in the string at the given offset.
char &	operator[] (int32 index)
	Return a reference to the data at the given offset.
char	operator[] (int32 index) const
	Returns the character in the string at the given offset.
Case Manipulation
BString &	Capitalize ()
	Convert the first character to uppercase, rest to lowercase.
BString &	CapitalizeEachWord ()
	Convert the first character of every word to uppercase, rest to lowercase.
BString &	ToLower ()
	Convert the BString to lowercase.
BString &	ToUpper ()
	Convert the BString to uppercase.
Escaping and Deescaping Methods
This class contains some methods to help you with escaping and de-escaping certain characters. Note that this is the C-style of escaping, where you place a character before the character that is to be escaped, and not HTML style escaping, where certain characters are replaced by something else.
BString &	CharacterDeescape (char escapeChar)
	Remove the character to escape with from this string.
BString &	CharacterDeescape (const char *original, char escapeChar)
	Remove the character to escape with from a given string.
BString &	CharacterEscape (const char *setOfCharsToEscape, char escapeWith)
	Escape selected characters of this string.
BString &	CharacterEscape (const char *original, const char *setOfCharsToEscape, char escapeWith)
	Escape selected characters on a given string.
Comparison Methods
There are two different comparison methods. First of all there is the whole range of operators that return a boolean value, secondly there are methods that return an integer value, both case sensitive and case insensitive. There are also global comparison operators and global compare functions. You might need these in case you have a sort routine that takes a generic comparison function, such as BList::SortItems(). See the String.h documentation file to see the specifics, though basically there are the same as implemented in this class.
int	Compare (const char *string, int32 length) const
	Lexographically compare a number of characters of this string to another.
int	Compare (const BString &string, int32 length) const
	Lexographically compare a number of characters of this string to another.
int	Compare (const char *string) const
	Lexographically compare this string to another.
int	Compare (const BString &string) const
	Lexographically compare this string to another.
int	ICompare (const char *string, int32 length) const
	Lexographically compare a number of characters of this string to another.
int	ICompare (const BString &string, int32 length) const
	Lexographically compare a number of characters of this string to another.
int	ICompare (const char *string) const
	Lexographically compare this string to another in a case-insensitive way.
int	ICompare (const BString &string) const
	Lexographically compare this string to another in a case-insensitive way.
bool	operator!= (const char *string) const
	Lexographically compare if this string is not equal to a given string.
bool	operator!= (const BString &string) const
	Lexographically compare if this string is not equal to a given string.
bool	operator< (const char *string) const
	Lexographically compare if this string is less than a given string.
bool	operator< (const BString &string) const
	Lexographically compare if this string is less than a given string.
bool	operator<= (const char *string) const
	Lexographically compare if this string is less than or equal to a given string.
bool	operator<= (const BString &string) const
	Lexographically compare if this string is less than or equal to a given string.
bool	operator== (const char *string) const
	Lexographically compare if this string is equal to a given string.
bool	operator== (const BString &string) const
	Lexographically compare if this string is equal to a given string.
bool	operator> (const char *string) const
	Lexographically compare if this string is more than a given string.
bool	operator> (const BString &string) const
	Lexographically compare if this string is more than a given string.
bool	operator>= (const char *string) const
	Lexographically compare if this string is more than or equal to a given string.
bool	operator>= (const BString &string) const
	Lexographically compare if this string is more than or equal to a given string.
Substring Copying
void	CopyInto (char *into, int32 fromOffset, int32 length) const
	Copy the BString data (or part of it) into the supplied buffer.
BString &	CopyInto (BString &into, int32 fromOffset, int32 length) const
	Copy the object's data (or part of it) into another BString.
Access Methods
int32	CountChars () const
	Returns the length of the object measured in characters.
int32	Length () const
	Get the length of the string in bytes.
const char *	String () const
	Return a pointer to the object string, NULL terminated.
Searching Methods
int32	FindFirst (char c, int32 fromOffset) const
	Find the first occurrence of the given character, starting from the given offset.
int32	FindFirst (char c) const
	Find the first occurrence of the given character.
int32	FindFirst (const char *string, int32 fromOffset) const
	Find the first occurrence of the given string, starting from the given offset.
int32	FindFirst (const BString &string, int32 fromOffset) const
	Find the first occurrence of the given BString, starting from the given offset.
int32	FindFirst (const char *string) const
	Find the first occurrence of the given string.
int32	FindFirst (const BString &string) const
	Find the first occurrence of the given BString.
int32	FindLast (char c, int32 beforeOffset) const
	Find the last occurrence of the given character, starting from the given offset and going backwards.
int32	FindLast (char c) const
	Find the last occurrence of the given character.
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 (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) const
	Find the last occurrence of the given string.
int32	FindLast (const BString &string) const
	Find the last occurrence of the given BString.
int32	IFindFirst (const char *string, int32 fromOffset) const
	Find the first occurrence of the given string case-insensitively, starting from the given offset.
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) const
	Find the first occurrence of the given BString case-insensitively.
int32	IFindFirst (const BString &string) const
	Find the first occurrence of the given BString case-insensitively.
int32	IFindLast (const char *string, int32 beforeOffset) const
	Find the last occurrence of the given string case-insensitively, starting from the given offset, and going backwards.
int32	IFindLast (const BString &string, int32 beforeOffset) const
	Find the last occurrence of the given BString case-insensitively, starting from the given offset, and going backwards.
int32	IFindLast (const char *string) const
	Find the last occurrence of the given string case-insensitively.
int32	IFindLast (const BString &string) const
	Find the last occurrence of the given BString case-insensitively.
Inserting Methods
BString &	Insert (char, int32 count, int32 pos)
	Insert the given character repeatedly at the given position into the object's data.
BString &	Insert (const BString &string, int32 fromOffset, int32 length, int32 pos)
	Insert the given string at the given position into the object's data.
BString &	Insert (const BString &string, int32 length, int32 pos)
	Insert the given BString at the given position into the object's data.
BString &	Insert (const BString &string, int32 pos)
	Insert the given BString at the given position into the object's data.
BString &	Insert (const char *string, int32 fromOffset, int32 length, int32 pos)
	Insert the given string at the given position into the object's data.
BString &	Insert (const char *string, int32 length, int32 pos)
	Inserts the given string at the given position into the object's data.
BString &	Insert (const char *string, int32 pos)
	Insert the given string at the given position into the object's data.
Replacing Methods
BString &	IReplace (const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset=0)
	Replace a number of occurances of a string with another string. Case-insensitive.
BString &	IReplace (char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset=0)
	Replace a number of occurances of a character with another character. Case-insensive.
BString &	IReplaceAll (const char *replaceThis, const char *withThis, int32 fromOffset=0)
	Replace all occurances of a string with another string. Case-insensitive.
BString &	IReplaceAll (char replaceThis, char withThis, int32 fromOffset=0)
	Replace all occurances of a character with another character. Case-insensitive.
BString &	IReplaceFirst (const char *replaceThis, const char *withThis)
	Replace the first occurance of a string with another string. Case-insensitive.
BString &	IReplaceFirst (char replaceThis, char withThis)
	Replace the first occurance of a character with another character. Case insensitive.
BString &	IReplaceLast (const char *replaceThis, const char *withThis)
	Replace the last occurance of a string with another string. Case-insensitive.
BString &	IReplaceLast (char replaceThis, char withThis)
	Replace the last occurance of a character with another character. Case-insensitive.
BString &	Replace (const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset=0)
	Replace a number of occurances of a string with another string.
BString &	Replace (char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset=0)
	Replace a number of occurances of a character with another character.
BString &	ReplaceAll (const char *replaceThis, const char *withThis, int32 fromOffset=0)
	Replace all occurances of a string with another string.
BString &	ReplaceAll (char replaceThis, char withThis, int32 fromOffset=0)
	Replace all occurances of a character with another character.
BString &	ReplaceFirst (const char *replaceThis, const char *withThis)
	Replace the first occurance of a string with another string.
BString &	ReplaceFirst (char replaceThis, char withThis)
	Replace the first occurance of a character with another character.
BString &	ReplaceLast (const char *replaceThis, const char *withThis)
	Replace the last occurance of a string with another string.
BString &	ReplaceLast (char replaceThis, char withThis)
	Replace the last occurance of a character with another character.
BString &	ReplaceSet (const char *setOfChars, const char *with)
	Replaces characters that are in a certain set with a chosen string.
BString &	ReplaceSet (const char *setOfChars, char with)
	Replaces characters that are in a certain set with a chosen character.
Low-Level Manipulation
char *	LockBuffer (int32 maxLength)
	Locks the buffer and return the internal C-string for manipulation.
BString &	UnlockBuffer (int32 length=-1)
	Unlocks the buffer after you are done with lowlevel manipulation.
Removing Methods
void	MoveInto (char *into, int32 from, int32 length)
	Move the BString data (or part of it) into the given buffer.
BString &	MoveInto (BString &into, int32 from, int32 length)
	Move the BString data (or part of it) into another BString.
BString &	Remove (int32 from, int32 length)
	Remove some bytes, starting at the given offset.
BString &	RemoveAll (const char *string)
	Remove all occurrences of the given string.
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 &	RemoveFirst (const BString &string)
	Remove the first occurrence of the given BString.
BString &	RemoveLast (const char *string)
	Remove the last occurrence of the given string.
BString &	RemoveLast (const BString &string)
	Remove the last occurrence of the given BString.
BString &	RemoveSet (const char *setOfCharsToRemove)
	Remove all the characters specified.
BString &	Truncate (int32 newLength, bool lazy=true)
	Truncate the string to the new length.
Simple sprintf Replacement Methods
These methods may be slower than sprintf(), but they are overflow safe.
BString &	operator<< (float value)
	Convert the float f to a string and append it to the object.
BString &	operator<< (int64 value)
	Convert the integer i to a string and append it to the object.
BString &	operator<< (uint64 value)
	Convert the unsigned integer i to a string and append it to the object.
BString &	operator<< (int32 value)
	Convert the integer i to a string and append it to the object.
BString &	operator<< (uint32 value)
	Convert the unsigned integer i to a string and append it to the object.
BString &	operator<< (unsigned int value)
	Convert the unsigned integer i to a string and append it to the object.
BString &	operator<< (int value)
	Convert the integer i to a string and append it to the object.
BString &	operator<< (char c)
	Append the character c to the object.
BString &	operator<< (const BString &string)
	Append the string string to the object.
BString &	operator<< (const char *string)
	Append the string str to the object.
Prepending Methods
BString &	Prepend (char c, int32 count)
	Prepend the given character repeatedly to the object.
BString &	Prepend (const BString &string, int32 length)
	Prepend the given BString to the object.
BString &	Prepend (const char *string, int32 length)
	Prepend the given string to the object.
BString &	Prepend (const BString &string)
	Prepend the given BString to the object.
BString &	Prepend (const char *string)
	Prepend the given string to the object.
Protected Attributes
char *	fPrivateData
	BString's storage for data.

---

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.

Author:

Marc Flerackers <mflerackers@androme.be>

Stefano Ceccherini <burton666@freemail.it>

Oliver Tappe <openbeos@hirschaefer.de>

---

Constructor & Destructor Documentation

BString::BString

(

const char *

str

)

Create a BString and initializes it to the given string.

Parameters:

str

Pointer to a NULL terminated string.

BString::BString

(

const BString &

string

)

Create a BString and makes it a copy of the supplied one.

Parameters:

string

the BString object to be copied.

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

Create a BString and initializes it to the given string.

Parameters:

	str	Pointer to a NULL terminated string.
	maxLength	The amount of characters you want to copy from the original string.

BString::~BString

(

)

Free all resources associated with the object.

The destructor frees the internal buffer associated with the string.

---

Member Function Documentation

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

Adopt the data of the given BString object.

This method adopts the data. Please note that the object that is adopted from is not deleted, only its private data is initialized to a null string. So if the from object was created on the heap, you need to clean it up yourself.

Parameters:

	from	The string object to adopt.
	length	Amount of characters to get from the original BString.

Returns:

The function always returns *this .

See also:

operator=(const BString &string)

SetTo(const BString &string, int32 length)

BString & BString::Adopt

(

BString &

from

)

Adopt the data of the given BString object.

This method adopts the data. Please note that the object that is adopted from is not deleted, only its private data is initialized to a null string. So if the from object was created on the heap, you need to clean it up yourself.

Parameters:

from

The string object to adopt.

Returns:

The function always returns *this .

See also:

operator=(const BString &string)

SetTo(const BString &string, int32 length)

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

Append the given character repeatedly to the object.

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)

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

Append a part of the given string to the object.

Parameters:

	str	A pointer to the string to append.
	length	The maximum bytes to get from the original string.

Returns:

This method always returns *this .

See also:

operator+=(const char *str)

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

Append a part of the given BString to the object.

Parameters:

	string	The BString to append.
	length	The maximum number ofbytes to get from the original object.

Returns:

This method always returns *this .

See also:

operator+=(const BString &string)

BString & BString::Append

(

const char *

str

)

[inline]

Append the given string to the object.

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

See also:

Append(const char *str, int32 length)

BString & BString::Append

(

const BString &

string

)

[inline]

Append the given string to the object.

Parameters:

string

The string to append

Returns:

This method always returns *this .

See also:

Append(const BString &string, int32 length)

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 byte.

Parameters:

index

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

Returns:

Returns a reference to the specified byte. If you are out of bounds, it will return 0.

BString & BString::Capitalize

(

)

Convert the first character to uppercase, rest to lowercase.

Returns:

This method always returns *this .

BString & BString::CapitalizeEachWord

(

)

Convert the first character of every word to uppercase, rest to lowercase.

Converts the first character of every "word" (series of alpabetical characters separated by non alphabetical characters) to uppercase, and the rest to lowercase.

Returns:

This method always returns *this .

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 *setOfCharsToEscape, char escapeWith)

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 *original, const char *setOfCharsToEscape, char escapeWith)

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 escapeChar)

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 paramater, 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 escapeChar)

CharacterDeescape(const char *original, char escapeChar)

int BString::Compare	(	const char *	str,
		int32	n
	)			const

Lexographically compare a number of characters of this string to another.

See also:

Compare(const BString &string, int32 n) const

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

Lexographically compare a number of characters of this string to another.

Parameters:

	string	The string to compare to.
	n	The number of characters to compare

Return values:

	>0	The object sorts lexographically after string.
	=0	The object is equal to string.
	<0	The object sorts lexographically before string.

int BString::Compare

(

const char *

str

)

const

Lexographically compare this string to another.

See also:

Compare(const BString &string) const

int BString::Compare

(

const BString &

string

)

const

Lexographically compare this string to another.

Parameters:

string

The string to compare to.

Return values:

	>0	The object sorts lexographically after string.
	=0	The object is equal to string.
	<0	The object sorts lexographically before string.

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 amount of bytes to copy.

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 where to copy the object.
	fromOffset	The zero-based offset where to begin the copy.
	length	The amount of bytes to copy.

Returns:

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

int32 BString::CountChars

(

)

const

Returns the length of the object measured in characters.

BString is somewhat aware of UTF8 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()

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 has been found.

Return values:

B_ERROR

Could not find c.

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 has been found.

Return values:

B_ERROR

Could not find c.

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

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

Parameters:

	str	The string to search for.
	fromOffset	The offset where to start the search.

Returns:

The offset(zero based) into the data where the given string has been found.

Return values:

	B_BAD_VALUE	The str pointer is invalid.
	B_ERROR	Could not find str.

See also:

IFindFirst(const char *str, int32 fromOffset) const

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

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

Parameters:

	string	The BString to search for.
	fromOffset	The offset where to start the search.

Returns:

An integer which is the offset(zero based) into the data where the given BString has been found.

Return values:

B_ERROR

Could not find string.

See also:

IFindFirst(const BString &string, int32 fromOffset) const

int32 BString::FindFirst

(

const char *

str

)

const

Find the first occurrence of the given string.

Parameters:

str

The string to search for.

Returns:

The offset(zero based) into the data where the given string has been found.

Return values:

	B_BAD_VALUE	The str pointer is invalid.
	B_ERROR	Could not find str.

See also:

IFindFirst(const char *str) const

int32 BString::FindFirst

(

const BString &

string

)

const

Find the first occurrence of the given BString.

Parameters:

string

The BString to search for.

Returns:

The offset(zero based) into the data where the given BString has been found.

Return values:

B_ERROR

Could not find string.

See also:

IFindFirst(const BString &string) const

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

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

Parameters:

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

Returns:

The offset(zero based) into the data where the given character has been found.

Return values:

B_ERROR

Could not find c.

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 character has been found.

Return values:

B_ERROR

Could not find c.

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

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

Parameters:

	str	The string to search for.
	beforeOffset	The offset wh