Collapse all Symbian^3 Product Developer Library

TDes8 Class Reference

class TDes8 : public TDesC8

Abstract base class for 8-bit modifiable descriptors.

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 TDesC8.

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.

TDes TDesC8 TDesC16

Inherits from

TDes8
- TDesC8

Public Member Functions
IMPORT_C void	Append(TChar)
IMPORT_C void	Append(const TDesC8 &)
IMPORT_C void	Append(const TDesC16 &)
IMPORT_C void	Append(const TUint8 *, TInt)
IMPORT_C void	AppendFill(TChar, TInt)
IMPORT_C void	AppendFormat(TRefByValue< const TDesC8 >, TDes8Overflow *, ...)
IMPORT_C void	AppendFormat(TRefByValue< const TDesC8 >, ...)
IMPORT_C void	AppendFormatList(const TDesC8 &, VA_LIST, TDes8Overflow *)
IMPORT_C void	AppendJustify(const TDesC8 &, TInt, TAlign, TChar)
IMPORT_C void	AppendJustify(const TDesC8 &, TInt, TInt, TAlign, TChar)
IMPORT_C void	AppendJustify(const TUint8 *, TInt, TAlign, TChar)
IMPORT_C void	AppendJustify(const TUint8 *, TInt, TInt, TAlign, TChar)
IMPORT_C void	AppendNum(TInt64)
IMPORT_C void	AppendNum(TUint64, TRadix)
IMPORT_C TInt	AppendNum(TReal, const TRealFormat &)
IMPORT_C void	AppendNumFixedWidth(TUint, TRadix, TInt)
IMPORT_C void	AppendNumFixedWidthUC(TUint, TRadix, TInt)
IMPORT_C void	AppendNumUC(TUint64, TRadix)
IMPORT_C void	Capitalize()
IMPORT_C void	Collapse()
IMPORT_C void	Collate()
IMPORT_C void	Copy(const TDesC8 &)
IMPORT_C void	Copy(const TUint8 *, TInt)
IMPORT_C void	Copy(const TUint8 *)
IMPORT_C void	Copy(const TDesC16 &)
IMPORT_C void	CopyC(const TDesC8 &)
IMPORT_C void	CopyCP(const TDesC8 &)
IMPORT_C void	CopyF(const TDesC8 &)
IMPORT_C void	CopyLC(const TDesC8 &)
IMPORT_C void	CopyUC(const TDesC8 &)
IMPORT_C void	Delete(TInt, TInt)
IMPORT_C TPtr16	Expand()
IMPORT_C void	Fill(TChar)
IMPORT_C void	Fill(TChar, TInt)
IMPORT_C void	FillZ()
IMPORT_C void	FillZ(TInt)
IMPORT_C void	Fold()
IMPORT_C void	Format(TRefByValue< const TDesC8 >, ...)
IMPORT_C void	FormatList(const TDesC8 &, VA_LIST)
IMPORT_C void	Insert(TInt, const TDesC8 &)
IMPORT_C void	Justify(const TDesC8 &, TInt, TAlign, TChar)
IMPORT_C TPtr8	LeftTPtr(TInt)
IMPORT_C void	LowerCase()
TInt	MaxLength()
TInt	MaxSize()
IMPORT_C TPtr8	MidTPtr(TInt)
IMPORT_C TPtr8	MidTPtr(TInt, TInt)
IMPORT_C void	Num(TInt64)
IMPORT_C void	Num(TUint64, TRadix)
IMPORT_C TInt	Num(TReal, const TRealFormat &)
IMPORT_C void	NumFixedWidth(TUint, TRadix, TInt)
IMPORT_C void	NumFixedWidthUC(TUint, TRadix, TInt)
IMPORT_C void	NumUC(TUint64, TRadix)
IMPORT_C const TUint8 *	PtrZ()
IMPORT_C void	Repeat(const TUint8 *, TInt)
IMPORT_C void	Repeat(const TDesC8 &)
IMPORT_C void	Replace(TInt, TInt, const TDesC8 &)
IMPORT_C TPtr8	RightTPtr(TInt)
IMPORT_C void	SetLength(TInt)
IMPORT_C void	SetMax()
IMPORT_C void	Swap(TDes8 &)
IMPORT_C void	Trim()
IMPORT_C void	TrimAll()
IMPORT_C void	TrimLeft()
IMPORT_C void	TrimRight()
IMPORT_C void	UpperCase()
IMPORT_C void	Zero()
IMPORT_C void	ZeroTerminate()
TDes8 &	operator+=(const TDesC8 &)
TDes8 &	operator=(const TUint8 *)
TDes8 &	operator=(const TDesC8 &)
TDes8 &	operator=(const TDes8 &)
const TUint8 &	operator[](TInt)
TUint8 &	operator[](TInt)

Protected Member Functions
	TDes8(TInt, TInt, TInt)
	TDes8()
void	DoAppendNum(TUint64, TRadix, TUint, TInt)
void	DoPadAppendNum(TInt, TInt, const TUint8 *)
TUint8 *	WPtr()

Inherited Functions
	TDesC8::Alloc()const
	TDesC8::AllocL()const
	TDesC8::AllocLC()const
	TDesC8::AtC(TInt)const
	TDesC8::Compare(const TDesC8 &)const
	TDesC8::CompareC(const TDesC8 &)const
	TDesC8::CompareF(const TDesC8 &)const
	TDesC8::DoSetLength(TInt)
	TDesC8::Find(const TDesC8 &)const
	TDesC8::Find(const TUint8 *,TInt)const
	TDesC8::FindC(const TDesC8 &)const
	TDesC8::FindC(const TUint8 *,TInt)const
	TDesC8::FindF(const TDesC8 &)const
	TDesC8::FindF(const TUint8 *,TInt)const
	TDesC8::Left(TInt)const
	TDesC8::Length()const
	TDesC8::Locate(TChar)const
	TDesC8::LocateF(TChar)const
	TDesC8::LocateReverse(TChar)const
	TDesC8::LocateReverseF(TChar)const
	TDesC8::Match(const TDesC8 &)const
	TDesC8::MatchC(const TDesC8 &)const
	TDesC8::MatchF(const TDesC8 &)const
	TDesC8::Mid(TInt)const
	TDesC8::Mid(TInt,TInt)const
	TDesC8::Ptr()const
	TDesC8::Right(TInt)const
	TDesC8::Size()const
	TDesC8::TDesC8()
	TDesC8::TDesC8(TInt,TInt)
	TDesC8::Type()const
	TDesC8::operator!=(const TDesC8 &)const
	TDesC8::operator<(const TDesC8 &)const
	TDesC8::operator<=(const TDesC8 &)const
	TDesC8::operator==(const TDesC8 &)const
	TDesC8::operator>(const TDesC8 &)const
	TDesC8::operator>=(const TDesC8 &)const

Protected Attributes
	__DECLARE_TEST
TInt	iMaxLength

Constructor & Destructor Documentation

TDes8(TInt, TInt, TInt)

TDes8	(	TInt	aType,
		TInt	aLength,
		TInt	aMaxLength
	)	[protected, inline]

Parameters

TInt aType
TInt aLength
TInt aMaxLength

TDes8()

TDes8

(

)

[protected, inline]

Member Functions Documentation

Append(TChar)

IMPORT_C void

Append

(

TChar

aChar

)

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

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

panic: USER 23 if the resulting new length of this descriptor is greater than its maximum length.

Parameters

TChar aChar

The 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.

Append(const TDesC8 &)

IMPORT_C void

Append

(

const TDesC8 &

aDes

)

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

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

panic: USER 23 if the resulting new length of this descriptor is greater than its maximum length.

Parameters

const TDesC8 & aDes

An 8-bit non-modifiable descriptor whose data is to be appended.

Append(const TDesC16 &)

IMPORT_C void

Append

(

const TDesC16 &

aDes

)

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

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

panic: USER 23 if the resulting new length of this descriptor is greater than its maximum length.

Parameters

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.

Append(const TUint8 *, TInt)

IMPORT_C void	Append	(	const TUint8 *	aBuf,
			TInt	aLength
		)

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

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

panic: USER 23 if the resulting new length of this descriptor is greater than its maximum length.

panic: USER 29 if aLength is negative.

Parameters

const TUint8 * aBuf	A pointer to the data to be copied.
TInt aLength	The length of the data to be copied.

AppendFill(TChar, TInt)

IMPORT_C void	AppendFill	(	TChar	aChar,
			TInt	aLength
		)

Appends and fills this descriptor with the specified character.

The descriptor is appended with the specified number of characters. and its length is changed to reflect this.

panic: USER 23 if aLength is negative, or the resulting length of this descriptor is greater than its maximum length.

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	The number of fill characters to be appended.

AppendFormat(TRefByValue< const TDesC8 >, TDes8Overflow *, ...)

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

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 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. See 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:

1. calls the Overflow() member function of the overflow handler, if an overflow handler is supplied 2 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 the function:

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

2 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.

panic: USER 23 if the length of the descriptor exceeds its maximum length and no overflow handler has been supplied.

panic: USER 24 if the format string has incorrect syntax.

TDes8::Format() TDes8Overflow::Overflow()

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	A pointer to the overflow handler.
...

AppendFormat(TRefByValue< const TDesC8 >, ...)

IMPORT_C void	AppendFormat	(	TRefByValue< const TDesC8 >	aFmt,
			...
		)

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.

Literal text is appended on a character by character basis.

Text converted from a trailing argument is appended as a complete string.

panic: USER 23 if the resulting length of text in this descriptor exceeds the descriptor's maximum length.

panic: USER 24 if the format string has incorrect syntax.

TDes8::Format()

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.
...

AppendFormatList(const TDesC8 &, VA_LIST, TDes8Overflow *)

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

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(TRefByValue<const TDesC8> aFmt,TDes8Overflow *aOverflowHandler,...). In practice, it is better and easier to use AppendFormat(), passing a variable number of arguments as required by the format string.

TDes8::AppendFormat VA_LIST

Parameters

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

AppendJustify(const TDesC8 &, TInt, TAlign, TChar)

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

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.

panic: USER 23 if the resulting length of this descriptor is greater than its maximum length or aWidth has a negative value other than KDefaultJustifyWidth.

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.
TAlign anAlignment	The alignment of the data within the target area.
TChar aFill	The fill character used to pad the target area.

AppendJustify(const TDesC8 &, TInt, TInt, TAlign, TChar)

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

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

The source of the appended data is an existing descriptor.

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.

panic: USER 23 if the resulting length of this descriptor is greater than its maximum length or aWidth has a negative value other than KDefaultJustifyWidth.

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. Note that 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.
TAlign anAlignment	The alignment of the data within the target area.
TChar aFill	The fill character used to pad the target area.

AppendJustify(const TUint8 *, TInt, TAlign, TChar)

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

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.

panic: USER 23 if the resulting length of this descriptor is greater than its maximum length or aWidth has a negative value other than KDefaultJustifyWidth.

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), 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 zero terminated string (excluding the zero terminator).
TAlign anAlignment	The alignment of the data within the target area.
TChar aFill	The fill character used to pad the target area.

AppendJustify(const TUint8 *, TInt, TInt, TAlign, TChar)

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

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

The source of the appended data is a memory location.

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.

panic: USER 23 if the resulting length of this descriptor is greater than its maximum length or aWidth has a negative value other than KDefaultJustifyWidth.

panic: USER 29 if aLength is negative.

Parameters

const TUint8 * aString	A pointer to a source 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.
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.
TAlign anAlignment	The alignment of the data within the target area.
TChar aFill	The fill character used to pad the target area.

AppendNum(TInt64)

IMPORT_C void

AppendNum

(

TInt64

aVal

)

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.

AppendNum(TUint64, TRadix)

IMPORT_C void	AppendNum	(	TUint64	aVal,
			TRadix	aRadix
		)

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

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

AppendNum(TReal, const TRealFormat &)

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

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.

1.KErrArgument - the supplied floating point number is not a valid number. The three characters NaN are appended to this descriptor.

2.KErrOverflow - the number is too large to represent. 2.1 For positive overflow, the three characters Inf are appended to this descriptor. 2.2 For negative overflow, the four characters -Inf are appended to this descriptor.

3.KErrUnderflow - the number is too small to represent. 3.1 For positive underflow, the three characters Inf are appended to this descriptor. 3.2 For negative underflow, the four characters -Inf are appended to this descriptor.

4.KErrGeneral - the conversion cannot be completed. There are a number of possible reasons for this, but the two most common are: 4.1 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 4.2 the character representation format (i.e. the format type), as defined in the TRealFormat object is not recognised

Parameters

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

AppendNumFixedWidth(TUint, TRadix, TInt)

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

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, and to be appended to this descriptor.

AppendNumFixedWidthUC(TUint, TRadix, TInt)

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

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, and to be appended to this descriptor.

AppendNumUC(TUint64, TRadix)

IMPORT_C void	AppendNumUC	(	TUint64	aVal,
			TRadix	aRadix = EDecimal
		)

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

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

Capitalize()

IMPORT_C void

Capitalize

(

)

Capitalises the content of this descriptor.

Capitalisation is implemented as appropriate to the current locale.

Collapse()

IMPORT_C void

Collapse

(

)

Collapse all characters from 16 to 8 bits

The length of descriptor truncated by 2 (length /= 2).

panic: USER 188 if either the descriptor length or the maximum length is odd or data pointer is not aligned by 2-bytes boundary.

Collate()

IMPORT_C void

Collate

(

)

Performs collation on the content of this descriptor.

Copy(const TDesC8 &)

IMPORT_C void

Copy

(

const TDesC8 &

aDes

)

Copies data into this descriptor replacing any existing data.

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

panic: USER 23 if the length of aDes is greater than the maximum length of this (target) descriptor.

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.

Copy(const TUint8 *, TInt)

IMPORT_C void	Copy	(	const TUint8 *	aBuf,
			TInt	aLength
		)

Copies data into this descriptor replacing any existing data.

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

panic: USER 23 if aLength is greater than the maximum length of this (target) descriptor.

Parameters

const TUint8 * aBuf	The start address of data to be copied.
TInt aLength	The length of data to be copied.

Copy(const TUint8 *)

IMPORT_C void

Copy

(

const TUint8 *

aString

)

Copies data into this descriptor replacing any existing data.

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

panic: USER 23 if the length of aString, excluding the zero terminator, is greater than the maximum length of this (target) descriptor.

Parameters

const TUint8 * aString

A pointer to a zero-terminated string.

Copy(const TDesC16 &)

IMPORT_C void

Copy

(

const TDesC16 &

aDes

)

Copies data into this descriptor replacing any existing data.

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

panic: USER 23 if the length of the aDes is greater than the maximum length of this (target) descriptor.

Parameters

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.

CopyC(const TDesC8 &)

IMPORT_C void

CopyC

(

const TDesC8 &

aDes

)

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.

panic: USER 23 if the length of aDes is greater than the maximum length of this target descriptor.

Parameters

const TDesC8 & aDes

An 8 bit non-modifiable descriptor.

CopyCP(const TDesC8 &)

IMPORT_C void

CopyCP

(

const TDesC8 &

aDes

)

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.

panic: USER 23 if the length of aDes is greater than the maximum length of this target descriptor.

Parameters

const TDesC8 & aDes

An 8-bit non-modifiable descriptor.

CopyF(const TDesC8 &)

IMPORT_C void

CopyF

(

const TDesC8 &

aDes

)

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.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used when dealing with strings in natural language.

panic: USER 23 if the length of aDes is greater than the maximum length of this target descriptor.

Parameters

const TDesC8 & aDes

An 8-bit non-modifiable descriptor.

CopyLC(const TDesC8 &)

IMPORT_C void

CopyLC

(

const TDesC8 &

aDes

)

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.

panic: USER 23 if the length of aDes is greater than the maximum length of this target descriptor.

Parameters

const TDesC8 & aDes

An 8-bit non-modifiable descriptor.

CopyUC(const TDesC8 &)

IMPORT_C void

CopyUC

(

const TDesC8 &

aDes

)

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.

panic: USER 23 if the length of aDes is greater than the maximum length of this target descriptor.

Parameters

const TDesC8 & aDes

An 8-bit non-modifiable descriptor.

Delete(TInt, TInt)

IMPORT_C void	Delete	(	TInt	aPos,
			TInt	aLength
		)

Deletes data from this descriptor.

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

panic: USER 22 if aPos is negative or is greater than the length of this descriptor.

Parameters

TInt aPos	The position within the data where deletion is to start. This is an offset value; a zero value refers to the leftmost data position.
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.

DoAppendNum(TUint64, TRadix, TUint, TInt)

void	DoAppendNum	(	TUint64	aVal,
			TRadix	aRadix,
			TUint	aA,
			TInt	aW
		)	[protected]

Parameters

TUint64 aVal
TRadix aRadix
TUint aA
TInt aW

DoPadAppendNum(TInt, TInt, const TUint8 *)

void	DoPadAppendNum	(	TInt	aLength,
			TInt	aW,
			const TUint8 *	aBuf
		)	[protected]

Parameters

TInt aLength
TInt aW
const TUint8 * aBuf

Expand()

IMPORT_C TPtr16

Expand

(

)

Expand all characters from 8 to 16 bits

The length of descriptor increased by 2 (length *= 2).

panic: USER 187 if either the descriptor length or the maximum length is odd or data pointer is not aligned by 2-bytes boundary

Fill(TChar)

IMPORT_C void

Fill

(

TChar

aChar

)

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

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.

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.

Fill(TChar, TInt)

IMPORT_C void	Fill	(	TChar	aChar,
			TInt	aLength
		)

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

The descriptor is filled with the specified number of characters. and its length is changed to reflect this.

panic: USER 23 if aLength is negative or is greater than the maximum length of this descriptor.

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	The new length of the descriptor and the number of fill characters to be copied into it.

FillZ()

IMPORT_C void

FillZ

(

)

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

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.

FillZ(TInt)

IMPORT_C void

FillZ

(

TInt

aLength

)

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

The descriptor is filled with the specified number of binary zeroes. The descriptor's length is changed to reflect this.

panic: USER 23 if aLength is negative, or is greater than the maximum length of this descriptor.

Parameters

TInt aLength

The new length of the descriptor and the number of binary zeroes to be copied into it.

Fold()

IMPORT_C void

Fold

(

)

Performs folding on the content of this descriptor.

Format(TRefByValue< const TDesC8 >, ...)

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

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

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

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 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.

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

The full description of the syntax of a format string cannot be included here. For full details, navigate to the Symbian OS guide, and follow the hierarchy of links:

Symbian OS Guide
	Base
		Using  User Library (E32)
			Buffers and Strings
				Using Descriptors
					How to Use Descriptors
						Format string syntax

panic: USER 23 if the resulting length of text in this descriptor exceeds the descriptor's maximum length.

panic: USER 24 if the format string has incorrect syntax.

TDes8::Num() TDes8::NumUC()

Parameters

TRefByValue< const TDesC8 > aFmt	The descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC8 type.
...

FormatList(const TDesC8 &, VA_LIST)

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

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.

TDes8::Format() VA_LIST

Parameters

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

Insert(TInt, const TDesC8 &)

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

Inserts data into this descriptor.

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

panic: USER 22 if aPos is negative or is greater than the length of this descriptor.

panic: USER 23 if the resulting length of this descriptor is greater than its maximum length.

Parameters

TInt aPos	The position within the data where insertion is to start. This is an offset value; a zero value refers to the leftmost data position.
const TDesC8 & aDes	An 8 bit non modifiable descriptor whose data is to be inserted.

Justify(const TDesC8 &, TInt, TAlign, TChar)

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

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.

panic: USER 23 if the resulting length of this descriptor is greater than its maximum length or aWidth has a negative value other than KDefaultJustifyWidth.

Parameters

const TDesC8 & aDes	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.
TAlign anAlignment	The alignment of the data within the target area
TChar aFill	The fill character used to pad the target area.

LeftTPtr(TInt)

IMPORT_C TPtr8

LeftTPtr

(

TInt

aLength

)

const

Extracts the leftmost part of the data.

The function does not cut or remove any data but constructs a modifiable pointer descriptor to represent the leftmost part of the data.

panic: USER 22 if aLength is negative.

Parameters

TInt aLength

The length of the data to be extracted. If this value is greater than the length of the descriptor, the function extracts the whole of the descriptor.

LowerCase()

IMPORT_C void

LowerCase

(

)

Converts the content of this descriptor to lower case.

Conversion is implemented as appropriate to the current locale.

MaxLength()

TInt

MaxLength

(

)

const [inline]

Gets 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.

MaxSize()

TInt

MaxSize

(

)

const [inline]

Gets 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.

MidTPtr(TInt)

IMPORT_C TPtr8

MidTPtr

(

TInt

aPos

)

const

Extracts a portion of the data.

The function does not cut or remove any data but constructs a modifiable pointer descriptor to represent the defined portion.

The portion is identified by its starting position and by the length of the remainder of the data starting from the specified position.

panic: USER 22 if aPos is negative or aPos is greater than the length of the descriptor.

Parameters

TInt aPos

The starting position of the data to be extracted. This is an offset value; a zero value refers to the leftmost data position.

MidTPtr(TInt, TInt)

IMPORT_C TPtr8	MidTPtr	(	TInt	aPos,
			TInt	aLength
		)	const

Extracts a portion of the data.

The function does not cut or remove any data but constructs a modifiable pointer descriptor to represent the defined portion.

The portion is identified by its starting position and by its length.

panic: USER 22 if aPos is negative or aPos plus aLength is greater than the length of the descriptor.

Parameters

TInt aPos	The starting position of the data to be extracted. This is an offset value; a zero value refers to the leftmost data position.
TInt aLength	The length of data to be extracted.

Num(TInt64)

IMPORT_C void

Num

(

TInt64

aVal

)

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.

Num(TUint64, TRadix)

IMPORT_C void	Num	(	TUint64	aVal,
			TRadix	aRadix
		)

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

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

Num(TReal, const TRealFormat &)

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

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.

Note that 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.

1.KErrArgument - the supplied floating point number is not a valid number. The three characters NaN are appended to this descriptor.

TRealFormat::iType

Parameters

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

NumFixedWidth(TUint, TRadix, TInt)

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

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:

1. a fixed length target field

2. padding with zero characters, for example "%08x".

When this is the case, always use NumFixedWidth() in preference to Format() as it is more efficient.

TDes8::Format()

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.

NumFixedWidthUC(TUint, TRadix, TInt)

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

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:

1. a fixed length target field

2. padding with zero characters, for example "%08x".

When this is the case, always use NumFixedWidthUC() in preference to Format() as it is more efficient.

TDes8::Format()

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, and to be copied into this descriptor.

NumUC(TUint64, TRadix)

IMPORT_C void	NumUC	(	TUint64	aVal,
			TRadix	aRadix = EDecimal
		)

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

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

PtrZ()

IMPORT_C const TUint8 *

PtrZ

(

)

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, however, be strictly less than the descriptor's maximum length. This condition guarantees that there is sufficient space for the zero terminator.

panic: USER 23 if the descriptor's length is not strictly less than its maximum length.

Repeat(const TUint8 *, TInt)

IMPORT_C void	Repeat	(	const TUint8 *	aBuf,
			TInt	aLength
		)

Copies data with repetition into this descriptor, from a memory location specified by pointer, 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.

panic: USER 29 if aLength is negative.

Parameters

const TUint8 * aBuf	A pointer to data to be repeatedly copied.
TInt aLength	The length of data to be copied.

Repeat(const TDesC8 &)

IMPORT_C void

Repeat

(

const TDesC8 &

aDes

)

Copies data with repetition into this descriptor, from another 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.

Replace(TInt, TInt, const TDesC8 &)

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

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.

panic: USER 20 if aLength is negative or the sum of aLength and aPos is greater than the length of this descriptor.

panic: USER 22 if aPos is negative or is greater than the length of this descriptor.

panic: USER 23 if the resulting length of this descriptor is greater than its maximum length.

panic: USER 28 if the length of the source descriptor aDes is negative or is greater than the maximum length of this target descriptor,

Parameters

TInt aPos	The position within the data where replacement is to start. This is an offset value; a zero value refers to the leftmost data position.
TInt aLength	The length of data to be replaced.
const TDesC8 & aDes	The source 8-bit non-modifiable descriptor whose data is to replace the target descriptor's data at aPos.

RightTPtr(TInt)

IMPORT_C TPtr8

RightTPtr

(

TInt

aLength

)

const

Extracts the rightmost part of the data.

The function does not cut or remove any data but constructs a modifiable pointer descriptor to represent the rightmost part of the data.

panic: USER 22 if aLength is negative.

Parameters

TInt aLength

The length of data to be extracted. If this value is greater than the length of the descriptor, the function extracts the whole of the descriptor.

SetLength(TInt)

IMPORT_C void

SetLength

(

TInt

aLength

)

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

panic: USER 23 if alength is negative or is greater than the maximum length of this (target) descriptor.

Parameters

TInt aLength

The new length of the descriptor.

SetMax()

IMPORT_C void

SetMax

(

)

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

Swap(TDes8 &)

IMPORT_C void

Swap

(

TDes8 &

aDes

)

Swaps the data represented by this descriptor with the data represented by the specified descriptor.

The lengths of both descriptors are swapped to reflect the change.

Note that each descriptor must be capable of accommodating the contents of the other descriptor.

panic: USER 23 if the maximum length of either descriptor is smaller than the length of the other descriptor.

Parameters

TDes8 & aDes

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

Trim()

IMPORT_C void

Trim

(

)

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

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

TDes8::TrimLeft() TDes8::TrimRight()

TrimAll()

IMPORT_C void

TrimAll

(

)

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

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

TDes8::Trim()

TrimLeft()

IMPORT_C void

TrimLeft

(

)

Deletes leading whitespace characters from the descriptor's data.

All whitespace characters up to, but not including the first non-whitespace character, are deleted.

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

TrimRight()

IMPORT_C void

TrimRight

(

)

Deletes trailing whitespace 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 whitespace characters up to, but not including the first non-whitespace character, are deleted.

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

UpperCase()

IMPORT_C void

UpperCase

(

)

Converts the content of this descriptor to upper case.

Conversion is implemented as appropriate to the current locale.

WPtr()

TUint8 *

WPtr

(

)

const [protected, inline]

Zero()

IMPORT_C void

Zero

(

)

Sets the length of the data to zero.

ZeroTerminate()

IMPORT_C void

ZeroTerminate

(

)

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

The length of the descriptor is not changed. It must, however, be strictly less than the descriptor's maximum length. This condition guarantees that there is sufficient space for the zero terminator.

panic: USER 23 if the descriptor's length is not strictly less than its maximum length.

operator+=(const TDesC8 &)

TDes8 &

operator+=

(

const TDesC8 &

aDes

)

[inline]

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.

panic: USER 23, if the resulting length of this descriptor is greater than its maximum length.

Parameters

const TDesC8 & aDes

An-8 bit non-modifiable descriptor whose data is to be appended.

operator=(const TUint8 *)

TDes8 &

operator=

(

const TUint8 *

aString

)

[inline]

Copies data into this descriptor replacing any existing data.

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

panic: USER 23, if the length of the string, excluding the zero terminator, is greater than the maximum length of this (target) descriptor.

Parameters

const TUint8 * aString

A pointer to a zero-terminated string.

operator=(const TDesC8 &)

TDes8 &

operator=

(

const TDesC8 &

aDes

)

[inline]

Copies data into this descriptor replacing any existing data.

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

panic: USER 23, if the length of the descriptor aDes is greater than the maximum length of this (target) descriptor.

Parameters

const TDesC8 & aDes

An 8-bit non-modifiable descriptor.

operator=(const TDes8 &)

TDes8 &

operator=

(

const TDes8 &

aDes

)

[inline]

Copies data into this descriptor replacing any existing data.

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

panic: USER 23, if the length of the descriptor aDes is greater than the maximum length of this (target) descriptor.

Parameters

const TDes8 & aDes

An 8-bit modifiable descriptor.

operator[](TInt)

const TUint8 &

operator[]

(

TInt

anIndex

)

const [inline]

Gets a const reference to a single data item within this descriptor's data.

panic: USER 21, if anIndex is negative or is greater than or equal to the current length of this descriptor.

Parameters

TInt anIndex

The position of the data item within this descriptor's data. This is an offset value; a zero value refers to the leftmost data position.

operator[](TInt)

TUint8 &

operator[]

(

TInt

anIndex

)

[inline]

Gets a non-const reference to a single data item within this descriptor's data.

panic: USER 21, if anIndex is negative or is greater than or equal to the current length of this descriptor.

Parameters

TInt anIndex

The position of the data item within this descriptor's data. This is an offset value; a zero value refers to the leftmost data position.

Member Data Documentation

__DECLARE_TEST

[protected]

TInt iMaxLength

TInt

iMaxLength

[protected]