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 destroys the internal buffer of string class, and makes the memory allocated by the MemoryAllocate function the new internal buffer. The string class has the control privilege to release this attached memory.

Example 11.32. How to Use the Attach Function

// only "abc" would be registered if string length were not set by 2nd argument
SFXAnsiString str;
ACharPtr ptr;

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

// processing with allocated memory

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

// ptr must not be explicitly released

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

The Detach function is to pass the control privilege to release the internal buffer of string class to a programmer.

A programmer must release the memory (pointer) which is returned by the Detach function with the MemoryFree function.

Example 11.33. How to Use the Detach Function

SFXAnsiString str;
ACharPtr ptr;
SInt32 length;

str = "The best application for BREW.";

// processing with str 

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

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

// processing with ptr

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