StringReserve
StringReserve
Reserves the buffer of a specified size for a string in memory.
bool StringReserve(
string& string_var, // string
uint new_capacity // buffer size for storing a string
);Parameters
- string_var
[in][out] String the buffer size should change the size for.
- new_capacity
[in] Buffer size required for a string. If the new_capacity size is less than the string length, the size of the current buffer does not change.
Return Value
In case of successful execution, returns true, otherwise - false. To receive an error code, the GetLastError() function should be called.
Note
Generally, the string size is not equal to the size of the buffer meant for storing the string. When creating a string, the appropriate buffer is usually allocated with a margin. The StringReserve() function allows managing the buffer size and specify the optimal size for future operations.
UnlikeStringInit(), the StringReserve() function does not change the string contents and does not fill it with characters.
Example:
void OnStart()
{
string s;
//--- check the operation speed without using StringReserve
ulong t0=GetMicrosecondCount();
for(int i=0; i< 1024; i++)
s+=" "+(string)i;
ulong msc_no_reserve=GetMicrosecondCount()-t0;
s=NULL;
//--- now, let's do the same using StringReserve
StringReserve(s,1024 * 3);
t0=GetMicrosecondCount();
for(int i=0; i< 1024; i++)
s+=" "+(string)i;
ulong msc_reserve=GetMicrosecondCount()-t0;
//--- check the time
Print("Test with StringReserve passed for "+(string)msc_reserve+" msc");
Print("Test without StringReserve passed for "+(string)msc_no_reserve+" msc");
/* Result
Test with StringReserve passed for 50 msc
Test without StringReserve passed for 121 msc
*/
}See also
StringBufferLen, StringSetLength, StringInit, StringSetCharacter