11.4. Internal Buffer in the String Class

The String class encapsulates complex buffer management processes.

11.4.1. Getting String of C Programming Language

The String(SFXAnsiString / SFXWideString) class has the internal buffer for storing its string.

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 is returned
TRACE("%s", str.GetBuffer());

// no error occurs because a pointer to '\0' is returned
TRACE("%s", str.GetCString());

11.4.2. String Containing Several '\0's

The string class(SFXAnsiString / SFXWideString) has the ability to process several nulls('\0's). The following functions have different meanings.

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

Function	Description
`SFXAnsiString::GetLength`	Get the length of string including '\0'. '\0' will be counted.
`SFXAnsiString::GetLengthCString`	Get the length of string up to the first '\0'. '\0' will not be counted.
`SFXAnsiString::IsEmpty`	Check or not whether the length of string including the '\0' character equals 0. For instance, if the first character is '\0', false will be returned since its lenghth is more than one.
`SFXAnsiString::IsEmptyCString`	Check whether or not the length of string up to the first '\0' equals 0. For instance, if the first character is '\0', true will be returned since there is no character up to the first '\0'.

Example 11.31. Handling String Containing Several the null('\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

// nullstring1 is the string including no character
SFXAnsiString nullstring1;

Bool x = nullstring1.IsEmpty();        // x = true
Bool y = nullstring1.IsEmptyCString(); // y = true

// nullstring2 is the string including only one '\0' character
SFXAnsiString nullstring2("\0", 1);

Bool x = nullstring2.IsEmpty();        // x = false
Bool y = nullstring2.IsEmptyCString(); // y = true

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