seanhalle@3: /* 
seanhalle@3:  * File:   Vector.h
seanhalle@3:  * Author: Me
seanhalle@3:  *
seanhalle@3:  * Created on May 14, 2010, 3:08 PM
seanhalle@3:  */
seanhalle@3: 
seanhalle@3: #ifndef _DYNARRAY_H
seanhalle@3: #define	_DYNARRAY_H
seanhalle@3: 
seanhalle@3: #include <PR__include/PR__primitive_data_types.h>
seanhalle@3: 
seanhalle@3: 
seanhalle@3: 
seanhalle@3: /*WARNING: Passing a DynArray as a param is dangerous if add to the DynArray
seanhalle@3:  * inside the function called!   After adding or other operation that might
seanhalle@3:  * change the size, must re-read the addr of the chunk of memory that is the
seanhalle@3:  * array, via the DynArrayInfo.
seanhalle@3:  *Here's why: An array variable is a location, either on the stack
seanhalle@3:  * or in a field of a struct, whose contents is an addr.  That addr is of the
seanhalle@3:  * first location of a chunk of locations.  The DynArray works by changing
seanhalle@3:  * the chunk of locations, then modifying the contents of the original 
seanhalle@3:  * array variable.  It overwrites the addr of the old chunk of locations
seanhalle@3:  * with the addr of the new chunk.
seanhalle@3:  *But when the array variable is passed as a parameter, such as 
seanhalle@3:  * in this: "foo( myDynArray )", then there are now two locations that hold
seanhalle@3:  * the addr of the same chunk of locations.  So when a call is made that
seanhalle@3:  * adds to the DynArray, and inside the DynArray expands, it only updates
seanhalle@3:  * the original location with  the new addr.  Hence, the function will begin
seanhalle@3:  * overwriting memory past the end of the old chunk, because it still has 
seanhalle@3:  * the pointer to the old chunk of locations.
seanhalle@3:  *
seanhalle@3:  *A dynamic array is accessed same as any other array.  However, must use
seanhalle@3:  * dyn array calls, defined in here, in order to add or increase the size.
seanhalle@3:  * Must re-read the original array variable after any size-changing calls.
seanhalle@3:  *To pass a DynArray as a parameter to a function, can only pass the 
seanhalle@3:  * DynArrayInfo, then inside the function, to read the addr of the first 
seanhalle@3:  * location in the chunk of locations that is the array, do this:
seanhalle@3:  * "localArrayCopy = *(myDynArrayInfo->addrOfPtrToArray).  After that, can 
seanhalle@3:  * treat localArrayCopy as a normal array, as long as don't make any calls
seanhalle@3:  * that add or otherwise could increase the size of the array.  If do make
seanhalle@3:  * such a call, then re-copy the array via the above.  Can then use the
seanhalle@3:  * copy up until another add to the array.
seanhalle@3:  * 
seanhalle@3:  */
seanhalle@3: typedef struct
seanhalle@3:  {
seanhalle@3:    void ***addrOfPtrToArray; //addr of var that is array of ptrs == triple *
seanhalle@3:    int32   numInArray;  //num entries added
seanhalle@3:    int32   sizeOfArray; //num elems alloc'd
seanhalle@3:    int32   sizeOfElem;  //num bytes in one elem of array -- used in 2nd version
seanhalle@3:  }
seanhalle@3: PrivDynArrayInfo;
seanhalle@3: 
seanhalle@3: PrivDynArrayInfo *
seanhalle@3: makePrivDynArrayInfoFrom( void ***addrOfPtrToArray, int32 sizeOfArray );
seanhalle@3: 
seanhalle@3: PrivDynArrayInfo *
seanhalle@3: makePrivDynArrayOfSize( void ***addrOfPtrToArray, int32 sizeOfArray );
seanhalle@3: 
seanhalle@3: PrivDynArrayInfo *
seanhalle@3: makePrivDynArrayOfSize_Ext( void ***addrOfPtrToArray, int32 sizeOfArray );
seanhalle@3: 
seanhalle@3: int32
seanhalle@3: addToDynArray( void *value, PrivDynArrayInfo *info );
seanhalle@3: 
seanhalle@3: void
seanhalle@3: makeHighestDynArrayIndexBe( PrivDynArrayInfo *info, int32 highestIndex );
seanhalle@3: 
seanhalle@3: void
seanhalle@3: makeHighestDynArrayIndexBeAtLeast(PrivDynArrayInfo *info,int32 highestIndex);
seanhalle@3: 
seanhalle@3: void
seanhalle@3: increaseSizeOfDynArrayTo( PrivDynArrayInfo *info, int32 newSize );
seanhalle@3: 
seanhalle@3: typedef void  (*FreeFnPtr)  ( void * ); //fn has to cast void * to whatever
seanhalle@3: 
seanhalle@3: void
seanhalle@3: freeDynArrayDeep( PrivDynArrayInfo *info, FreeFnPtr freeFnPtr );
seanhalle@3: 
seanhalle@3: void
seanhalle@3: freeDynArrayFlat( PrivDynArrayInfo *info );
seanhalle@3: 
seanhalle@3: 
seanhalle@3: typedef void  (*DynArrayFnPtr)  ( void * );  //fn has to cast void *
seanhalle@3: 
seanhalle@3: void
seanhalle@3: forAllInDynArrayDo( PrivDynArrayInfo *info, DynArrayFnPtr fnPtr );
seanhalle@3: 
seanhalle@3: #endif	/* _DYNARRAY_H */
seanhalle@3: