Class TDesC16

TDesC16

Support

Supported from 5.0

Description

Abstract base class for 16 bit descriptors.

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

Data represented by this class is treated as a contiguous set of 16-bit (i.e. double byte) values or data items.

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 want access to descriptor data but do not need to modify that data.

Defined in TDesC16:
Alloc(), AllocL(), AllocLC(), Compare(), CompareC(), CompareF(), Find(), FindC(), FindF(), Left(), Length(), Locate(), LocateF(), LocateReverse(), LocateReverseF(), Match(), MatchC(), MatchF(), Mid(), Ptr(), Right(), Size(), operator!=(), operator<(), operator<=(), operator==(), operator>(), operator>=(), operator[]()

See also:

• TPtrC16
• Using TDesC16

TInt Length() const;

Description

Returns the length of the data.

This is the number of 16 bit values or data items represented by the descriptor.

Return value

TInt The length of the data represented by the descriptor.

TInt Size() const;

Description

Returns the size of the data.

This is the number of bytes occupied by the data represented by the descriptor.

Return value

TInt The size of the data represented by the descriptor. This is always twice the length.

const TUint16* Ptr() const;

Description

Returns a pointer to the data represented by the descriptor.

The data cannot be changed through the returned pointer.

Return value

TUint16* A pointer to the data

TPtrC16 Left(TInt aLength) const;

Description

Extracts the leftmost part of the data.

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

Parameters

TInt aLength The length of the data to be extracted. This value cannot be negative, otherwise the function raises a USER 10 panic. If this value is greater than the length of the descriptor, the function extracts the whole of the descriptor. In EPOC Release 5, if aLength was greater than the descriptor's length, the function raised a USER 10 panic.

Return value

TPtrC16 The 16 bit non-modifiable pointer descriptor representing the leftmost part of the data.

TPtrC16 Right(TInt aLength) const;

Description

Extracts the rightmost part of the data.

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

Parameters

TInt aLength The length of data to be extracted. This value cannot be negative, otherwise the function raises a USER 10 panic. If this value is greater than the length of the descriptor, the function extracts the whole of the descriptor. In EPOC Release 5, if aLength was greater than the descriptor's length, the function raised a USER 10 panic.

Return value

TPtrC16 The 16 bit non-modifiable pointer descriptor representing the rightmost part of the data.

TPtrC16 Mid(TInt aPos) const;
TPtrC16 Mid(TInt aPos,TInt aLength) const;

Description

Extracts a portion of the data.

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

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

Parameters

TInt aPos The starting position of the data to be extracted. This is an offset; a zero value refers to the leftmost data position. TInt aLength If specified, the length of data to be extracted. If not specified, the implied length is the length of the remainder of the data starting from the specified position.

Return value

TPtrC16 The 16 bit non-modifiable pointer descriptor representing the specified portion of the data.

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

Description

Subscript operator.

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

Parameters

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

Return value

TUint16& A reference to the data item.

HBufC16* Alloc() const;

Description

Creates an HBufC initialised with this descriptor data.

Creates a new 16 bit heap descriptor and initialises it with a copy of this descriptor's data.

Return value

HBufC16* A pointer to the new 16 bit heap descriptor, if creation is successful. NULL, if creation of the descriptor fails.

HBufC16* AllocL() const;

Description

Creates an HBufC initialised with this descriptor data; leaves on failure.

Creates a new 16 bit heap descriptor and initialises it with a copy of this descriptor's data.

The function leaves, if creation of the descriptor fails.

Return value

HBufC16* A pointer to the 16 bit heap descriptor, if creation is successful.

HBufC16* AllocLC() const;

Description

Creates an HBufC initialised with this descriptor data; leaves on failure; uses the cleanupstack.

Creates a new 16 bit heap descriptor and initialises it with a copy of this descriptor's data

The function leaves, if creation of the descriptor fails.

Return value

HBufC16* A pointer to the 16 bit heap descriptor, if creation is successful. The pointer is also put onto the cleanup stack.

TInt Compare(const TDesC16& aDes) const;

Description

Compares this descriptor's data with the specified descriptor's data.

The comparison proceeds on a double-byte for double byte basis. The result of the comparison is based on the difference of the first pair of bytes to disagree.

Two descriptors are equal if they have the same length and content. Where two descriptors have different lengths and the shorter descriptor's data matches the first part of the longer descriptor's data, the shorter is considered to be less than the longer.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor’s data.

Return value

TInt Positive if this descriptor is greater than the specified descriptor. Negative if this descriptor is less than the specified descriptor. Zero if both descriptors have the same length and the their contents are the same.

See also:

• Comparing data

TInt CompareC(const TDesC16& aDes) const;

Description

Compares data using the standard collation method.

Compares this descriptor's data with the specified descriptor's data using the standard collation method appropriate to the current locale.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data.

Return value

TInt Positive, if this descriptor is greater than the specified descriptor. Negative, if this descriptor is less than the specified descriptor. Zero, if the content of both descriptors match.

See also:

• TDesC16::Compare()

TInt CompareC(const TDesC16& aDes, TInt aMaxLevel, const TCollationMethod* aCollationMethod) const;

Support

Supported from 5.1

Description

Compares data to the specified maximum collation level.

Compares this descriptor's data with the specified descriptor's data to the specified maximum collation level and using the specified collation method.

If no collation method is supplied, a default method is used that uses a locale-independent collation table. This means that sorting and matching will not be based on the current locale.

This function is only defined for 16 bit (Unicode) build variants. This means that the function is not defined for 8 bit build variants, even when an explicit 16 bit descriptor is used.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data. TInt aMaxLevel The maximum collation level. This is an integer with values: 0, 1, 2 or 3, which, effectively, determines how 'tight' the matching should be. Level 3 is always used if the aim is to sort strings. const TCollationMethod* aCollationMethod A pointer to the collation method or NULL. Collation methods can be retrieved by calls to Mem::CollationMethodByIndex() and Mem::CollationMethodById(). Specifying NULL means that the default method is used.

Return value

TInt Positive, if this descriptor is greater than the specified descriptor. Negative, if this descriptor is less than the specified descriptor. Zero, if the content of both descriptors match.

Notes:

• Strings may match even if the lengths of their respective descriptors are different.

See also:

• Mem::CollationMethodByIndex()
• Mem::CollationMethodById()
• TDesC16::Compare()

TInt CompareC(const TDesC16& aDes, const TInt16* aCollationRules) const;

Support

Withdrawn in 6.0

Description

Compares data using a specified collation rule set.

[Use of this function is DEPRECATED from release 5.1].

Compares this descriptor's data with the specified descriptor's data using the specified collation rule set.

This function is only defined for 16 bit (Unicode) build variants. This means that the function is not defined for 8 bit build variants, even when an explicit 16 bit descriptor is used.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data. const TInt16* aCollationRules A pointer to the collation rule set in this locale's collation repertoire.

Return value

TInt Positive, if this descriptor is greater than the specified descriptor. Negative, if this descriptor is less than the specified descriptor. Zero, if the content of both descriptors match.

See also:

• TDesC16::Compare()

TInt CompareC(const TDesC16& aDes,TUint32 aDesiredCollationRulesId,TUint32& aActualCollationRulesId) const;

Support

Withdrawn in 6.0

Description

Compares data using collation rule set identified by a UID.

[Use of this function is DEPRECATED from release 5.1].

Compares this descriptor's data with the specified descriptor's data using the collation rule set associated with the specified Uid. If no collation rule set with the specified Uid can be found, the function uses a default collation rule set and returns its associated Uid.

This function is only defined for 16 bit (Unicode) build variants. This means that the function is not defined for 8 bit build variants, even when an explicit 16 bit descriptor is used.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data. TUint32 aDesiredCollationRulesId The Uid of the collation rule set required. TUint32& aActualCollationRulesId On return, contains the Uid of the collation rule set used. This may be different from the specified Uid, if there is no collation rule set with that Uid.

Return value

TInt Positive, if this descriptor is greater than the specified descriptor. Negative, if this descriptor is less than the specified descriptor. Zero, if the content of both descriptors match.

See also:

• TDesC16::Compare()

TInt CompareF(const TDesC16& aDes) const;

Description

Compares folded data.

Compares this descriptor's folded data with the specified descriptor's folded data. The function uses the standard folding method appropriate to the current locale.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data.

Return value

TInt Positive, if this descriptor is greater than the specified descriptor. Negative, if this descriptor is less than the specified descriptor. Zero, if both descriptors have the same length and the their contents are the same.

See also:

• TDesC16::Compare()

TInt operator==(const TDesC16& aDes) const;

Description

Determines whether this descriptor's data is equal to the specified descriptor's data.

The comparison is implemented using the Compare() member function.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data.

Return value

TInt True if equal, false otherwise.

See also:

• TDesC16::Compare()

TInt operator!=(const TDesC16& aDes) const;

Description

Determines whether this descriptor's data is not equal to the specified descriptor's data.

The comparison is implemented using the Compare() member function.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data.

Return value

TInt True if not equal, false otherwise.

See also:

• TDesC16::Compare()

TInt operator<(const TDesC16& aDes) const;

Description

Determines whether this descriptor's data is less than the specified descriptor's data.

The comparison is implemented using the Compare() member function.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data.

Return value

TInt True if less than, false otherwise.

See also:

• TDesC16::Compare()

TInt operator<=(const TDesC16& aDes) const;

Description

Determines whether this descriptor's data is less than or equal to the specified descriptor's data.

The comparison is implemented using the Compare() member function.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data.

Return value

TInt True if less than or equal, false otherwise.

See also:

• TDesC16::Compare()

TInt operator>(const TDesC16& aDes) const;

Description

Determines whether this descriptor's data is greater than the specified descriptor's data.

The comparison is implemented using the Compare() member function.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data.

Return value

TInt True if greater than, false otherwise.

See also:

• TDesC16::Compare()

TInt operator>=(const TDesC16& aDes) const;

Description

Determines whether this descriptor's data is greater than or equal to the specified descriptor's data.

The comparison is implemented using the Compare() member function.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor whose data is to be compared with this descriptor's data.

Return value

TInt True if greater than, false otherwise.

See also:

• TDesC16::Compare()

TInt Locate(TChar aChar) const;

Description

Searches for a character in forwards direction.

Searches for the first occurrence of a character within this descriptor's data. The search starts at the beginning of the data, i.e. at the leftmost position.

Parameters

TChar aChar The character to be found.

Return value

TInt The offset of the character position from the beginning of the data.KErrNotFound, if no matching character can be found.

See also:

• Locating a character

TInt LocateF(TChar aChar) const;

Description

Searches for a character in forwards direction; folded.

Searches for the first occurrence of a folded character within this descriptor's folded data. The search starts at the beginning of the data, i.e. at the leftmost position. The function uses the standard folding method appropriate to the current locale.

Parameters

TChar aChar The character to be found.

Return value

TInt The offset of the character position from the beginning of the data.KErrNotFound, if no matching character can be found.

TInt LocateReverse(TChar aChar) const;

Description

Searches for a character in backwards direction.

Searches for the first occurrence of a character within this descriptor's data, searching from the end of the data. The search starts at the rightmost position.

Parameters

TChar aChar The character to be found

Return value

TInt The offset of the character position from the beginning of the data.KErrNotFound, if no matching character can be found.

TInt LocateReverseF(TChar aChar) const;

Description

Searches for a character in backwards direction; folded.

Searches for the first occurrence of a folded character within this descriptor's folded data, searching from the end of the data. The search starts at the rightmost position. The function uses the standard folding method appropriate to the current locale.

Parameters

TChar aChar The character to be found

Return value

TInt The offset of the character position from the beginning of the data.KErrNotFound, if no matching character can be found

TInt Find(const TDesC16& aDes) const;
TInt Find(const TUint16* pS,TInt aLenS) const;

Description

Finds data.

Searches for the first occurrence of the specified data sequence within this descriptor. Searching always starts at the beginning of this descriptor's data.

The search data can be defined within another descriptor or it may be defined as a pointer and length pair.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor containing the data sequence to be searched for. const TUint16* pS A pointer to a location containing the data sequence to be searched for. TInt aLenS The length of the data sequence to be searched for. This value must not be negative, otherwise the function raises a USER 17 panic.

Return value

TInt The offset of the data sequence from the beginning of this descriptor's data. KErrNotFound, if the data sequence cannot be found.

See also:

• Finding data

TInt FindC(const TDesC16& aDes) const;
TInt FindC(const TUint16* pS,TInt aLenS) const;

Description

Finds data; collated.

Searches for the first occurrence of the specified collated data sequence within this descriptor's collated data. Searching always starts at the beginning of this descriptor's data. The function uses the standard collation method appropriate to the current locale.

The search data can be defined within another descriptor or it may be defined as a pointer and length pair.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor containing the data sequence to be searched for. const TUint16* pS A pointer to a location containing the data sequence to be searched for. TInt aLenS The length of the data sequence to be searched for. This value must not be negative, otherwise the function raises a USER 17 panic.

Return value

TInt The offset of the data sequence from the beginning of this descriptor's data. KErrNotFound, if the data sequence cannot be found.

TInt FindF(const TDesC16& aDes) const;
TInt FindF(const TUint16* pS,TInt aLenS) const;

Description

Finds data; folded.

Searches for the first occurrence of the specified folded data sequence within this descriptor's folded data. Searching always starts at the beginning of this descriptor's data. The function uses the standard folding method appropriate to the current locale.

The search data can be defined within another descriptor or it may be defined as a pointer and length pair.

Parameters

const TDesC16& aDes The 16 bit non modifable descriptor containing the data sequence to be searched for. const TUint16* pS A pointer to a location containing the data sequence to be searched for. TInt aLenS The length of the data sequence to be searched for. This value must not be negative, otherwise the function raises a USER 17 panic.

Return value

TInt The offset of the data sequence from the beginning of this descriptor's data. KErrNotFound, if the data sequence cannot be found.

TInt Match(const TDesC16& aDes) const;

Description

Pattern-matches data.

Searches this descriptor's data for a match with the match pattern supplied in the specified descriptor.

The match pattern can contain the wildcard characters "*" and "?", where "*" matches zero or more consecutive occurrences of any character and "?" matches a single occurrence of any character.

Parameters

const TDesC16& aDes A 16 bit non modifable descriptor containing the match pattern.

Return value

TInt If a match is found, the offset within this descriptor's data where the match first occurs. KErrNotFound, if there is no match.

TInt MatchC(const TDesC16& aDes) const;

Description

Pattern-matches data; collated.

Searches this descriptor's collated data for a match with the collated match pattern supplied in the specified descriptor. The function uses the standard collation method appropriate to the current locale.

The match pattern can contain the wildcard characters "*" and "?", where "*" matches zero or more consecutive occurrences of any character and "?" matches a single occurrence of any character.

Parameters

const TDesC16& aDes A 16 bit non modifable descriptor containing the match pattern.

Return value

TInt If a match is found, the offset within this descriptor's data where the match first occurs. KErrNotFound, if there is no match.

TInt MatchF(const TDesC16& aDes) const;

Description

Pattern-matches data; folded.

Searches this descriptor's folded data for a match with the folded match pattern supplied in the specified descriptor. The function uses the standard folding method appropriate to the current locale.

The match pattern can contain the wildcard characters ‘*’ and ‘?’, where ‘*’ matches zero or more consecutive occurrences of any character and ‘?’ matches a single occurrence of any character.

Parameters

const TDesC16& aDes A 16 bit non modifable descriptor containing the match pattern.

Return value

TInt If a match is found, the offset within this descriptor's data where the match first occurs. KErrNotFound, if there is no match.