11.3. Internal Buffer in the String Class

The String class encapsulates complex buffer management processes.

11.3.1. Getting the String of C Programming Language

The String class has the internal buffer for storing strings.

At the end of this internal buffer, the '\0' character is automatically added.

Two functions are available to get the pointer to this internal buffer.

Table 11.4. Function to Get the Pointer to the Internal Buffer

Function	Description	When the string is the null string
`SFXAnsiString::GetBuffer`	Get the pointer to the internal buffer of string.	Return null.
`SFXAnsiString::GetCString`	Get the const pointer to the internal buffer of string. The buffer cannot be updated through this pointer.	Return a pointer to the '\0' character.

	Note
	When the string is the null string, the `SFXAnsiString::GetBuffer` function returns null, while the `SFXAnsiString::GetCString` function returns a pointer to the '\0' character.

Example 11.30. Difference between SFXAnsiString::GetBuffer and SFXAnsiString::GetCString

SFXAnsiString str;

// error occurs since null pointer is returned
TRACE("%s", str.GetBuffer());

// no error occurs because pointer to null string is returned
TRACE("%s", str.GetCString());

11.3.2. String Containing Several '\0's

The string class has the ability to process several '\0's. The following functions have different meanings.

Table 11.5. Difference of String Processing Functions with the String Containing Several '\0's

Function	Description
`SFXAnsiString::GetLength`	Get the length of string.
`SFXAnsiString::GetLengthCString`	Get the length of string up to the first '\0'.
`SFXAnsiString::IsEmpty`	Check whether the string is null or not.
`SFXAnsiString::IsEmptyCString`	Check whether the first character is '\0' or not

Example 11.31. Handle the string containing several the '\0' characters

// only "abc" is registered if string length is not specified with 2nd argument
SFXAnsiString str("abc\0abc\0\0abc", 12);

SInt32 i = str.GetLength();         // i = 12
SInt32 j = str.GetLengthCString();  // j = 3

11.3.3. Delegating the Internal Buffer

The Attach function makes the specified memory in the argument be the new internal buffer of the string object. After calling the Attach function, the string object will have the control privilege to release this memory.

	Note
	By calling the Attach function, the current internal buffer of the string object will be released.

Example 11.32. How to Use the Attach Function

SFXAnsiString string;
ACharPtr char_ptr;

char_ptr = static_cast<ACharPtr>(MemoryAllocate(10240));     // allocate memory

// processing with char_ptr

// delegate allocated memory onto string instance
string.Attach(char_ptr, 10240);

// char_ptr must not be explicitly released

// when not using Attach function
// string.Set(char_ptr, 10240); // it would be slow since contents of char_ptr are copied

	Note
	The char_ptr memory which has been delegeted to the string object must not be released by calling the MemoryFree function. The string object will have the control privilege to release this memory.

The Detach function returns the current internal buffer of the string object. The receiver will have control privilege to release this memory.

Example 11.33. How to Use the Detach Function

SFXAnsiString string;
ACharPtr char_ptr;
SInt32 length;

string = "The best application for BREW.";

// processing with string 

// delegate control privilege to release internal buffer of string onto programmer
ptr = string.Detach(&length);

// display size of char_ptr
TRACE("%d", length);

// processing with char_ptr

// after char_ptr has been used, be sure to release it with MemoryFree function
MemoryFree(char_ptr);

	Note
	The char_ptr memory which has been returned by the string object must be released by calling the MemoryFree function. The char_ptr memory will have the control privilege to release this memory.

	Note
	The Attach function and the Detach function perform the reverse operartion each other.