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(HBufC8*) 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(const RBuf8& ) 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(TInt).
Related APIs
RBuf - Defines a build-independent resizable buffer descriptor.
RBuf::Assign(const RBuf8&)
RBuf::Create(const TDesC8&)
RBuf::CreateL(const TDesC8&)
RBuf::CreateMax(TInt)
RBuf::CreateMaxL(TInt)
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
RBuf::Create(const TDesC8&)
RBuf::Swap(RBuf8&)
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
RBuf::Assign(const RBuf8&)
RBuf::Create(TInt)
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
RBuf::ReAlloc(TInt)
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
RBuf::Delete(TInt , TInt)
RBuf::Replace(TInt ,TInt ,const TDesC16&)
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 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.