TDesC16 Class Reference

anIndex

)

const [protected]

Compare ( const TDesC16 & )

IMPORT_C TInt

Compare

(

const TDesC16 &

aDes

)

const

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
aDes	The 16-bit non-modifable descriptor whose data is to be compared with this descriptor's data.

Return Value: 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.

CompareC ( const TDesC16 & )

IMPORT_C TInt

CompareC

(

const TDesC16 &

aDes

)

const

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

CompareC ( const TDesC16 &, TInt, const TCollationMethod * )

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

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.

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

Parameters
aDes	The 16-bit non-modifable descriptor whose data is to be compared with this descriptor's data.
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.
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: 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.

CompareF ( const TDesC16 & )

IMPORT_C TInt

CompareF

(

const TDesC16 &

aDes

)

const

Compares this descriptor's folded data with the specified descriptor's folded 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 for comparing strings in natural language; use CompareC() for this.

DoSetLength ( TInt )

void

DoSetLength

(

aLength

)

[protected, inline]

Find ( const TDesC16 & )

IMPORT_C TInt

Find

(

const TDesC16 &

aDes

)

const

Searches for the first occurrence of the specified data sequence within this descriptor.

Searching always starts at the beginning of this descriptor's data.

Parameters
aDes	The 16-bit non-modifiable descriptor containing the data sequence to be searched for.

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

Find ( const TUint16 *, TInt )

IMPORT_C TInt	Find	(	const TUint16 *	aBuf,
			TInt	aLen
		)	const

Searches for the first occurrence of the specified data sequence within this descriptor.

Searching always starts at the beginning of this descriptor's data.

Parameters
aBuf	A pointer to a location containing the data sequence to be searched for.
aLen	The length of the data sequence to be searched for. This value must not be negative, otherwise the function raises a panic.

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

Panic Codes
USER	17 if aLenS is negative.

FindC ( const TDesC16 & )

IMPORT_C TInt

FindC

(

const TDesC16 &

aDes

)

const

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.

Parameters
aDes	The 16-bit non-modifable descriptor containing the data sequence to be searched for.

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

FindC ( const TUint16 *, TInt )

IMPORT_C TInt	FindC	(	const TUint16 *	aBuf,
			TInt	aLen
		)	const

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.

Parameters
aBuf	A pointer to a location containing the data sequence to be searched for.
aLen	The length of the data sequence to be searched for.

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

Panic Codes
USER	17 if aLength is negative.

FindC ( const TUint16 *, TInt, TInt )

IMPORT_C TInt	FindC	(	const TUint16 *	aText,
			TInt	aLength,
			TInt	aMaxLevel
		)	const

Searches for the first occurrence of the specified collated data sequence within this descriptor's collated data to the specified maximum collation level.

Parameters
aText	A pointer to a location containing the data sequence to be searched for.
aLength	The length of the data sequence to be searched for.
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.

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

FindC ( const TDesC16 &, TInt &, const TCollationMethod &, TInt )

IMPORT_C TInt	FindC	(	const TDesC16 &	aDes,
			TInt &	aLengthFound,
			const TCollationMethod &	aMethod,
			TInt	aMaxLevel
		)	const

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.

Parameters
aDes	The 16-bit non-modifable descriptor containing the data sequence to be searched for.
aLengthFound	A refernce to the maximal length of the match found in the candidate string. KErrNotFound, if the data sequence cannot be found.
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.

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

FindCorruptSurrogate ( )

IMPORT_C TInt

FindCorruptSurrogate

(

)

const

Look for the first corrupt surrogate in the descriptor.

Return Value: The 16-bit position of the first corrupt surrogate. KErrNotFound, if not found.

FindF ( const TDesC16 & )

IMPORT_C TInt

FindF

(

const TDesC16 &

aDes

)

const

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.

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 for finding strings in natural language; use FindC() for this.

FindF ( const TUint16 *, TInt )

IMPORT_C TInt	FindF	(	const TUint16 *	aBuf,
			TInt	aLen
		)	const

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.

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 for finding strings in natural language; use FindC() for this.

Panic Codes
USER	17 if aLenS is negative

GetCollationKeysL ( TInt, const TCollationMethod * )

IMPORT_C HBufC8 *	GetCollationKeysL	(	TInt	aMaxLevel,
			const TCollationMethod *	aCollationMethod
		)	const

Get the collation keys of this 16 bit descriptor for a given collation level If no collation method is supplied, a default method is used that uses a locale-independent collation table.

Parameters
aMaxLevel	The maximum collation level. This is an integer with values: 0, 1, 2 or 3. Level 3 is always used if the aim is to sort strings.
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: A pointer to the 8-bit heap buffer containing the collation keys if creation is succesful

Leave Codes
KErrNoMemory	if not enough memory to construct the output buffer

GetFoldedDecomposedFormL ( )

IMPORT_C HBufC16 *

GetFoldedDecomposedFormL

(

)

const

Get the folded decomposed form of this 16 bit descriptor

Return Value: A pointer to the 16-bit heap buffer containing folded decomposed form if creation is succesful

Leave Codes
KErrNoMemory	if not enough memory to construct the output buffer

GetNormalizedDecomposedFormL ( )

IMPORT_C HBufC16 *

GetNormalizedDecomposedFormL

(

)

const

Get the normalized decomposed form of this 16 bit descriptor

Return Value: A pointer to the 16-bit heap buffer containing normalized decomposed form if creation is successful

Leave Codes
KErrNoMemory	if not enough memory to construct the output buffer

HasPrefixC ( const TDesC16 &, TInt, const TCollationMethod * )

IMPORT_C TPrefix	HasPrefixC	(	const TDesC16 &	aPossiblePrefix,
			TInt	aLevel,
			const TCollationMethod *	aCollationMethod
		)	const

Compares aPossiblePrefix against the start of the descriptor, using a collated comparison.

0: Only check character identities.

1: Check accents as well.

2: Check case as well.

3: Check Unicode values.

Currently only level 0 is supported.

Parameters
aLevel	The maximum level at which to perform the collation.
aCollationMethod	The collation method to be used for the matching.

Return Value: EIsPrefix, if aPossiblePrefix can be extended to be equivalent to the text at the start of this descriptor. EIsNotPrefix if aPossiblePrefix cannot be extended to be equivalent to the text at the start of this descriptor. EMightBePrefix if it currently does not seem to be a prefix, but it is possible that it could be extended to become equivalent to text at the start of this descriptor. EMightBePrefix is returned in cases where it would be expensive to determine for sure.

Left ( TInt )

IMPORT_C TPtrC16

Left

(

aLength

)

const

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.

USER 10 if aLength is negative.

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

Return Value: The 16-bit non-modifiable pointer descriptor representing the leftmost part of the data.

Length ( )

TInt

Length

(

)

const [inline]

Gets the length of the data.

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

Return Value: The length of the data represented by the descriptor.

Locate ( TChar )

IMPORT_C TInt

Locate

(

aChar

)

const

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
aChar	The character to be found.

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

Locate2 ( TChar )

IMPORT_C TInt

Locate2

(

aChar

)

const

The surrogate aware version of Locate().

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.

LocateF ( TChar )

IMPORT_C TInt

LocateF

(

aChar

)

const

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.

Parameters
aChar	The character to be found.

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

LocateF2 ( TChar )

IMPORT_C TInt

LocateF2

(

aChar

)

const

The surrogate aware version of LocateF().

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.

LocateReverse ( TChar )

IMPORT_C TInt

LocateReverse

(

aChar

)

const

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
aChar	The character to be found.

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

LocateReverse2 ( TChar )

IMPORT_C TInt

LocateReverse2

(

aChar

)

const

The surrogate aware version of LocateReverse().

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.

LocateReverseF ( TChar )

IMPORT_C TInt

LocateReverseF

(

aChar

)

const

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.

Parameters
aChar	The character to be found

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

LocateReverseF2 ( TChar )

IMPORT_C TInt

LocateReverseF2

(

aChar

)

const

The surrogate aware version of LocateReverseF().

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.

Match ( const TDesC16 & )

IMPORT_C TInt

Match

(

const TDesC16 &

aDes

)

const

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.

Note that there is no 'escape character', which means that it is not possible to match either the "*" character itself or the "?" character itself using this function.

Parameters
aDes	A 16-bit non-modifable descriptor containing the match pattern.

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

Match2 ( const TDesC16 & )

IMPORT_C TInt

Match2

(

const TDesC16 &

aDes

)

const

The surrogate aware version of Match().

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.

Note that there is no 'escape character', which means that it is not possible to match either the "*" character itself or the "?" character itself using this function.

MatchC ( const TDesC16 & )

IMPORT_C TInt

MatchC

(

const TDesC16 &

aDes

)

const

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.

Note that there is no 'escape character', which means that it is not possible to match either the "*" character itself or the "?" character itself using this function.

Parameters
aDes	A 16-bit non-modifable descriptor containing the match pattern.

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

MatchC ( const TDesC16 &, TInt, TInt, TInt, TInt, const TCollationMethod * )

IMPORT_C TInt	MatchC	(	const TDesC16 &	aPattern,
			TInt	aWildChar,
			TInt	aWildSequenceChar,
			TInt	aEscapeChar,
			TInt	aMaxLevel = 3,
			const TCollationMethod *	aCollationMethod = NULL
		)	const

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 specified by aWildChar and aWildSequenceChar parameters, where aWildSequenceChar matches zero or more consecutive occurrences of any character and aWildChar matches a single occurrence of any character.

Parameters
aPattern	A 16-bit non-modifable descriptor containing the match pattern.
aWildChar	Wild card character which may be specified for aSearchTerm.
aWildSequenceChar	Wild card sequence character which may be specified for aSearchTerm.
aEscapeChar	The escape character, or 0 if there is to be none. The escape character removes any special meaning from the subsequent character. For example, if the escape, wild card and wild sequence characters are \, ? And * respectively, the search term "\?\\\" matches only the candidate string "?\";
aMaxLevel	Determines the tightness of the collation. At level 0, only character identities are distinguished. At level 1 accents are distinguished as well. At level 2 case is distinguishes as well. At level 3 all valid different Unicode characters are considered different.
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: If a match is found, the offset within this descriptor's data where the match first occurs. KErrNotFound, if there is no match.

MatchC ( const TDesC16 &, const TCollationMethod *, TInt, TInt, TInt, TInt )

IMPORT_C TInt	MatchC	(	const TDesC16 &	aPattern,
			const TCollationMethod *	aCollationMethod,
			TInt	aMaxLevel = 3,
			TInt	aWildChar = '?',
			TInt	aWildSequenceChar = '*',
			TInt	aEscapeChar = 0
		)	const

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.

MatchF ( const TDesC16 & )

IMPORT_C TInt

MatchF

(

const TDesC16 &

aDes

)

const

Searches this descriptor's folded data for a match with the folded 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.

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 for matching strings in natural language; use MatchC() for this.

Note that there is no 'escape character', which means that it is not possible to match either the "*" character itself or the "?" character itself using this function.

Mid ( TInt )

IMPORT_C TPtrC16

Mid

(

aPos

)

const

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 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
aPos	The 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 non-modifiable pointer descriptor representing the specified portion of the data.

Mid ( TInt, TInt )

IMPORT_C TPtrC16	Mid	(	TInt	aPos,
			TInt	aLength
		)	const

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.

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

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

Return Value: The 16-bit non-modifiable pointer descriptor representing the specified portion of the data.

Ptr ( )

IMPORT_C const TUint16 *

Ptr

(

)

const

Gets a pointer to the data represented by the descriptor.

The data cannot be changed through the returned pointer.

Return Value: A pointer to the data

Right ( TInt )

IMPORT_C TPtrC16

Right

(

aLength

)

const

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.

USER 10 if aLength is negative.

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

Return Value: The 16-bit non-modifiable pointer descriptor representing the rightmost part of the data.

Size ( )

TInt

Size

(

)

const [inline]

Gets the size of the data.

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

Return Value: The size of the data represented by the descriptor. This is always twice the length.

Type ( )

TInt

Type

(

)

const [protected, inline]

operator!= ( const TDesC16 & )

operator!=

(

const TDesC16 &

aDes

)

const [inline]

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

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

See also: TDesC16::Compare

Parameters
aDes	The 16-bit non-modifiable descriptor whose data is to be compared with this descriptor's data.

Return Value: True if not equal, false otherwise.

operator< ( const TDesC16 & )

operator<

(

const TDesC16 &

aDes

)

const [inline]

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

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

See also: TDesC16::Compare

Parameters
aDes	The 16-bit non-modifable descriptor whose data is to be compared with this descriptor's data.

Return Value: True if less than, false otherwise.

operator<= ( const TDesC16 & )

operator<=

(

const TDesC16 &

aDes

)

const [inline]

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.

See also: TDesC16::Compare

Parameters
aDes	The 16-bit non- modifiable descriptor whose data is to be compared with this descriptor's data.

Return Value: True if less than or equal, false otherwise.

operator== ( const TDesC16 & )

operator==

(

const TDesC16 &

aDes

)

const [inline]

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

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

See also: TDesC16::Compare

Parameters
aDes	The 16-bit non-modifiable descriptor whose data is to be compared with this descriptor's data.

Return Value: True if equal, false otherwise.

operator> ( const TDesC16 & )

operator>

(

const TDesC16 &

aDes

)

const [inline]

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

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

See also: TDesC16::Compare

Parameters
aDes	The 16-bit non-modifiable descriptor whose data is to be compared with this descriptor's data.

Return Value: True if greater than, false otherwise.

operator>= ( const TDesC16 & )

operator>=

(

const TDesC16 &

aDes

)

const [inline]

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.

See also: TDesC16::Compare

Parameters
aDes	The 16-bit non-modifiable descriptor whose data is to be compared with this descriptor's data.

Return Value: True if greater than or equal, false otherwise.

operator[] ( TInt )

const TUint16 &

operator[]

(