HBufC16 Class Reference

#include <e32des16.h>

class HBufC16 : public TBufCBase16

Inherits from

Public Member Functions
IMPORT_C TPtr16Des()
IMPORT_C HBufC16 *New(TInt)
IMPORT_C HBufC16 *NewL(TInt)
IMPORT_C HBufC16 *NewL(RReadStream &, TInt)
IMPORT_C HBufC16 *NewLC(TInt)
IMPORT_C HBufC16 *NewLC(RReadStream &, TInt)
IMPORT_C HBufC16 *NewMax(TInt)
IMPORT_C HBufC16 *NewMaxL(TInt)
IMPORT_C HBufC16 *NewMaxLC(TInt)
IMPORT_C HBufC16 *ReAlloc(TInt)
IMPORT_C HBufC16 *ReAllocL(TInt)
IMPORT_C HBufC16 &operator=(const TUint16 *)
IMPORT_C HBufC16 &operator=(const TDesC16 &)
HBufC16 &operator=(const HBufC16 &)
Inherited Enumerations
TDesC16:TPrefix
Inherited Functions
TBufCBase16::Copy(const TDesC16 &,TInt)
TBufCBase16::Copy(const TUint16 *,TInt)
TBufCBase16::DoDes(TInt)
TBufCBase16::TBufCBase16()
TBufCBase16::TBufCBase16(TInt)
TBufCBase16::TBufCBase16(const TDesC16 &,TInt)
TBufCBase16::TBufCBase16(const TUint16 *,TInt)
TBufCBase16::WPtr()const
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
TDesC16::operator[](TInt)const

Detailed Description

16-bit heap descriptor.

This is a descriptor class which provides a buffer of fixed length, allocated on the heap, for containing and accessing data.

The class is intended for instantiation.

Heap descriptors have the important property that they can be made larger or smaller, changing the size of the descriptor buffer. This is achieved by reallocating the descriptor. Unlike the behaviour of dynamic buffers, reallocation is not done automatically.

Data is intended to be accessed, but not modified; however, it can be completely replaced using the assignment operators of this class. The base class (TDesC16) provides the functions through which the data is accessed.

The descriptor is hosted by a heap cell, and the 16-bit data that the descriptor represents is part of the descriptor object itself. The size of the cell depends on the requested maximum length of the descriptor buffer when the descriptor is created or re-allocated.

It is important to note that the size of the allocated cell, and, therefore, the resulting maximum length of the descriptor, may be larger than requested due to the way memory is allocated in Symbian OS. The amount by which this may be rounded up depends on the platform and build type.

See also: HBufC TPtr16 TDesC16

Member Function Documentation

Des ( )

IMPORT_C TPtr16Des()

Creates and returns a 16-bit modifiable pointer descriptor for the data represented by this 16-bit heap descriptor.

The content of a heap descriptor normally cannot be altered, other than by complete replacement of the data. Creating a modifiable pointer descriptor provides a way of changing the data.

The modifiable pointer descriptor is set to point to this heap descriptor's data.

The length of the modifiable pointer descriptor is set to the length of this heap descriptor.

The maximum length of the modifiable pointer descriptor is set to the length of the heap descriptor's buffer. Note that the maximum length is the length of the descriptor buffer in the allocated host heap cell; this may be greater than the maximum length requested when this descriptor was originally created or last re-allocated.

When data is modified through this new pointer descriptor, the lengths of both it and this heap descriptor are changed.

Note that it is a common mistake to use Des() to create a TDesC16& reference. While not incorrect, it is simpler and much more efficient to simply dereference the heap descriptor.

Return Value
A 16-bit modifiable pointer descriptor representing the data in this 16-bit heap descriptor.

New ( TInt )

IMPORT_C HBufC16 *New(TIntaMaxLength)[static]

Creates, and returns a pointer to, a new 16-bit heap descriptor.

The heap descriptor is empty and its length is zero.

Data can, subsequently, be assigned into it using the assignment operators.

USER 18 if aMaxLength is negative.

See also: HBufC16::operator=()

Parameters
aMaxLengthThe requested maximum length of the descriptor. Note that the resulting heap cell size and, therefore, the resulting maximum length of the descriptor may be larger than requested.
Return Value
A pointer to the new 16-bit heap descriptor. NULL, if the 16-bit heap descriptor cannot be created.

NewL ( TInt )

IMPORT_C HBufC16 *NewL(TIntaMaxLength)[static]

Creates, and returns a pointer to, a new 16-bit heap descriptor, and leaves on failure.

The heap descriptor is empty and its length is zero.

Data can, subsequently, be assigned into it using the assignment operators.

USER 18 if aMaxLength is negative.

See also: HBufC16::operator=()

Parameters
aMaxLengthThe requested maximum length of the descriptor. Note that the resulting heap cell size and, therefore, the resulting maximum length of the descriptor may be larger than requested.
Return Value
A pointer to the new 16-bit heap descriptor. The function leaves, if the new 16-bit heap descriptor cannot be created.

NewL ( RReadStream &, TInt )

IMPORT_C HBufC16 *NewL(RReadStream &aStream,
TIntaMaxLength
)[static]

NewLC ( TInt )

IMPORT_C HBufC16 *NewLC(TIntaMaxLength)[static]

Creates, adds a pointer onto the cleanup stack and returns a pointer to, a new 16-bit heap descriptor; leaves on failure.

The heap descriptor is empty and its length is zero.

Data can, subsequently, be assigned into it using the assignment operators.

USER 18 if aMaxLength is negative.

See also: HBufC16::operator=()

Parameters
aMaxLengthThe requested maximum length of the descriptor. Note that the resulting heap cell size and, therefore, the resulting maximum length of the descriptor may be larger than requested.
Return Value
A pointer to the new 16-bit heap descriptor. The function leaves, if the new 16-bit heap descriptor cannot be created.

NewLC ( RReadStream &, TInt )

IMPORT_C HBufC16 *NewLC(RReadStream &aStream,
TIntaMaxLength
)[static]

NewMax ( TInt )

IMPORT_C HBufC16 *NewMax(TIntaMaxLength)[static]

Creates, and returns a pointer to, a new 16-bit heap descriptor.

No data is assigned into the new descriptor but its length is set to aMaxLength.

Data can, subsequently, be assigned into it using the assignment operators.

USER 18 if aMaxLength is negative.

See also: HBufC16::operator=()

Parameters
aMaxLengthThe requested maximum length of the descriptor. Note that the resulting heap cell size and, therefore, the resulting maximum length of the descriptor may be larger than requested. This also means that the resulting maximum length of the descriptor may be greater than its length.
Return Value
A pointer to the new 16-bit heap descriptor. NULL, if the new 16-bit heap descriptor cannot be created.

NewMaxL ( TInt )

IMPORT_C HBufC16 *NewMaxL(TIntaMaxLength)[static]

Creates, and returns a pointer to, a new 16-bit heap descriptor; leaves on failure.

No data is assigned into the new descriptor but its length is set to aMaxLength.

Data can, subsequently, be assigned into it using the assignment operators.

USER 18 if aMaxLength is negative.

See also: HBufC16::operator=()

Parameters
aMaxLengthThe requested maximum length of the descriptor. Note that the resulting heap cell size and, therefore, the resulting maximum length of the descriptor may be larger than requested. This also means that the resulting maximum length of the descriptor may be greater than its length.
Return Value
A pointer to the new 16-bit heap descriptor. The function leaves, if the new 16-bit heap descriptor cannot be created.

NewMaxLC ( TInt )

IMPORT_C HBufC16 *NewMaxLC(TIntaMaxLength)[static]

Creates, adds a pointer onto the cleanup stack and returns a pointer to, a new 16-bit heap descriptor; leaves on failure.

No data is assigned into the new descriptor but its length is set to aMaxLength.

Data can, subsequently, be assigned into it using the assignment operators.

USER 18 if aMaxLength is negative.

See also: HBufC16::operator=()

Parameters
aMaxLengthThe requested maximum length of the descriptor. Note that the resulting heap cell size and, therefore, the resulting maximum length of the descriptor may be larger than requested.
Return Value
A pointer to the new 16-bit heap descriptor. This is also put onto the cleanup stack. The function leaves, if the new 16-bit heap descriptor cannot be created.

ReAlloc ( TInt )

IMPORT_C HBufC16 *ReAlloc(TIntaMaxLength)

Expands or contracts this 16-bit heap descriptor.

This is done by:

1. creating a new heap descriptor.

2. copying the original data into the new descriptor.

3. deleting the original descriptor.

USER 14 if aMaxLength is less than the length of the existing data. USER 18 if aMaxLength is negative.

Parameters
aMaxLengthThe new requested maximum length of the descriptor. Note that the resulting heap cell size and, therefore, the resulting maximum length of the descriptor may be larger than requested.
Return Value
A pointer to the new expanded or contracted 16-bit heap descriptor - the original descriptor is deleted. NULL, if the new 16-bit heap descriptor cannot be created - the original descriptor remains unchanged.

ReAllocL ( TInt )

IMPORT_C HBufC16 *ReAllocL(TIntaMaxLength)

Expands or contracts this 16-bit heap descriptor; leaves on failure.

This is done by:

1. creating a new heap descriptor.

2. copying the original data into the new descriptor.

3. deleting the original descriptor.

USER 14 if aMaxLength is less than the length of the existing data. USER 18 if aMaxLength is negative.

Parameters
aMaxLengthThe new requested maximum length of the descriptor. Note that the resulting heap cell size and, therefore, the resulting maximum length of the descriptor may be larger than requested.
Return Value
A pointer to the new expanded or contracted 16-bit heap descriptor - the original descriptor is deleted. The function leaves, if the new 16-bit heap descriptor cannot be created - the original descriptor remains unchanged.

operator= ( const TUint16 * )

IMPORT_C HBufC16 &operator=(const TUint16 *aString)

Copies data into this 16-bit heap descriptor replacing any existing data.

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

Note that the maximum length of this (target) descriptor is the length of the descriptor buffer in the allocated host heap cell; this may be greater than the maximum length specified when this descriptor was created or last re-allocated.

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

Parameters
aStringA pointer to a zero-terminated string.
Return Value
A reference to this 16-bit heap descriptor.

operator= ( const TDesC16 & )

IMPORT_C HBufC16 &operator=(const TDesC16 &aDes)

Copies data into this 16-bit heap descriptor replacing any existing data.

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

Note that the maximum length of this (target) descriptor is the length of the descriptor buffer in the allocated host heap cell; this may be greater than the maximum length specified when this descriptor was created or last re-allocated.

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

Parameters
aDesA 16-bit non-modifiable descriptor.
Return Value
A reference to this 16-bit heap descriptor.

operator= ( const HBufC16 & )

HBufC16 &operator=(const HBufC16 &aLcb)[inline]

Copies data into this 16-bit heap descriptor replacing any existing data.

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

Note that the maximum length of this (target) descriptor is the length of the descriptor buffer in the allocated host heap cell; this may be greater than the maximum length specified when this descriptor was created or last re-allocated.

Parameters
aLcbThe source 16-bit heap descriptor.
Return Value
A reference to this 16-bit heap descriptor.
Panic Codes
USER11, if the length of the descriptor aLcb is greater than the maximum length of this (target) descriptor