Direct access to string buffer

The methods described here allow the developer to directly access the string buffer of Str object instances in read / write mode. User code must never manipulate string content directly unless GetBuffer was called first.

Str::GetBuffer

STRCHAR* GetBuffer ()
STRCHAR* GetBuffer (CPOS min_chars)

This method will return the address of a writable character buffer for the string object. If min_chars is specified, the buffer will have the capacity to hold at least that many characters (even if the current length of the string is smaller).

After the call to GetBuffer, no other methods should be called on the object (even simple ones, like IsEmpty and GetLength) before the buffer is released with ReleaseBuffer. Also, the string object is not thread safe during this time interval.

Example:

   STRCHAR* buf = str.GetBuffer(MAX_LINE_CHARS);
   if (fgets(buf, MAX_LINE_CHARS, somefile) == NULL) {
      str.ReleaseBuffer(0); // Read failed, force empty string
      // Handle error and return here...
   }
   str.ReleaseBuffer(); // Length not specified, so it will be automatically determined

Calls to GetBuffer cannot be nested.

Str::ReleaseBuffer

void ReleaseBuffer(CPOS newlen = -1)

This method should be called after your code is done modifying the buffer acquired with GetBuffer.

If you know the length of the string you stored in the buffer, you should pass it in the newlen parameter. In this case, ReleaseBuffer will automatically append a terminating null.

If the string you placed in the buffer is null-terminated, you can leave the default value for newlen and the method will calculate the string length automatically.

Never call ReleaseBuffer if GetBuffer was not called before that. Calls to ReleaseBuffer cannot be nested.

Str::GetBufferSetLength

STRCHAR* GetBufferSetLength (CPOS newlen)

This method is similar to GetBuffer - it will return the address of a writable character buffer for the string object with space for exactly newlen characters. However, the string object size field will also be set to newlen so your program need not (and must not!) call ReleaseBuffer.

After the call to GetBuffer, no other methods should be called on the object (even simple ones, like IsEmpty and GetLength) before your code places a string of exactly newlen characters in the returned buffer. Also, immediately after calling this method the content of the buffer is undefined; Str Library only guarantees that a terminating null will be placed after the space allotted for newlen characters.

Example:

   // In this example, we know there'a a string exactly 4 characters long
   // at the source location; it may or may not be null terminated.
   STRCHAR* source = some_string_of_4_characters();
   // Place this data in a Str object
   STRCHAR* buf = str.GetBufferSetLength(4);
   memcpy (buf, source, 4 * sizeof(STRCHAR));