FAQ-0599 How do I use descriptors for my strings?


FAQ-0599 How do I use descriptors for my strings?

» Symbian OS » Developer Knowledgebase » FAQ-0599

Classification:	C++	Category:	Base
Created:	06/20/97	Modified:	07/22/2003
Number:	FAQ-0599
Platform:	Not Applicable

Question:
I'm a programmer used to other C++ environments.
Please could I have a crib sheet to help me use descriptors?

Answer:
Here are some guidelines and examples for translating from C or C++ in other environments to the Symbian OS environment.
· Replace char* data members, variables and function return values with TPtr, TPtrC or HBufC*
· Replace char* parameters to functions with (const TDesC&) or (TDes&)
· Replace char[N] data members and variables with TBuf or TBufC
· Replace const char* with the 'C' versions of the classes
· For allocated memory use HBufC*.
· Use the constructor or Set() to change what a descriptor points to; use the assignment operator to change what its buffer contains.
· Warning: Initialisation and assignment have totally different semantics. This contravenes almost every C++ style guide in existence, but the decision dates back to before most of them existed and now we're stuck with it. The assignment operator does a memory copy.
In the following examples, string represents a read-only character string. buf represents a modifiable buffer for manipulating strings.

Data Members and Initialization

Typical C++ For Null-Terminated Strings	In Psion EPOC32
char buf[BUFSIZE];	TDes buf;
// String referenced by a class: const char* iString; iString = ...;	TPtrC iString; iString.Set( ... );
// String managed by a class char * iBuf = ... ;	HBufC* ipBuf = ... ;
const char* string = "Hello";	TPtrC string( _L( "Hello" ) );
const char* string = charArrayZ;	TPtrC string( charArrayZ );

Parameters and values

foo( const char* aString )	foo( const TDesC& aString )
modify( char * aBuf, int iSize );	modify( TDes& aBuf );
// Returning allocated memory char* buf = foo() delete [] buf;	HBufC* pBuf = foo() delete pBuf;
// Returning ptr to another's mem const char* string = foo();	TPtrC string = foo();

Operations on strings

strlen( string );	string.Length();
memset( buf, '\0', BUFSIZE );	buf.FillZ( buf.MaxLength() );
buf[0] = '\0';	buf.Zero();
strcpy( buf, "Hello" );	buf = _L( "Hello" );
sprintf( buf, "%s\n", string );	buf.Format( _L("%S\n"), &string);
strcpy( buf, string1 ); strcat( buf, string2 );	buf = string1; buf.Append( string2 );
char * iBuf = strdup( string );	HBufC* ipBuf = string.AllocL();

Notes

Descriptors reference chunks of memory of known size. Compared with standard C they replace the common combination of char* plus integer buffer length.

Descriptors combine

The data adress [ char* x; ]

The data length [ strlen( x ) ], and, for modifiable buffers:

The buffer size [int xBufferSize; ] They cope seamlessly with unicode (two-byte) characters.

What the classes actually contain:

TDesC (abstract base class for everything) has a length;

TPtrC adds a memory address to TDesC.

TDes (abstract) is a modifiable TDesC, and therefore adds a maximum length to TDesC

TPtr adds a memory address to TDes

TBufC contains a read-only char array of size N

TBuf contains a read-write char array of max size N, plus its current length

HBufC adds an allocated buffer to TDes. The 'C' is misleading; an HBufC is modifiable; just call Des() on it to get a TPtr. You might think of it as similar to a Pascal string, combining length and allocated memory. Use HBufC::New(), NewL() or NewLC() to allocate an empty buffer, or use the function AllocL() on any descriptor to make an allocated copy of its data.