Manage buffer size

Str::Preallocate

void Preallocate (CPOS size)

This method will allocate a buffer for the specified number of characters without modifying the string content. If the buffer requested is smaller or equal to what is already allocated, the method will just return without doing anything.

The method is useful when the program is continually adding data to a string; if the approximate size of the final string is known beforehand, Preallocate can be called beforehand to ensure that the library will not need to constantly increase the buffer size as the data grows, thus enhancing performance.

Calling Preallocate is just an optimization; no matter how large the string grows, Str will internally make sure that there is enough memory, instead of requiring the programmer to estimate the final string length every single time.

Str::GetBufferLength

CPOS GetBufferLength() const

Returns the size of the currently allocated buffer, in characters. If you wish to estimate the number of bytes taken, multiply this by sizeof(TCHAR) -- 1 in ANSI programs, 2 in Unicode. Also, there is a 12 byte overhead (20 byte for multithread-safe code) per each buffer that is not included in the value GetBufferLength returns.

Str::Compact

void Compact (CPOS only_above = 0)

This method will shrink the buffer size of the string object, thus releasing memory to the underlying OS. The passed value is the number of characters the new buffer should contain. If only_above is 0, or is less than the minimum requirement for the current string content, the buffer will be shrinked as much as possible without touching the string data.

If there are currently multiple Str objects referring to the same buffer, the method will do nothing (because the operation is unsafe). The same will happen if the object is marked at multithread-enabled.

Compact cannot increase the size of a string's buffer; for that, you need to call Preallocate.