ElementArrayRemoveReference()

void	ElementArrayRemoveReference(
        optr		arr,				/* optr of element array */
        word		token,				/* Index of element to 
						 * unreference */

        dword		callbackData,				/* Passed to callback routine */
        void _pascal (*callback)		(void *element, dword valueForCallback));
/* Routine is called if element is actually removed */

This routine decrements the reference count of the specified element. If the reference count drops to zero, the element will be removed. If an element is to be removed, ElementArrayRemoveReference() calls the callback routine on that element. The callback routine should perform any cleanup necessary; it is passed a pointer to the element and the callbackData argument. If you pass a null function pointer, no callback routine will be called.

Note that when an element is removed, it is actually resized down to zero size and added to a list of free elements. That way the index numbers of later elements are preserved.

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayDelete().

Include: chunkarr.h

ElementArrayRemoveReferenceHandles()

void	ElementArrayRemoveReferenceHandles(
        MemHandle		mh,			/* Handle of LMem heap */
        ChunkHandle		ch,			/* Chunk handle of element array */
        word		token,			/* Index of element to unreference */
        dword		callbackData,				/* Passed to callback routine */
        void _pascal (*callback)		(void *element, dword valueForCallback));
/* Routine is called if element is actually removed */

This routine is exactly like ElementArrayRemoveReference() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

ElementArrayTokenToUsedIndex()

word	ElementArrayTokenToUsedIndex(
        optr	arr,	/* Handle of element array */
        word	token,	/* Index of element to unreference */
        dword	callbackData,	/* Data passed to callback routine */
        Boolean 	_pascal (*callback)	/* Return true to count this element */
        	    (void *element, dword cbData));

This routine is passed the token of an element array. It translates the token into an index from some non-standard indexing scheme. The indexing scheme can either number the elements from zero, counting only those elements in use (i.e. those with a reference count greater than zero); or it can use a more restrictive scheme. If a callback routine is passed, the callback routine will be called for every used element; it should be declared _pascal and return true if the element should be counted. If a null callback pointer is passed, every used element will be counted.

Include: chunkarr.h

ElementArrayTokenToUsedIndexHandles()

word	ElementArrayTokenToUsedIndexHandles(
        MemHandle 		mh,		/* Handle of LMem heap */
        ChunkHandle 		ch,		/* Chunk handle of element array */
        word		token,		/* Index of element to unreference */
        dword		callbackData, /* Data passed to the
						 * callback routine */

        Boolean 	_pascal (*callback)	/* Return true to count this element */
        		(void *element, dword cbData));

This routine is exactly like ElementArrayTokenToUsedIndex() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

ElementArrayUsedIndexToToken()

word	ElementArrayUsedIndexToToken(
        optr	arr,		/* optr to element array */
        word	index,		/* Find token of element with this index */
        dword	callbackData,		/* This is passed to the callback routine */
        Boolean _pascal (*callback)			/* Return true to count this element */
        		(void *element, dword cbData));

This routine takes an index into an element array from some non-standard indexing scheme. The routine finds the element specified and returns the element's token. The indexing scheme can either number the elements from zero, counting only those elements in use (i.e. those with a reference count greater than zero); or it can use a more restrictive scheme. If a callback routine is passed, the callback routine will be called for every used element; it should should be declared _pascal return true if the element should be counted. If a null callback pointer is passed, every used element will be counted.

If no matching element is found, ElementArrayUsedIndexToToken() returns CA_NULL_ELEMENT.

Include: chunkarr.h

ElementArrayUsedIndexToTokenHandles()

word	ElementArrayUsedIndexToTokenHandles(
        MemHandle 		mh,		/* Handle of LMem heap's block */
        ChunkHandle 		ch,		/* Handle of element array */
        word		index,		/* Find token of element with this index */
        dword		callbackData, /* Data passed to the
	 						  * callback routine */

        Boolean 	_pascal (*callback)	/* Return true to count this element */
        	    (void *element, dword cbData));

This routine is exactly like ElementArrayUsedIndexToToken() above, except that the element array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h