Programming mobile devices

Part II

Programming Symbian devices with Symbian C++

Strings, Buffers and data collections

Content

• Descriptors

• Dynamic Buffers

Descriptors

• Data buffer

• Buffers size

• Different descriptors for different purposes

• Methods for – writing the buffer– reading the buffer– accessing different properties of the buffer,

like the size

Descriptors

• Buffer– the buffer is inside the descriptor– TBuf...

• Pointer– the buffer is outside and the descriptor contains

a pointer to the buffer – TPtr...

• Heap– HBuf...

Descriptors

• Can be either modifiable or not

• C for constant

• e.g. HBufC

• Either 8 or 16 bit data

• e.g. TBuf8

Non-modifiable API

• Length()• Size()• Ptr() (const TUInt *)• Alloc(), AllocL(), AllocLC()• Left(), Mid(), Right()• Find() 0 based offset or KErrNotFound• <, >, ==, !=, []• =

Modifiable API

• MaxLength()• MaxSize()• SetLength(),SetMax(),Zero()• Append()• Insert()• Delete()• Format()• Copy()

Descriptor classes

• TBuf8 <n> modifiable 8 bit buffer

• TBuf16 <n> modifiable 16 bit buffer

• TBuf8C <n> non-modifiable 8 bit buffer

• TBuf16C <n> non-modifiable 16 bit buffer

• TPtr8 <n> modifiable 8 bit pointer descriptor

• TPtr16 <n> modifiable 16 bit pointer descriptor

Descriptor classes

• TPtrC8 <n> non-modifiable 8 bit pointer descriptor

• TPtrC16 <n> non-modifiable 16 bit pointer descriptor

• HBuf8C <n> non-modifiable 8 bit heap descriptor

• HBuf16C <n> non-modifiable 16 bit heap descriptor

String descriptors

• 16 bit descriptors (unicode)

• For binary data 8 bit descriptors

• For strings we use literals, which behave like descriptors

Literals

• _LIT

• _L

• e.g. _LIT(myString, "Test data...")

• behaves like a non-modifiable descriptor

• _LIT creates an instance of TLitC class

• Can be converted to Descriptors

Literal to Descriptor

• Three ways– implicit– &– ()

• e.g.

_LIT(KMyExampleLiteral, "Test data...")

const TDesc *ptr = &KMyExampleLiteral;

or

KMyExampleLiteral().Length();

Buffer Descriptors

• TBuf and TBufC– the class contains the data buffer

• TBuf <10> Buf would be a 16 bit descriptor with a buffer large enough for 10 16-bit values

• Type 4b

• Length 28 b

• Max length 32 b

• Buffer

HBufC

• H for Heap (allocate on the heap, but does not inherit CBase)

• New() if no leaving needed

• NewL() if leaving necessary

• NewLC() if cleanup stack needed

• Alloc() can be used to create a HBufC from an existing descriptor

Modifying HBufC content

• HBufC::Des() returns a TPtr pointer

• e.g.

_LIT(testString, "PLO");

HBufC *testBuf = HBufC::NewLC(testString().Length());

TPtr testPtr = testBuf->Des();

testPtr.Copy(testString);

HBufC::ReAlloc

• Very handy for incrementing the size of a HBufC

• e.g.

HBufC *firstBuf = HBufC::NewLC(10);

....

firstBuf=firstBuf->ReAlloc(20);

...

HBufC::ReAlloc

• be careful with cleanup stack (if you use cleanup stack, be sure to pop the old pointer and push the new one)

• You can also use ReAllocLC

TBuf

• TBuf <10> buf creates an empty buffer

• _LIT(KString,"Hello");• TBuf <10> buf(KString); creates the buffer with

letters Hello in it

• _LIT(KString,"Hello");• TBuf <12> buf();• buf.Copy(KString); copies Hello into buf

TBuf

• _LIT(KString2," world");

• buf.Append(KString2); appends world into buf

• Be careful not to go past the limit of the buffer (a buffer with 10 elements in the previous example would not be enough)

TBufC

• C for constant

• not modifiable

• hence, only one length value

• you cannot add data

• you can replace old data

• replacing is done with = operator

Descriptors as arguments

• Often base class types used

• TDes and TDesC

• e.g.

void doSomething(const &TDesC)

void doMore(&TDes)

... and return types

• A function can also return a descriptor

• e.g.

const TDesc& myFunc()

{

return ...;

}

Comparison

• Strings can be compared with the Compare method, for example:

_LIT(KStr1, "PLO");

_LIT(KStr2, "plo");

TBuf<10> str1(KStr1);

TInt result = str1.Compare(KStr1);

0 for same, negative if KStr1 is less and

positive if KStr1 is greater than str1

Search

• using function Find

_LIT(KStr1, "example text for searching");

_LIT(KStr2, "for");

TBuf<40> str1(KStr1);

TInt result = str1.Find(KStr1);

returns either -1 (KErrNotFound) or the position

Match

• Like Find, but wildcards, like * are accepted.

• * any string sequence

• ? any one character

_LIT(KStr1, "PLO");

_LIT(KStr2, "?LO");

TBuf<10> str2(KStr2);

TInt result = str2.Match(KStr1);

Substrings

• Left• Right• Mid• e.g.

_LIT(KStr1, "Symbian programming...");

TBuf<10> str1(KStr1);

TPtrC result = str1.Left(7); // Symbian

TPtrC result = str1.Mid(12,4); // gram

Copying to a descriptor

• use Copy()– replaces existing data– updates the size

• CopyCP capital

• CopyLC lower case

• CopyUC upper case

Copying to a descriptor

TUInt8 binaryData[4] = {0xB0,0xB1,0xB2,0xB3};

TBuf8<sizeof(binaryData)> binDescr;

binDescr.Copy(binaryData, sizeof(binaryData));

Appending to a descriptor

_LIT(KStr1, "PLO");

_LIT(KStr2, " course");

TBuf<20> str(KStr1);

TInt result = str.Append(KStr2);