Descriptors FAQ

36. How do I use RBuf to read from a file?

2006-11-25T13:26:00.000-08:00

This was posted by Simo as a comment here:

RBuf is also the best choice when reading strings from file. Using RBuf instead of HBufC requires less code. Also, error handling becomes more simpler.

Here is simple example how to read from RReadStream:

in .h: RBuf iSomeSetting;
in .cpp: iSomeSetting.CreateL( stream, KMaxTInt );

the HBufC would be:
in .h: HBufC* iSomeSetting;
in .cpp: iSomeSetting = HBufC::NewL( stream, KMaxTInt );
TPtr tmp( iSomeSetting->Des() );
stream >> tmp;

Error handling is also easier because there are no NULL pointer checks required for RBuf.

References to other descriptors resources

2006-05-21T14:16:00.000-07:00

10,000 hits!

2006-04-26T12:52:00.000-07:00

My hit counter (www.statcounter.com) informs me that this blog clocked over 10,000 hits today. Thanks everyone for visiting over the last few months!

The blogs have been running for about a year now and are overdue for a makeover. I'm hoping to make some changes to the format and include more regular updates and new content in the near future. This will probably include moving them to a new home. But don't worry, the current content won't be removed and there will be plenty of notice of any changes.

Besides this blog, I'd just like to flag another descriptors resource on the web. Take a look at this presentation on the Symbian site, for another view of descriptors.

Best wishes,

Jo
Vancouver, April 26th 2006

35. How do I use TLex?

2005-08-06T13:18:00.000-07:00

Well firstly, what is TLex?

It's a lexical analysis class and the lexer example code, which comes with the Symbian OS SDK, gives one example of how to use it. You can find a brief description of the lexer example in the Symbian Developer Library documentation which comes with each SDK; it is also available on the Symbian website (see the References section for details).

And, in case you're in some doubt as to what the lexer example is doing - I did - [reference 8] is a very useful resource about Reverse Polish Notation.

The rest of this article will summarise the main features of TLex into groups of useful API calls. I'd like to create another, simple, example of how to use the class, but am a bit stuck for ideas of what would be useful. If anyone's got any thoughts on how best to illustrate the main features, please do add a comment to this post and I'll see what I can do.

The main class, TLex, is like the descriptors in that two classes are available, TLex8 and TLex16 and the neutral version, TLex, is a typedef to TLex16 for today's UNICODE builds of Symbian OS. You can find the Symbian API reference documentation for TLex16 in [reference 9].

As the documentation states, TLex "...provides general string-parsing functions suitable for numeric format conversions and syntactical-element parsing...An instance of this class stores a string, maintaining an extraction mark to indicate the current lexical element being analysed and a pointer to the next character to be examined..."

TLex can be constructed with the data for lexical analysis or constructed empty and later assigned the data. Both construction and assignment take either another TLex object, a 16 bit non-modifiable descriptor or a TUint16* pointer to string data.

At the very simplest level, when the string contains just numerical data, the descriptor contents can be converted to an integer by using the Val() function of TLex. For example:

_LIT(KTestString1, "54321");

TLex lex(KTestString1());
TInt value = 0;
User::LeaveIfError(lex.Val(value));
ASSERT(value==54321);

The Val() function is overloaded for different signed integer types: TInt, TInt8, TInt16, TInt32, TInt64 - with or without limit checking. Likewise, there are Val() overloads for the unsigned integer types, passing in a radix type (decimal, hexadecimal, binary or octal). There are also overloads of Val() for TReal.

However, there's a lot more you can do with TLex. The Symbian Developer Library has more information about lexical analysis with TLex - see [reference 10] for more information.

For example, you can move through the string using the Inc() functions, or just inspect each character using Peek(). Calling Get() will both increment the position and return the character - it can be reversed using UnGet().

You can skip whitespace using SkipSpace() or characters using SkipCharacters(). The end of the string is hit when EoS() returns ETrue.

You can put an extraction marker at position in the string, using the Mark() overloads. Marking is also useful if you want to reverse (UnGetToMark() or skip using SkipAndMark() or SkipSpaceAndMark()).

Tokens are used to describe a character string which is deliminated by white space. There are a number of token methods available, such as TokenLength(), MarkedToken() - which extracts a token - and NextToken(). If you don't use tokens, you can use offsets and remainders instead - there are a number of methods for navigating the string in this way.

34. Is there a way to get binary data in a _LIT?

2005-06-27T17:20:00.000-07:00

Check out the answer to FAQ-0814 on Symbian's Developer FAQ & Tech Tips site:

Is there a way to get binary data in a _LIT?

33. Can you give an example of how to use RBuf?

2005-06-26T19:28:00.000-07:00

Yes. I was initially reluctant to do so, because there isn't any published example code out there yet. But I'll take the plunge with this example, which shows how to use RBuf16. I'll leave code to use RBuf8, and to use the non-leaving Create() methods as an exercise for the reader, for now.

void ExampleRBufCodeL()
{
__UHEAP_MARK;
// RBuf::CreateL
RBuf modifiableBuf;
modifiableBuf.CreateL(12);
ASSERT(modifiableBuf.Length()==0);
ASSERT(modifiableBuf.MaxLength()==12);
... // Do stuff. First push modifiableBuf onto the cleanup stack if a leave may occur
modifiableBuf.Close();

// RBuf::CreateMaxL
modifiableBuf.CreateMaxL(12);
ASSERT(modifiableBuf.Length()==12);
ASSERT(modifiableBuf.MaxLength()==12);
... // Do stuff. First push modifiableBuf onto the cleanup stack if a leave may occur
modifiableBuf.Close();

// RBuf::CreateL passing in a descriptor
_LIT(KHelloWorld, "Hello World");
modifiableBuf.CreateL(KHelloWorld());
ASSERT(modifiableBuf.Length()==11);
ASSERT(modifiableBuf.MaxLength()==11);
... // Do stuff. First push modifiableBuf onto the cleanup stack if a leave may occur
modifiableBuf.Close();

// RBuf::CreateL passing in a descriptor and a maximum length
modifiableBuf.CreateL(KHelloWorld(), 15);
ASSERT(modifiableBuf.Length()==11);
ASSERT(modifiableBuf.MaxLength()==15);
... // Do stuff. First push modifiableBuf onto the cleanup stack if a leave may occur
modifiableBuf.Close()

// RBuf::CreateL and ReAllocL & modifiable descriptor base class methods
_LIT(KHello, "Hello");
_LIT(KWorld, " World");
modifiableBuf.CreateL(5);
modifiableBuf.Copy(KHello());
modifiableBuf.CleanupClosePushL(); // Push onto cleanup stack for leave safety
modifiableBuf.ReAllocL(11);
modifiableBuf.Append(KWorld);
CleanupStack::PopAndDestroy(); // Calls modifiableBuf.Close()

// RBuf::Assign
HBufC* hBuf = KHello().AllocL();
modifiableBuf.Assign(hBuf);
ASSERT(modifiableBuf.Length()==5);
... // Do stuff. First push modifiableBuf onto the cleanup stack if a leave may occur
modifiableBuf.Close();

// RBuf::Assign, ReAllocL and use of TDes::Append
TUint16* ptr = static_cast(User::AllocL(5*sizeof(TText)));
modifiableBuf.Assign(ptr,5);
ASSERT(modifiableBuf.Length()==0);
modifiableBuf.Copy(KHello()); // Copying any more would panic
modifiableBuf.CleanupClosePushL(); // Push onto cleanup stack for leave safety
modifiableBuf.ReAllocL(12);
modifiableBuf.Append(KWorld);
CleanupStack::PopAndDestroy(); // Calls modifiableBuf.Close()

__UHEAP_MARKEND;
}

32. How do I use RBuf? What is it?

2005-06-26T18:54:00.000-07:00

From the Symbian OS 8.1a SDK

RBuf16

16-bit resizable buffer descriptor [Jo comments - an equivalent 8-bit version, RBuf8, also exists]

The class provides a buffer that contains, accesses and manipulates TUint16 data. The buffer itself is on the heap, and is managed by the class.

Internally, RBuf16 behaves in one of two ways:

* as a TPtr16 descriptor type, where the buffer just contains data,
* as a pointer to a heap descriptor, an HBufC16* type, where the buffer contains both descriptor information and the data.

Note that the handling of the distinction is hidden from view.

An RBuf16 object can allocate its own buffer. Alternatively, it can take ownership of a pre-existing section of allocated memory, or it can take ownership of a pre-existing heap descriptor. It can also reallocate the buffer to resize it. Regardless of the way in which the buffer has been allocated, the RBuf16 object is responsible for freeing memory when the object itself is closed.

The class is intended for instantiation.
The class is derived from TDes16, which means that data can be both accessed and modified. The base classes provide the functions through which the data is accessed. In addition, an RBuf16 object can be passed to any function that is prototyped to take a TDes16 or a TDesC16 type.

So what does this mean for me?

An RBuf object is rather like an HBufC in that it can be created dynamically by specifying the maximum length required. However, it also benefits from being modifiable, since it derives from TDes16. This means that you don’t have to create a TPtr around the data in order to modify it, which makes it preferable to HBufC when you know you need to dynamically allocate a descriptor, and later modify it.

You don’t need to worry too much about how it’s represented internally – either as a TPtr or HBufC. In fact, all you need to know is how to create and destroy an RBuf, because calling the other descriptor operations on it should be second nature, given that you have access to all the base class methods of TDes16 and TDes16C.

But you must remember that, although RBuf manages the descriptor buffer by freeing it when you call Close(), it doesn’t manage the size of the buffer and reallocate it when you need more memory for any particular operation.

So, for example, if you call Append() on a RBuf object for which there is insufficient memory available, a panic will occur – the RBuf object will not automatically reallocate the buffer. This should be clear from the fact that the base class methods are non-leaving, that is, there is no scope for the reallocation to fail in the event of low memory.

So you still need to manage the memory for descriptor operations that may need to extend the descriptor.

The RBuf class was first introduced in Symbian OS v8.0, but first documented in the 8.1 SDK and is used extensively in software written for devices based on v9.x. The RBuf class is ideal for handling HBufC using a stack-based R class object, and may often be preferable to the contortions required to modify an HBufC.

I've created a short example of how to use the class in 33. Can you give an example of how to use RBuf?

I'd like to acknowledge JP's help and advice with this post.

31. How do I convert between Java strings and descriptors?

2005-06-24T13:42:00.000-07:00

Check out the answer to FAQ-0277 on Symbian's Developer FAQ & Tech Tips site:

"How do I convert between Java strings and Unicode descriptors?"

30. How do I convert an 8-bit descriptor to a Java string?

2005-06-24T11:52:00.000-07:00

Check out the answer to FAQ-0298 on Symbian's Developer FAQ & Tech Tips site:

"How do I convert an 8-bit descriptor to a Java string?"

These days, it's not necessary to use the Symbian cast macros (eg REINTERPRET_CAST) since these are simply defined as the equivalent C++ standard (eg reinterpret_cast). They're a legacy from when GCC didn't support the casts.

29. How can I write the most efficient code when using HBufC?

2005-06-17T14:29:00.000-07:00

(1) Spawn HBufC from existing descriptors using TDesC::AllocL() rather than creating and copying into them

HBufC can be spawned from a existing descriptor using the Alloc() or AllocL() overloads of by TDesC. You can thus replace code like this:

void SomeFunctionL(const TDesC& aDes)
{
HBufC* heapBuffer = HBufC::NewL(aDes.Length());
TPtr ptr(heapBuffer->Des());
ptr.Copy(aDes);
...
}

With the more efficient single line:

void SomeFunctionL(const TDesC& aDes)
{
HBufC* heapBuffer = aDes.AllocL();
...
}

(2) Don't call HBufC::Des() if you need only non-modifiable access to the data

It is clearer and more efficient simply to dereference an HBufC if you need a non modifiable reference to its data. You only need to call Des() when you need to modify it - Des() will return a TPtr. That is:

void Log(const TDesC& aLogBuf); // Forward declaration
void Convert(TDes& aBuf);

void CMyClass::SomeFunction()
{// iHeapBuf is a member of CMyClass
// Get non-modifiable access (TDesC&) to iHeapBuf
Log(*iHeapBuf); // Call a method which takes const TDesC&

// Now get modifiable access (TDes&) to iHeapBuf
Convert(iHeapBuf->Des()); // Call a method which takes TDes&
}

By the way, an interesting side-effect of creating a modifiable descriptor from a non-modifiable heap descriptor is discussed in Tip 9.

28. How do I know what the equivalent C string library functions are for descriptors?

2005-06-17T11:38:00.000-07:00

Just about all the C string library functionality has been implemented by the descriptor base classes, so you can chop them up, rearrange, tokenise and format them just like you have always been able to do with C strings.

Here's a useful table which compares C string functions with their descriptor equivalents. I found the information in section 5 of [reference 7]

27. How do I know which kind of descriptor to use?

2005-06-13T16:15:00.000-07:00

This flowchart may help. It's taken from my book, Symbian OS Explained (page 76), with some modification:

26. How do I convert between 8 bit and 16 bit descriptors?

2005-06-12T18:49:00.000-07:00

TDes defines a set of Copy() methods to copy data from another descriptor of either width, from a pointer to a block of data of a specified length or from a NULL-terminated string. There are also methods for copying with folding,collation or case adjustment.

In each case, the data is copied *from* the source specified in the parameter *into* the modifiable, target, descriptor upon which the method is called. If the length of the 'incoming' data is greater than the target descriptor, a USER 11 panic occurs.

// From the definition of TDes16 in e32des16.h

IMPORT_C void Copy(const TDesC8& aDes); // Copies an 8 bit descriptor
IMPORT_C void Copy(const TDesC16& aDes); // Copies a 16 bit descriptor
IMPORT_C void Copy(const TUint16* aBuf, TInt aLength); // Copies aLength characters from the aBuf pointer
IMPORT_C void Copy(const TUint16* aString); // Copies the NULL terminated aString
IMPORT_C void CopyF(const TDesC16& aDes); // Copies and folds
IMPORT_C void CopyC(const TDesC16& aDes); // Copies and collates
IMPORT_C void CopyLC(const TDesC16& aDes); // Copies and converts the text to lower case
IMPORT_C void CopyUC(const TDesC16& aDes); // Copies and converts the text to upper case
IMPORT_C void CopyCP(const TDesC16& aDes); // Copies and capitalizes the text

Note that, because the Copy() method is overloaded to take either an 8- or 16-bit descriptor, it is possible to copy:

a narrow descriptor onto a narrow descriptor (TDes8 -> TDes8),
a wide descriptor onto a wide descriptor (TDes16 -> TDes16),
a narrow descriptor onto a wide descriptor (TDes8 -> TDes16),
a wide descriptor onto a narrow descriptor (TDes16 -> TDes8).

Copying between descriptors of equivalent character widths is fairly self-explanatory, but copying between descriptors of different character widths is worthy of elaboration:

The Copy() method implemented by TDes16 to copy an 8 bit descriptor parameter will pad each incoming character with a trailing zero.

// Instantiate a wide descriptor
_LIT16(KFred, "Fred");
TBuf16<4> wideFred(KFred); // Bytewise = F\0R\0E\0D\0

// Instantiate a narrow descriptor
_LIT8(KBert, "Bert");
TBuf8<5> narrowBert(KBert); // Bytewise = BERT

// Copy the contents of the narrow descriptor into the wide descriptor
wideFred.Copy(narrowBert); // Bytewise = B\0E\0R\0T\0

The Copy() method implemented by TDes8 to copy an incoming 16-bit descriptor will strip out alternate characters which are assumed to be zeroes. This means that this form of copy will only work if the characters in the wide string do not exceed 255 (decimal).

// Instantiate a wide descriptor
_LIT16(KFred, "Fred");
TBuf16<4> wideFred(KFred); // Bytewise = F\0R\0E\0D\0

// Instantiate a narrow descriptor
_LIT8(KBert, "Bert");
TBuf8<5> narrowBert(KBert); // Bytewise = BERT

// Copy the contents of the wide descriptor into the narrow descriptor
narrowBert.Copy(wideFred); // Bytewise = FRED

Copy() thus forms a simple way to copy and convert between narrow and wide descriptors when the character set is encoded by one 8-bit byte per character and the last byte of each wide character is simply a NULL character padding.

If you need to do a proper conversion between 16-bit Unicode and 8-bit, non-Unicode, character sets (or between Unicode and the UTF-7 and UTF-8 transformation sets), use the Symbian OS conversion library, charconv.lib.

25. What do Length(), MaxLength(), SetLength() and SetMax() do?

2005-06-12T17:59:00.000-07:00

TDesC::Length() returns the number of characters the descriptor contains.

[While we're on the subject of descriptor length, beware! Be careful not to confuse Size() and Length(). They do similar things, but while Length() returns the number of characters the descriptor contains, Size() returns the number of bytes it occupies. For 8-bit descriptors, where each character occupies a byte, this is the same thing. However, on all releases of Symbian OS since v5u, the native character width has been 16 bits, so each character occupies two bytes. Unless you're working with a very old SDK, you'll find that Size() always returns a value which is double that of Length()].

TDes::MaxLength() returns the maximum length allowed for a modifiable descriptor.

TDes::SetLength() can be used to change the descriptor's length to any value between zero and its maximum length. You can also use TDes::Zero() to set the length to zero. And TDes::SetMax() to set the length to the maximum.

[SetMax() has a slightly misleading name. It doesn’t allow you to change the maximum length of the descriptor, which would, in effect, allow you to resize its data area].

23. Why is the _L literal descriptor macro deprecated?

2005-05-28T17:36:00.000-07:00

Why is the original _L macro now deprecated in all but test code? These have the advantage of being used in place rather than declared separately, for example:

User::Panic(_L("TEST SERVER"), KErrNotOVerflow);

You will still see them used in test code since they saves typing and thinking up a name for each literal. It's OK to do so where memory use is not critical, but you should avoid using them in production code. Why?

Well, the text, for example "TEST SERVER" is built into ROM as a basic, NULL-terminated C style string, with no initial length member. Because the layout of the stored literal is not like that of a descriptor, it means that when each instance of the literal is used, a temporary TPtrC must be constructed around the data in ROM. The construction of the temporary, which requires 4 bytes of memory for the length/type data, and instructions to set the pointer, the length and the descriptor type, is an unnecessary overhead when compared to _LIT descriptors which can be used directly because they are stored in ROM to look like descriptors.

The generation of each temporary results in inline constructor code which may bloat binaries where many string literals are used. Furthermore, the use of a run-time temporary is safe as long as it is used only during the lifetime of the function in which it is created

So, in summary, you should use _LIT to _L for your literal descriptors, because _L has an overhead associated with constructing a run-time temporary TPtrC and _LIT does not.

22. What are literal descriptors?

2005-05-28T17:34:00.000-07:00

Literal descriptors are constant descriptors which are compiled into ROM because their contents does not ever change. They are equivalent to static char[] in C.

There are two types of literal descriptor, _LIT which is the most efficient, and preferred, Symbian OS literal and _L, which is now deprecated in all but test code.

In the examples I've included in this blog, I've used _LIT throughout, so you've seen it in action already, for example:

_LIT(KFred, "Fred");

On the wide builds of Symbian OS created today, this is equivalent to the following:
_LIT16(KFred, "Fred");

If an explicitly narrow literal descriptor is required, this can be created using the _LIT8 macro:
_LIT8(KFred, "Fred");

KFred can then be used as a constant descriptor, either directly or to initialise a TPtrC/TPtr or TBufC/TBuf.

The macros are defined in the Symbian OS header file e32def.h and create an object of type TLitC16 or TLitC8 (defined in e32des.h). These classes do not derive from TDesC8 or TDesC16 but have the same binary layout as TBufC8 or TBufC16. This means that the literal object can be used wherever TDesC is used. The literal classes provide operator()() which is very useful to cast the literal object to a TDesC. For example:

_LIT(KFred, "Fred");
HBufC8* theHeapBuffer = KFred().AllocL();

To save you additional code, Symbian OS already defines a literal to represent a blank string, defined as follows:

Build independent: _LIT(KNullDesC,"");
8-bit for non-Unicode strings: _LIT8(KNullDesC8,"");
16-bit for Unicode strings: _LIT16(KNullDesC16,"");

21. Why is there no HBuf class?

2005-05-28T16:53:00.000-07:00

Well, there is and there isn't. Up until Symbian OS v8.0, there was no modifiable heap descriptor class, HBuf, in symmetry with the TBufC and TBuf stack buffers. There were a number of reasons for this:

(1) The expectation might be that, for a modifiable heap descriptor, the maximum length would expand and contract on the heap as the content was modified. An HBuf class which is modifiable but does not dynamically resize could be considered odd and rather pointless. But to add dynamic resizing to HBuf would be difficult because these methods could leave under low memory conditions and would have to be adjusted accordingly. But, as I’ve previously described, all the modifiable descriptor operations are implemented in the base class, TDes, thus affecting all descriptor types.

(2) If dynamic reallocation were added to HBuf, the location of the buffer might change as code is reallocated, affecting all TPtr objects referencing that heap buffer's data, as well as compromising the cleanup stack, if the HBuf pointer is stored there.

(3) Heap buffers were initially intended to allow efficient reading of constant resource strings of variable length. Because they are constant, they save on the additional four bytes required to store a maximum length, which allows them to be as compact as possible. They can still be modified using Des() if necessary, If a separate HBuf class were provided, it would have an extra 4-byte overhead - and may frequently be created unnecessarily, which might add to a significant waste of heap space over time.

However, this is a somewhat spurious argument since making an HBufC::Des() call is non-trivial and the resultant TPtr itself occupies 12 bytes of stack space. If a modifiable heap descriptor is definitely needed, creating a constant buffer and then an additional, TPtr to update wastes memory *and* processor instructions.

To this end, Symbian OS 8.0 and 8.1 introduced class RBuf for resizable descriptors. The Symbian documentation for this class can be found in [reference 6].

I discuss class RBuf in more detail in 32. How do I use RBuf? What is it?.

20. How do I use heap-based buffer descriptors?

2005-05-28T16:05:00.000-07:00

Heap-based descriptors, HBufC<n>, can be used for dynamic allocation of string data whose size is not known at compile time. It should also be used to store string data too large for the stack. In effect, HBufC should be used where malloc’d data would be used in C.

Although the class representing these descriptors is HBufC, these descriptors are always referred to by pointer, HBufC*. The class doesn’t comply with the standard Symbian OS naming conventions, but then, it doesn’t really fit any of the standard Symbian OS types exactly. It is simply prefixed with H to indicate that the data is stored on the heap.

HBufC can be created using one of the static NewL() functions of the class. These may leave if there is insufficient memory available (the non-leaving version will return NULL). The heap buffers must be constructed using one of these methods or by using one of the Alloc() or AllocL() methods of the TDesC class to spawn an HBufC copy of any descriptor.

The ‘C’ suffix in the class name indicates that these descriptors are constant, although, in common with the stack-based non-modifiable buffer descriptors, the class has a set of assignment operators to allow the entire contents of the buffer to be replaced (as long as the new data does not exceed the length of the heap cell originally allocated). In addition, as with TBufC, the heap-based descriptors can be manipulated at runtime by creating a modifiable pointer descriptor, TPtr over the heap buffer, using the Des() method. For example:

_LIT(KFred, "Fred");
// Allocate an empty heap descriptor of max length 4
HBufC* heapBuf = HBufC::NewL(4);
// Copy in the contents of KFred
*heapBuf = KFred; // heapBuf now contains "Fred"
// Or, a more direct alternative:
HBufC* heapBuf = KFred().AllocL();

_LIT(KBert, "Bert");
TPtr ptr(heapBuf->Des()); // Modifiable TPtr over heapBuf data area
ptr = KBert(); // Copies "Bert" into heapBuf
delete heapBuf; // heapBuf deleted - ptr is now invalid

The heap descriptors can be created dynamically to the size required, but are not automatically resized when additional data storage is needed. Instead, you must make sure the buffer has sufficient memory before calling a modification operation. If necessary, you can reallocate the buffer, to grow it to the desired size, using the set of ReAllocL() methods. These may potentially move the buffer from its previous memory location. If there is insufficient memory, they will leave.

_LIT(KFred, "Fred");
// Allocate a heap descriptor of max length 4
HBufC* heapBuf = KFred().AllocLC();

_LIT(KCyril, "Cyril");
TPtr ptr(heapBuf->Des()); // Modifiable TPtr over heapBuf data area
ptr = KCyril(); // This would panic because max length (4) is exceeded

// Instead, we need to do a reallocation
// Leave on cleanup stack in case the realloc fails and a leave occurs
heapBuf = heapBuf->ReAllocL(5);

// Realloc succeeded, but heapBuf pointer may have changed
// We must update the pointer stored on the cleanup stack
CleanupStack::Pop(); // Push it off
// Push it back on again
CleanupStack::PushL(heapBuf);

// Since realloc may have changed the location in memory
// we must also reset ptr
ptr.Set(heapBuf->Des());
ptr = KCyril(); // Copies "Cyril" into heapBuf

CleanupStack::PopAndDestroy(heapBuf); // heapBuf destroyed

Moral of the story
Heap descriptors can be created dynamically but are not automatically resized should they need to be extended.

19. How do I use stack-based buffer descriptors?

2005-05-28T15:05:00.000-07:00

The stack-based buffer descriptor classes are TBufC<n> and TBuf<n>. They are useful for fixed-size or relatively small strings, say up to the length of a 256-character filename (i.e. where n <=256). As I've previously described in 6. Large stack-based descriptors and in Tip 3, because they are stack-based, and stack space is limited on Symbian OS, if you need a larger buffer, you should use the heap (either by using the heap-based buffer descriptors, or having TBuf or TBufC as member variables of C classes). Being stack-based, these descriptors should also only be used when they have a lifetime that coincides with that of their creator.

The TBuf and TBufC descriptors are somewhat equivalent to char[] in C, but benefit from internal overflow checks. As you've probably guessed by now, they may be constant (TBufC) or modifiable (TBuf).

TBufC
The layout of the buffer descriptors is such that the string data forms part of the descriptor object itself, and follows the length word for TBufC and the maximum length word for TBuf. You can find a diagram in [reference 5].

TBufC is a thin template class which uses the TInt value to fix the size of the data area. The non-modifiable buffer class is used to hold constant string or binary data. It derives from TBufCBase (which derives from TDesC, and only exists as an inheritance convenience. It should not be used directly). You can find more about thin templates from Chapter 19 of my book, Symbian OS Explained, more details of which are in the References section.

TBufC defines constructors that allow it to be created from a copy of any other descriptor or from a zero-terminated string. They can also be created empty and filled later. This may at first seem unintuitive for a constant buffer, but in fact, while the data itself is constant, the contents of the buffer may be replaced by calling the assignment operator of the class. The replacing data must not exceed the length specified when the buffer was created, or a panic will occur, in both debug and release modes.

TBufC also has a Des() method which returns a modifiable pointer descriptor for the data represented by the buffer. So, while the contents cannot be altered directly by calling functions such as Format() or LowerCase() upon it, it is possible to change the data indirectly by creating a TPtr around the data in the buffer. When the modification occurs, the length of both the pointer descriptor and the constant buffer descriptor it refers to are changed. But remember, it cannot be extended because the descriptor classes do not provide memory management. So, don't call Append() on the TPtr unless you know there's sufficient space!

_LIT(KFred, "Fred");
_LIT(KBert, "Bert");
TBufC<4> fredBuf(KFred); // Constructed from literal descriptor
TPtr ptr(FredBuf.Des()); // max length = 4
ptr = KBert; // fredBuf now containts "Bert"

_LIT(KCyril, "Cyril");
ptr = KCyril; // Panic! KCyril exceeds max length of ptr (=4)

TBuf
Like TBufC, the corresponding modifiable buffer class, TBuf<n>, is a thin template class, where n defines the maximum length of the descriptor data area. TBuf derives from TBufBase, which itself derives from TDes. TBuf thus inherits the full range of descriptor operations from TDes and TDesC.

Although the buffer is modifiable, as with all descriptors, memory management of the TBuf is your responsibility and it cannot be extended beyond the initial maximum length set on construction. If it needs to expand, you need to make sure that you either make it large enough at compile time (but not too large to waste valuable stack space) or use a descriptor which you can dynamically allocate at runtime. This means using an HBufC heap descriptor, described in 20. How do I use heap-based buffer descriptors?.

18. How do I declare a TPtr or TPtr8 for definition later?

2005-05-28T12:08:00.000-07:00

I want to initialise a TPtr later, but declare it now. How do I do this?

TPtr8 myPtr(NULL, 0);

or, for member data, in the constructor's initialization list:

CMyClass::CMyClass()
: iPtr(NULL, 0)
{}

To assign to it later, use Set() as described in 16. What does TPtrC::Set() do?. For example:

myTPtr.Set(myHBufC->Des());
iPtr.Set(someExistingBuf);

17. What does TPtr::operator=() do?

2005-05-14T14:00:00.000-07:00

The assignment operator, operator=(), defined for modifiable pointers only, copies data into the memory already referenced by the pointer.

If the length of the data to be copied exceeds the length available, the assignment will panic. TPtr also has a Set() method to change the descriptor to point at different data and you should be careful not to confuse them.

To reiterate:
As I described in 16. What does TPtrC::Set() do?, TPtr::Set() resets either a constant or modifiable pointer descriptor to point at a new data area (with corresponding changes to the length and maximum length members).

The assignment operator on TPtr copies data into the existing descriptor area if it is large enough, or panics if it is not. It may modify the descriptor length but will not affect its maximum length.

16. What does TPtrC::Set() do?

2005-05-14T13:59:00.000-07:00

Set() may be called on a constant or modifiable pointer descriptor to change what it points to, that is, to set it to reference different string data.

For example:

_LIT(KFred, "Fred");
_LIT(KBert, "Bert");
TPtrC fred(KFred); // contains 'Fred'
TPtrC bert(KBert); // contains 'Bert'
bert.Set(fred); // bert now contains 'Fred'

15. What is the memory layout of pointer descriptors? How much memory do they occupy besides the data itself?

2005-05-14T13:37:00.000-07:00

Since pointer descriptors all derive from TDesC (either directly for constant pointer descriptors or from TDes, for modifiable descriptors), the first 4 bytes are used to store the current length of the descriptor data.

In a constant pointer descriptor (TPtrC), a 4-byte pointer to the data follows the length word, thus the total size of the descriptor object is two words (8 bytes).

In a modifiable pointer descriptor (TPtr) which derives from TDes, the maximum data length word follows the current length, which is then followed by the data pointer. Thus, the descriptor object is three words in length (12 bytes).

You can find some diagrams which illustrate this in [reference 4].

14. Do pointer descriptors own and manage the memory they point to?

2005-05-14T13:18:00.000-07:00

No. Absolutely not.

The memory that holds the data referenced by a pointer descriptor is not owned by it, but will have been previously allocated. Pointer descriptors are agnostic about where the memory they point to is actually stored (in ROM, on the heap or on the stack).

The string data of a pointer descriptor is separate from the descriptor object itself and pointer descriptors themselves are usually stack-based, although they can be used on the heap, for example as a member variable of a CBase-derived class.

12. What is the layout of modifiable descriptors?

2005-05-09T16:27:00.000-07:00

Modifiable descriptors all derive from the base class TDes, which itself is a subclass of TDesC. TDes has an additional 4-byte member variable, which is used to store the maximum length of data currently allocated to the descriptor.

TDes defines a range of methods for modifying string data. Like the non-modifiable descriptors, all the manipulation is inherited by the derived classes, and works regardless of their type. The subclasses only implement specific methods for construction and copy assignment.

Apart from the allocation methods of the heap buffer descriptors, no descriptor functions allocate any memory. So any modification which extends the data of the descriptor, eg Append(), will check that there is sufficient memory available before proceeding. The contents of the descriptor can shrink and expand at will, as long as the length does not exceed the maximum. If the length of the descriptor contents is less than the maximum length, the end of the block of memory allocated to the descriptor is simply unused.

Descriptor code uses assertion statements to ensure that the maximum length of the descriptor is sufficient, before proceeding. The checks are made in both debug and release builds, and panic if an overflow would occur. This avoids the hard-to-trace memory scribbles and buffer overflows typical of C style strings.

(See also 11. What is the layout of non-modifiable descriptors?)