# HG changeset patch
# User Sean Halle <seanhalle@yahoo.com>
# Date 1362749865 28800
# Node ID 958dcb7754caf25a52d77224aa3ad4d6c07bfaeb
# Parent  69980bfe2cf6287c46213851ec73e458ddbdbbce
PR branch -- added comments about safe usage

diff -r 69980bfe2cf6 -r 958dcb7754ca DynArray.c
--- a/DynArray.c	Mon Sep 03 15:09:32 2012 -0700
+++ b/DynArray.c	Fri Mar 08 05:37:45 2013 -0800
@@ -7,6 +7,7 @@
 
 
 #include <stdio.h>
+#include <malloc.h>
 
 #include "DynArray.h"
 
@@ -45,7 +46,7 @@
 makePrivDynArrayOfSize_Ext( void ***addrOfPtrToArray, int32 sizeOfArray )
  { PrivDynArrayInfo *info;
 
-   info = malloc( sizeof(PrivDynArrayInfo) );
+   info = (PrivDynArrayInfo*) malloc( sizeof(PrivDynArrayInfo) );
 
    info->addrOfPtrToArray = addrOfPtrToArray;
 
@@ -132,16 +133,16 @@
  */
 void
 increaseSizeOfDynArrayTo( PrivDynArrayInfo *info, int32 newSize )
- { int32 oldSizeOfArray, i;
+ { int32 oldsizeOfArray, i;
    void **newArray, **oldArray;
 
-   oldSizeOfArray   = info->sizeOfArray;
-   if( newSize <= oldSizeOfArray ) return;
+   oldsizeOfArray   = info->sizeOfArray;
+   if( newSize <= oldsizeOfArray ) return;
 
    oldArray         = *(info->addrOfPtrToArray);
    newArray         = PR_int__malloc( newSize * sizeof(void *) );
 
-   for( i = 0; i < oldSizeOfArray; i++ )
+   for( i = 0; i < oldsizeOfArray; i++ )
     {
       newArray[i] = oldArray[i];
     }
@@ -157,16 +158,16 @@
  */
 void
 increaseSizeOfDynArrayTo_Ext( PrivDynArrayInfo *info, int32 newSize )
- { int32 oldSizeOfArray, i;
+ { int32 oldsizeOfArray, i;
    void **newArray, **oldArray;
 
-   oldSizeOfArray   = info->sizeOfArray;
-   if( newSize <= oldSizeOfArray ) return;
+   oldsizeOfArray   = info->sizeOfArray;
+   if( newSize <= oldsizeOfArray ) return;
 
    oldArray         = *(info->addrOfPtrToArray);
    newArray         = malloc( newSize * sizeof(void *) );
 
-   for( i = 0; i < oldSizeOfArray; i++ )
+   for( i = 0; i < oldsizeOfArray; i++ )
     {
       newArray[i] = oldArray[i];
     }
diff -r 69980bfe2cf6 -r 958dcb7754ca DynArray.h
--- a/DynArray.h	Mon Sep 03 15:09:32 2012 -0700
+++ b/DynArray.h	Fri Mar 08 05:37:45 2013 -0800
@@ -12,16 +12,44 @@
 #include "PR_impl/Services_Offered_by_PR/Memory_Handling/vmalloc.h"
 
 
-   //A dynamic array is same as any other array, but add a DynArrayInfo next
-   // to it.  Accesses and updates of array indexes are done normally, it's
-   // only when add a new element into array that use the extra info.
-   // An add can cause the pointer to the normal array to change..  so must
-   // be protected to single VP at a time.
+
+/*WARNING: Passing a DynArray as a param is dangerous if add to the DynArray
+ * inside the function called!   After adding or other operation that might
+ * change the size, must re-read the addr of the chunk of memory that is the
+ * array, via the DynArrayInfo.
+ *Here's why: An array variable is a location, either on the stack
+ * or in a field of a struct, whose contents is an addr.  That addr is of the
+ * first location of a chunk of locations.  The DynArray works by changing
+ * the chunk of locations, then modifying the contents of the original 
+ * array variable.  It overwrites the addr of the old chunk of locations
+ * with the addr of the new chunk.
+ *But when the array variable is passed as a parameter, such as 
+ * in this: "foo( myDynArray )", then there are now two locations that hold
+ * the addr of the same chunk of locations.  So when a call is made that
+ * adds to the DynArray, and inside the DynArray expands, it only updates
+ * the original location with  the new addr.  Hence, the function will begin
+ * overwriting memory past the end of the old chunk, because it still has 
+ * the pointer to the old chunk of locations.
+ *
+ *A dynamic array is accessed same as any other array.  However, must use
+ * dyn array calls, defined in here, in order to add or increase the size.
+ * Must re-read the original array variable after any size-changing calls.
+ *To pass a DynArray as a parameter to a function, can only pass the 
+ * DynArrayInfo, then inside the function, to read the addr of the first 
+ * location in the chunk of locations that is the array, do this:
+ * "localArrayCopy = *(myDynArrayInfo->addrOfPtrToArray).  After that, can 
+ * treat localArrayCopy as a normal array, as long as don't make any calls
+ * that add or otherwise could increase the size of the array.  If do make
+ * such a call, then re-copy the array via the above.  Can then use the
+ * copy up until another add to the array.
+ * 
+ */
 typedef struct
  {
-   void ***addrOfPtrToArray; //addr of array of ptrs == triple *
-   int32   numInArray;
-   int32   sizeOfArray;
+   void ***addrOfPtrToArray; //addr of var that is array of ptrs == triple *
+   int32   numInArray;  //num entries added
+   int32   sizeOfArray; //num elems alloc'd
+   int32   sizeOfElem;  //num bytes in one elem of array -- used in 2nd version
  }
 PrivDynArrayInfo;