Class TDes8

TDes8

Support

Supported from 5.0

Description

Modifiable 8-bit descriptor; abstract class. The class encapsulates the data member containing the maximum length of data represented by an 8 bit descriptor. It also provides member functions through which the data can be modified.

The class adds to the behaviour provided by the base class.

This class cannot be instantiated as it is intended to form part of a class hierarchy; it provides a well defined part of descriptor behaviour. It can, however, be passed as an argument type for functions which need to both modify and access descriptor data.

Derivation

TDes8 Modifiable 8-bit descriptor; abstract class TDesC8 Abstract base class for 8 bit non-modifiable descriptors

Defined in TDes8:
Append(), AppendFill(), AppendFormat(), AppendFormatList(), AppendJustify(), AppendNum(), AppendNumFixedWidth(), AppendNumFixedWidthUC(), AppendNumUC(), Capitalize(), Collate(), Copy(), CopyC(), CopyCP(), CopyF(), CopyLC(), CopyUC(), Delete(), Fill(), FillZ(), Fold(), Format(), FormatList(), Insert(), Justify(), LowerCase(), MaxLength(), MaxSize(), Num(), NumFixedWidth(), NumFixedWidthUC(), NumUC(), PtrZ(), Repeat(), Replace(), SetLength(), SetMax(), Swap(), Trim(), TrimAll(), TrimLeft(), TrimRight(), UpperCase(), Zero(), ZeroTerminate(), operator+=(), operator=, operator[]()

Inherited from TDesC8:
Alloc(), AllocL(), AllocLC(), Compare(), CompareC(), CompareF(), Find(), FindC(), FindF(), Left(), Length(), Locate(), LocateF(), LocateReverse(), LocateReverseF(), Match(), MatchC(), MatchF(), Mid(), Ptr(), Right(), Size(), operator!=(), operator<(), operator<=(), operator==(), operator>(), operator>=()

See also:

• TDesC8
• TDesC16

TInt MaxLength() const;

Description

Returns the maximum length of the descriptor. This is the upper limit for the number of 8 bit values or data items that the descriptor can represent.

Return value

TInt The maximum length of data that the descriptor can represent.

TInt MaxSize() const;

Description

Returns the maximum size of the descriptor. This is the upper limit for the number of bytes which the data represented by the descriptor can occupy.

Return value

TInt The maximum size of the descriptor data

void SetLength(TInt aLength)

Description

Sets the data length. Sets the length of the data represented by the descriptor to the specified value.

Parameters

TInt aLength The new length of the descriptor data. This value must be non-negative and must not be greater than the maximum length otherwise the function raises a USER 23 panic.

void SetMax()

Description

Sets the length of the data to the maximum length of the descriptor.

void Zero()

Description

Sets the length of the data to zero.

const TUint8& operator[](TInt anIndex) const;
TUint8& operator[](TInt anIndex);

Description

Returns a reference to a single data item within this descriptor's data. The compiler chooses the appropriate variant.

Parameters

TInt anIndex The position the data item within this descriptor's data. This is an offset; a zero value refers to the leftmost data position. This value must be non-negative and must be less than the current length of this descriptor otherwise the operation raises a USER 21 panic.

Return value

const TUint8& A const reference to the data item at the specified position. TUint8& A non-const reference to the data item at the specified position.

See also:

• Accessing individual data items

void Copy(const TDesC8& aDes);
void Copy(const TDesC16& aDes);
void Copy(const TUint8* aBuf,TInt aLength);
void Copy(const TUint8* aString);

Description

Copies data into this descriptor replacing any existing data. The length of this descriptor is set to reflect the new data.

Parameters

const TDesC8& aDes An 8 bit non modifiable descriptor. The length of the data cannot be greater than the maximum length of the target descriptor otherwise the function raises a USER 23 panic. const TDesC16& aDes A 16 bit non modifiable descriptor. Each double-byte value can only be copied into the corresponding single byte when the double-byte value is less than decimal 256. A double-byte value of 256 or greater cannot be copied and the corresponding single byte is set to a value of decimal 1. The length of the data cannot be greater than the maximum length of the target descriptor otherwise the function raises a USER 23 panic const TUint8* A pointer to data to be copied. TInt aLength The length of data to be copied. This value must be non-negative and must not be greater than maximum length of the target descriptor, otherwise the function raises a USER 23 panic. const TUint8* aString A pointer to a zero-terminated string. The length of the string, excluding the zero terminator, must not be greater than the maximum length of the target descriptor, otherwise the function raises a USER 23 panic.

See also:

• Copying data

TDes8& operator=(const TDesC8& aDes);
TDes8& operator=(const TDes8& aDes);
TDes8& operator=(const TUint8* aString);

Description

Copies data into this descriptor replacing any existing data. The length of this descriptor is set to reflect the new data.

Parameters

const TDesC8& aDes An 8 bit non-modifiable descriptor. The length of the data cannot be greater than the maximum length of the target descriptor, otherwise the function raises a USER 23 panic. const TDes8& aDes An 8 bit modifiable descriptor. The length of the data cannot be greater than the maximum length of the target descriptor, otherwise the function raises a USER 23 panic. const TUint8* aString A pointer to a zero-terminated string. The length of the string, excluding the zero terminator, must not be greater than the maximum length of the target descriptor, otherwise the function raises a USER 23 panic.

Return value

TDes8& A reference to this, the target descriptor

void CopyC(const TDesC8& aDes);

Description

Copies and collates. Copies and collates data from the specified descriptor into this descriptor replacing any existing data. The length of this descriptor is set to reflect the new data.

Parameters

const TDesC8& aDes An 8 bit non-modifiable descriptor. The length of the data cannot be greater than the maximum length of the target descriptor otherwise the function raises a USER 23 panic.

void CopyF(const TDesC8& aDes);

Description

Copies and folds data from the specified descriptor into this descriptor replacing any existing data. The length of this descriptor is set to reflect the new data.

Parameters

const TDesC8& aDes An 8 bit non-modifiable descriptor. The length of the data cannot be greater than the maximum length of the target descriptor otherwise the function raises a USER 23 panic.

void CopyCP(const TDesC8& aDes);

Description

Copies text from the specified descriptor and capitalises it before putting it into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

Capitalisation is implemented as appropriate to the current locale.

Parameters

const TDesC8& aDes An 8 bit non-modifiable descriptor. The length of the data cannot be greater than the maximum length of the target descriptor otherwise the function raises a USER 23 panic.

void CopyLC(const TDesC8& aDes);

Description

Copies text from the specified descriptor and converts it to lower case before putting it into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

Conversion to lower case is implemented as appropriate to the current locale.

Parameters

const TDesC8& aDes An 8 bit non modifiable descriptor. The length of the data cannot be greater than the maximum length of the target descriptor otherwise the function raises a USER 23 panic.

void CopyUC(const TDesC8& aDes);

Description

Copies text from the specified descriptor and converts it to upper case before putting it into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

Conversion to upper case is implemented as appropriate to the current locale.

Parameters

const TDesC8& aDes An 8 bit non modifiable descriptor. The length of the data cannot be greater than the maximum length of the target descriptor otherwise the function raises a USER 23 panic

void Repeat(const TUint8* aBuf,TInt aLength);
void Repeat(const TDesC8& aDes);

Description

Copies data with repetition into this descriptor replacing any existing data.

Copying proceeds until this descriptor is filled up to its current length. If it cannot contain a whole number of copies of the source data, then the last copy is truncated.

Parameters

const TDesC8& aDes An 8 bit non modifiable descriptor whose data is to be repeatedly copied. const TUint8* aBuf A pointer to data to be repeatedly copied. TInt aLength The length of data to be copied. This value must be non-negative, otherwise the function raises a USER 29 panic.

See also:

• Copying data with repetition

void Justify(const TDesC8& aDes,TInt aWidth,TAlign anAlignment,TChar aFill);

Description

Copies data into this descriptor and justifies it, replacing any existing data. The length of this descriptor is set to reflect the new data.

The target area is considered to be an area of specified width positioned at the beginning of this descriptor's data area. Source data is copied into, and aligned within, this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

The resulting length of this descriptor cannot be greater than its maximum length otherwise the function raises a USER 23 panic.

Parameters

const TDesC8& Des An 8 bit non modifiable descriptor containing the source data. The length of the data to be copied is the smaller of: the length of the source descriptor, and the width of the target area (only if this is not the explicit negative value KDefaultJustifyWidth). TInt aWidth The width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source. If it has any other negative value, then the function raises a USER 23 panic. TAlign anAlignment The alignment of the data within the target area. TChar aFill The fill character used to pad the target area.

See also:

• Copying data and justifying

void Num(TInt aVal);

Description

Converts the specified signed integer into a decimal character representation and copies the conversion into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

If the integer is negative, the character representation is prefixed by a minus sign.

Parameters

TInt aVal The signed integer value.

See also:

• Copying conversion from signed integer to decimal character

void Num(TUint aVal,TRadix aRadix=EDecimal);

Description

Converts the specified unsigned integer into a character representation based on the specified number system and copies the conversion into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

When a hexadecimal conversion is specified, hexadecimal characters are in lower case.

Parameters

TUint aVal The unsigned integer value TRadix aRadix The number system representation for the unsigned integer. If no explicit value is specified, then EDecimal is the default.

See also:

• Copying conversion from unsigned integer to specified number system

void NumUC(TUint aVal,TRadix aRadix=EDecimal);

Description

Converts the specified unsigned integer into a character representation based on the specified number system and copies the conversion into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

When a hexadecimal conversion is specified, hexadecimal characters are in upper case.

Parameters

TUint aVal The unsigned integer value. TRadix aRadix The number system representation for the unsigned integer. If no explicit value is specified, then EDecimal is the default.

See also:

• Copying conversion from unsigned integer to specified number system

void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);

Description

Converts the specified unsigned integer into a fixed width character representation based on the specified number system and copies the conversion into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

The function generates the exact number of specified characters, either padding to the left with character zeroes or discarding low order characters as necessary.

When a hexadecimal conversion is specified, hexadecimal characters are in lower case.

This function is equivalent to using Format() with parameters which specify:

• a fixed length target field

• padding with zero characters

for example "%08x". When this is the case, always use NumFixedWidth() in preference to Format() as it is more efficient.

Parameters

TUint aVal The unsigned integer value. TRadix aRadix The number system representation for the unsigned integer. TInt aWidth The number of characters: to be used to contain the conversion, to be copied into this descriptor.

void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);

Description

Converts the specified unsigned integer into a fixed width character representation based on the specified number system and copies the conversion into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

The function generates the exact number of specified characters, either padding to the left with character zeroes or discarding low order characters as necessary.

When a hexadecimal conversion is specified, hexadecimal characters are in upper case.

This function is equivalent to using Format() with parameters which specify:

• a fixed length target field

• padding with zero characters

for example "%08x".When this is the case, always use NumFixedWidthUC() in preference to Format() as it is more efficient.

Parameters

TUint aVal The unsigned integer value. TRadix aRadix The number system representation for the unsigned integer. TInt aWidth The number of characters: to be used to contain the conversion, to be copied into this descriptor.

void Num(TInt64 aVal);

Description

Converts the 64 bit signed integer into a decimal character representation and copies the conversion into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

If the integer is negative, the character representation is prefixed by a minus sign.

Parameters

TInt64 aVal The 64 bit signed integer value.

void Num(TInt64 aVal,TRadix aRadix);

Description

Converts the specified 64 bit unsigned integer into a character representation based on the specified number system and copies the conversion into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

When a hexadecimal conversion is specified, hexadecimal characters are in lower case.

Parameters

TInt64 aVal The 64 bit integer value. This is treated as an unsigned value. TRadix aRadix The number system representation for the 64 bit integer.

void NumUC(TInt64 aVal,TRadix aRadix=EDecimal);

Description

Converts the specified 64 bit unsigned integer into a character representation based on the specified number system and copies the conversion into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

When a hexadecimal conversion is specified, hexadecimal characters are in upper case.

Parameters

TInt64 aVal The 64 bit integer value. This is treated as an unsigned value. TRadix aRadix The number system representation for the 64 bit integer. If no explicit value is specified, then EDecimal is the default.

TInt Num(TReal aVal,const TRealFormat& aFormat);

Description

Converts the specified floating point number into a character representation and copies the conversion into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

The character representation of the real number is dictated by the specified format.

Parameters

TReal aVal The floating point number to be converted. const TRealFormat& aFormat The format of the conversion.

Return value

TInt If the conversion is successful, the length of this descriptor. If the conversion fails, a negative value indicating the cause of failure. In addition, extra information on the cause of the failure may be appended onto this descriptor. The possible values and their meaning are:KErrArgument - the supplied floating point number is not a valid number. The three characters NaN are appended to this descriptor.KErrOverflow - the number is too large to represent.& For positive overflow, the three characters Inf are appended to this descriptor. For negative overflow, the four characters -Inf are appended to this descriptor. KErrUnderflow - the number is too small to represent. For positive underflow, the three characters Inf are appended to this descriptor. For negative underflow, the four characters -Inf are appended to this descriptor. KErrGeneral - the conversion cannot be completed. There are a number of possible reasons for this but the two most common are: the maximum number of characters necessary to represent the number, as defined in the TRealFormat object, is greater than the maximum length of this descriptor. the character representation format (i.e. the format type), as defined in the TRealFormat object is not recognised.

Leave codes

The function leaves if the iType data member of the specified TRealFormat object has both an invalid character representation format (i.e. the format type) and invalid format flags.

void Format(TRefByValue<const TDesC8> aFmt,...);

Description

Formats and copies text into this descriptor, replacing any existing data. The length of this descriptor is set to reflect the new data.

(Note that formatting of single numerical values can be achieved more conveniently using the Num() and NumUC() member functions of this class.)

The function takes a format string and a variable number of arguments. The format string contains literal text, embedded with directives, for converting the trailing list of arguments into text.

The embedded directives are character sequences prefixed with the '%' character. The literal text is simply copied into this descriptor unaltered while the '%' directives are used to convert successive arguments from the trailing list.

The resulting stream of literal text and converted arguments is copied into this descriptor.

The syntax of the embedded directives follows one of four general patterns. If any directive has incorrect syntax, then the function raises a USER 24 panic.

If the resulting length of text in this descriptor exceeds its maximum length, then the function raises a USER 23 panic.

Parameters

TRefByValue<const TDesC8> aFmt The descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC8 type ... A variable number of arguments to be converted to text as dictated by the format string.

See also:

• String formatting syntax
• TDes8::Num()
• TDes8::NumUC()
• Using TDes8::Format()

void FormatList(const TDesC8& aFmt,VA_LIST aList);

Description

Formats and copies text into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

The behaviour of this function is the same as Format(). In practice, it is better and easier to use Format(), passing a variable number of arguments as required by the format string.

Parameters

const TDesC8& aFmt The descriptor containing the format string. VA_LIST aList A pointer to an argument list.

See also:

• TDes8::Format()
• VA_LIST
• Format string syntax

void Insert(TInt aPos,const TDesC8& aDes);

Description

Inserts data into this descriptor. The length of this descriptor is changed to reflect the extra data.

The resulting length of this descriptor cannot be greater than its maximum length otherwise the function raises a USER 23 panic.

Parameters

TInt aPos The position within the data where insertion is to start. This is an offset; a zero value refers to the leftmost data position. This value must not be negative and must not be greater than the length of this descriptor, otherwise the function raises a USER 22 panic. const TDesC8& aDes An 8 bit non modifiable descriptor whose data is to be inserted.

See also:

• Inserting data

void Replace(TInt aPos,TInt aLength,const TDesC8& aDes);

Description

Replaces data in this descriptor. The specified length can be different to the length of the replacement data. The length of this descriptor changes to reflect the change of data.

The resulting length of this descriptor cannot be greater than its maximum length otherwise the function raises a USER 23 panic.

Parameters

TInt aPos The position within the data where replacement is to start. This is an offset; a zero value refers to the leftmost data position. This value must not be negative and must not be greater than the length of this descriptor, otherwise the function raises a USER 22 panic. TInt aLength The length of data to be replaced. This length must not be negative and the sum of this value plus aPos must not be greater than the length of this descriptor, otherwise the function raises a USER 20 panic. const TDesC8& aDes The source 8 bit non modifiable descriptor whose data is to replace the target descriptor's data at aPos. The length of the source descriptor must not be negative and must not exceed the maximum length of the target descriptor, otherwise the function raises a USER 28 panic

See also:

• Replacing data

void Swap(TDes8& aDes);

Description

Swaps the data represented by this descriptor with the data represented by the specified descriptor. The lengths of both descriptors are also swapped to reflect the change.

Each descriptor must be capable of accommodating the contents of the other descriptor. If the maximum length of either descriptor is smaller than the length of the other descriptor, then the function raises a USER 23 panic.

Parameters

TDes8& aDes The 8 bit modifiable descriptor whose data is to be swapped with the data of this descriptor.

See also:

• Swapping data

void Delete(TInt aPos,TInt aLength);

Description

Deletes data from this descriptor. The length of this descriptor is changed to reflect the loss of data.

Parameters

TInt aPos The position within the data where deletion is to start. This is an offset; a zero value refers to the leftmost data position. This value must not be negative and must not be greater than the length of this descriptor, otherwise the function raises a USER 22 panic. TInt aLength The length of data to be deleted. If necessary, the function adjusts this value to ensure that no data beyond the end of the descriptor data area is deleted.

See also:

• Deleting data

void TrimLeft();

Description

Deletes leading space characters from the descriptor’s data. All space characters up to, but not including the first non-space character, are deleted.

The length of the descriptor is reduced to reflect the loss of the space characters.

See also:

• Deleting leading spaces

void TrimRight();

Description

Deletes trailing space characters from the descriptor's data. The process starts on the right hand side of the descriptor’s data and proceeds to the left. All space characters up to, but not including the first non-space character, are deleted.

The length of the descriptor is reduced to reflect the loss of the space characters.

See also:

• Deleting trailing spaces

void Trim();

Description

Deletes leading and trailing space characters from the descriptor's data.

The length of the descriptor is reduced to reflect the loss of the space characters.

See also:

• TDes8::TrimLeft()
• TDes8::TrimRight()
• Deleting leading and trailing spaces

void TrimAll();

Description

Deletes leading and trailing space characters from the descriptor's data and replaces each contiguous set of space characters within the data by one space character.

The length of the descriptor is reduced to reflect the loss of the space characters.

See also:

• TDes8::Trim()
• Deleting leading, trailing and internal spaces

void Append(TChar aChar);
void Append(const TDesC8& aDes);
void Append(const TDesC16& aDes);
void Append(const TUint8* aBuf,TInt aLength);

Description

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content; the new length cannot be greater than this descriptor's maximum length otherwise the function raises a USER 23 panic

Parameters

TChar aChar A single character to be appended. The length of the descriptor is incremented by one. The function assumes that the character is non-Unicode and that it can be represented by a single byte. const TDesC8& aDes An 8 bit non modifiable descriptor whose data is to be appended. const TDesC16& aDes A 16 bit non modifiable descriptor whose data is to be appended. Each double-byte value can only be appended as a single byte when the double-byte value is less than decimal 256. A double-byte value of 256 or greater cannot be appended and the corresponding single byte is set to a value of decimal 1. const TUint8* aBuf A pointer to data to be copied TInt aLength The length of data to be copied. This value must be non-negative otherwise the function raises a USER 29 panic.

void AppendFill(TChar aChar,TInt aLength);

Description

Appends and fills this descriptor with the specified character. The function assumes that the character is non-Unicode and that it can be represented by a single byte.

The length of this descriptor is incremented by the specified length; the new length cannot be greater than this descriptor's maximum length otherwise the function raises a USER 23 panic

Parameters

TChar aChar The fill character. TInt aLength The number of fill characters to be appended. This value must be non-negative otherwise the function raises a USER 23 panic.

void AppendJustify(const TDesC8& Des,TInt aWidth,TAlign anAlignment,TChar aFill);

Description

Appends data onto the end of this descriptor's data and justifies it.

The source of the appended data is an existing descriptor.

The target area is considered to be an area of specified width, immediately following this descriptor's existing data. Source data is copied into, and aligned within, this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

The resulting length of this descriptor cannot be greater than its maximum length otherwise the function raises a USER 23 panic.

Parameters

const TDesC8& Des An 8 bit non modifiable descriptor containing the source data. The length of the data to be copied is the smaller of: the length of the source descriptor, the width of the target area (only if this is not the explicit negative value KDefaultJustifyWidth). TInt aWidth The width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source. If it has any other negative value, then the function raises a USER 23 panic. TAlign anAlignment The alignment of the data within the target area. TChar aFill The fill character used to pad the target area.

See also:

• Append and justify

void AppendJustify(const TDesC8& Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

Description

Appends data onto the end of this descriptor's data and justifies it.

The source of the appended data is an existing descriptor.

The target area is considered to be an area of specified width, immediately following this descriptor's existing data. Source data is copied into, and aligned within, this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

The resulting length of this descriptor cannot be greater than its maximum length otherwise the function raises a USER 23 panic.

Parameters

const TDesC8& Des An 8 bit non modifiable descriptor containing the source data. TInt aLength The length of data to be copied from the source descriptor. If this is greater than the width of the target area, then the length of data copied is limited to the width. The length of data to be copied must not be greater than the length of the source descriptor. This condition is not automatically tested. TInt aWidth The width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source. If it has any other negative value, then the function raises a USER 23 panic. TAlign anAlignment The alignment of the data within the target area. TChar aFill The fill character used to pad the target area.

See also:

• Append and justify with explicit length

void AppendJustify(const TUint8* aString,TInt aWidth,TAlign anAlignment,TChar aFill);

Description

Appends a zero terminated string onto the end of this descriptor's data and justifies it. The zero terminator is not copied.

The target area is considered to be an area of specified width, immediately following this descriptor's existing data. Source data is copied into, and aligned within, this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

The resulting length of this descriptor cannot be greater than its maximum length otherwise the function raises a USER 23 panic.

Parameters

const TUint8* aString A pointer to a zero terminated string The length of the data to be copied is the smaller of: the length of the string (excluding the zero terminator), the width of the target area (only if this is not the explicit negative value KDefaultJustifyWidth). TInt aWidth The width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the zero terminated string (excluding the zero terminator). If it has any other negative value, then the function raises a USER 23 panic. TAlign anAlignment The alignment of the data within the target area. TChar aFill The fill character used to pad the target area.

void AppendJustify(const TUint8* aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

Description

Appends data onto the end of this descriptor's data and justifies it.

The source of the appended data is a memory location.

The target area is considered to be an area of specified width, immediately following this descriptor's existing data. Source data is copied into, and aligned within, this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

The resulting length of this descriptor cannot be greater than its maximum length otherwise the function raises a USER 23 panic.

Parameters

const TUint8* aString A pointer to a memory location. TInt aLength The length of data to be copied. If this is greater than the width of the target area, then the length of data copied is limited to the width. This value cannot be negative otherwise the function raises a USER 29 panic. TInt aWidth The width of the target area. If this has the specific negative valueKDefaultJustifyWidth, then the width is re-set to the length of the data source. If it has any other negative value, then the function raises a USER 23 panic. TAlign anAlignment The alignment of the data within the target area. TChar aFill The fill character used to pad the target area.

TDes8& operator+=(const TDesC8& aDes);

Description

Appends data onto the end of this descriptor's data and returns a reference to this descriptor.

The length of this descriptor is incremented to reflect the new content; the new length cannot be greater than this descriptor's maximum length otherwise the function raises a USER 23 panic

Parameters

const TDesC8& aDes An 8 bit non modifiable descriptor whose data is to be appended.

Return value

TDes8& A reference to this descriptor

See also:

• Append data operator

void AppendNum(TInt aVal);

Description

Converts the specified signed integer into a decimal character representation and appends the conversion onto the end of this descriptor's data. The length of this descriptor is incremented to reflect the new content

If the integer is negative, the character representation is prefixed by a minus sign.

Parameters

TInt aVal The signed integer value.

See also:

• Append conversion from signed integer to decimal character

void AppendNum(TUint aVal,TRadix aRadix=EDecimal);

Description

Converts the specified unsigned integer into a character representation based on the specified number system and appends the conversion onto the end of this descriptor's data. The length of this descriptor is incremented to reflect the new content

When a hexadecimal conversion is specified, hexadecimal characters are in lower case.

Parameters

TUint aVal The unsigned integer value TRadix aRadix The number system representation for the unsigned integer. If no explicit value is specified, then EDecimal is the default.

See also:

• Append conversion from unsigned integer to specified number system

void AppendNumUC(TUint aVal,TRadix aRadix=EDecimal);

Description

Converts the specified unsigned integer into a character representation based on the specified number system and appends the conversion onto the end of this descriptor's data. The length of this descriptor is incremented to reflect the new content

When a hexadecimal conversion is specified, hexadecimal characters are in upper case.

Parameters

TUint aVal The unsigned integer value. TRadix aRadix The number system representation for the unsigned integer. If no explicit value is specified, then EDecimal is the default.

See also:

• Append conversion from unsigned integer to specified number system

void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);

Description

Converts the specified unsigned integer into a fixed width character representation based on the specified number system and appends the conversion onto the end of this descriptor's data. The length of this descriptor is incremented to reflect the new content

The function generates the exact number of specified characters, either padding to the left with character zeroes or discarding low order characters as necessary.

When a hexadecimal conversion is specified, hexadecimal characters are in lower case.

Parameters

TUint aVal The unsigned integer value. TRadix aRadix The number system representation for the unsigned integer. TInt aWidth The number of characters: to be used to contain the conversion, to be appended to this descriptor.

See also:

• Append fixed width conversion

void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);

Description

Converts the specified unsigned integer into a fixed width character representation based on the specified number system and appends the conversion onto the end of this descriptor's data. The length of this descriptor is incremented to reflect the new content

The function generates the exact number of specified characters, either padding to the left with character zeroes or discarding low order characters as necessary.

When a hexadecimal conversion is specified, hexadecimal characters are in upper case.

Parameters

TUint aVal The unsigned integer value. TRadix aRadix The number system representation for the unsigned integer. TInt aWidth The number of characters: to be used to contain the conversion, to be appended to this descriptor.

See also:

• Append fixed width conversion

void AppendNum(TInt64 aVal);

Description

Converts the 64 bit signed integer into a decimal character representation and appends the conversion onto the end of this descriptor's data. The length of this descriptor is incremented to reflect the new content

If the integer is negative, the character representation is prefixed by a minus sign.

Parameters

TInt64 aVal The 64 bit signed integer value.

void AppendNum(TInt64 aVal,TRadix aRadix);

Description

Converts the specified 64 bit unsigned integer into a character representation based on the specified number system and appends the conversion onto the end of this descriptor's data. The length of this descriptor is incremented to reflect the new content

When a hexadecimal conversion is specified, hexadecimal characters are in lower case.

Parameters

TInt64 aVal The 64 bit integer value. This is treated as an unsigned value. TRadix aRadix The number system representation for the 64 bit integer.

void AppendNumUC(TInt64 aVal,TRadix aRadix=EDecimal);

Description

Converts the specified 64 bit unsigned integer into a character representation based on the specified number system and appends the conversion onto the end of this descriptor's data. The length of this descriptor is incremented to reflect the new content

When a hexadecimal conversion is specified, hexadecimal characters are in upper case.

Parameters

TInt64 aVal The 64 bit integer value. This is treated as an unsigned value. TRadix aRadix The number system representation for the 64 bit integer. If no explicit value is specified, then EDecimal is the default.

TInt AppendNum(TReal aVal,const TRealFormat& aFormat);

Description

Converts the specified floating point number into a character representation and appends the conversion onto the end of this descriptor's data. The length of this descriptor is incremented to reflect the new content.

The character representation of the real number is dictated by the specified format.

Parameters

TReal aVal The floating point number to be converted. const TRealFormat& aFormat The format of the conversion.

Return value

TInt If the conversion is successful, the length of this descriptor. If the conversion fails, a negative value indicating the cause of failure. In addition, extra information on the cause of the failure may be appended onto this descriptor. The possible values and their meaning are:KErrArgument - the supplied floating point number is not a valid number. The three characters NaN are appended to this descriptor.KErrOverflow - the number is too large to represent. For positive overflow, the three characters Inf are appended to this descriptor. For negative overflow, the four characters -Inf are appended to this descriptor.KErrUnderflow - the number is too small to represent. For positive underflow, the three characters Inf are appended to this descriptor. For negative underflow, the four characters -Inf are appended to this descriptor.KErrGeneral - the conversion cannot be completed. There are a number of possible reasons for this but the two most common are: the maximum number of characters necessary to represent the number, as defined in the TRealFormat object, is greater than the maximum length of this descriptor. the character representation format (i.e. the format type), as defined in the TRealFormat object is not recognised.

Leave codes

The function leaves if the iType data member of the specified TRealFormat object has both an invalid character representation format (i.e. the format type) and invalid format flags.

void AppendFormat(TRefByValue<const TDesC8> aFmt,TDes8Overflow* aOverflowHandler,...);
void AppendFormat(TRefByValue<const TDesC8> aFmt,...);

Description

Formats and appends text onto the end of this descriptor's data. The length of this descriptor is incremented to reflect the new content.

The function takes a format string and a variable number of arguments. The format string contains literal text, embedded with directives, for converting the trailing list of arguments into text.

The syntax of the format string can be found in the description of the Format() function.

Literal text is appended on a character by character basis. If it results in the length of this descriptor exceeding its maximum length, then the function:

• calls the Overflow() member function of the overflow handler, if an overflow handler is supplied.

• raises a USER 23 panic, if no overflow handler is supplied.

As much literal text as possible will have been copied into this descriptor and this descriptor will have reached its maximum length.

Text converted from a trailing argument is appended as a complete string. If an attempt to append this string fails because the resulting length of this descriptor would exceed its maximum length, then this function:

• calls the Overflow() member function of the overflow handler, if an overflow handler is supplied.

• raises a USER 23 panic, if no overflow handler is supplied.

None of the generated text is appended and length of this descriptor may be less than the maximum.

Parameters

TRefByValue<const TDesC8> aFmt The 8 bit non modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC8 type TDes8Overflow* aOverflowHandler If supplied, a pointer to the overflow handler. ... A variable number of arguments to be converted to text as dictated by the format string.

See also:

• Using TDes8Overflow
• TDes8::Format()

void AppendFormatList(const TDesC8& aFmt,VA_LIST aList,TDes8Overflow *aOverflowHandler=NULL);

Description

Formats and appends text onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

The behaviour of this function is the same as AppendFormat(). In practice, it is better and easier to use AppendFormat(), passing a variable number of arguments as required by the format string.

Parameters

const TDesC8& aFmt The descriptor containing the format string. VA_LIST aList A pointer to an argument list. TDes8Overflow* aOverflowHandler If supplied, a pointer to the overflow handler.

See also:

• TDes8::AppendFormat()
• VA_LIST
• Format string syntax

void ZeroTerminate();

Description

Appends a zero terminator onto the end of this descriptor's data.

The length of the descriptor is not changed. It must be strictly less than the descriptor's maximum length otherwise the function raises a USER 23 panic. This condition guarantees that there is sufficient space for the zero terminator.

const TUint8* PtrZ();

Description

Appends a zero terminator onto the end of this descriptor's data and returns a pointer to the data.

The length of the descriptor is not changed. It must be strictly less than the descriptor's maximum length otherwise the function raises a USER 23 panic. This condition guarantees that there is sufficient space for the zero terminator.

Return value

TUint8* A pointer to the descriptor data.

void Fill(TChar aChar);
void Fill(TChar aChar,TInt aLength);

Description

Fills the descriptor's data area with the specified character, replacing any existing data.

If an explicit length is not specified, then the descriptor is filled from the beginning up to its current length. The descriptor's length does not change. It is not filled to its maximum length.

If an explicit length is specified, then the descriptor is filled with this number of characters. The descriptor's length is changed to reflect this.

Parameters

TChar aChar The fill character. The function assumes that the character is non-Unicode and that it can be represented by a single byte. TInt aLength If specified, the new length of the descriptor and the number of fill characters to be copied into it. This value must not be negative and must not be greater than the maximum length of this descriptor, otherwise the function raises a USER 23 panic.

void FillZ();
void FillZ(TInt aLength);

Description

Fills the descriptor's data area with binary zeroes, i.e.0x00, replacing any existing data.

If an explicit length is not specified, then the descriptor is filled from the beginning up to its current length. The descriptor's length does not change. It is not filled to its maximum length.

If an explicit length is specified, then the descriptor is filled with this number of binary zeroes. The descriptor's length is changed to reflect this.

Parameters

TInt aLength If specified, the new length of the descriptor and the number of binary zeroes to be copied into it. This value must not be negative and must not be greater than the maximum length of this descriptor, otherwise the function raises a USER 23 panic.

void Capitalize();

Description

Capitalises the content of this descriptor.

Capitalisation is implemented as appropriate to the current locale.

void LowerCase();

Description

Converts the content of this descriptor to lower case.

Conversion is implemented as appropriate to the current locale.

void UpperCase();

Description

Converts the content of this descriptor to upper case.

Conversion is implemented as appropriate to the current locale.

void Collate();

Description

Performs collation on the content of this descriptor.

void Fold();

Description

Performs folding on the content of this descriptor.