Class CBufBase

CBufBase

Support

Supported from 5.0

Description

Specifies the interface for dynamic buffers. Functions are grouped into several categories:

• the basic functions, InsertL(), Read(), Write(), Delete(), Reset() and Size(), transfer data between the buffer and other places, and allow that data to be deleted

• the ExpandL() and Resize() functions allow some operations to be carried out with greater efficiency

• a Compress() function frees (back to the heap) any space which may have been allocated, but not used

• Ptr() and BackPtr() allow look-up of contiguous data from any given position, forward or backward

In addition, important information is maintained in data members.

Derivation

CBase Base class for all classes to be instantiated on the heap CBufBase Specifies the interface for dynamic buffers

Defined in CBufBase:
BackPtr(), Compress(), Delete(), ExpandL(), InsertL(), Ptr(), Read(), Reset(), ResizeL(), Size(), Write()

Inherited from CBase:
operator new()

void InsertL(TInt aPos,const TDesC8& aDes);
void InsertL(TInt aPos,const TDesC8& aDes,TInt aLength);
void InsertL(TInt aPos,const TAny* aPtr,TInt aLength);

Description

Inserts data into the buffer — overloaded function. Data at and beyond the insertion position is moved to make way for the inserted data. Data before the insertion position remains in place.

Notes:

• Insertion may require more buffer space to be allocated.

• In the case of flat buffers, the buffer is extended by a ReAllocL() of the buffer’s heap cell, to the smallest multiple of the granularity that will contain the data required. If this reallocation fails, the insertion is impossible and a leave occurs.

• In the case of segmented buffers, a reallocation is performed if the segment containing the insertion position has insufficient space, and immediately-neighbouring segments cannot be used to contain the new data. As many new segments as are necessary to contain the inserted data are allocated. Each new segment’s length is the buffer’s granularity. If extension or new allocation fails, a leave occurs.

• Insertion may also require data to be shuffled. In the case of flat buffers, data beyond the insertion point is shuffled up to create a gap: the new data is then inserted into this gap. In the case of segmented buffers, shuffling is minimised by inserting the new data into newly-allocated buffers, and shuffling only immediately-neighbouring buffers if possible. This may result in some wastage of space, but is much more time-efficient for large amounts of data.

Parameters

TInt aPos Buffer position before which the data will be inserted: must be in range zero to Size() const TDesC8& aDes If specified, contains data to insert and specifies the length of the data: the length in the descriptor is overridden if aLength is also specified TInt aLength If specified, the length of the data to insert const TAny* aPtr If specified, the address of the data to insert

Leave codes

If the insertion requires space beyond that already contained in the buffer, and the necessary allocation or re-allocation fails, then a leave occurs.

void Write(TInt aPos,const TDesC8& aDes);
void Write(TInt aPos,const TDesC8& aDes,TInt aLength);
void Write(TInt aPos,const TAny* aPtr,TInt aLength);

Description

Writes data from a descriptor to the buffer — overloaded function. The existing data from the insertion position, for as many bytes as there are data in the descriptor, is overwritten.

Notes:

• No new space is allocated: this function cannot fail (provided the parameters are specified within the bounds of the buffer and descriptor).

• No shuffling occurs: new data is written to the memory locations occupied by the data it overwrites.

Parameters

TInt aPos Buffer position at which data will begin to be written: must be in range zero to Size() minus the length of the data to write const TDesC8& aDes If specified, contains data to write and specifies the length of the data: the length in the descriptor is overridden if aLength is also specified TInt aLength If specified, the length of the data to write const TAny* aPtr If specified, the address of the data to write

void Read(TInt aPos,TDes8& aDes) const;
void Read(TInt aPos,TDes8& aDes,TInt aLength) const;
void Read(TInt aPos,TAny* aPtr,TInt aLength) const;

Description

Reads data from the buffer into a descriptor — overloaded function. Data from the buffer position is transferred into the descriptor, for as many bytes as the maximum length of the descriptor, or the length argument specified in the call.

Parameters

TInt aPos Buffer position from which data is read: must be in range zero to Size() minus the length of the data to read TDes8& aDes If specified, on return, contains data read from the buffer; on call, its MaxLength() specifies the amount of data to be read: this is overridden if aLength is also specified TInt aLength If specified, the length of the data to read const TAny* aPtr If specified, the address into which the data should be read

TInt Size() const;

Description

Returns the number of data bytes in the buffer.

Note:

The number of heap bytes used by the buffer may be greater than its size, because there is typically extra room to allow for expansion. Use the Compress() function to reduce the extra allocation as much as possible

Return value

TInt The number of data bytes in the buffer

virtual void Delete(TInt aPos,TInt aLength)=0;

Description

Deletes data from the buffer. Data before the buffer position is not affected. From the buffer position, the number of bytes specified are deleted. Bytes beyond the deleted region are moved back to the buffer position. The size of data in the buffer is thus reduced.

Parameters

TInt aPos Buffer position where the deletion will begin: must be in the range zero to Size() minus the length of the data to be deleted. TInt aLength The number of bytes to delete: must be non-negative.

void Reset();

Description

Deletes all data in the buffer. Its action is the same as Delete(0,Size()). The buffer is compressed before the function returns.

void ExpandL(TInt aPos,TInt aLength);

Description

Inserts an uninitialised region into the buffer. Data at and beyond the insertion position is moved to make way for the inserted region. Data before the insertion position remains in place.

Note:

• The inserted region is not initialised. After using ExpandL(), you should then use a series of Write()s to fill this region with data.

• Use ExpandL() followed by a series of Write()s when you know the amount of data to be inserted, in advance. It is more efficient than a series of InsertL()s. In addition, once the result of the ExpandL() has been checked, it is guaranteed that the Write()s do not leave, which can sometimes be useful.

Parameters

TInt aPos Buffer position before which the region will be inserted: must be in range zero to Size() TInt aLength The length of the region to insert

Leave codes

If the expansion requires space beyond that already contained in the buffer, and the necessary allocation or re-allocation fails, then a leave occurs.

void ResizeL(TInt aSize);

Description

Re-sizes the buffer to the specified size. The new size can be larger or smaller than the existing size.

If the new size is larger than the existing size, the buffer is expanded by adding uninitialised data to the end of it.

If the new size is smaller than the existing size, the buffer is reduced; any data at the end of the buffer is lost.

Notes:

• If the new size is larger than the existing size, the function is equivalent to Delete(aSize,Size()-aSize).

• If the new size is smaller than the existing size, the function is equivalent to ExpandL((Size(),aSize-Size()).

• The motivations for using ResizeL() are the same as those for using Delete() and ExpandL().

Parameters

TInt aSize The new size of the buffer; this value must be greater than or equal to zero.

Leave codes

If the expansion requires space beyond that already contained in the buffer, and the necessary allocation or re-allocation fails, then a leave occurs.

virtual void Compress()=0;

Description

Compresses the buffer so as to occupy minimal space. Normally, you would do this when a buffer has reached its final size, or when you know it will not expand again for a while, or when an out-of-memory error has occurred and your program is taking measures to save space. Compression in these circumstances releases memory for other programs to use, but has no adverse effect on performance.

virtual TPtr8 Ptr(TInt aPos)=0;

Description

Returns a pointer descriptor which refers to all from the specified data byte until the end of the contiguous region containing that byte. The descriptor will point to the end of the segment containing the byte.

Parameters

TInt aPos Buffer position: must be in range zero to Size()

Return value

TPtr8 Descriptor whose address points to the byte at the buffer position, and whose length indicates the number of contiguous bytes stored in the buffer, forward from that point. The length will be non-zero unlessaPos==Size().

virtual TPtr8 BackPtr(TInt aPos)=0;

Description

Returns a pointer descriptor which refers to data from just before the specified data byte backward until the beginning of the contiguous region containing that byte.

Parameters

TInt aPos Buffer position: must be in range zero to Size()

Return value

TPtr8 Descriptor containing address and length of backward contiguous region. The address in the descriptor is the pointer to the bytes at the buffer position, unless the buffer position was at the beginning of a non-first segment in the buffer: in this case, the address is a pointer just beyond the last data byte in the previous segment. The length is the number of contiguous bytes from the address backwards to the beginning of the segment.