Object oriented operating system6836879Abstract An object oriented operating system handles all objects related to text strings as belonging to one of three classes, in which each class performs a different function and at least one such class is modified to do so in a way that reduces code and cycle overhead. This reduces executable code overhead to minimise the amount of memory required, and allows execution in a minimum number of cycles to minimise power consumption. The operating system is particularly well suited to ROM based mobile computing devices. Claims What is claimed is: Description BACKGROUND
The code fragments illustrate the use of Left( ).
. . .
TBufC<8>str(_L("abcdefg"));
. . . // returns a TPtrC descriptor
str.Left(4); / representing the sting
. . . // "abcd"
The result of this specific example can be visualized in a before (shown in FIG. 9) and after (shown in FIG. 10) fashion. The underlined text in the "after" diagram (FIG. 10) indicates the data represented by the returned descriptor.
The code fragments illustrate the use of Right( ).
. . .
TBufC<8>str(_L("abcdefg"));
. . . // returns a TPtrC descriptor
str.Right(4); // representing the string
. . . // "defg"
The result of this specific example can be visualized in a before (FIG. 11) and after (FIG. 12) fashion. The underlined text in the "after" diagram (FIG. 12) indicates the data represented by the returned descriptor. The code fragments illustrate the use of AllocL( ).
. . .
TBufC<16>str(_L("abcdefg"));
HBufC* ptr;
. . .
ptr = str.AllocL( ); // Returns address of new HBufC descriptor
. . . // holding the string "abcdefg".
ptr.Length( ); // Returns the length 7
. . .
The result of this specific example can be visualised in a before (FIG. 13) and after (FIG. 14) fashion. The following code fragments illustrate the use of Justify( ). . . . TBuf<16> tgt(_L("abc")); . . . tgt.JustifyLL("xyz"),8,ECenter,`@`); The descriptor tgt has a maximum length of 16 and initially holds the string "abc". After the call to Justify( ), the content of tgt changes to "@@xyz@@@" as illustrated at FIG. 15. In this example, the content of the source descriptor is taken to form an 8 character field which replaces the original content of the descriptor tgt. The characters "xyz" are centred within the new field and padded on both sides with the fill character`@`. Setting the alignment to ELeft would change the content of tgt to "xyz@@@@@" while setting the alignment to ERight would change the content of tgt to "@@@@@xyz" In all three cases, the length of the descriptor tgt changes from 3 to 8. . . . TBuf<8> tgtLL("abc")); . . . . . . tgt.JustifyLL("xyz"),9,ECenter,`@`); This call to Justify( ) will panic because the resulting length of data in tgt would exceed the maximum length of tgt. . . . TBuf<16> tgt(_L("abc")); . . . tgt.Justify(_L("rstuvwxyz"),8,ECenter,`@`); In this call to Justify( ), the content of tgt changes to "rstuvwxy" as illustrated at FIG. 16. Only eight of the nine characters in the source descriptor's data area are copied. The following code fragments illustrate the use of AppendJustify( ). . . . TBuf<16> tgt(_L("abc")); tgt.AppendJustify(_L("xyz"),8,ECenter,`@`); The descriptor tgt has a maximum length of 16 and initially holds the string "abc". After the call to AppendJustify( ), the content of tgt changes to "abc@@xyz@@@" as illustrated at FIG. 17. The following code fragments illustrate the use of AppendJustify( ). . . . TBuf<16> tgt(_L("abc")); tgt.AppendJustify(_L("xyz01234456`,789"),3,8,ECenter,`@`); The descriptor tgt has a maximum length of 16 and initially holds the string "abc". After the call to AppendJustify( ), the content of tgt changes to "abc@@xyz@@@" as illustrated at FIG. 18. The following code fragment depited in FIG. 19 illustrates the use of ZeroTerminate( ). . . . TBuf<8> tgt(_L("abcde")); . . . tgt.ZeroTerminate( ) . . . The length of the descriptor tgt is 5 both before and after the call to ZeroTerminate( ). The following code fragments extracted from the E3232def.h header file (see Appendix 1 for the SDK) show how this is implemented by defining the variant independent class names as appropriate. #if defined(_UNICODE) . . . typedef TPtr16 TPtr; #else . . . typedef Ttr8 TPtr; . . . #endif Application code should avoid using `C` style string literals directly. Instead, one should use the _S macro to create a `C` style string of the appropriate width, returning a pointer of the appropriate type. Also, one should use the _L macro (_L for "literal") to create a Descriptor of the appropriate type. See e32.macro._S and e32.macro._L for the definitions of these macros. For example, const TText* str=_S("Hello"); generates a string of single byte characters in an ASCII build but a string of double-byte characters in a UNICODE build. _L("Hello"); generates an 8 bit Descriptor in an ASCII build and a 16 bit Descriptor in a UNICODE build. Always use _L("abcdef"), for example, rather than plain "abcdef" as it will always construct a Descriptor of the correct variant. Note that an 8 bit `C` style string and an 8 bit pointer Descriptor can be explicitly constructed, independently of the build variant, by using the _S8 and _L8 macros respectively. The corresponding 16 bit versions, _S16 and _L16 are also available. See e32.macro._S8, e32.macro._L8, e32.macro._S16 and e32.macro._L16 for their definitions. Length and Size E3232.descriptors.length-and-size A Descriptor characterizes the data it represents by the length of that data. The length of a Descriptor is the number of data items. For the 8 bit variants, the length of the Descriptor is the number of single-bytes of data it represents; for the 16 bit variants, the length of the Descriptor is the number of double-bytes of data it represents. The size of a Descriptor is the number of bytes occupied by the Descriptor's data; this is not necessarily the same as the Descriptor's length. For the 8 bit variants, the size is the same as the length but for the 16 bit variants, the size is twice the length. Those Descriptors which allow their data to be modified are also characterized by their maximum length. For these Descriptors, the length of data represented can vary from zero up to and including this maximum value. The maximum length for any Descriptor is 2.sup.28. Text and Binary Data E3232.descriptors.text-and-binary In `C`, strings are characterized by the need for a zero terminator to flag the end of the string. They suffer from a number of problems. In particular, they cannot include binary data within them (in case that data includes binary zeroes) and operations on them are, in general, inefficient. `C` strings need to be handled in a different way to binary data, as reflected in the memxxx( ) and strxxx( ) function groups in the ANSI `C` library. Descriptors allow strings and binary data to be represented in the same way; this allows the same functions to be used in both cases. For binary data, the 8 bit Descriptors should be used explicitly. The distinction between UNICODE and ASCH has no meaning for binary data. Note that there is no practical use for explicit 16 bit binary data. Memory Allocation E3232.descriptors.alloc The Descriptor classes (except HBufC) behave as built-in types. They allocate no memory and have no destructors. This means that they can be orphaned on the stack in the same way as a built-in type. This is particularly important in situations where code can leave. (See E3232.exception.trap.cleanup.requirements for the implications of orphaning). An HBufC Descriptor object is allocated on the heap and cannot be created on the stack. Exceptions E3232.descriptors.exceptions All parameters to Descriptor member functions are checked to ensure that the operations are correctly specified and that no data is written outside the Descriptor's data area. A particular consequence is that no member function can extend a modifiable Descriptor beyond its maximum allocated length. It is the programmer's responsibility to ensure that all Descriptors are sufficiently large to contain their data, either by making the original allocation large enough or by anticipating the need for a larger Descriptor and dynamically allocating one at run-time. The static approach is simpler to implement but if this were to prove wasteful in a specific case, then the dynamic approach could be more worthwhile. In the event of an exception, it can be safely assumed that no illegal access of memory has taken place and that no data has been moved or damaged. The Descriptor Types E3232.descriptors.types There are three kinds of Descriptor object: pointer Descriptors. The Descriptor object is separate from the data it represents but is constructed for a pre-existing area in memory. They come in two forms: a constant pointer Descriptor, TPtrC a modifiable pointer Descriptor, TPtr buffer Descriptors. The data area is part of the Descriptor object. They come in two forms: a constant buffer Descriptor, TBufC<TInt S> a modifiable buffer Descriptor, TBuf<TInt S> heap Descriptor. The data area is part of the Descriptor object and the whole object occupies a cell allocated from the heap. This comes in only one form: a constant heap Descriptor, HBufC Pointer Descriptor--TPtrC E3232.descriptors.buffer-descriptor.TPtrC TPtrC is a constant Descriptor through which no data can be modified. All of its member functions (except the constructors) are constant. TPtrC is shown schematically at FIG. 1. TPtrC is useful for referencing constant strings or data; for example, accessing text built into ROM resident code, or passing a reference to data in RAM which must not be modified through that reference. TPtr is derived from TDesC, which provides a large number of member functions for operating on its content; for example, locating characters within text or extracting portions of data. Pointer Descriptor--TPtr E3232.descriptors.buffer-descriptor.TPtr TPtr is a modifiable pointer Descriptor through which data can be modified, provided that the data is not extended beyond the maximum length. The maximum length is set by the constructor. TPtr points directly to an area in memory containing the data to be modified. TPtr is shown schematically in FIGS. 2A and 2B. The maximum number of data items that the area can contain is defined by the maximum length. The length of the TPtr indicates how many data items are currently contained within the data. When this value is less than the maximum, a portion of the data area is unused. TPtr is useful for constructing a reference to an area of RAM which contains data intended to be modified through that reference, or even to an area of RAM which contains no data yet but in which data will be constructed using the Descriptor reference and member functions. TPtr is also useful for constructing a reference to a TBufC or an HBufC Descriptor which contain the data to be modified. A TPtr used in this way points to a TBufC or an HBufC Descriptor. The data contained by the TBufC or HBufC Descriptors can be modified through the TPtr. TPtr is derived from TDes which, in turn, is derived from TDesC. Therefore, it inherits all the const member functions defined in TDesC plus the member functions from TDes which can manipulate and change the data; for example, appending a character to the end of existing text. Buffer Descriptor--TBufC<TInt S> E3232.descriptors.buffer-descriptor.TBufC TBufC is a buffer Descriptor containing a length followed by the data area. Data can be set into the Descriptor at construction time or by the assignment operator (operator=) at any other time. Data already held by the Descriptor is constant. TBufC is shown schematically at FIG. 3. The length of a TBufC is defined by an integer template; for example, TBufC<40> defines a TBufC which can contain up to 40 data items. TBufC is derived from TDesC, which provides a large number of member functions for operating on its content; for example, locating characters within text or extracting portions of data. TBufC provides the member function, Des( ), which creates a modifiable pointer Descriptor (a TPtr) to reference the TBufC. This allows the TBufC data to be changed through the TPtr, as indicated schematically at FIG. 4. The maximum length of the TPtr is the value of the integer template parameter. Buffer Descriptor--TBuf<TInt S> E3232.descriptors.buffer-descriptor.TBuf TBuf is a modifiable buffer Descriptor containing data which can be modified, provided that the data is not extended beyond its maximum length. TBuf is shown schematically at FIG. 5. The maximum number of data items that the data area within TBuf can contain, is defined by the maximum length. The length of the Descriptor indicates how many data items are currently contained within the data area. When this value is less than the maximum, a portion of the data area is unused. The maximum length of a TBuf is defined by an integer template; for example, TBuf<40> defines a TBuf which can contain up to 40 data items (and no more!). A TBuf is useful for containing data which needs to be manipulated and changed but whose length will not exceed a known maximum; for example, word processor text. TBuf is derived from TDes which, in turn, is derived from TDesC. Therefore, it inherits all the const member functions defined in TDesC plus the member functions from TDes which can manipulate and change the data; for example, appending a character to the end of existing text. Heap Descriptor--HBufC E3232.descriptors.buffer-descriptor.HBufC HBufC is a Descriptor containing a length followed by data It is allocated on the heap using the New( ), NewL( ) or NewLC( ) static member functions. The length of the Descriptor is passed as a parameter to these static functions. HBufC is shown schematically at FIG. 6. Data can be set into the Descriptor at construction time or by the assignment operator (operator=) at any other time. Data already contained by the Descriptor is constant. HBufC is derived from TDesC, which provides a large number of member functions for operating on its content; for example, locating characters within text or extracting portions of data. HBufC provides the member function, Des( ), which creates a modifiable pointer Descriptor (a TPtr) to reference the HBufC. This allows the HBufC data to be changed through the TPtr. The maximum length of the TPtr is the length of the HBufC data area. FIG. 7 illustrates this schematically. Heap Descriptors can be re-allocated. The ReAlloc( ) or ReAllocL( ) functions allow the heap Descriptor's data area to expand or contract. The length of the data area, however, cannot be made smaller than the length of data currently held. Before contracting the data area, the length of the data held by the Descriptor must be reduced. The length of data which the assignment operator can set into the heap Descriptor is limited by the space allocated to the Descriptor's data area The memory occupied by heap Descriptors must be explicitly freed either by calling User::Free( ) or by using the delete keyword. The Descriptor Classes' Relationships E32.descriptors.classes All of the Descriptor classes TPtrC, TPtr, TBufC, TBuf and HBufC are derived from the abstract base classes TDesC and TDes. The class TBufCBase, although marked as an abstract class, is merely an implementation convenience. FIG. 8 schematically illustrates the relationship between the classes. The behaviour of the concrete Descriptor classes is very similar, and therefore, most of the functionality of Descriptors is provided by the abstract base classes. Because Descriptors are widely used (especially on the stack), the size of Descriptor objects must be kept to a minimum. To help with this, no virtual functions are defined in order to avoid the overhead of a virtual function table pointer in each Descriptor object. As a consequence, the base classes have implicit knowledge of the classes derived from them. E32 supplies two variants of the Descriptor classes, one for handling 8 bit (ASCII) text and binary data and the other for handling 16 bit (UNICODE) text. The 8 bit variants of the concrete classes are: TPtrC8, TPtr8, TBufC8<TInt S>, TBuf8<TInt S> and HBufC8 while the 8 bit variants of the abstract classes are: TDesC8, TDes8. Similarly, the 16 bit variants are named: TPtrC, TPtr16, TBufC16<TInt S>, TBuf16<TInt S>, HBufC16, TDesC16 and TDes16 respectively. This distinction is transparent for Descriptors intended to represent text. By writing programs which construct and use TPtrC, TPtr, TBufC<TInt S>, TBuf<TInt S> and HBufC classes, compatibility is maintained between both UNICODE and ASCII. The appropriate variant is selected at build time depending on whether the _UNICODE macro has been defined or not. If the _UNICODE macro is defined, the 16 bit variant is used, otherwise the 8 bit variant is used as explained in e32descriptors.char-set Descriptors for binary data must explicitly use the 8 bit variants; in other words, code must explicitly construct TPtrC8, TPtr8, TBufC8<TInt S>, TBuf8<TInt S> and HBufC8 classes. Explicit use of the 16 bit variants for binary data is possible but not recommended. In general, 8 bit and 16 bit variants are identical in structure and implementation; the description of the classes themselves uses the build independent names throughout. N.B. Many member functions take arguments which are either of type TUint8* or type TUint16* depending on whether the Descriptor is the 8 bit or 16 bit variant. To simplify explanation, these arguments are written in function prototypes as TUint??*. Using Descriptors for Function Interfaces e32.descriptors.using-function-interfaces Many interfaces which use or manipulate text strings or general binary data use descriptors to specify the interface. In conventional `C` programming, interfaces would be specified using a combination of char*, void* and length values. In E32 descriptors are always used. There are four main cases: Passing a constant string In `C`: StringRead(const char* aString); The length of the string is implied by the zero terminator; therefore, the function does not require the length to be explicitly specified. In E32: StringRead(const TDesC& aString); The descriptor contains both the string and its length. Passing a string which can be changed. In `C`: StringWrite(char* aString, int aMaxLength); The length of the passed string is implied by the zero terminator. aMaxLength indicates the maximum length to which the string may be extended. In E32: StringWrite(TDes& aString); The descriptor contains the string, its length and the maximum length to which the string may be extended. Passing a buffer containing general binary data In `C`: BufferRead(const void* aBuffer, int aLength); Both the address and length of the buffer must be specified. In E32: BufferRead(const TDes8& aBuffer); The descriptor contains both the address and the length of the data. The 8 bit variant is explicitly specified; the buffer is treated as byte data, regardless of the build variant. Passing a buffer containing general binary data which can be changed. In `C`: BufferWrite(void* aBuffer, int& aLength, int aMaxLength); The address of the buffer, the current length of the data and the maximum length of the buffer are specified. The aLength parameter is specified as a reference to allow the function to indicate the length of the data on return. In E32: BufferRead(TDes8& aBuffer); The descriptor contains the address, the length of the data and the maximum length. The 8 bit variant is explicitly specified; the buffer is treated as byte data, regardless of the build variant. Folding and Collating e32.descriptors.folding-collating There are two techniques that may be used to modify the characters in a descriptor prior to performing some operations on text: folding collating Variants of member functions that fold or collate are provided where appropriate. Folding e32.descriptors.folding Folding means the removal of differences between characters that are deemed unimportant for the purposes of inexact or case-insensitive matching. As well as ignoring differences of case, folding ignores any accent on a character. By convention, folding converts lower case characters into upper case and removes any accent. Collating e32.descriptors.collating Collating means the removal of differences between characters that are deemed unimportant for the purposes of ordering characters into their collating sequence. For example, collate two strings if they are to be arranged in properly sorted order, this may be different from a strict alphabetic order. Using Descriptors e32.descriptors.using The following series of examples show how descriptors can be used. Specifically, the examples illustrate: the basic concepts of the pointer descriptors, TPtrC and TPtr. See e32.descriptors.using.pointer-descriptors. the basic concepts of the buffer descriptors, TBufC and TBuf. See e32.descriptors.using.buffer-descriptors. how descriptors can represent general binary data. See e32.descriptors.using.general-binary-data. some of the member functions which do not modify the content of a descriptor. See e32.descriptors.using.non-modifying-functions. some of the member functions which modify the content of a descriptor. See e32.descriptors.using.modifying-functions. how descriptors can be used in interfaces. See e32.descritpors.using.interface-specifiers. the basic concepts of the heap descriptor, HBufC. See e32.descritpors.using.heap-descriptors. Pointer Descriptors e32.descriptors.using.pointer-descriptors The code fragments shown here to illustrate the use of pointer descriptors are extracted from the sample source code in the eudesptr project. Run the code in this project to see pointer descriptors in action. TPtrC The 8 bit variant A TPtrC is useful for referencing constant strings or data; for example, accessing text built into ROM resident code, or passing a reference to data in RAM which must not be modified through that reference. For example, define a constant `C` style ASCII string: const TText8* cstr8=(TText8*)"Hello World!"; A TPtrC8 descriptor can be constructed to represent this pre-defined area containing the string "Hello World!": TPtrC8 ptrC8(cstr8); The descriptor is separate from the data it represents. While the length of the `C` string is 12, its size is 13 to allow for the zero terminator. From the descriptor's viewpoint, both the length and the size of the data is 12. The descriptor uses the length to determine the amount of data represented. The address of the descriptor's data area, as returned by: ptrC8.Ptr( ); is the same as same as the address of the original `C` string, cstr8. The 16 bit variant (UNICODE) Similarly, define a constant `C` style string of wide (or UNICODE) characters: const TText16 cstr16=(TText16)L"Hello World!"; A TPtrC descriptor can be constructed to represent this area containing the string of double-byte characters "Hello World!": TPtrC ptrC(cstr16); Again, the descriptor is separate from the data it represents. The length of the descriptor, as returned by a call to ptrc16.Length( ), is 12 as it represents 12 text characters but the size, as returned by a call to ptrc16.Size( ), is now 24 as each character occupies 2 bytes. Again, the address of the descriptor's data area, as returned by: ptrc16.Ptr( ); is the same as the address of the original `C` string, cstr16. The _S macro and build independent names Use the _S macro to define a constant `C` style string of the appropriate width. The TText variant is defined at build time (as either TText8 or TText16) depending on whether the _UNICODE macro has been defined. For example: const TText* cstr=_S("Hello World!"); The TPtrC descriptor: TPtrC ptrc(cstr); represents the area containing the text "Hello World!"; the TPtrC variant is defined at build time (as either TPtrC8 or TPtr16) depending on whether the _UNICODE macro has been defined. The length of the descriptor, as returned by ptrc.Length( ), is 12 for all build variants but the size of the descriptor, as returned by ptrc.Size( ) is 12 for an ASCII build and 24 for a UNICODE build. See e32.macro._S. The _L macro The _L macro constructs a TPtrC of the correct variant and is frequently used as a source descriptor when constructing a buffer descriptor or a heap descriptor. The macro is also useful for constructing a TPtrC to be passed as a parameter to a function. For example, the Printf( ) member function of the RTest class used in these examples requires a descriptor as its first parameter. Here, the _L macro constructs a TPtrC representing the constant static area generated by the compiler containing the text ".backslash.nThe _L macro constructs a TPtrC". testConsole.Printf(_L(".backslash.n The _L macro constructs a TPtrC")); See e32.macro._L. TPtr A TPtr is a modifiable pointer descriptor through which data can be modified, provided that the data is not extended beyond the maximum length. The maximum length is set by the constructor. For example, define a TText area initialised to contain the string "Have a nice day": ##EQU1## A TPtr descriptor can be constructed to represent the data in this area; further, this data can be changed, contracted and expanded provided that the length of the data does not exceed the maximum. TPtr ptr(&str[0],15,16); The descriptor ptr represents the data in str and is constructed to have a current length of 15 (the length of the text, excluding the zero terminator) and a maximum length of 16 (the actual length of str). Once the descriptor has been constructed, it has no farther use for the zero terminator. The data can be completely replaced using the assignment operator: ptr=_L("Hi there"); Note the use of the _L macro to construct a TPtrC of the correct build variant as the source of the assignment. The length of ptr is now 8 but the maximum length remains 16. The size depends on the build variant. In an ASCII build, this is 8 but in a UNICODE build, this becomes 16 (two bytes for every character). The length of the data represented can be changed. For example, after ptr.SetLength(2), the descriptor represents the text "Hi". The length can even be set to zero so that after ptr.Zero( ), the descriptor represents no data. Nevertheless, the maximum length remains at 16 so that: ptr=_L("Have a nice day!"); puts the 16 characters "Have a nice day" into the descriptor's data area. See also e32.macro._L. Buffer Descriptors e32.descriptors.using.buffer-descriptors The code fragments shown here to illustrate the use of buffer descriptors are extracted from the sample source code in the eudesbuf project. Run the code in this project to see buffer descriptors in action. TBufC A TBufC is a buffer descriptor where the data area is part of the descriptor itself. Data can be set into the descriptor at construction time or by the assignment operator at any other time. Data already held by the descriptor cannot be modified but it can be completely replaced (again, using the assignment operator). For example: TBufC<16> bufc2(_L("Hello World!")); constructs a TBufC which can contain up to 16 data items. During construction, the descriptor's data area is set to contain the text "Hello World!" and the length of the descriptor is set to 12. The data within bufc2 cannot be modified but it can be replaced using the assignment operator: bufc2=_L("Replacement text"); To prevent any possibility of replacing the data, declare bufc2 as const. The data within a TBufC can be changed by constructing a TPtr from the TBufC using the Des( ) member function; the data can then be changed through the TPtr. The maximum length of the TPtr is the value of the TBufC template parameter. For example: bufc2=_L("Hello World!"); TPtr ptr=bufc2.Des( ); ptr.Delete((ptr.Length( )-1),1); ptr.Append(_L("& Hi")); This deletes the last character in the TBufC and adds the characters "& Hi" so that the TBufC now contains the text "Hello World & Hi" and its length is 16. Note that the length of both the TBufC and the TPtr reflect the changed data. TBuf A TBuf is a modifiable buffer descriptor where the data area is part of the descriptor itself. The data can be modified provided that the data is not extended beyond the maximum length. The maximum length is set by the constructor. For example: TBuf<16> buf(_L("Hello World!")); constructs a TBuf which can contain up to 16 data items. During construction, the descriptor's data area is set to contain the text "Hello World!", the length of the descriptor is set to 12 and its maximum length is set to 16. The data can be modified directly: buf.Append(`@`); changes buf's data to "Hello World!@" and its length to 13 while: buf.SetLength(3); changes it length to 3 and its data to "Hel". The maximum length of the descriptor always remains at 16. Like a TBufC descriptor, the data contained within a TBuf can be replaced entirely using the assignment operator: buf=_L("Replacement text"); replaces "Hello World" with "Replacement text" and changes the length of the descriptor to 16. An attempt to increase the length of the data beyond the maximum generates an exception (a panic). For example: buf=_L("Text replacement causes panic!"); generates a panic at run time because the length of the replacement text (30) is greater than the maximum (16). General Binary Data e32.descriptors.using.general-binary-data The code fragments shown here, illustrating how descriptors can handle, general binary data, are extracted from the sample source code in the eudesbin project. Run the code in this project to see the sample in action. The kind of data represented or contained by descriptors is not restricted to text. Descriptors can also handle general binary data. To deal with general binary data, always explicitly construct an 8 bit variant descriptor. Binary data should always be treated as 8 bit data regardless of the build. For example set up an area in memory initialised with binary data: TUint8 data[6]={0x00,0x01,0x02,0xAD,0xAE,0xAF}; Construct a modifiable buffer descriptor using the default constructor: TBuf8<32> buffer; The following code extracted from the eudesbin project puts the binary data into the descriptor, appends a number of single byte values and then displays the data at the test console. The length of the buffer is 9, the maximum length is 32 and the size is 9 regardless of the build.
TInt index;
TInt counter;
buffer.Append(&data[0],sizeof(data));
buffer.Append(0xFD);
buffer.Append(0xFE);
buffer.Append(0xFF);
counter = buffer.Length( );
for (index = 0; index < counter; index++)
testConsole.Printf(_L("0x%02x"),buffer[index]);
testConsole.Printf(_L("; Length( )=%d;.backslash.n"),
buffer.Length( )
);
testConsole.Printf(_L("Size( )=%d; MaxLength( )=%d.backslash.n"),
buffer.Size( ),
buffer.MaxLength( )
);
Text and general binary data can be freely mixed; so that:
buffer.Append(`A`);
buffer.Append(`B`);
buffer.Append(0x11);
is acceptable.
Non-modifying Functions e32.descriptors.using.non-modifying-functions The code fragments shown here, illustrating some of the non-modifying descriptor member functions, are extracted from the sample source code in the eudesc project. Look at the code in this project to see the full set of examples These examples all use a TBufC descriptor constructed to contain the text "Hello World!". Note also that the descriptor is declared const so that its data cannot be replaced using the assignment operator: const TBufC<16> bufc(_L("Hello World!")); Right( ) & Mid( ) These functions construct a TPtrc to represent a portion of bufc's data TPtrC ptrc1=bufc.Right(5); ptrc1 represents the right hand 5 data items in bufc. ptrc1's data is "orld!", its length is 5 and the address of its data area is the address of bufc's data area plus 7. The Left( ) member function works in a similar way. TPtrC ptrc2=bufc.Mid(3,6); ptrc2 represents the 6 data items offset 3 from the start of bufc's data area ptrc2's data is "lo Wor", its length is 6 and the address of its data area is the address of bufc's data area plus 3. In practice, it may not be necessary to assign the returned TPtrC to another TPtrC. For example, the following code puts a value of 3 in pos; this is the offset of char `W` within the chars "lo Wor" (see later for an explicit example of Locate( )) TInt pos; . . . pos=(bufc.Mid(3,6)).Locate(`W`); These functions can panic. For example, requesting the 13 right hand data items in bufc will cause an exception (there are only 12): TPtrC ptrc3=bufc.Right(13); Compare( ) & CompareF( ) The compare functions can be used to compare the content of two descriptors. Any kind of data can be compared. For binary data, use Compare( ). For text use Compare( ), CompareF( ) or CompareC( ). The following example compares the content of bufc with the content of a number of descriptors and displays the results at the test console:
. . .
TInt index;
. . .
TPtrC genptr;
const TBufC<19>lessthan(_L(" is less than "));
const TBufC<19>greaterthan(_L(" is greater than "));
const TBufC<19>equalto(_L(" is equal to "));
. . .
const TBufC<16>compstr[7] = {_L("Hello World!@@"),
_L("Hello"),
_L("Hello Worl"),
_L("Hello World!"),
_L("hello world!"),
_L("Hello World"),
_L("Hello World@"),
};
for (index = 0; index < 7; index++)
{
if( (bufc.Compare(compstr[index])) < 0)
genptr.Set(lessthan);
else if( (bufc.Compare(compstr[index])) > 0)
genptr.Set(greaterthan);
else genptr.Set(equalto);
testConsole.
Printf(_L(".backslash."%S.backslash."%S.backslash."%S.backslash.".backslas
h.n"),
&bufc,
&genptr,
&compstr[index]
);
}
The case of text is important using Compare( ); the fourth comparison is equal but the fifth comparison is not (the `w` characters are a different case). Using CompareF( ), the case is not important; both the fourth and fifth comparisons return an equal result. Locate( ), LocateF( ) & LocateReverse( ) The locate functions can be used to find the position (offset) of a character within text or a specific value within general binary data. The following example attempts to find the positions (i.e. the offsets) of the characters `H`, `!`, `o` and `w` within the text "Hello World!" and displays the result at the test console:
. . .
TInt index;
TInt pos;
TPtrC genptr;
const TBufC<9> notfound(_L("NOT FOUND")),
const TBufC<5> found(_L("found"));
. . .
TChar ch[4] = {`H`, `!`, `o`, `w`};
. . .
testConsole.Printf(_L("using Locate( ).backslash.n"));
for (index = 0 ; index < 4; index++)
{
pos = bufc.Locate(ch[index]);
if (pos < 0)
genptr.Set(notfound);
else
genptr.Set(found);
testConsole.Printf(_L(".backslash."%S.backslash." Char %c is at pos %d
(%S).backslash.n"),
&bufc,
ch[index],
pos,
&genptr
);
}
The character `w` is not found using Locate( ) but is found using LocateF( ). This is because Locate( ) is case sensitive while LocateF( ). This example uses LocateReverse( ) which is used to find the position of a character starting from the end of the descriptor's data area
. . .
testConsole.Printf(_L("using LocateReverse( ).backslash.n"));
for (index = 0 ; index < 4; index++)
{
pos = bufc.LocateReverse(ch[index]);
if(pos < 0)
genptr.Set(notfound);
else
genptr.Set(found);
testConsole.Printf(_L(".backslash."%S.backslash." Char %c is at pos %d
(%S).backslash.n"),
&bufc,
ch[index],
pos,
&genptr
);
}
Note that the 2nd char `o` in the string "Hello World!" is found this time. Match( ) & MatchF( ) The following example shows the use of the Match( ) and MatchF( ) member functions. The result of a matches between the content of buf and a series of descriptors with varying combinations of match strings is displayed at the test console.
. . .
TInt index;
TInt pos;
TPtrC genptr;
const TBufC<9> notfound(_L("NOT FOUND"));
const TBufC<5> found(_L("found"));
. . .
TBufC<8>matchstr[7] = {_L("*World*"),
_L("*W?rld*"),
_L("*Wor*"),
_L("Hello"),
_L("*W*"),
_L("hello"),
_L("*"),
};
for (index = 0 ; index < 7; index++)
{
pos = bufc.Match(matchstr[index]);
if(pos < 0)
genptr.Set(notfound);
else
genptr.Set(found);
testConsole.Printf(_L("%- 8S pos %2d (%S).backslash.n"),
&matchstr[index],
pos,
&genptr
):
}
Note that when using MatchF( ), the result is different when matching the 6th string where the case is ignored. Modifying Functions e32.descriptors.using.modifying-functions The code fragments shown here, illustrating some of the modifying descriptor member functions, are extracted from the sample source code in the eudes project. Look at the code in this project to see the full set of examples. These examples all use a TBuf descriptor constructed to contain the text "Hello World!". TBuf<32> buf(_L("Hello World!")); Swap( ) The contents, length and size of altbuf1 and buf are swapped; the maximum lengths of the descriptors do NOT change. TBuf<16> altbuf1(_L("What a nice day")); . . . buf.Swap(altbuf1); Repeat( ) The current length of buf is set to 16. Repeat copying the characters "Hello" generates the text sequence "HelloHelloHelloH" in buf. buf.SetLength(16); buf.Repeat(_L("Hello")); Setting the length of buf to and re-doing the repeat generates the text sequence "HelloHel". Justify( ) The example uses src as the source descriptor. TBufVC<40> src(_"Hello World!")); . . . buf.Justify(src,16,ELeft,`@`); The descriptor src has length 12. The target field in buf has width 16 (this is greater than the length of the descriptor src). src is copied into the target field, aligned left and padded with `@` characters. The length of buf becomes the same as the specified width, i.e 16. buf.Justify(src,16,ECenter,`@`); The target field in buf has width 16 (this is greater than the length of the descriptor src). src is copied into target field, aligned centrally and padded with `@` characters. The length of buf becomes the same as the specified width, i.e 16 buf.Justify(src,10,ECenter,`@`); The target field in buf has width 10 (this is smaller than the length of the descriptor src). src is copied into the target field but truncated to 10 characters and, therefore, alignment and padding information is not used. The length of buf becomes the same as the width, i.e. 10 buf.Justify(src,KDefaultJustifyWidth,ECenter,`@`); The target field in buf is set to the length of the descriptor src (whatever it currently is). src is copied into the target field. No padding and no truncation is needed and so the alignment and padding information is not used. The length of buf becomes the same as the length of src, i.e. 12. Descriptors as Interface Specifiers e32.descriptors.using.interface-specifiers See the eudesint project for examples illustrating the use of descriptors in function interfaces. Heap Descriptors e32.descriptors.using.heap-descriptors The code fragments shown here, illustrating the use of heap descriptors, are extracted from the sample source code in the eudeshbc project. Look at the code in this project to see the the sample in action. An HBufC is always constructed on the heap using the static member functions New( ), NewL( ) or NewLC( ). For example: HBufC* buf; . . . buf=HBufC::NewL(15); This constructs an HBufC which can hold up to 15 data items. The current length is zero. Although existing data within an HBufC cannot be modified, the assignment operator can be used to replace that data For example: *buf=_L("Hello World!"); To allow more than 15 characters or data items to be assigned into the HBufC, it must be reallocated first. For example: buf=buf-> ReAllocL(20); This permits the following assignment to be done without causing a panic: *buf=_L("Hello World! Morning"); buf may or may not point to a different location in the heap after relocation. The location of the reallocated descriptor depends on the heap fragmentation and the size of the new cell. The Des( ) function returns a TPtr to the HBufC. The data in the HBufC can be modified through the TPtr. The maximum length of the TPtr is determined from the size of the cell allocated to the data area of the HBufC. For example: TPtr ptr=buf-> Des( ); . . . ptr.Delete((ptr.Length( )-9),9); ptr.Append(_L("& Hi")); This changes the data in the HBufC and the length of the HBufC. TPtrC Class Constant Pointer Descriptor Overview Derivation TDesC Abstract: implements descriptor behaviour which does not modify data. TPtrC A constant pointer descriptor. Defined in e32des8.h for the 8 bit variant (TPtr8). e32des16.h for the 16bit variant (TPtr16). Description Create a TPtrC descriptor to access a pre-existing location in either ROM or RAM where the data at that location is to be accessed but not changed (or where the data cannot be changed). A common use for a TPtrC is to access a string of text in a code segment. This will normally be constructed using the _L macro which constructs a TPtrC descriptor for either an ASCII or UNICODE build. Often, a TPtrC will appear as the right hand side of an expression or as an initialisation value for another descriptor, for example: TBuf<16> str(_L"abcdefghijklmnop")); . . . str.Find(_L"abc"); str.Find(_L"bcde"); The _L macro expands to a TPtrC which is defined as either a TPtr8 or TPtrC16 depending on the build variant (TBuf is also defined in a similar way). The 8 bit variant, TPtrC8 can be constructed to access binary data The 8 bit variant is always explicitly used for binary data. Five constructors are available to build a TPtr and include a default constructor. A TPtrC can be (re-)initialised after construction by using the set( ) functions. All the member functions described under the TDesC class are available for use by a TPtrc descriptor. In summary these are:
Length( ) Fetch length of descriptor data.
Size( ) Fetch the number of bytes occupied by
descriptor data.
Ptr( ) Return a pointer to the descriptor data.
Compare( ), Compare data (normally), (folded), (collated).
CompareF( ),
CompareC( )
Match( ), Pattern match data (normally), (folded),
MatchF( ), MatchC( ) (collated).
Locate( ), LocateF( ) Locate a character in forwards direction
(normally), (folded).
LocateReverse( ), Locate a character in reverse direction
LocateReverseF( ) (normally), (folded).
Find( ), FindF( ), FindC Find data (normally), (folded), (collated).
Left( ) Construct TPtrC for leftmost part of data.
Right( ) Construct TPtrC for rightmost part of data.
Mid( ) Construct TPtrC for portion of data.
Alloc( ), Construct an HBufC for this descriptor.
AllocL( ), AllocLC( )
HufEncode( ) Huffman encode
HufDecode( ) Huffman decode
operators < <= > >= == Comparison operators
operator [ ] Indexing operator
Construction e32.descriptors.TPtrC.construction TPtrC( ) Default C++ constructor Description The default C++ constructor is used to construct a constant pointer descriptor. The length of the constructed descriptor is set to zero and its pointer is set to NULL. Notes Use the Set( ) member function to initialise the pointer descriptor. TPtrC( ) Copy constructor TPtrC(const TPtrC& aDes); Description The C++ copy constructor constructs a new TPtrC object from the existing one. The length of the constructed descriptor is set to the length of aDes and is set to point to aDes's. data. TPtrC( ) C++ constructor [with any descriptor] TPtrC(const TDesC& aDes); Description The C++ constructor is used to construct the TPtrC with any kind of descriptor. The length of the constructed descriptor is set to the length of aDes, and it is set to point to aDes's data. Arguments const TDesC& aDes A reference to any type of descriptor used to construct the TPtrC. Notes If aDes is a reference to a heap descriptor (HBufC), then the data also resides on the heap. TPtrC( ) C++ constructor [with zero terminated string] TPtrC(const TText* aString); Description The C++ constructor is used to construct the TPtrC object with a zero terminated string. The length of the descriptor is set to the length of the zero terminated string, excluding the zero terminator. The constructed descriptor is set to point to the location of the string, whether in RAM or ROM. Arguments const TText* aString A pointer to the zero terminated used to construct the TPtrC. TPtrC( )C++ constructor [with address and length] TPtrC(const TUint??* aBuf,TInt aLength); Description The C++ constructor is used to construct the TPtrC with the memory address and length. The length of the constructed descriptor is set to the value of aLength. The constructed descriptor is set to point to the memory address supplied in aBuf; the address can refer to RAM or ROM. Arguments const TUint??* aBuf The address which is to be the data area of the constant pointer descriptor. For the 8 bit variant, this is type TUint8*; for the 16 bit variant, this is type TUint16*. TInt aLength The length of the constructed constant pointer descriptor. This value must be non-negative otherwise the constructor will panic with ETDes8LengthNegative for the 8 bit variant or ETDes16LengthNegative for the 16 bit variant. Late Initialisation e32.descriptors.TPtrC.late-initialisation Set( ) Initialisation taking any descriptor void Set(const TDesC& aDes); Description Use this function to initialise (or re-initialise) a constant pointer descriptor using the content of any kind of descriptor. The length of this constant pointer descriptor is set to the length of aDes. This descriptor is set (or re-set) to point to aDes's data Arguments const TDesC& aDes A reference to any descriptor whose content is to be used to initialise this constant pointer descriptor. Notes The Set( ) function can be used to initialise a constant pointer descriptor constructed using the default constructor. If aDes is a reference to a heap descriptor (HBufC), then the data also resides on the heap. Set( ) Initialisation taking address and length void Set(const TUint??* aBuf,TInt aLength); Use this function to initialise (or re-initialise) a constant pointer descriptor using the supplied memory address and length. The length of this constant pointer descriptor is set to the value of aLength. The descriptor is set to point to the memory address supplied in aBuf; the address can refer to RAM or ROM. Arguments const TUint??* aBuf The address which is to be the data area of the constant pointer descriptor. For the 8 bit variant, this is type TUint8*; for the 16 bit variant, this is type TUint16*. TInt aLength The length of the constant pointer descriptor. This value must be non-negative otherwise the constructor will panic with ETDes8LengthNegative for the 8 bit variant or ETDes16LengthNegative for the 16 bit variant. Notes The Set( ) function can be used to initialise a constant pointer descriptor constructed using the default constructor. TPtr Class Modifiable Pointer Descriptor Overview Derivation TDesC Abstract: implements descriptor behaviour which does not modify data. TDes Abstract: implements descriptor behaviour which can change data. TPtr A modifiable pointer descriptor. Defined in e32des8.h for the 8 bit variant (TPtr8). e32des16.h for the 16 bit variant (TPtr16). Description Create a TPtr descriptor to access a pre-existing area or buffer in RAM where the contents of that buffer are to be accessed and manipulated. A common use for a TPtr is to access the buffer of an existing TBufC or an HBufC descriptor using the Des( ) member functions (of TBufC and HBufC). For example: TBufC<8> str(_L("abc")); str.Des( ).Append(`x`); TPtr is defined as either a TPtr8 or TPtr16 depending on the build variant and can be used to access text. The 8 bit variant, TPtr8 can be constructed to access binary data. The 8 bit variant is always explicitly used for binary data Two constructors are available to build a TPtr and include a default constructor. A TPtr can be (re-)initialised after construction by using the set( ) functions. All the member functions described under the TDesC and TDes classes are available for use by a TPtr descriptor. In summary these are:
Length( ) Fetch length of descriptor data.
Size( ) Fetch the number of bytes occupied by
descriptor data.
Ptr( ) Fetch address of descriptor data.
Compare( ), Compare data (normally), (folded), (collated).
CompareF( ),
CompareC( )
Match( ), Pattern match data (normally), (folded),
MatchF( ), MatchC( ) (collated).
Locate( ), LocateF( ) Locate a character in forwards direction
(normally), (folded).
LocateReverse( ), Locate a character in reverse direction
LocateReverseF( ) (normally), (folded).
Find( ), FindF( ), FindC Find data (normally), (folded), (collated).
Left( ) Construct TPtrC for leftmost part of data.
Right( ) Construct TPtrC for rightmost part of data.
Mid( ) Construct TPtrC for portion of data.
Alloc( ), Construct an HBufC for this descriptor.
AllocL( ), AllocLC( )
HufEncode( ) Huffman encode
HufDecode( ) Huffman decode
MaxLength( ) Fetch maximum length of descriptor.
MaxSize( ) Fetch maximum size of descriptor
SetLength( ) Set length of descriptor data
Zero( ) Set length of descriptor data to zero
SetMax( ) Set length of descriptor data to the
maximum value.
Swap( ) Swap data between two descriptors.
Copy( ), Copy data (normally), (and fold), (and collate).
CopyF( ), CopyC( )
CopyLC( ) Copy data and convert to lower case.
CopyUC( ) Copy data and convert to upper case
CopyCP( ) Copy data and capitalise
Repeat( ) Copy and repeat.
Justify( ) Copy and justify.
Insert( ) Insert data.
Delete( ) Delete data.
Replace( ) Replace data.
TrimLeft( ) Delete spaces from left side of data area.
TrimRight( ) Delete spaces from right side of data area.
Trim( ) Delete spaces from both left and right side of
data area.
Fold( ) Fold characters.
Collate( ) Collate characters.
LowerCase( ) Convert to lower case.
UpperCase( ) Convert to upper case.
Capitalise( ) Capitalise.
Fill( ) Fill with specified character.
FillZ( ) Fill with 0x00.
Num( ) Convert numerics to character (hex.digits to
lower case).
NumUC( ) Convert numerics to (upper case) character.
Format( ), Convert multiple arguments to character
FormatList( ) according to format specification.
Append( ) Append data.
AppendFill( ) Append with fill characters.
AppendJustify( ) Append data and justify
AppendNum( ) Append from converted numerics.
AppendNumUC( ) Append from converted numerics; convert to
upper case.
AppendFormat( ), Append from converted multiple arguments.
AppendFormatList( )
ZeroTerminate( ) Append zero terminator.
PtrZ( ) Append zero terminator and return a pointer.
operators < <= > >= == Comparison operators.
operator += Appending operator.
operator [ ] Indexing operator.
Construction e32.descriptors.TPtr.construction TPtr( ) C++ constructor [with address and maximum length] TPtr(TUint??* aBuf,TInt aMaxLength); Description The C++ constructor is used to construct the TPtr with the address and maximum length. The length of the constructed descriptor is set to zero and its maximum length is set to aMaxLength. The constructed descriptor is set to point to the memory address supplied in aBuf which can refer either to RAM or ROM. Arguments TUint??* aBuf The address which is to be the data area of the modifiable pointer descriptor. For the 8 bit variant, this is type TUint8*; for the 16 bit variant, this is type TUint16*. TInt aMaxLength The maximum length of the new modifiable pointer descriptor. This value must be non-negative otherwise the constructor will panic with ETDes8MaxLengthNegative for the 8 bit variant or ETDes16MaxLengthNegative for the 16 bit variant. TPtr( ) C++ constructor [with address, length and maximum length] TPtr(TUint??* aBuf,TInt aLength,TInt aMaxLength); Description The C++ constructor is used to construct the TPtr with the address, length and maximum length. Use this to construct a modifiable pointer descriptor using the supplied memory address, length and maximum length to initialise it. The length of the constructed descriptor is set to aLength and its maximum length is set to aMaxLength. The constructed descriptor is set to point to the memory address supplied in aBuf which can refer either to RAM or ROM. Arguments TUint??* aBuf The address which is to be the data area of the modifiable pointer descriptor. For the 8 bit variant, this is type TUint8*; for the 16 bit variant, this is type TUint16*. TInt aLength The length of the new modifiable pointer descriptor. This value must be non-negative and not greater than the value of aMaxLength otherwise the constructor will panic with ETDes8LengthOutOfRange for the 8 bit variant or ETDes8LengthOutOfRange for 16 bit variant. TInt aMaxLength The maximum length of the new modifiable pointer descriptor. This value must be non-negative otherwise the constructor will panic with ETDes8MaxLengthNegative for the 8 bit variant or ETDes16MaxLengthNegative for 16 bit variant. Late Initialisation e32.descriptors.TPtr.late-initialisation Set( ) Initialisation by copying a TPtr void Set(TPtr& apt); Use this function to initialise (or re-initialise) a modifiable pointer descriptor using the content of another modifiable pointer descriptor. The function behaves as a copy constructor. The length of the descriptor is set to the length of aPtr and its maximum length is set to the maximum length of aPtr. The descriptor is set (or re-set) to point to aPtr's data. Arguments TPtr& aPtr A reference to a modifiable pointer descriptor whose content is to be used to initialise this modifiable pointer descriptor. Set( ) Initialisation taking address, length and maximum length void Set(TUint??* aBuf,TInt aLength,TInt aMaxLength); Use this function to initialise (or re-initialise) a modifiable pointer descriptor using the supplied memory address, length and maximum length. The length of the resulting descriptor is set to the value of aLength and its maximum length is set to the value of aMaxLength. The descriptor is set (or re-set) to point to the memory address supplied in aBuf; the address can refer to RAM or ROM. Arguments TUint??* aBuf The address which is to be the data area of the modifiable pointer descriptor. For the 8 bit variant, this is type TUint8*; for the 16 bit variant, this is type TUint16*. TInt aLength The length of the modifiable pointer descriptor. This value must be non-negative and not greater than the value of aMaxLength otherwise the constructor will panic with ETDes8LengthOutOfRange for the 8 bit variant or ETDes16LengthOutOfRange for the 16 bit variant TInt aMaxLength The maximum length of the modifiable pointer descriptor. This value must be non-negative otherwise the constructor will panic with ETDes8MaxLengthNegative for the 8 bit variant or ETDes16MaxLengthNegative for the 16 bit variant Assignment Operators e32.descriptors.TPtr.assignment-operators See also e32.descriptors.TDes.assignment-operators. operator= Operator=taking a TPtr TPtr& operator=(const TPtr& aDes); Description This assignment operator copies a modifiable pointer descriptor to this modifiable pointer descriptor. aDes's data is copied into this descriptor's data area, replacing the existing content. The length of this descriptor is set to the length of aDes. Arguments const TPtr& aDes A reference to the modifiable pointer descriptor whose data is to be copied. Return value TPtr& A reference to this descriptor. Notes The length of aDes must not be greater than the maximum length of this descriptor otherwise the operation will panic with ETDes8Overflow for the 8 bit variant or ETDes16Overflow for the 16 bit variant operator= Operator=taking any descriptor TPtr& operator=(const TDesC& aDes); Description This assignment operator copies the content of any type of descriptor, aDes, to this modifiable pointer descriptor. aDes's data is copied into this descriptor's data area, replacing the existing content. The length of this descriptor is set to the length of aDes. Arguments const TDesC& aDes A reference to any type of descriptor whose data is to be copied. Return value TPtr& A reference to this descriptor. Notes The length of aDes must not be greater than the maximum length of this descriptor otherwise the operation will panic with ETDes8Overflow for the 8 bit variant or ETDes16Overflow for the 16 bit variant operator= Operator=taking a zero terminated string TPtr& operator=(const TText aString); Description This assignment operator copies a zero terminated string, excluding the zero terminator, into this modifiable pointer descriptor. The copied string replaces the existing content of this descriptor. The length of this descriptor is set to the length of the string (excluding the zero terminator). Arguments const TText* aString The address of the zero terminated string to be copied. Return value TPtr& A reference to this descriptor. Notes The length of the string, excluding the zero terminator, must not be greater than the maximum length of this descriptor otherwise the operation will panic with ETDes8Overflow for the 8 bit variant or ETDes16Overflow for the 16 bit variant. TBufC<TInt S> Class Constant Buffer Descriptor Overview Derivation TDesC Abstract: implements descriptor behaviour which does not modify data. TBufCBase Abstract: implementation convenience. TBufC<TInt S> A constant buffer descriptor. Defined in e32des8.h for the 8 bit variant (TBufC8<TInt S>). e32des16.h for the 16 bit variant (TBufC16<TInt S>) Description Create a TBufC descriptor to provide a buffer of fixed length for containing and accessing constant data. The data held in a TBufC descriptor cannot be modified, although it can be replaced. Four constructors are available to build a TBufC descriptor and include a default constructor. The content of TBufC descriptor can be replaced after construction using the assignment operators. For example, to create a buffer of length 16 set to contain the characters "ABC" TBufC<16> str(_L("ABC")); The content cannot be modified but may be replaced, for example: str=_L("xyz"), To create a buffer which is intended to contain general binary data, explicitly construct the 8 bit variant of TBufC; for example, to create a 256 byte buffer: TBufC8<256> buf; . . . buf= . . . ; All the member functions described under the TDesC class are available for use by a TBufC descriptor. In summary these are:
Length( ) Fetch length of descriptor data.
Size( ) Fetch the number of bytes occupied by
descriptor data.
Ptr( ) Fetch address of descriptor data.
Compare( ), Compare data (normally), (folded), (collated).
CompareF( ),
CompareC( )
Match( ), Pattern match data (normally), (folded),
MatchF( ), MatchC( ) (collated).
Locate( ), LocateF( ) Locate a character in forwards direction
(normally), (folded).
LocateReverse( ), Locate a character in reverse direction
LocateReverseF( ) (normally), (folded).
Find( ), Find data (normally), (folded), (collated).
FindF( ), FindC
Left( ) Construct TPtrC for leftmost part of data.
Right( ) Construct TPtrC for rightmost part of data.
Mid( ) Construct TPtrC for portion of data.
Alloc( ), Construct an HBufC for this descriptor.
AllocL( ), AllocLC( )
HufEncode( ) Huffman encode
HufDecode( ) Huffman decode
operators < <= > >= == Comparison operators
operator [ ] Indexing operator
Construction e32.descriptors.TBufC.construction TBufC( ) Default C++ constructor TfBufC( ); Description The default C++ constructor is used construct a non-modifiable buffer descriptor. The integer template parameter<TInt S> is used, by the compiler, to calculate the size of the data area to be created as part of the descriptor object. The length of the constructed descriptor is set to zero. Notes Use the assignment operators to initialise the non-modifiable buffer descriptor. TBufC( ) Copy constructor TBuf(const TBufC<S>& aLcb); Description The C++ copy constructor constructs a new TBufC<S> object from the existing one. The integer template parameter <TInt S> is used, by the compiler, to calculate the size of the data area to be created as part of the constructed descriptor. aLcb's data is copied into the constructed descriptor's data area. The length of the constructed descriptor is set to the length of aLcb. TBufC( ) C++ constructor [with any descriptor] TBufC(const TDesC& aDes); Description The C++ constructor is used to construct the TBufC<S> with any kind of descriptor. The integer template parameter <TInt S> is used, by the compiler, to calculate the size of the data area to be created as part of the constructed descriptor. aDes's data is copied into the constructed descriptor's data area. The length of the constructed descriptor is set to the length of aDes. Arguments const TDesC& aDes A reference to any type of descriptor used to construct the TBufC<S>. Notes The length of aDes must not be greater than the value of the integer template parameter <TInt S> otherwise the constructor will panic with ETDes8LengthOutOfRange for the 8 bit variant or ETDes16LengthOutOfRange for the 16 bit variant. TBufC( ) C++ constructor[with zero terminated string] TBufC(const TText* aString); Description The C++ constructor is used to construct the TBufC<S> with a zero terminated string. The integer template parameter <TInt S> is used, by the compiler, to calculate the size of the data area to be created as part of the constructed descriptor object. The string, excluding the zero terminator, is copied into the constructed descriptor's data area. The length of the constructed descriptor is set to the length of the string, excluding the zero terminator. Arguments const TText* aString The address of the zero terminated string used to construct the TBufC<S>. Notes The length of the string, excluding the zero terminator, must not be greater than the value of the integer template parameter <TInt S> otherwise the constructor will panic with ETDes8LengthOutOfRange for the 8 bit variant or ETDes16LengthOutOfRange for the 16 bit variant. Create a Modifiable Pointer Descriptor e32.descriptors.TBufC.create-TPtr Des( ) Create & return a TPtr TPtr Des( ); Description Use this function to construct and return a modifiable pointer descriptor to represent this descriptor. The content of a non-modifiable buffer descriptor cannot be altered but creating a modifiable pointer descriptor provides a mechanism for modifying that data. The length of the new TPtr is set to the length of this descriptor. The maximum length of the new TPtr is set to the value of the integer template parameter <TInt S>. The new TPtr is set to point to this descriptor. This descriptor's data is neither copied nor moved. This descriptor's data can be modified through the newly constructed TPtr. If there is any change to the length of the data, then the length of both this descriptor and the TPtr is modified to reflect that change. Return value TPtr A modifiable pointer descriptor representing this non-modifiable buffer descriptor. Assignment Operators e32.descriptors.TBufC.assignment-operators See also e32.descriptors.TDes.assignment-operators. operator= Operator=taking a TBufC<S> TBufC<S>& operator=(const TBufC<S>& aLcb); Description This assignment operator copies the content of the non-modifiable buffer descriptor aLcb into this non-modifiable buffer descriptor. aLcb's data is copied into this descriptor's data area, replacing the existing content. The length of this descriptor is set to the length of aLcb. Arguments const TBufC<S>& aLcb A reference to a non-modifiable buffer descriptor whose content is to be copied. Return value TBufC<S>& A reference to this descriptor. operator= Operator=taking any descriptor TBufC<S>& operator=(const TDesC& aDes); Description This assignment operator copies the content of any type of descriptor aDes into this non-modifiable buffer descriptor. aDes's data is copied into this descriptor's data area, replacing the existing content. The length of this descriptor is set to the length of aDes. Arguments const TDesc& aDes A reference to any type of descriptor whose data is to be copied. Return value TBufC<S>& A reference to this descriptor. Notes The length of aDes must not be greater than the value of the integer template parameter <TInt S> otherwise the operation will panic with ETDes8Overflow for the 8 bit variant or ETDes16Overflow for the 16 bit variant operator=Operator=taking zero terminated string TBufC<S>& operator=(const TText* aString); Description This assignment operator copies a zero terminated string, excluding the zero terminator, into this non-modifiable buffer descriptor. The copied string replaces the existing content of this descriptor. The length of this descriptor is set to the length of the string, excluding the zero terminator. Arguments const TText* aString The address of the zero terminated string to be copied. Return value TBufC<S>& A reference to this descriptor. Notes The length of the string, excluding the zero terminator, must not be greater than the value of the template parameter <TInt S> otherwise the operation will panic with ETDes8Overflow for the 8 bit variant or ETDes16Overflow for the 16 bit variant TBuf<TInt S> Class Modifiable Buffer Descriptor Overview Derivation TDesC Abstract: implements descriptor behaviour which does not modify data. TDes Abstract: implements descriptor behaviour which can change data. A modifiable buffer descriptor. TBuf<TInt S> Defined In e32des8.h for the 8 bit variant (TBuf<TInt S>). e32des16.h for the 16 bit variant (TBuf<TInt S>). Description Create a TBuf descriptor to provide a buffer of fixed length for containing, accessing and manipulating data. Five constructors are available to build a TBuf descriptor and include a default constructor. The content of a TBuf descriptor can be replaced after construction using the assignment operators. For example, to create a buffer of length 8 initially set to contain the characters "ABC" TBuf<8> str(_L("ABC")); The content of the buffer descriptor can be replaced provided the length of the new data does not exceed the value of the integer template parameter, for example: str=_L("xyz"); //OK str=_L("rstuvwxyz"); //causes an exception To create a buffer which is intended to contain general binary data, explicitly construct the 8 bit variant TBuf8, for example, to create a 256 byte buffer: TBuf8<256> buf; . . . buf= . . . ; All the member functions described under the TDesC and TDes classes are available for use by a TBuf descriptor. In summary these are:
Length( ) Fetch length of descriptor data.
Size( ) Fetch the number of bytes occupied by
descriptor data.
Ptr( ) Fetch address of descriptor data.
Compare( ), Compare data (normally), (folded), (collated).
CompareF( ),
CompareC( )
Match( ), Pattern match data (normally), (folded),
MatchF( ), MatchC( ) (collated).
Locate( ), LocateF( ) Locate a character in forwards direction
(normally), (folded).
LocateReverse( ), Locate a character in reverse direction
LocateReverseF( ) (normally), (folded).
Find( ), Find data (normally), (folded), (collated).
FindF( ), FindC
Left( ) Construct TPtrC for leftmost part of data.
Right( ) Construct TPtrC for rightmost part of data.
Mid( ) Construct TPtrC for portion of data.
Alloc( ), Construct an HBufC for this descriptor.
AllocL( ), AllocLC( )
HufEncode( ) Huffman encode
HufDecode( ) Huffman decode
MaxLength( ) Fetch maximum length of descriptor.
MaxSize( ) Fetch maximum size of descriptor
SetLength( ) Set length of descriptor data
Zero( ) Set length of descriptor data to zero
SetMax( ) Set length of descriptor data to the
maximum value.
Swap( ) Swap data between two descriptors.
Copy( ), Copy data (normally), (and fold), (and collate).
CopyF( ), CopyC( )
CopyLC( ) Copy data and convert to lower case.
CopyUC( ) Copy data and convert to upper case
CopyCP( ) Copy data and capitalise
Repeat( ) Copy and repeat.
Justify( ) Copy and justify.
Insert( ) Insert data.
Delete( ) Delete data.
Replace( ) Replace data.
TrimLeft( ) Delete spaces from left side of data area.
TrimRight( ) Delete spaces from right side of data area.
Trim( ) Delete spaces from both left and right side of
data area.
Fold( ) Fold characters.
Collate( ) Collate characters.
LowerCase( ) Convert to lower case.
UpperCase( ) Convert to upper case.
Capitalise( ) Capitalise.
Fill( ) Fill with specified character.
FillZ( ) Fill with 0x00.
Num( ) Convert numerics to character (hex digits to
lower case).
NumUC( ) Convert numerics to (upper case) character.
Format( ), Convert multiple arguments to character
FormatList( ) according to format specification.
Append( ) Append data.
AppendFill( ) Append with fill characters.
AppendJustify( ) Append data and justify
AppendNum( ) Append from converted numerics (hex digits
to lower case).
AppendNumUC( ) Append from converted numerics; convert
to uppercase.
AppendFormat( ), Append from converted multiple arguments.
AppendFormatList( )
ZeroTerminate( ) Append zero terminator.
PtrZ( ) Append zero terminator and return a pointer.
operators < <= > >= == Comparison operators.
operator += Appending operator.
operator [ ] Indexing operator.
Construction e32.descriptors.TBuf.construction TBuf( ) Default C++ constructor TBuf( ); Description The default C++ constructor is used to construct a modifiable buffer descriptor. The integer template parameter <TInt S> is used, by the compiler, to calculate the size of the data area to be created as part of the constructed descriptor. The length of the constructed descriptor is set to zero and the maximum length is set to the value of the integer template parameter <TInt S>. TBuf( ) C++ constructor[with length] TBuf(TInt aLength); Description The C++ constructor is used to construct the TBuf<S> with the length. The integer template parameter <TInt S> is used, by the compiler, to calculate the size of the data area to be created as part of the constructed descriptor. The length of the constructed descriptor is set to aLength and the maximum length is set to the value of the integer template parameter <TInt S>. Arguments TInt aLength The length of the constructed modifiable buffer descriptor. This value must be non-negative and not greater than the value of the integer template parameter <1Int S> otherwise the constructor will panic with ETDes8LengthOutOfRange for the 8 bit variant or ETDes16LengthOutOfRange for the 16 bit variant TBuf( ) Copy constructor TBuf(const TBuf<S>& aBuf); Description The C++ copy constructor constructs a new TBuf<S> object from the existing one. The integer template parameter <TInt S> is used, by the compiler, to calculate the size of the data area to be created as part of the constructed descriptor object. aBuf's data is copied into the constructed descriptor's data area. The length of the constructed descriptor is set to the length of aBuf and the maximum length is set to the value of the integer template parameter <TInt S>. TBuf( ) C++ constructor [with any descriptor] TBuf(const TDesC& aDes); Description The C++ constructor is used to construct the TBuf<S> with any kind of descriptor. The integer template parameter <TInt S> is used, by the compiler, to calculate the size of the data area to be created as part of the constructed descriptor. aDes's data is copied into the constructed descriptor's data area. The length of the constructed descriptor is set to the length of aDes and the maximum length is set to the value of the integer template parameter <TInt S>. Arguments const TDesC& aDes A reference to any type of descriptor used to construct the TBuf<S>. Notes The length of aDes must not be greater than the value of the integer template parameter <TInt S> otherwise the constructor will panic with ETDes8Overflow for the 8 bit variant or ETDes16Overflow for the 16 bit variant TBuf( ) C++ constructor [with zero terminated string] TBuf(const TText aString); Description The Cup constructor is used to construct the TBuf<S> with a zero terminated string. The integer template parameter <TInt S> is used, by the compiler, to calculate the size of the data area to be created as part of the constructed descriptor. The string, excluding the zero terminator, is copied into the constructed descriptor's data area. The length of the constructed descriptor is set to the length of the string, excluding the zero terminator, and the maximum length is set to the value of the integer template parameter <TInt S>. Arguments const Text* aString The address of the zero terminated string used to construct the TBuf<S>. Notes The length of the string, excluding the zero terminator must not be greater than the value of the integer template parameter <TInt S> otherwise the constructor will panic with ETDes8Overflow for the 8 bit variant or ETDes16Overflow for the 16 bit variant Assignment Operators e32.descriptors.TBuf.assignment-operators See also e32.descriptors.TDes.assignment-operators. operator= Operator=taking a TBuf<S> TBuf<S>& operator=(const TBuf<S>& aBuf); Description This assignment operator copies the content of the modifiable buffer descriptor aBuf into this modifiable buffer descriptor. aBuf's data is copied into this descriptor's data area, replacing the existing content. The length of this descriptor is set to the length of aBuf. Arguments const TBuf<S>& aBuf A reference to the modifiable pointer descriptor whose content is to be copied. Return value TBuf<S>& A reference to this descriptor. Operator= Operator=taking any descriptor TBuf<S>& operator=(const TDesC& aDes); Description This assignment operator copies the content of any type of descriptor aDes into this modifiable buffer descriptor. aDes's data is copied into this descriptor's data area, replacing the existing content. The length of this descriptor is set to the length of aDes. Arguments const TDesc& aDes A reference to any type of descriptor whose content is to be copied. Return value TBuf<S>& A reference to this descriptor. Notes The length of aDes must not be greater than the value of the integer template parameter <TInt S> otherwise the operation will panic with ETDes8Overflow for the 8 bit variant or ETDes16Overflow for the 16 bit variant operator= Operator=taking a zero terminated string TBuf<S>& operator=(const TText* aString); Description This assignment operator copies a zero terminated string, excluding the zero terminator, into this modifiable buffer descriptor. The copied string replaces the existing content of this descriptor. The length of this descriptor is set to the length of the string, excluding the zero terminator. Arguments const TText* aString The address of the zero terminated string to be copied. Return value TBuf<S>& A reference to this descriptor. Notes The length of the string, excluding the zero terminator, must not be greater than the value of the template parameter <TInt S> otherwise the operation will panic with ETDes8Overflow for the 8 bit variant or ETDes16Overflow for the 16 bit variant HBufC Class Heap Descriptor Overview Derivation TDesC Abstract: implements descriptor behaviour which does not modify data. TBufCBase Abstract: implementation convenience. HBufC A heap descriptor. Defined in e32des8.h for the 8 bit variant (HBufC8). e32des16.h for the 16 bit variant (HBufC) Description Create an HBufC descriptor to provide a buffer of fixed length for containing and accessing data. The data held in an HBufC descriptor cannot be modified, although it can be replaced using the assignment operators. The descriptor exists only on the heap but has the important property that it can be resized, i.e. made either larger or smaller, to change the size of its data area. This is achieved by reallocating the descriptor. Unlike the behaviour of dynamic buffers (see e32.dynamic-buffers) reallocation is not done automatically. An HBufC descriptor is useful in situations where a large fixed length buffer may be required initially but, thereafter, a smaller fixed length buffer is sufficient. An HBufC descriptor must be constructed using the static member functions New( ), NewL( ) or NewLC( ) and resized using the ReAlloc( ) or ReAllocL( ) member functions. A code fragment illustrates bow these might be used:
class CAnyClass: CBase
{
public:
void AddToBuf(const TDesC& aSrcBuf);
private:
HBufC* iTgtBuf;
TInt iAllocLen;
}
void CAnyClass::AddToBuf(const TDesC& aSrcBuf)
{
TInt SrcLen = aSrcBuf.Length( );
if(iTgtBuf)
{
if (SrcLen > iAllocLen)
{
iTgtBuf = iTgtBuf->ReAllocL(SrcLen);
iAllocLen = SrcLen;
}
}
else
{
iTgtBuf = HBufC::NewL(SrcLen);
iAllocLen = SrcLen;
}
*iTgtBuf = aSrcBuf;
}
In practice, the use of ReAlloc( ) here is a little inefficient as the data in the HBufC descriptor is saved across the re-allocation but is then discarded when the content of aSrcBuf is assigned to it. All the member functions described under the TDesC class are available for use by a TBufC descriptor. In summary these are:
Length( ) Fetch length of descriptor data.
Size( ) Fetch the number of bytes occupied by
descriptor data.
Ptr( ) Fetch address of descriptor data.
Compare( ), Compare data (normally), (folded), (collated).
CompareF( ),
CompareC( )
Match( ), Pattern match data (normally), (folded),
MatchF( ), MatchC( ) (collated).
Locate( ), LocateF( ) Locate a character in forwards direction
(normally), (folded).
LocateReverse( ), Locate a character in reverse direction
LocateReverseF( ) (normally), (folded).
Find( ), FindF( ), FindC Find data (normally), (folded), (collated).
Left( ) Construct TPtrC for leftmost part of data.
Right( ) Construct TPtrC for rightmost part of data.
Mid( ) Construct TPtrC for portion of data.
Alloc( ), Construct an HBufC for this descriptor.
AllocL( ), AllocLC( )
HufEncode( ) Huffman encode
HufDecode( ) Huffman decode
operators < <= > >= == Comparison operators
operator [ ] Indexing operator
Allocation and Construction e32.descriptors.HBufC.allocation-and-construction New( ), NewL( ), NewLC( ) Create new HBufC e32.descriptors.new static HBufC* New(TInt aMaxLength); static HBufC* NewL(TInt aMaxLength); static HBufC* NewLC(TInt aMaxLength); Description Use these functions to construct a new HBufC descriptor on the heap. The functions attempt to acquire a single cell large enough to hold an HBufC object containing a data area with a length which is at least aMaxLength. The resulting length o | ||||||