rbufexample: Using resizable buffer descriptors

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:

Download

Click on the following link to download the example: rbufexample.zip.

Click: browse to view the example code.

Description

Creating an RBuf

The example demonstrates creating an RBuf in the following ways:

  1. Using RBuf::Create() or RBuf::CreateL(): These functions create either an empty descriptor, or one with data copied from another descriptor.

  2. Using RBuf::CreateMax() or RBuf::CreateMaxL(): These functions set the buffer's current length to be the same as its maximum length.

  3. By assigning from an HBufC: RBuf::Assign(HBufC8*) transfers ownership of the heap descriptor. It is not possible to access the original heap descriptor once ownership has been transferred.

  4. By assigning some previously allocated memory: RBuf::Assign(const RBuf8& ) transfers ownership of allocated memory. It is then not possible to access the original memory.

  5. 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(TInt).

Related APIs

Swapping two RBufs

The example creates two resizable buffers using RBuf::Create(const TDesC8&). Then it swaps the contents of them using RBuf::Swap(RBuf8&).

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(const TDesC8&). 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(const RBuf8&), ownership of the buffer is transferred. Assign(const RBuf8&) 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(const RBuf8&), 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

Reallocating an RBuf

The example creates a resizable buffer descriptor, then it resizes it using RBuf::ReAlloc(TInt). 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(TInt) 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(TInt ,TInt ,const TDesC16&). The start position and length of the data to be replaced, and the replacement text are passed as parameters. RBuf::Delete(TInt , TInt) is then used to delete the replacement text, by specifying the position and length of the data to be deleted.

Related APIs

Class summary

  • 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.

  • RFs

Build

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.