HugeArrayEnum()

Boolean	HugeArrayEnum(
        VMFileHandle		vmFile,			/* subject to override */
        VMBlockHandle		vmBlock,			/* Handle of the Huge Array's directory
					 * block */

        Boolean	 _pascal 	(*callback) (						/* return true to stop */
        		void *			element,			/* element to examine */
        		void * 			enumData),
        dword		startElement,				/* first element to examine */
        dword		count,			/* examine this many elements */
        void *		enumData;			/* this pointer is passed to callback
					 * routine */

This routine lets you examine a sequence of elements in a Huge Array. HugeArrayEnum() is passed six arguments. The first two are a file handle and block handle; these specify the Huge Array to be examined. The third is a pointer to a Boolean callback routine. The fourth argument is the index of the first element to be examined (remember, the first element in the Huge Array has an index of zero). The fifth argument is the number of elements to examine, or -1 to examine through the last element. The sixth argument is a pointer which is passed unchanged to the callback routine; you can use this to pass data to the callback routine, or to keep track of a scratch space.

The callback routine, which must be declared _pascal, itself takes two arguments. The first is a pointer to an element in the huge array. The callback routine will be called once for each element in the specified range; each time, the first argument will point to the element being examined. The second argument is the pointer that was passed as the final argument to HugeArrayEnum() . The callback routine can make HugeArrayEnum() abort by returning true ; this is useful if you need to search for a specific element. Otherwise, the callback routine should return false . If the callback routine aborts the enumeration, HugeArrayEnum() returns true ; otherwise, it returns false .

HugeArrayEnum() is guaranteed to examine the elements in numerical order, beginning with startElement . The routine will automatically stop with the last element, even if count elements have not been enumerated. However, the starting element must be the index of an element in the array.

Include: hugearr.h

Warnings: The callback routine may not allocate, free, or resize any elements in the Huge Array. All it should do is examine or change ( without resizing) a single element.

The starting element must be an element in the array. If you pass a starting index which is out-of-bounds, the results are undefined.

HugeArrayExpand()

word	HugeArrayExpand(
        void **		elemPtr,				/* **elemPtr is element at location
						 * where new elements will be
						 * created */

        word		numElem,				/* # of elements to insert */
        const void *		initData);				/* Copy this into each new 
						 * element */

This routine inserts a number of elements at a specified location in a HugeArray. The element pointed to will be shifted so it comes after the newly-created elements. The pointer will be fixed up to point to the first new element. The data pointed to by initData will be copied into each new element. If initData is null, the new elements will be uninitialized.

If the elements are of variable size, this routine will insert a single element; this element will be numElem bytes long.

Include: hugearr.h

HugeArrayInsert()

void	HugeArrayInsert(
        VMFileHandle		vmFile,
        VMBlockHandle		vmBlock,			/* Handle of directory block */
        word		numElem,			/* # of elements to insert */
        dword		elemNum,			/* Index of first new element */
        const void *		initData);			/* Copy this into each new element */

This routine inserts one or more elements in the midst of a Huge Array. The first new element will have index elemNum ; thus, the element which previously had that index will now come after the new elements. The data pointed to by initData will be copied into each new element. If initData is null, the new elements will be uninitialized.

If the elements are of variable size, this routine will insert a single element; this element will be numElem bytes long.

Include: heap.h

HugeArrayLock()

dword	HugeArrayLock(
        VMFileHandle		vmFile,
        VMBlockhandle		vmBlock,			/* Handle of directory block */
        dword		elemNum,			/* Element to lock */
        void **		elemPtr,			/* Pointer to element is written here */
        word *		elemSize);

This routine locks an element in a Huge Array. It writes the element's address to *elemPtr . The dword returned indicates how many elements come before and after the element in that blok The upper word indicates how many elements come before the locked one, counting the locked element; the lower word indicates how many elements come after the locked element, again counting the locked one. If an error occured, then the lower word of the return value will be zero.

The routine also writes the size of the locked element (in bytes) to *elemSize . You may examine or change all the other elements in the block without making further calls to HugeArrayLock() .

Include: heap.h

See Also: HAL_COUNT(), HAL_PREV().

HugeArrayNext()

word	HugeArrayNext(
        void **		elemPtr,
        word *		size);

This routine increments a pointer to an element in a HugeArray to point to the next element. If the element was the last element in its block, HugeArrayNext() will unlock its block and lock the next one. The routine writes the pointer to *elemPtr; it returns the number of elements which come after the newly-locked one in its block, counting the newly-locked element. If this routine is passed a pointer to the last element in a HugeArray, it returns zero and elemPtr will point to the last element.

If the elements are variable-sized, then the word pointed to by size will be updated to reflect the size of the newly-locked element; otherwise, the value will be undefined.

Include: heap.h

Warnings: This routine may unlock the block containing the passed element. Therefore, if you need to mark the block as dirty, do so before making this call.

HugeArrayDestroy()

HugeArrayEnum()

HugeArrayExpand()

HugeArrayGetCount()

HugeArrayInsert()

HugeArrayLock()

HugeArrayNext()