rbufexample: +Using resizable buffer descriptors

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.

Description

Creating an RBuf
Swapping two RBufs
Copying data to an RBuf using the assignment operator
Reallocating an RBuf
Replacing and modifying the data in an RBuf

Creating an RBuf

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.
RBuf::Assign()
RBuf::Create()
RBuf::CreateL()
RBuf::CreateMax()
RBuf::CreateMaxL()

Swapping two RBufs

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

RBuf::Create()
RBuf::Swap()

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

RBuf16::Close()
RBuf::Assign()
RBuf::Create()

Reallocating an +RBuf

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

RBuf::ReAlloc()

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::Delete()
RBuf::Replace()