Class HBufC16

HBufC16

Support

Supported from 5.0

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 intended for instantiation. The 16 bit data that the descriptor represents is part of the descriptor object itself.

Heap descriptors have the important property that they can be made larger or smaller, changing the size of the data area. 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 provides the functions through which the data is accessed.

Derivation

HBufC16 16 bit heap descriptor TBufCBase16 Base class used in the derivation of TBufC16, TBufC and HBufC16 TDesC16 Abstract base class for 16 bit descriptors

Defined in HBufC16:
Des(), HBufC16(), New(), NewL(), NewL(), NewLC(), NewLC(), NewMax(), NewMaxL(), NewMaxLC(), ReAlloc(), ReAllocL(), iBuf, operator=()

Inherited from 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:

• TPtr16
• TDesC16

static HBufC16* New(TInt aMaxLength);

Description

Creates, and returns a pointer to, a new 16 bit heap descriptor that has the specified maximum length.

The heap descriptor is empty and its length is zero.

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

Parameters

TInt aMaxLength The maximum length of data that the descriptor can represent. This value must be non-negative otherwise the function raises a USER 18 panic.

Return value

HBufC16* A pointer to the new 16 bit heap descriptor.NULL, if the 16 bit heap descriptor cannot be created.

See also:

• HBufC16::operator=()

static HBufC16* NewL(TInt aMaxLength);

Description

Creates, and returns a pointer to, a new 16 bit heap descriptor that has the specified maximum length; leaves on failure.

The heap descriptor is empty and its length is zero.

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

Parameters

TInt aMaxLength The maximum length of data that the descriptor can represent. This value must be non-negative otherwise the function raises a USER 18 panic.

Return value

HBufC16* A pointer to the new 16 bit heap descriptor. The function leaves, if the new 16 bit heap descriptor cannot be created.

See also:

• HBufC16::operator=()

static HBufC16* NewL(RReadStream& aStream,TInt aMaxLength);

Description

Creates, and returns a pointer to, a new 16 bit heap descriptor that has been initialised with data from the specified read stream; leaves on failure.

Data is assigned to the new descriptor from the specified stream. This variant assumes that the stream contains the length of the data followed by the data itself.

Parameters

RReadStream& aStream The stream from which the length of the new descriptor and the data to be assigned to the new descriptor, are taken. TInt aMaxLength The upper limit on the length of data that the descriptor is to represent. The actual maximum length of the descriptor is taken from the stream. The value of this parameter must be non-negative otherwise the function raises a USER 18 panic.

Return value

HBufC16* A pointer to the new 16 bit heap descriptor. The function leaves, if the new 16 bit heap descriptor cannot be created.

Leave codes

KErrOverflow If the length of the data as read from the stream is greater than the upper limit as specified in the aMaxLength parameter.

Notes:

• To use this variant, project files must also link against estor.lib
• The length of the data in the stream is represented by a TCardinality object.

See also:

• TCardinality

static HBufC16* NewLC(TInt aMaxLength);

Description

Creates, adds a pointer onto the cleanup stack and returns a pointer to, a new 16 bit heap descriptor that has the specified maximum length; leaves on failure.

The heap descriptor is empty and its length is zero.

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

Parameters

TInt aMaxLength The maximum length of data that the descriptor can represent. This value must be non-negative otherwise the function raises a USER 18 panic.

Return value

HBufC16* A pointer to the new 16 bit heap descriptor. The function leaves, if the new 16 bit heap descriptor cannot be created.

See also:

• HBufC16::operator=()

static HBufC16* NewLC(RReadStream &aStream,TInt aMaxLength);

Description

Creates, adds a pointer onto the cleanup stack and returns a pointer to, a new 16 bit heap descriptor that has been initialised with data from the specified read stream; leaves on failure.

Data is assigned to the new descriptor from the specified stream. This variant assumes that the stream contains the length of the data followed by the data itself.

Parameters

RReadStream& aStream The stream from which the length of the new descriptor and the data to be assigned to the new descriptor, are taken. TInt aMaxLength The upper limit on the length of data that the descriptor is to represent. The actual maximum length of the descriptor is taken from the stream. The value of this parameter must be non-negative otherwise the function raises a USER 18 panic.

Return value

HBufC16* A pointer to the new 16 bit heap descriptor. The function leaves, if the new 16 bit heap descriptor cannot be created.

Leave codes

KErrOverflow If the length of the data as read from the stream is greater than the upper limit as specified in the aMaxLength parameter.

Notes:

• To use this variant, project files must also link against estor.lib
• The length of the data in the stream is represented by a TCardinality object.

See also:

• TCardinality

static HBufC16* NewMax(TInt aMaxLength);

Description

Creates, and returns a pointer to, a new 16 bit heap descriptor that has the specified maximum length.

No data is assigned into the new descriptor but its length is set to the same value as the specified maximum length.

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

Parameters

TInt aMaxLength The maximum length of data that the descriptor can represent. This value must be non-negative otherwise the function raises a USER 18 panic.

Return value

HBufC16* A pointer to the new 16 bit heap descriptor.NULL, if the new 16 bit heap descriptor cannot be created.

See also:

• HBufC16::operator=()

static HBufC16* NewMaxL(TInt aMaxLength);

Description

Creates, and returns a pointer to, a new 16 bit heap descriptor that has the specified maximum length; leaves on failure.

No data is assigned into the new descriptor but its length is set to the same value as the specified maximum length.

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

Parameters

TInt aMaxLength The maximum length of data that the descriptor can represent. This value must be non-negative otherwise the function raises a USER 18 panic.

Return value

HBufC16* A pointer to the new 16 bit heap descriptor. The function leaves, if the new 16 bit heap descriptor cannot be created.

See also:

• HBufC16::operator=()

static HBufC16* NewMaxLC(TInt aMaxLength);

Description

Creates, adds a pointer onto the cleanup stack and returns a pointer to, a new 16 bit heap descriptor that has the specified maximum length; leaves on failure.

No data is assigned into the new descriptor but its length is set to the same value as the specified maximum length.

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

Parameters

TInt aMaxLength The maximum length of data that the descriptor can represent. This value must be non-negative otherwise the function raises a USER 18 panic.

Return value

HBufC16* 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.

See also:

• HBufC16::operator=()

HBufC16* ReAlloc(TInt aMaxLength);

Description

Expands or contracts this 16 bit heap descriptor.

This is done by:

• creating a new heap descriptor.

• copying the original data into the new descriptor.

• deleting the original descriptor.

Parameters

TInt aMaxLength The maximum length of data that the new descriptor is to represent. This value must be non-negative otherwise the function raises a USER 18 panic. This value must not be less than the length of the data otherwise the function raises a USER 14 panic.

Return value

HBufC16* 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.

HBufC16* ReAllocL(TInt aMaxLength);

Description

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

This is done by:

• creating a new heap descriptor.

• copying the original data into the new descriptor.

• deleting the original descriptor.

Parameters

TInt aMaxLength The maximum length of data that the new descriptor is to represent. This value must be non-negative otherwise the function raises a USER 18 panic. This value must not be less than the length of the data otherwise the function raises a USER 14 panic.

Return value

HBufC16* 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.

inline HBufC16& operator=(const HBufC16& aLcb);
HBufC16& operator=(const TDesC16& aDes);
HBufC16& operator=(const TUint16* aString);

Description

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

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

Parameters

const HBufC16& aLcb The source 16 bit heap descriptor. The length of the data must not be greater than the length of the target descriptor otherwise the operator raises a USER 11 panic. const TDesC16& aDes An 16 bit non-modifiable descriptor. The length of the data cannot be greater than the maximum length of the target descriptor otherwise the function raises a USER 11 panic. const TUint16* aString A pointer to a zero-terminated string. The length of the string, excluding the zero terminator, must not be greater than the maximum length of the target descriptor, otherwise the function raises a USER 11 panic.

Return value

HBufC16& A reference to this 16 bit heap descriptor.

TPtr16 Des();

Description

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 data area.

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

TPtr16 A 16 bit modifiable pointer descriptor representing the data in this 16 bit heap descriptor.

private : inline HBufC16(TInt aLength);

Description

This is internal and is not intended for use.

private :   TText16 iBuf[1];

Description

This is internal and is not intended for use.