September 20, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Mastering Symbian OS Arrays

  • January 14, 2008
  • By Alex Gusev
  • Send Email »
  • More Articles »

Foreword

Symbian OS is well known for its complexity and often confusing documentation, one might say. Well, in fact, this is a kind of red herring because, once you know where to look, you find that a lot of things you would implement on other OSes yourself are already done for you here. From the other side, right, the number of the classes in SDK is enormous. Array classes are not an exception from this rule, so this article will guide you thought the various available array classes and their functionality on Symbian OS.

Simple Case: Fixed Arrays

To start with, you still may use good old C-type arrays just as usual. Nevertheless, I reckon you thought at least once or twice that it would be nice to wrap it in some template to have, for example, boundary checks or operations. All right, there are STL, ATL, you name it, you might say. That's true, and Symbian OS provides the STL port nowadays. Nevertheless, it costs you some overhead; this is not always acceptable. Symbian OS offers, in addition to standard C-style arrays, a number of various fixed and dynamic template array classes. Fixed arrays are discussed here. You will look at dynamic arrays later in this article.

Fixed C-style array wrapper

TFixedArray is a wrapper class for regular C-style arrays that, in addition to standard operators, performs an automatic boundary check to guarantee the validity of all the array's methods. The public methods are listed below:

template <class T,Tint>
class TFixedArray
   {
   ...
public:
   inline TFixedArray();
   inline TFixedArray(const T* aList, Tint aLength);
   //
   inline void Copy(const T* aList, Tint aLength);
   inline void Reset();    // zero fill
   inline void DeleteAll();
   //
   inline Tint Count() const;
   inline Tint Length() const;
   // Accessors - debug range checking
   inline T& operator[](Tint aIndex);
   inline const T& operator[] (Tint aIndex) const;
   // Accessors - always range checking
   inline T& At(Tint aIndex);
   inline const T& At(Tint aIndex) const;
   // Provides pointers to the beginning and end of the array
   inline T* Begin();
   inline T* End();
   inline const T* Begin() const;
   inline const T* End() const;
   //
   inline TArray<T> Array() const;
   ...
   };

The TFixedArray class implementation has few points to keep in mind when you use it. First, the Length() method returns the size, in bytes, of a single item in the array; for the number of items in the array, use Count(). DeleteAll() invokes the delete operator for every item in the array, so you can use it only for CBase-derived elements. The last things I want to mention here are At() and operator[]. They both let you access any given item in the array. You should remember that the former checks for indexes in range for both debug and release build; the latter checks only for debug.

Although TFixedArray is still useful, in your real applications you will use dynamic arrays more often than not.

CArray Dynamic Arrays

You start your guided tour in the Symbian dynamic arrays land from the CArray family of classes. You will find many different flavors of them in the SDK documentation. But, no worries; just think about two things to choose the right one to use: the expected array's item size (fixed or variable) and the method of keeping the data in the array, that is, as one linear buffer or segmented, just like some kind of linked list. The buffer type is important because if you don't resize it frequently, you might prefer Flat-arrays. If the size of your array varies often, Seg-type arrays give you much better performance.

So, the naming pattern is quite simple:

CArray[Fix|Var|Ptr|Pak][Flat|Seg]

Ptr-arrays contain the CBase-derived elements, and Pak-arrays, packed ones. You can shuffle these parts to use the list of all available classes, except CArrayPakSeg, which is not implemented. A good thing is that you don't need to worry about freeing the elements in the array; it does it for you automatically. The only exception is Ptr-arrays where you have to call ResetAndDestroy() to release the memory.

R-Arrays

With the evolution of Symbian OS, you have two new classes : RArray and RPointerArray. They are siblings of CArrayFixFlat and CArrayPtrFlat respectively but have better performance. The reasons lie in improved memory management and assertions usage. Thus they are recommended for Flat-arrays.

Using those classes is quite simple. You should call Close() to release RArray data when you no longer need it or Reset() just to free the memory without destroying the array and reuse it later. RPointerArray holds the pointers and therefore may be responsible to release the memory if it owns the data. ReleaseAndDestroy() does all the job.

Another small but important detail with RArray class is that it uses 4-byte alignment for the storage. It may affect appending, insertion, and access methods in the elements of the array that have different alignment and cause exceptions on some hardware that enforces it.

Descriptor Arrays

To keep your mind busy, that's not the end of the story with the arrays. Here are a few additional array classes to work specifically with descriptors:

  • CDesC16ArrayFlat
  • CDesC8ArrayFlat
  • CDesC16ArraySeg
  • CDesC8ArraySeg
  • CPtrC16Array
  • CPtrC8Array

In fact, you have some kind of two-dimensional set of arrays. They inherit from CArrayNNN[Fix|Seg] base classes; CDesC-arrays have Flat and Seg flavors, CPtr-arrays use Flat buffer only. Descriptor arrays have all the functionality of the CArray-family, but in addition provide methods to reflect descriptor-specific aspects.





Page 1 of 2



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel