This example application demonstrates how to use the RBuf class.
RBuf is a resizable buffer descriptor. It is part of the user library. It is used to contain strings and binary data when the maximum size of the data is not known until run time.
This overview contains the following sections:
Click on the following link to download the example: rbufexample.zip.
Click: browse to view the example code.
The example demonstrates creating an RBuf in the following ways:
Using RBuf::Create() or RBuf::CreateL(): These functions create either an empty descriptor, or one with data copied from another descriptor.
Using RBuf::CreateMax() or RBuf::CreateMaxL(): These functions set the buffer's current length to be the same as its maximum length.
By assigning from an HBufC: RBuf::Assign() transfers ownership of the heap descriptor. It is not possible to access the original heap descriptor once ownership has been transferred.
By assigning some previously allocated memory: RBuf::Assign() transfers ownership of allocated memory. It is then not possible to access the original memory.
Using RReadStream: The example writes some text to a file stream (RFileWriteStream). Then it creates the buffer by passing the open stream object to RBuf::CreateL().
Related APIs
RBuf - Defines a build-independent resizable buffer descriptor.
The example creates two resizable buffers using RBuf::Create(). Then it swaps the contents of them using RBuf::Swap().
Note: When you swap data between two RBuf s ensure that the maximum length of the target RBuf is sufficient to hold the data, otherwise a panic (User 11) occurs.
Related APIs
Copying data to an RBuf using the assignment operator
The example creates two resizable buffers and allocates memory using RBuf::Create(). It then copies data to these buffers. It also copies data from the first buffer to the second buffer using the assignment operator.
Notes:
When you use RBuf::Assign(), ownership of the buffer is transferred. Assign() neither checks nor frees any pre-existing owned allocated memory. If this descriptor already owns some allocated memory, RBuf16::Close() should be invoked on it before calling RBuf::Assign(), otherwise a memory leak will occur.
When you use the assignment operator, you must make sure the target descriptor's maximum length is equal to or greater than the length of the source descriptor, otherwise a User 11 panic (descriptor overflow) occurs. Any existing data in the target descriptor is replaced.
Related APIs
The example creates a resizable buffer descriptor, then it resizes it using RBuf::ReAlloc(). The old and new lengths are printed to the console to show how ReAlloc() does not change the length of the descriptor, but only its maximum length. Calling RBuf::ReAlloc() with a value of zero frees the memory and sets the length and maximum length to zero.
Related APIs
Replacing and modifying the data in an RBuf
The example creates a resizable buffer descriptor and replaces a portion of the data in it using RBuf::Replace(). The start position and length of the data to be replaced, and the replacement text are passed as parameters. RBuf::Delete() is then used to delete the replacement text, by specifying the position and length of the data to be deleted.
Related APIs
RBuf - Defines a build-independent resizable buffer descriptor.
HBufC - Defines a build-independent heap descriptor.
RFileWriteStream - Supports the writing of a stream to a file.
RFileReadStream - Supports the reading of a stream from a file.
The Symbian build process describes how to build this example application. The example builds an executable file called rbufexample.exe in the standard location (\epoc32\release\winscw\<build_variant> for the emulator). After launching the executable, depending on the emulator you are using, you may need to navigate away from the application launcher/shell screen to view the console.