TDes16 Class Reference

#include <e32des16.h>

class TDes16 : public TDesC16

Inherits from

Protected Attributes
__DECLARE_TEST
TInt iMaxLength
Public Member Functions
IMPORT_C voidAppend(TChar)
IMPORT_C voidAppend(const TDesC16 &)
IMPORT_C voidAppend(const TUint16 *, TInt)
IMPORT_C voidAppend2(TChar)
IMPORT_C voidAppendFill(TChar, TInt)
IMPORT_C voidAppendFill2(TChar, TInt)
IMPORT_C voidAppendFormat(TRefByValue< const TDesC16 >, TDes16Overflow *, ...)
IMPORT_C voidAppendFormat(TRefByValue< const TDesC16 >, ...)
IMPORT_C voidAppendFormatList(const TDesC16 &, VA_LIST, TDes16Overflow *)
IMPORT_C voidAppendJustify(const TDesC16 &, TInt, TAlign, TChar)
IMPORT_C voidAppendJustify(const TDesC16 &, TInt, TInt, TAlign, TChar)
IMPORT_C voidAppendJustify(const TUint16 *, TInt, TAlign, TChar)
IMPORT_C voidAppendJustify(const TUint16 *, TInt, TInt, TAlign, TChar)
IMPORT_C voidAppendJustify2(const TDesC16 &, TInt, TAlign, TChar)
IMPORT_C voidAppendJustify2(const TDesC16 &, TInt, TInt, TAlign, TChar)
IMPORT_C voidAppendJustify2(const TUint16 *, TInt, TAlign, TChar)
IMPORT_C voidAppendJustify2(const TUint16 *, TInt, TInt, TAlign, TChar)
IMPORT_C TIntAppendNum(TReal, const TRealFormat &)
IMPORT_C voidAppendNum(TInt64)
IMPORT_C voidAppendNum(TUint64, TRadix)
IMPORT_C voidAppendNumFixedWidth(TUint, TRadix, TInt)
IMPORT_C voidAppendNumFixedWidthUC(TUint, TRadix, TInt)
IMPORT_C voidAppendNumUC(TUint64, TRadix)
IMPORT_C voidCapitalize()
IMPORT_C voidCapitalize2()
IMPORT_C TPtr8Collapse()
IMPORT_C voidCollate()
IMPORT_C voidCollate2()
IMPORT_C voidCopy(const TDesC8 &)
IMPORT_C voidCopy(const TDesC16 &)
IMPORT_C voidCopy(const TUint16 *, TInt)
IMPORT_C voidCopy(const TUint16 *)
IMPORT_C voidCopyC(const TDesC16 &)
IMPORT_C voidCopyC2(const TDesC16 &)
IMPORT_C voidCopyCP(const TDesC16 &)
IMPORT_C voidCopyCP2(const TDesC16 &)
IMPORT_C voidCopyF(const TDesC16 &)
IMPORT_C voidCopyF2(const TDesC16 &)
IMPORT_C voidCopyLC(const TDesC16 &)
IMPORT_C voidCopyLC2(const TDesC16 &)
IMPORT_C voidCopyUC(const TDesC16 &)
IMPORT_C voidCopyUC2(const TDesC16 &)
IMPORT_C voidDelete(TInt, TInt)
IMPORT_C voidFill(TChar)
IMPORT_C voidFill(TChar, TInt)
IMPORT_C voidFill2(TChar)
IMPORT_C voidFill2(TChar, TInt)
IMPORT_C voidFillZ()
IMPORT_C voidFillZ(TInt)
IMPORT_C voidFold()
IMPORT_C voidFold2()
IMPORT_C voidFormat(TRefByValue< const TDesC16 >, ...)
IMPORT_C voidFormatList(const TDesC16 &, VA_LIST)
IMPORT_C voidInsert(TInt, const TDesC16 &)
IMPORT_C voidJustify(const TDesC16 &, TInt, TAlign, TChar)
IMPORT_C voidJustify2(const TDesC16 &, TInt, TAlign, TChar)
IMPORT_C TPtr16LeftTPtr(TInt)
IMPORT_C voidLowerCase()
IMPORT_C voidLowerCase2()
TInt MaxLength()
TInt MaxSize()
IMPORT_C TPtr16MidTPtr(TInt)
IMPORT_C TPtr16MidTPtr(TInt, TInt)
IMPORT_C TIntNum(TReal, const TRealFormat &)
IMPORT_C voidNum(TInt64)
IMPORT_C voidNum(TUint64, TRadix)
IMPORT_C voidNumFixedWidth(TUint, TRadix, TInt)
IMPORT_C voidNumFixedWidthUC(TUint, TRadix, TInt)
IMPORT_C voidNumUC(TUint64, TRadix)
IMPORT_C const TUint16 *PtrZ()
IMPORT_C voidRepeat(const TDesC16 &)
IMPORT_C voidRepeat(const TUint16 *, TInt)
IMPORT_C voidReplace(TInt, TInt, const TDesC16 &)
IMPORT_C TPtr16RightTPtr(TInt)
IMPORT_C voidSetLength(TInt)
IMPORT_C voidSetMax()
IMPORT_C voidSwap(TDes16 &)
IMPORT_C voidTrim()
IMPORT_C voidTrimAll()
IMPORT_C voidTrimLeft()
IMPORT_C voidTrimRight()
IMPORT_C voidUpperCase()
IMPORT_C voidUpperCase2()
IMPORT_C voidZero()
IMPORT_C voidZeroTerminate()
TDes16 &operator+=(const TDesC16 &)
TDes16 &operator=(const TUint16 *)
TDes16 &operator=(const TDesC16 &)
TDes16 &operator=(const TDes16 &)
const TUint16 &operator[](TInt)
TUint16 &operator[](TInt)
Protected Member Functions
TDes16()
TDes16(TInt, TInt, TInt)
voidDoAppendNum(TUint64, TRadix, TUint, TInt)
voidDoPadAppendNum(TInt, TInt, const TUint8 *)
TUint16 *WPtr()
Inherited Enumerations
TDesC16:TPrefix
Inherited Functions
TDesC16::Alloc()const
TDesC16::AllocL()const
TDesC16::AllocLC()const
TDesC16::AtC(TInt)const
TDesC16::Compare(const TDesC16 &)const
TDesC16::CompareC(const TDesC16 &)const
TDesC16::CompareC(const TDesC16 &,TInt,const TCollationMethod *)const
TDesC16::CompareF(const TDesC16 &)const
TDesC16::DoSetLength(TInt)
TDesC16::Find(const TDesC16 &)const
TDesC16::Find(const TUint16 *,TInt)const
TDesC16::FindC(const TDesC16 &)const
TDesC16::FindC(const TDesC16 &,TInt &,const TCollationMethod &,TInt)const
TDesC16::FindC(const TUint16 *,TInt)const
TDesC16::FindC(const TUint16 *,TInt,TInt)const
TDesC16::FindCorruptSurrogate()const
TDesC16::FindF(const TDesC16 &)const
TDesC16::FindF(const TUint16 *,TInt)const
TDesC16::GetCollationKeysL(TInt,const TCollationMethod *)const
TDesC16::GetFoldedDecomposedFormL()const
TDesC16::GetNormalizedDecomposedFormL()const
TDesC16::HasPrefixC(const TDesC16 &,TInt,const TCollationMethod *)const
TDesC16::Left(TInt)const
TDesC16::Length()const
TDesC16::Locate(TChar)const
TDesC16::Locate2(TChar)const
TDesC16::LocateF(TChar)const
TDesC16::LocateF2(TChar)const
TDesC16::LocateReverse(TChar)const
TDesC16::LocateReverse2(TChar)const
TDesC16::LocateReverseF(TChar)const
TDesC16::LocateReverseF2(TChar)const
TDesC16::Match(const TDesC16 &)const
TDesC16::Match2(const TDesC16 &)const
TDesC16::MatchC(const TDesC16 &)const
TDesC16::MatchC(const TDesC16 &,TInt,TInt,TInt,TInt,const TCollationMethod *)const
TDesC16::MatchC(const TDesC16 &,const TCollationMethod *,TInt,TInt,TInt,TInt)const
TDesC16::MatchF(const TDesC16 &)const
TDesC16::Mid(TInt)const
TDesC16::Mid(TInt,TInt)const
TDesC16::Ptr()const
TDesC16::Right(TInt)const
TDesC16::Size()const
TDesC16::TDesC16()
TDesC16::TDesC16(TInt,TInt)
TDesC16::Type()const
TDesC16::operator!=(const TDesC16 &)const
TDesC16::operator<(const TDesC16 &)const
TDesC16::operator<=(const TDesC16 &)const
TDesC16::operator==(const TDesC16 &)const
TDesC16::operator>(const TDesC16 &)const
TDesC16::operator>=(const TDesC16 &)const

Detailed Description

Abstract base class for 16-bit modifiable descriptors.

The class encapsulates the data member containing the maximum length of data represented by a 16-bit descriptor. It also provides member functions through which the data can be modified.

The class adds to the behaviour provided by TDesC16.

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.

See also: TDes TDesC8 TDesC16

Member Attribute Documentation

__DECLARE_TEST

__DECLARE_TEST[protected]

iMaxLength

TInt iMaxLength[protected]

Constructor & Destructor Documentation

TDes16 ( )

TDes16()[protected, inline]

TDes16 ( TInt, TInt, TInt )

TDes16(TIntaType,
TIntaLength,
TIntaMaxLength
)[protected, inline]

Member Function Documentation

Append ( TChar )

IMPORT_C voidAppend(TCharaChar)

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

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

USER 11 if the resulting new length of this descriptor is greater than its maximum length.

Parameters
aCharA single character to be appended. The length of the descriptor is incremented by one.

Append ( const TDesC16 & )

IMPORT_C voidAppend(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.

USER 11 if the resulting new length of this descriptor is greater than its maximum length.

Parameters
aDesA 16-bit non modifiable descriptor whose data is to be appended.

Append ( const TUint16 *, TInt )

IMPORT_C voidAppend(const TUint16 *aBuf,
TIntaLength
)

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

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

USER 11 if the resulting new length of this descriptor is greater than its maximum length. USER 17 if aLength is negative.

Parameters
aBufA pointer to the data to be copied.
aLengthThe length of data to be copied.

Append2 ( TChar )

IMPORT_C voidAppend2(TCharaChar)

The surrogate aware version of Append().

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

The length of this descriptor is incremented to reflect the new content. The length will be increased by 1 if aChar is inside BMP or 2 if aChar is outside BMP.

USER 11 if the resulting new length of this descriptor is greater than its maximum length.

USER 217 if corrupt surrogate found in aChar. This functions will not validate already existing surrogate in the descriptor.

See also: TDes16::Append()

Parameters
aCharA single character to be appended. Can be inside or outside BMP.

AppendFill ( TChar, TInt )

IMPORT_C voidAppendFill(TCharaChar,
TIntaLength
)

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.

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

Parameters
aCharThe fill character.
aLengthThe number of fill characters to be appended.

AppendFill2 ( TChar, TInt )

IMPORT_C voidAppendFill2(TCharaChar,
TIntaLength
)

The surrogate aware version of AppendFill().

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.

If aChar is supplementary character, and available space to fill is odd in 16-bit unit, then the last 16-bit unit will be filled with high surrogate.

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

USER 217 if corrupt surrogate found in aChar. These functions will not validate already existing surrogate in the descriptor.

See also: TDes16::AppendFill()

Parameters
aCharThe fill character. Can be inside or outside BMP.
aLengthThe length of additional space to append into.

AppendFormat ( TRefByValue< const TDesC16 >, TDes16Overflow *, ... )

IMPORT_C voidAppendFormat(TRefByValue< const TDesC16 >aFmt,
TDes16Overflow *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 11 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 11 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.

USER 11 if the length of the descriptor exceeds its maximum length and no overflow handler has been supplied. USER 12 if the format string has incorrect syntax.

See also: TDes16::Format() TDes16Overflow::Overflow()

Parameters
aFmtThe 16-bit non-modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC16 type.
aOverflowHandlerA pointer to the overflow handler.

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

IMPORT_C voidAppendFormat(TRefByValue< const TDesC16 >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.

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.

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

USER 11 if the resulting length of text in this descriptor exceeds the descriptor's maximum length. USER 12 if the format string has incorrect syntax.

See also: TDes16::Format()

Parameters
aFmtThe 16-bit non-modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC16 type.

AppendFormatList ( const TDesC16 &, VA_LIST, TDes16Overflow * )

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

See also: TDes16::AppendFormat VA_LIST

Parameters
aFmtThe descriptor containing the format string.
aListA pointer to an argument list.
aOverflowHandlerIf supplied, a pointer to the overflow handler.

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

IMPORT_C voidAppendJustify(const TDesC16 &Des,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

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.

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

Parameters
DesA 16-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).
aWidthThe 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.
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area.

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

IMPORT_C voidAppendJustify(const TDesC16 &Des,
TIntaLength,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

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.

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

Parameters
DesAn 8-bit non-modifiable descriptor containing the source data.
aLengthThe 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.
aWidthThe 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.
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area.

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

IMPORT_C voidAppendJustify(const TUint16 *aString,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

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.

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

Parameters
aStringA 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).
aWidthThe 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).
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area.

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

IMPORT_C voidAppendJustify(const TUint16 *aString,
TIntaLength,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

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.

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

USER 17 if aLength is negative.

Parameters
aStringA pointer to a source memory location.
aLengthThe 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.
aWidthThe 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.
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area.

AppendJustify2 ( const TDesC16 &, TInt, TAlign, TChar )

IMPORT_C voidAppendJustify2(const TDesC16 &aDes,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

The surrogate aware version of AppendJustify.

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.

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

USER 217 if corrupt surrogate found in the parameters or in the descriptor.

See also: TDes16::AppendJustify()

Parameters
aDesA 16-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).
aWidthThe 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.
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area. Can be inside or outside BMP.

AppendJustify2 ( const TDesC16 &, TInt, TInt, TAlign, TChar )

IMPORT_C voidAppendJustify2(const TDesC16 &aDes,
TIntaLength,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

The surrogate aware version of AppendJustify.

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.

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

USER 217 if corrupt surrogate found in the parameters or in the descriptor.

See also: TDes16::AppendJustify()

Parameters
aDesAn 8-bit non-modifiable descriptor containing the source data.
aLengthThe 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.
aWidthThe 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.
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area. Can be inside or outside BMP.

AppendJustify2 ( const TUint16 *, TInt, TAlign, TChar )

IMPORT_C voidAppendJustify2(const TUint16 *aString,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

The surrogate aware version of AppendJustify.

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.

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

USER 217 if corrupt surrogate found in the parameters or in the descriptor.

See also: TDes16::AppendJustify()

Parameters
aStringA 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).
aWidthThe 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).
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area. Can be inside or outside BMP.

AppendJustify2 ( const TUint16 *, TInt, TInt, TAlign, TChar )

IMPORT_C voidAppendJustify2(const TUint16 *aString,
TIntaLength,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

The surrogate aware version of AppendJustify.

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.

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

USER 17 if aLength is negative.

USER 217 if corrupt surrogate found in the parameters or in the descriptor.

See also: TDes16::AppendJustify()

Parameters
aStringA pointer to a source memory location.
aLengthThe 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.
aWidthThe 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.
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area. Can be inside or outside BMP.

AppendNum ( TReal, const TRealFormat & )

IMPORT_C TIntAppendNum(TRealaVal,
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
aValThe floating point number to be converted.
aFormatThe format of the conversion.
Return Value
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:

AppendNum ( TInt64 )

IMPORT_C voidAppendNum(TInt64aVal)

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
aValThe 64-bit signed integer value.

AppendNum ( TUint64, TRadix )

IMPORT_C voidAppendNum(TUint64aVal,
TRadixaRadix
)

Converts the specified 64 bit 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
aValThe 64 bit integer value. This is always treated as an unsigned value.
aRadixThe number system representation for the 64 bit integer.

AppendNumFixedWidth ( TUint, TRadix, TInt )

IMPORT_C voidAppendNumFixedWidth(TUintaVal,
TRadixaRadix,
TIntaWidth
)

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
aValThe unsigned integer value.
aRadixThe number system representation for the unsigned integer.
aWidthThe number of characters to be used to contain the conversion, and to be appended to this descriptor.

AppendNumFixedWidthUC ( TUint, TRadix, TInt )

IMPORT_C voidAppendNumFixedWidthUC(TUintaVal,
TRadixaRadix,
TIntaWidth
)

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
aValThe unsigned integer value.
aRadixThe number system representation for the unsigned integer.
aWidthThe number of characters: to be used to contain the conversion, to be appended to this descriptor.

AppendNumUC ( TUint64, TRadix )

IMPORT_C voidAppendNumUC(TUint64aVal,
TRadixaRadix = EDecimal
)

Converts the specified 64 bit 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
aValThe 64 bit integer value. This is always treated as an unsigned value.
aRadixThe number system representation for the 64 bit integer. If no explicit value is specified, then EDecimal is the default.

Capitalize ( )

IMPORT_C voidCapitalize()

Capitalises the content of this descriptor.

Capitalisation is implemented as appropriate to the current locale.

Capitalize2 ( )

IMPORT_C voidCapitalize2()

The surrogate aware version of Capitalize().

Capitalises the content of this descriptor.

Capitalisation is implemented as appropriate to the current locale.

USER 217 if corrupt surrogate found in the descriptor.

See also: TDes16::Capitalize()

Collapse ( )

IMPORT_C TPtr8Collapse()

Collapse all characters from 16 to 8 bits

Return Value
8-bit pointer descriptor to transformed text

Collate ( )

IMPORT_C voidCollate()

Performs collation on the content of this descriptor.

Collate2 ( )

IMPORT_C voidCollate2()

The surrogate aware version of Collate().

Performs collation on the content of this descriptor.

USER 217 if corrupt surrogate found in the descriptor.

See also: TDes16::Collate()

Copy ( const TDesC8 & )

IMPORT_C voidCopy(const TDesC8 &aDes)

Copies data into this descriptor replacing any existing data.

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

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

Parameters
aDesAn 8 bit non modifiable descriptor.

Copy ( const TDesC16 & )

IMPORT_C voidCopy(const TDesC16 &aDes)

Copies data into this descriptor replacing any existing data.

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

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

Parameters
aDesA 16-bit non modifiable descriptor.

Copy ( const TUint16 *, TInt )

IMPORT_C voidCopy(const TUint16 *aBuf,
TIntaLength
)

Copies data into this descriptor replacing any existing data.

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

USER 11 if aLength is negative or is greater than maximum length of this (target) descriptor.

Parameters
aBufThe start address of data to be copied.
aLengthThe length of data to be copied.

Copy ( const TUint16 * )

IMPORT_C voidCopy(const TUint16 *aString)

Copies data into this descriptor replacing any existing data.

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

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

Parameters
aStringA pointer to a zero-terminated string.

CopyC ( const TDesC16 & )

IMPORT_C voidCopyC(const TDesC16 &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.

USER 11 if the length of aDes is greater than the maximum length of this target descriptor.

Parameters
aDesA 16-bit non-modifiable descriptor.

CopyC2 ( const TDesC16 & )

IMPORT_C voidCopyC2(const TDesC16 &aDes)

The surrogate aware version of CopyC().

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.

USER 11 if the length of aDes is greater than the maximum length of this target descriptor.

USER 217 if corrupt surrogate found in aDes or in the descriptor.

See also: TDes16::CopyC()

Parameters
aDesA 16-bit non-modifiable descriptor.

CopyCP ( const TDesC16 & )

IMPORT_C voidCopyCP(const TDesC16 &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.

USER 11 if the length of aDes is greater than the maximum length of this target descriptor.

Parameters
aDesA 16-bit non-modifiable descriptor.

CopyCP2 ( const TDesC16 & )

IMPORT_C voidCopyCP2(const TDesC16 &aDes)

The surrogate aware version of CopyCP().

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.

USER 11 if the length of aDes is greater than the maximum length of this target descriptor.

USER 217 if corrupt surrogate found in aDes or in the descriptor.

See also: TDes16::CopyCP()

Parameters
aDesA 16-bit non-modifiable descriptor.

CopyF ( const TDesC16 & )

IMPORT_C voidCopyF(const TDesC16 &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.

USER 11 if the length of aDes is greater than the maximum length of this target descriptor.

Parameters
aDesA 16-bit non-modifiable descriptor.

CopyF2 ( const TDesC16 & )

IMPORT_C voidCopyF2(const TDesC16 &aDes)

The surrogate aware version of CopyF().

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.

USER 11 if the length of aDes is greater than the maximum length of this target descriptor.

USER 217 if corrupt surrogate found in aDes or in the descriptor.

See also: TDes16::CopyF()

Parameters
aDesA 16-bit non-modifiable descriptor.

CopyLC ( const TDesC16 & )

IMPORT_C voidCopyLC(const TDesC16 &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.

USER 11 if the length of aDes is greater than the maximum length of this target descriptor.

Parameters
aDesA 16-bit non modifiable descriptor.

CopyLC2 ( const TDesC16 & )

IMPORT_C voidCopyLC2(const TDesC16 &aDes)

The surrogate aware version of CopyLC().

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.

USER 11 if the length of aDes is greater than the maximum length of this target descriptor.

USER 217 if corrupt surrogate found in aDes or in the descriptor.

See also: TDes16::CopyLC()

Parameters
aDesA 16-bit non modifiable descriptor.

CopyUC ( const TDesC16 & )

IMPORT_C voidCopyUC(const TDesC16 &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.

USER 11 if the length of aDes is greater than the maximum length of this target descriptor.

Parameters
aDesA 16-bit non modifiable descriptor.

CopyUC2 ( const TDesC16 & )

IMPORT_C voidCopyUC2(const TDesC16 &aDes)

The surrogate aware version of CopyUC().

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.

USER 11 if the length of aDes is greater than the maximum length of this target descriptor.

USER 217 if corrupt surrogate found in aDes or in the descriptor.

See also: TDes16::CopyUC()

Parameters
aDesA 16-bit non modifiable descriptor.

Delete ( TInt, TInt )

IMPORT_C voidDelete(TIntaPos,
TIntaLength
)

Deletes data from this descriptor.

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

USER 10 if aPos is negative or is greater than the length of this descriptor.

Parameters
aPosThe position within the data where deletion is to start. This is an offset value; a zero value refers to the leftmost data position.
aLengthThe 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 )

voidDoAppendNum(TUint64aVal,
TRadixaRadix,
TUintaA,
TIntaW
)[protected]

DoPadAppendNum ( TInt, TInt, const TUint8 * )

voidDoPadAppendNum(TIntaLength,
TIntaW,
const TUint8 *aBuf
)[protected]

Fill ( TChar )

IMPORT_C voidFill(TCharaChar)

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
aCharThe fill character.

Fill ( TChar, TInt )

IMPORT_C voidFill(TCharaChar,
TIntaLength
)

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.

USER 11 if aLength is negative or is greater than the maximum length of this descriptor.

Parameters
aCharThe fill character.
aLengthThe new length of the descriptor and the number of fill characters to be copied into it.

Fill2 ( TChar )

IMPORT_C voidFill2(TCharaChar)

The surrogate aware version of Fill().

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. If aChar is supplementary character, and available space to fill is odd in 16-bit unit, then the last 16-bit unit will be filled with high surrogate, and the length will keep unchanged.

See also: TDes16::Fill()

Parameters
aCharThe fill character. Can be inside or outside BMP.

Fill2 ( TChar, TInt )

IMPORT_C voidFill2(TCharaChar,
TIntaLength
)

The surrogate aware version of Fill().

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.

If aChar is supplementary character, and available space to fill is odd in 16-bit unit, then the last 16-bit unit will be left unchanged.

USER 11 if aLength is negative or is greater than the maximum length of this descriptor.

USER 217 if corrupt surrogate found in aChar. These functions will not validate already existing surrogate in the descriptor.

See also: TDes16::Fill()

Parameters
aCharThe fill character. Can be inside or outside BMP.
aLengthThe new length of the descriptor.

FillZ ( )

IMPORT_C voidFillZ()

Fills the descriptor's data area with binary zeroes, i.e.0x0000, 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 voidFillZ(TIntaLength)

Fills the descriptor's data area with binary zeroes, i.e. 0x0000, 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.

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

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

Fold ( )

IMPORT_C voidFold()

Performs folding on the content of this descriptor.

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.

Fold2 ( )

IMPORT_C voidFold2()

The surrogate aware version of Fold().

Performs folding on the content of this descriptor.

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.

USER 217 if corrupt surrogate found in the descriptor.

See also: TDes16::Fold()

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

IMPORT_C voidFormat(TRefByValue< const TDesC16 >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 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.

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

USER 11 if the resulting length of text in this descriptor exceeds the descriptor's maximum length. USER 12 if the format string has incorrect syntax.

See also: TDes16::Num() TDes16::NumUC()

Parameters
aFmtThe descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC8 type.

FormatList ( const TDesC16 &, VA_LIST )

IMPORT_C voidFormatList(const TDesC16 &aFmt,
VA_LISTaList
)

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.

See also: TDes16::Format() VA_LIST

Parameters
aFmtThe descriptor containing the format string.
aListA pointer to an argument list.

Insert ( TInt, const TDesC16 & )

IMPORT_C voidInsert(TIntaPos,
const TDesC16 &aDes
)

Inserts data into this descriptor.

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

USER 10 if aPos is negative or is greater than the length of this descriptor. USER 11 if the resulting length of this descriptor is greater than its maximum length.

Parameters
aPosThe position within the data where insertion is to start. This is an offset value; a zero value refers to the leftmost data position.
aDesA 16-bit non modifiable descriptor whose data is to be inserted.

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

IMPORT_C voidJustify(const TDesC16 &aDes,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

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.

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

Parameters
aDesA 16-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).
aWidthThe 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.
anAlignmentThe alignment of the data within the target area
aFillThe fill character used to pad the target area.

Justify2 ( const TDesC16 &, TInt, TAlign, TChar )

IMPORT_C voidJustify2(const TDesC16 &aDes,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

The surrogate aware version of Justify().

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.

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

USER 217 if corrupt surrogate found in the parameters or in the descriptor.

See also: TDes16::Justify()

Parameters
aDesA 16-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).
aWidthThe 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.
anAlignmentThe alignment of the data within the target area
aFillThe fill character used to pad the target area. Can be inside or outside BMP.

LeftTPtr ( TInt )

IMPORT_C TPtr16LeftTPtr(TIntaLength)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.

USER 10 if aLength is negative.

Parameters
aLengthThe 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.
Return Value
The 16-bit modifiable pointer descriptor representing the leftmost part of the data.

LowerCase ( )

IMPORT_C voidLowerCase()

Converts the content of this descriptor to lower case.

Conversion is implemented as appropriate to the current locale.

LowerCase2 ( )

IMPORT_C voidLowerCase2()

The surrogate aware version of LowerCase().

Converts the content of this descriptor to lower case.

Conversion is implemented as appropriate to the current locale.

USER 217 if corrupt surrogate found in the descriptor.

See also: TDes16::LowerCase()

MaxLength ( )

TInt MaxLength()const [inline]

Gets the maximum length of the descriptor.

This is the upper limit for the number of 16-bit values or data items that the descriptor can represent.

Return Value
The maximum length of data 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.

Return Value
The maximum size of the descriptor data.

MidTPtr ( TInt )

IMPORT_C TPtr16MidTPtr(TIntaPos)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.

USER 10 if aPos is negative or aPos is greater than the length of the descriptor.

Parameters
aPosThe starting position of the data to be extracted. This is an offset value; a zero value refers to the leftmost data position.
Return Value
The 16-bit modifiable pointer descriptor representing the specified portion of the data.

MidTPtr ( TInt, TInt )

IMPORT_C TPtr16MidTPtr(TIntaPos,
TIntaLength
)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.

USER 10 if aPos is negative or aPos plus aLength is greater than the length of the descriptor.

Parameters
aPosThe starting position of the data to be extracted. This is an offset value; a zero value refers to the leftmost data position.
aLengthThe length of data to be extracted.
Return Value
The 16-bit modifiable pointer descriptor representing the specified portion of the data.

Num ( TReal, const TRealFormat & )

IMPORT_C TIntNum(TRealaVal,
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.

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.

See also: TRealFormat::iType

Parameters
aValThe floating point number to be converted.
aFormatThe format of the conversion.
Return Value
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:

Num ( TInt64 )

IMPORT_C voidNum(TInt64aVal)

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
aValThe 64-bit signed integer value.

Num ( TUint64, TRadix )

IMPORT_C voidNum(TUint64aVal,
TRadixaRadix
)

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
aValThe 64 bit integer value. This is treated as an unsigned value for all builds.
aRadixThe number system representation for the 64 bit integer.

NumFixedWidth ( TUint, TRadix, TInt )

IMPORT_C voidNumFixedWidth(TUintaVal,
TRadixaRadix,
TIntaWidth
)

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.

Parameters
aValThe unsigned integer value.
aRadixThe number system representation for the unsigned integer.
aWidthThe number of characters: to be used to contain the conversion, to be copied into this descriptor.

NumFixedWidthUC ( TUint, TRadix, TInt )

IMPORT_C voidNumFixedWidthUC(TUintaVal,
TRadixaRadix,
TIntaWidth
)

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.

See also: TDes16::Format()

Parameters
aValThe unsigned integer value.
aRadixThe number system representation for the unsigned integer.
aWidthThe number of characters: to be used to contain the conversion, to be copied into this descriptor.

NumUC ( TUint64, TRadix )

IMPORT_C voidNumUC(TUint64aVal,
TRadixaRadix = 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
aValThe 64 bit integer value. This is always treated as an unsigned value for all builds.
aRadixThe number system representation for the 64 bit integer. If no explicit value is specified, then EDecimal is the default.

PtrZ ( )

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

USER 11 if the descriptor's length is not strictly less than its maximum length.

Return Value
A pointer to the descriptor's zero terminated data.

Repeat ( const TDesC16 & )

IMPORT_C voidRepeat(const TDesC16 &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
aDesA 16-bit non modifiable descriptor whose data is to be repeatedly copied.

Repeat ( const TUint16 *, TInt )

IMPORT_C voidRepeat(const TUint16 *aBuf,
TIntaLength
)

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.

USER 17 if aLength is negative.

Parameters
aBufA pointer to data to be repeatedly copied.
aLengthThe length of data to be copied.

Replace ( TInt, TInt, const TDesC16 & )

IMPORT_C voidReplace(TIntaPos,
TIntaLength,
const TDesC16 &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.

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

USER 10 if aPos is negative or is greater than the length of this descriptor.

USER 11 if the resulting length of this descriptor is greater than its maximum length.

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

Parameters
aPosThe position within the data where replacement is to start. This is an offset value; a zero value refers to the leftmost data position.
aLengthThe length of data to be replaced.
aDesThe source 16-bit non modifiable descriptor whose data is to replace the target descriptor's data at aPos.

RightTPtr ( TInt )

IMPORT_C TPtr16RightTPtr(TIntaLength)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.

USER 10 if aLength is negative.

Parameters
aLengthThe 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.
Return Value
The 16-bit modifiable pointer descriptor representing the rightmost part of the data.

SetLength ( TInt )

IMPORT_C voidSetLength(TIntaLength)

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

USER 11 if aLength is negative or is greater than the maximum length of this (target) descriptor.

Parameters
aLengthThe new length of the descriptor.

SetMax ( )

IMPORT_C voidSetMax()

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

Swap ( TDes16 & )

IMPORT_C voidSwap(TDes16 &aDes)

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.

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

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

USER 11 if the maximum length of either descriptor is smaller than the length of the other descriptor.

Parameters
aDesThe 16-bit modifiable descriptor whose data is to be swapped with the data of this descriptor.

Trim ( )

IMPORT_C voidTrim()

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.

See also: TDes16::TrimLeft() TDes16::TrimRight()

TrimAll ( )

IMPORT_C voidTrimAll()

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.

See also: TDes16::Trim()

TrimLeft ( )

IMPORT_C voidTrimLeft()

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 voidTrimRight()

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 voidUpperCase()

Converts the content of this descriptor to upper case.

Conversion is implemented as appropriate to the current locale.

UpperCase2 ( )

IMPORT_C voidUpperCase2()

The surrogate aware version of UpperCase().

Converts the content of this descriptor to upper case.

Conversion is implemented as appropriate to the current locale.

USER 217 if corrupt surrogate found in the descriptor.

See also: TDes16::UpperCase()

WPtr ( )

TUint16 *WPtr()const [protected, inline]

Zero ( )

IMPORT_C voidZero()

Sets the length of the data to zero.

ZeroTerminate ( )

IMPORT_C voidZeroTerminate()

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.

USER 11 if the descriptor's length is not strictly less than its maximum length.

operator+= ( const TDesC16 & )

TDes16 &operator+=(const TDesC16 &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.

Parameters
aDesA 16-bit non-modifiable descriptor whose data is to be appended.
Return Value
A reference to this descriptor.
Panic Codes
USER11, if the resulting length of this descriptor is greater than its maximum length.

operator= ( const TUint16 * )

TDes16 &operator=(const TUint16 *aString)[inline]

Copies data into this descriptor replacing any existing data.

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

Parameters
aStringA pointer to a zero-terminated string.
Return Value
A reference to this, the target descriptor.
Panic Codes
USER11, if the length of the string, excluding the zero terminator, is greater than the maximum length of this (target) descriptor.

operator= ( const TDesC16 & )

TDes16 &operator=(const TDesC16 &aDes)[inline]

Copies data into this descriptor replacing any existing data.

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

Parameters
aDesA 16-bit non-modifiable descriptor.
Return Value
A reference to this, the target descriptor.
Panic Codes
USER11, if the length of the descriptor aDes is greater than the maximum length of this (target) descriptor.

operator= ( const TDes16 & )

TDes16 &operator=(const TDes16 &aDes)[inline]

Copies data into this descriptor replacing any existing data.

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

Parameters
aDesA 16-bit modifiable descriptor.
Return Value
A reference to this, the target descriptor.
Panic Codes
USER11, if the length of the descriptor aDes is greater than the maximum length of this (target) descriptor.

operator[] ( TInt )

const TUint16 &operator[](TIntanIndex)const [inline]

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

Parameters
anIndexThe position the data item within this descriptor's data. This is an offset value; a zero value refers to the leftmost data position.
Return Value
A const reference to the data item at the specified position.
Panic Codes
USER9, if anIndex is negative or is greater than or equal to the current length of this descriptor.

operator[] ( TInt )

TUint16 &operator[](TIntanIndex)[inline]

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

Parameters
anIndexThe position of the data item within this descriptor's data. This is an offset value; a zero value refers to the leftmost data position.
Return Value
A non-const reference to the data item at the specified position.
Panic Codes
USER9, if anIndex is negative or is greater than or equal to the current length of this descriptor.