causerie

Introduction

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

Classes hierarchy graph

Class AVector

DescriptionHierarchyFieldsMethodsProperties

Unit

classwork

Declaration

type AVector = class(APrintingObject, CanStream)

Description

This class represents a vector, which is a dynamically-allocated one-dimensional array that contains elements which are all the same size. The class acts in a fashion similar to the dynamic arrays offered by Free Pascal, and can also read itself from and write itself to an arbitrary stream.

As with Free Pascal's dynamic arrays, vectors are zero-indexed, meaning the first element in the array is always at index zero (0). The last element in the array is always at index AVector.length - 1, and can also be referenced by calling AVector.lastElement.

It is unlikely that you will create a direct instance of this class, since its functionality is fairly basic. Instead, you will most likely derive a class from it that adds the functionality required, or use an instance of APointerVector or AnObjectVector.

Hierarchy

Overview

Fields

Protected myBuffer: pchar;
Protected myBufferLength: TCensus;
Protected myElementSize: longword;
Protected myLength: TCensus;

Methods

Public constructor ofLength(const initialLength: TCensus; const elementsSize: longword; const initialValue: pointer = nil); virtual;
Public function init: boolean; override;
Public destructor destroy; override;
Public procedure allocateElements(const elementCount: TCensus); virtual;
Public procedure grow(newElementCount: TCensus = 0); virtual;
Public procedure fillElements(const sourceValue: pointer); virtual;
Public procedure pushElement(const newElement: pointer);
Public procedure popElement(const destElement: pointer); virtual;
Public function appendElement(const newElement: pointer): TNodeAbsoluteIndex; virtual;
Public procedure insertElementAt(thisIndex: TNodeAbsoluteIndex; const newElement: pointer); virtual;
Public procedure removeElementAt(thisIndex: TNodeAbsoluteIndex; const destElement: pointer); virtual;
Public procedure deleteElementAt(const thisIndex: TNodeAbsoluteIndex); virtual;
Public procedure getElementAt(thisIndex: TNodeAbsoluteIndex; const destElement: pointer); virtual;
Public procedure setElementAt(thisIndex: TNodeAbsoluteIndex; const newElement: pointer); virtual;
Public function streamingLength: TStreamIOSize; virtual;
Public function writeTo(const Dest: AStream): TStreamIOSize; virtual;
Public function readFrom(const Source: AStream): TStreamIOSize; virtual;
Public function toString: AnsiString; override;
Public function buffer: pointer; virtual;
Public function lastElement: pointer; virtual;
Public function bufferLength: TCensus; virtual;
Public function elementSize: longword; virtual;
Public function length: TCensus; virtual;

Description

Fields

Protected myBuffer: pchar;

Refers to the memory block that stores the items in the array

Protected myBufferLength: TCensus;

Indicates the current size of the memory block that stores elements

Protected myElementSize: longword;

Indicates the size of elements in the array

Protected myLength: TCensus;

Indicates the current number of elements in the array

Methods

Public constructor ofLength(const initialLength: TCensus; const elementsSize: longword; const initialValue: pointer = nil); virtual;

Construct a new instance of AVector that will handle elements which are of the given size.

The array will be sized to contain the initialLength elements, all of which will be elementsSize bytes in length. If initialValue is specified, then all elements of the array will be set to the value it references.

If specified, it is the caller's responsiblity to ensure that initialValue points to an item that is at least size bytes in length. The value located there will be copied to all elements of the array. If initialValue is Nil, then the array will be zero-filled.

Exceptions raised
AVectorAllocationError
if the initial attempt to allocate memory for the buffer fails.
Public function init: boolean; override;

Initializer

Public destructor destroy; override;

Destroy the managed array and the data it contains.

If AVector.buffer contains pointers to instances of objects, these objects should be freed BEFORE this method is called, as this method does not free them. Alternatively, you may use an instance of AnObjectVector and set its ownsObjects property to True to ensure that object instances are freed when the array is destroyed.

Public procedure allocateElements(const elementCount: TCensus); virtual;

Allocate memory to hold array elements.

This method calls System.reallocMem to obtain a memory block that is large enough to hold elementCount elements that are all AVector.elementSize bytes in length. If the array already has a buffer allocated to it, then this method will attempt to increase the size of the array to include the new elements while preserving the existing elements.

If elementCount specifies a value that is less than or equal to the current value of AVector.length, then this routine does nothing.

This method is called by AVector.ofLength to perform the initial allocation of the array. It is also called by AVector.grow to extend the size of the array and by AVector.readFrom to obtain enough memory in order to read array elements from a given stream.

Exceptions raised
AVectorAllocationError
if a memory block large enough to hold the number of elements specified.
Public procedure grow(newElementCount: TCensus = 0); virtual;

Grow the array by the specified number of elements.

This method is called automatically whenever one or more new elements must be added to the array, but the value of AVector.bufferLength indicates there is not enough room to do so. It attempts to increase the size of the buffer so it can contain newElementCount items.

If newElementCount is zero (0), then the method will attempt to increase the size of the buffer by 1.5 times its current size. The new elements are zero-filled by this method.

This method calls AVector.allocateElements.

Exceptions raised
AVectorAllocationError
if the attempt to reallocate the buffer failed.
Public procedure fillElements(const sourceValue: pointer); virtual;

Fill the entire array with a copy of the specified value.

This method fills the array with the value specified by sourceValue. It is the caller's responsibility to ensure that sourceValue points to an item that is at least AVector.elementSize bytes in length.

If sourceValue is Nil, each element in the array is filled with zero bytes; thus, calling this method with a Nil pointer effectively zeroes the array.

Public procedure pushElement(const newElement: pointer);

Push an element onto the array as the last item in the array.

If necessary, the array will grow to accomodate the new item.

It is the caller's responsibility to ensure that newElement points to an item that is at least AVector.elementSize bytes in length. The value located there will be copied to the new element at the end of the array. If newElement is Nil, then the new item is initialized to all zero (0) bytes.

Public procedure popElement(const destElement: pointer); virtual;

Pop the last element from the array, thus removing it from the array.

It is the caller's responsibility to ensure that destElement points to an item that is at least AVector.elementSize bytes in length. The value located at the end of the array will be copied there. If destElement is Nil, then the element is removed from the array and discarded.

Public function appendElement(const newElement: pointer): TNodeAbsoluteIndex; virtual;

Add the element into the array as the last item in the array.

If necessary, the array will grow to accomodate the new item.

It is the caller's responsibility to ensure that newElement points to an item that is at least AVector.elementSize bytes in length. The value located there will be copied to the new element at the end of the array. If newElement is Nil, then the new item is initialized to all zero (0) bytes.

Returns

The index of the new item. This index is not permanent; if items are removed from the array, then the indices of any items after the one removed will change.

Public procedure insertElementAt(thisIndex: TNodeAbsoluteIndex; const newElement: pointer); virtual;

Add the element into the array at the specified index.

Any element which already exists at the index will be "shifted right"; in other words, the index assigned to it will increase by one.

If thisIndex specifies an index that is larger than the current value of AVector.length, then the item is added to the end of the array as though AVector.pushElement was called.

It is the caller's responsibility to ensure that newElement points to an item that is at least AVector.elementSize bytes in length. The value located there will be copied to the new element. If newElement is Nil, then the new item is initialized to all zero (0) bytes.

Public procedure removeElementAt(thisIndex: TNodeAbsoluteIndex; const destElement: pointer); virtual;

Remove the element at the specified index.

Any and all elements which exist "after" the specified index will be "shifted left"; in other words, the indices assigned to them will decrease by one each.

If thisIndex specifies an index that is larger than the current value of AVector.length, then the last item is removed from the array as though AVector.popElement was called.

It is the caller's responsibility to ensure that destElement points to an item that is at least AVector.elementSize bytes in length. The value at the specified index will be copied there before it is removed from the array. If destElement is Nil, then the element is removed from the array and discarded.

Public procedure deleteElementAt(const thisIndex: TNodeAbsoluteIndex); virtual;

Delete the element at the specified index.

Any and all elements which exist "after" the specified index will be "shifted left"; in other words, the indices assigned to them will decrease by one each.

If thisIndex specifies an index that is larger than the current value of AVector.length, then the last item is removed from the array as though AVector.popElement was called.

This method simply calls AVector.removeElementAt, passing a Nil pointer for the destElement.

Public procedure getElementAt(thisIndex: TNodeAbsoluteIndex; const destElement: pointer); virtual;

Retrieve the element at the specified index.

If thisIndex specifies an index that is larger than the current value of AVector.length, then the value of the last item in the array is retrieved, exactly as though AVector.lastElement was called.

It is the caller's responsibility to ensure that destElement points to an item that is at least AVector.elementSize bytes in length. The value at the specified index will be copied there. If destElement is Nil, then this routine does nothing.

Public procedure setElementAt(thisIndex: TNodeAbsoluteIndex; const newElement: pointer); virtual;

Set the element at the specified index.

If thisIndex specifies an index that is larger than the current value of AVector.length, then this method sets the value of the last item in the array.

It is the caller's responsiblity to ensure that newElement points to an item that is at least AVector.elementSize bytes in length. The value specified there will be copied to the array at the specified index, overwriting any value that is already there.

If newElement is Nil, then this routine zero-fills the element at the specified index.

Public function streamingLength: TStreamIOSize; virtual;

Calculate the number of bytes required to stream the vector.

This method calculates the size of its array and then adds the sizes of AVector.elementSize and AVector.length. This value is returned to the caller.

Public function writeTo(const Dest: AStream): TStreamIOSize; virtual;

Write the array and its elements to the specified stream.

This method writes the values of AVector.elementSize and AVector.length to Dest before writing the contents of the array itself. Only the used contents of its buffer are written; any extra space allocated by AVector.grow is ignored.

Returns

The total number of bytes written to Dest.

Public function readFrom(const Source: AStream): TStreamIOSize; virtual;

Read the array and its elements from the specified stream.

This method reads the values of AVector.elementSize and AVector.length from Source before reading the contents of the array itself. If the array already has elements, the new elements read from Source are appended to the end of the array, and the array is grown as necessary.

Returns

The total number of bytes read from Source.

Public function toString: AnsiString; override;

Construct a string representation of the object, suitable for output to a text-based device, such as a console.

This method constructs a string representation based on the format specified by vctrStringRepresentationSingular or vctrStringRepresentationPlural. The format includes the name of the class and the total number of elements contained by the array.

Public function buffer: pointer; virtual;

Retrieve a reference to the buffer used by the array.

The calling routine should not make any assumptions about the pointer returned by this routine. If it becomes necessary to resize the array, it is possible that this pointer will become invalid, depending upon how the underlying memory manager reallocates memory.

The pointer returned by this routine should NOT be used to free the buffer managed by the array.

Public function lastElement: pointer; virtual;

Retrieve a reference to the last item in the array.

The pointer returned by this routine should NOT be freed.

Public function bufferLength: TCensus; virtual;

Retrieve the size, in bytes, of the buffer used by the array.

Public function elementSize: longword; virtual;

Retrieve the size of, in bytes, of elements stored in the array.

Public function length: TCensus; virtual;

Retrieve the total number of elements in the array.

Generated by PasDoc 0.13.0 on 2015-01-10 17:13:18