TDesC8 Class Reference

#include <e32des8.h>

class TDesC8
Public Member Functions
IMPORT_C HBufC8 *Alloc()
IMPORT_C HBufC8 *AllocL()
IMPORT_C HBufC8 *AllocLC()
IMPORT_C TIntCompare(const TDesC8 &)
IMPORT_C TIntCompareC(const TDesC8 &)
IMPORT_C TIntCompareF(const TDesC8 &)
IMPORT_C TIntFind(const TDesC8 &)
IMPORT_C TIntFind(const TUint8 *, TInt)
IMPORT_C TIntFindC(const TDesC8 &)
IMPORT_C TIntFindC(const TUint8 *, TInt)
IMPORT_C TIntFindF(const TDesC8 &)
IMPORT_C TIntFindF(const TUint8 *, TInt)
IMPORT_C TPtrC8Left(TInt)
TInt Length()
IMPORT_C TIntLocate(TChar)
IMPORT_C TIntLocateF(TChar)
IMPORT_C TIntLocateReverse(TChar)
IMPORT_C TIntLocateReverseF(TChar)
IMPORT_C TIntMatch(const TDesC8 &)
IMPORT_C TIntMatchC(const TDesC8 &)
IMPORT_C TIntMatchF(const TDesC8 &)
IMPORT_C TPtrC8Mid(TInt)
IMPORT_C TPtrC8Mid(TInt, TInt)
IMPORT_C const TUint8 *Ptr()
IMPORT_C TPtrC8Right(TInt)
TInt Size()
TBool operator!=(const TDesC8 &)
TBool operator<(const TDesC8 &)
TBool operator<=(const TDesC8 &)
TBool operator==(const TDesC8 &)
TBool operator>(const TDesC8 &)
TBool operator>=(const TDesC8 &)
const TUint8 &operator[](TInt)
Protected Member Functions
TDesC8(TInt, TInt)
TDesC8()
IMPORT_C const TUint8 &AtC(TInt)
voidDoSetLength(TInt)
TInt Type()

Detailed Description

Abstract base class for 8-bit non-modifiable descriptors.

The class encapsulates the data member containing the length of data represented by an 8-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 8-bit (i.e. single 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.

See also: TDesC TPtrC8

Constructor & Destructor Documentation

TDesC8 ( TInt, TInt )

TDesC8(TIntaType,
TIntaLength
)[protected, inline]

TDesC8 ( )

TDesC8()[protected, inline]

Member Function Documentation

Alloc ( )

IMPORT_C HBufC8 *Alloc()const

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

Return Value
A pointer to the new 8 bit heap descriptor, if creation is successful. NULL, if creation of the descriptor fails.

AllocL ( )

IMPORT_C HBufC8 *AllocL()const

Creates a new 8-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
A pointer to the 8-bit heap descriptor, if creation is successful.

AllocLC ( )

IMPORT_C HBufC8 *AllocLC()const

Creates a new 8-bit heap descriptor, initialises it with a copy of this descriptor's data, and puts a pointer to the descriptor onto the cleanup stack.

The function leaves, if creation of the descriptor fails.

Return Value
A pointer to the 8 bit heap descriptor, if creation is successful. The pointer is also put onto the cleanup stack.

AtC ( TInt )

IMPORT_C const TUint8 &AtC(TIntanIndex)const [protected]

Compare ( const TDesC8 & )

IMPORT_C TIntCompare(const TDesC8 &aDes)const

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

The comparison proceeds on a byte for byte basis. The result of the comparison is based on the difference of the first 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
aDesThe 8-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 TDesC8 & )

IMPORT_C TIntCompareC(const TDesC8 &aDes)const
Deprecated

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

See also: TDesC8::Compare()

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

CompareF ( const TDesC8 & )

IMPORT_C TIntCompareF(const TDesC8 &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.

See also: TDesC8::Compare()

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

DoSetLength ( TInt )

voidDoSetLength(TIntaLength)[protected, inline]

Find ( const TDesC8 & )

IMPORT_C TIntFind(const TDesC8 &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
aDesThe 8-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.

Find ( const TUint8 *, TInt )

IMPORT_C TIntFind(const TUint8 *pS,
TIntaLenS
)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
pSA pointer to a location containing the data sequence to be searched for.
aLenSThe 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
USER29 if aLenS is negative.

FindC ( const TDesC8 & )

IMPORT_C TIntFindC(const TDesC8 &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 for narrow text appropriate to the current locale.

Deprecated

Parameters
aDesThe 8-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 TUint8 *, TInt )

IMPORT_C TIntFindC(const TUint8 *pS,
TIntaLenS
)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 for narrow text appropriate to the current locale.

Deprecated
Parameters
pSA pointer to a location containing the data sequence to be searched for.
aLenSThe 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
USER29 if aLength is negative.

FindF ( const TDesC8 & )

IMPORT_C TIntFindF(const TDesC8 &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.

See also: TDesC8::FindC()

Parameters
aDesThe 8-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. Zero, if the length of the search data sequence is zero.

FindF ( const TUint8 *, TInt )

IMPORT_C TIntFindF(const TUint8 *pS,
TIntaLenS
)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.

See also: TDesC8::FindC()

Parameters
pSA pointer to a location containing the data sequence to be searched for.
aLenSThe 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. Zero, if the length of the search data sequence is zero.
Panic Codes
USER29 if aLenS is negative

Left ( TInt )

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

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 8-bit non-modifiable pointer descriptor representing the leftmost part of the data.
Panic Codes
USER22 if aLength is negative.

Length ( )

TInt Length()const [inline]

Gets the length of the data.

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

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

Locate ( TChar )

IMPORT_C TIntLocate(TCharaChar)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
aCharThe 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.

LocateF ( TChar )

IMPORT_C TIntLocateF(TCharaChar)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.

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 searching strings in natural language.

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

LocateReverse ( TChar )

IMPORT_C TIntLocateReverse(TCharaChar)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
aCharThe 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.

LocateReverseF ( TChar )

IMPORT_C TIntLocateReverseF(TCharaChar)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.

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 searching strings in natural language.

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

Match ( const TDesC8 & )

IMPORT_C TIntMatch(const TDesC8 &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
aDesAn 8-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 TDesC8 & )

IMPORT_C TIntMatchC(const TDesC8 &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 for narrow text 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.

Deprecated

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

MatchF ( const TDesC8 & )

IMPORT_C TIntMatchF(const TDesC8 &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.

See also: TDesC8::MatchC()

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

Mid ( TInt )

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

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 8-bit non-modifiable pointer descriptor representing the specified portion of the data.
Panic Codes
USER22 if aPos is negative or aPos is greater than the length of the descriptor.

Mid ( TInt, TInt )

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

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 8 bit non-modifiable pointer descriptor representing the specified portion of the data.
Panic Codes
USER22 if aPos is negative or aPos plus aLength is greater than the length of the descriptor.

Ptr ( )

IMPORT_C const TUint8 *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 TPtrC8Right(TIntaLength)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.

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 8 bit non-modifiable pointer descriptor representing the rightmost part of the data.
Panic Codes
USER22 if aLength is negative.

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.

Type ( )

TInt Type()const [protected, inline]

operator!= ( const TDesC8 & )

TBool operator!=(const TDesC8 &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: TDesC8::Compare

Parameters
aDesThe 8-bit non-modifable descriptor whose data is to be compared with this descriptor's data.
Return Value
True if not equal, false otherwise.

operator< ( const TDesC8 & )

TBool operator<(const TDesC8 &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: TDesC8::Compare

Parameters
aDesThe 8-bit non-modifable descriptor whose data is to be compared with this descriptor's data.
Return Value
True if greater than or equal, false otherwise.

operator<= ( const TDesC8 & )

TBool operator<=(const TDesC8 &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: TDesC8::Compare

Parameters
aDesThe 8-bit non-modifable descriptor whose data is to be compared with this descriptor's data.
Return Value
True if less than or equal, false otherwise.

operator== ( const TDesC8 & )

TBool operator==(const TDesC8 &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: TDesC8::Compare

Parameters
aDesThe 8-bit non-modifable descriptor whose data is to be compared with this descriptor's data.
Return Value
True if equal, false otherwise.

operator> ( const TDesC8 & )

TBool operator>(const TDesC8 &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: TDesC8::Compare

Parameters
aDesThe 8-bit non-modifable descriptor whose data is to be compared with this descriptor's data.
Return Value
True if greater than, false otherwise.

operator>= ( const TDesC8 & )

TBool operator>=(const TDesC8 &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: TDesC8::Compare

Parameters
aDesThe 8-bit non-modifable descriptor whose data is to be compared with this descriptor's data.
Return Value
True if greater than, false otherwise.

operator[] ( TInt )

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

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

Parameters
anIndexThe position of the individual data item within the descriptor's data. This is an offset value; a zero value refers to the leftmost data position.
Return Value
A reference to the data item.
Panic Codes
USER21, if anIndex is negative or greater than or equal to the current length of the descriptor.
© Nokia 2005.