Creating and freeing general size vectors

To create a general size vector use one of the routines

      Gan_Vector *pvx;

      pvx = gan_vec_alloc(5);

or

      Gan_Vector vx;

      gan_vec_form ( &vx, 5 );

Both these examples create a vector with five elements. The former allocates a structure and passes back a pointer to it, whereas the latter builds the vector using the provided structure vx. Whichever routine is used, the two vectors are equivalent in every way and can be used in all the Gandalf general size vector routines.

In the above calls Gandalf will invoke malloc() to create the data block to hold the vector elements. Sometimes you will want to provide the data block yourself, avoiding the malloc() call, if you know the size, or at least the maximum size, of the vector. Then you can use the following routine.

      Gan_Vector vx;
      double adXData[10];

      gan_vec_form_data ( &vx, 5, adXData, 10 );

The last argument is the size of the array adXData passed in. This means that although the vector vx is created with size five, the size of the data block, 10, is also stored, and this allows the size of vx to change (see gan_vec_set_size() below) up to size 10.

Once you have finished with a vector use the routine

      gan_vec_free ( pvx ); /* for a pointer variable, OR */
      gan_vec_free ( &vx ); /* for a structure variable */

The gan_vec_free() routine applies without modification to all the methods of creating the vector. The vector structure maintains knowledge of which parts of it (the structure, the data block) were dynamically allocated, and only frees the bits that were allocated.

From now on the example code fragments we provide will use the convention that vectors are declared as structures rather than pointers, but bear in mind that either style may be used.

Error detection: All the above vector creation routines return a pointer to the created vector. If an error occurs, the Gandalf error handler is invoked and NULL is returned. The most likely error modes are failing to allocate the data required (i.e. internal malloc() or realloc() calls failing), or passing too small an array into the gan_vec_form_data() routine.