~mwshinn/+junk/neural

/*----------------------------------------------------------------------------*
\Module{Dynamic Allocation of Arrays}

[...the grand discussion of dynamic arrays]
*/

#include <stdlib.h>
#include <stdio.h>
//#include <malloc.h>

#include "neural.h"
#include "protos.h"



/*----------------------------------------------------------------------------*
\Section{Allocate/Release Memory from Heap}

   This first routine is provided as a wrapper for the standard library
function 'calloc'.  If memory allocation should fail, a message is written to
the standard output device and the program will terminate.

\ENTRY: 'n' specifies the number of bytes to allocate.

\EXIT:  'Alloc' returns a pointer to 'n' bytes of contiguous memory, NOT
         guaranteed to be cleared to zero.  'Alloc' will never return null.
*/

void *Alloc (int n)
{
  void *p;

  Assert(n > 0);

  if (p = malloc(n))
    return p;

  else
//    FatalError("*** Error: Cannot allocate %d bytes ***\n", n);
    printf("*** Error: Cannot allocate %d bytes ***\n", n);
    exit(255);
}


/*----------------------------------------------------------------------------*
   This second routine is provided as a wrapper for the standard library
function 'free'.  This routine checks the memory pointer for null so that the
caller can be absolved of such remedial duties.

\ENTRY: 'p' points to a block of memory allocated earlier with 'Alloc'.

\EXIT:  'p' is undefined.
*/

void Release (void *p)
{
  Assert(p);

  free(p);
}



/*----------------------------------------------------------------------------*
\Section{Create/Destroy One-Dimensional Array}

   This routine allocates an array of a specified number of elements of a
specified element size.  The array is retured as a pointer into memory and
works on the principle that

\S x[i]

is shorthand for

\S *(x+i)

where 'x' is an array pointer and 'i' is an array index.

\ENTRY: 'di' specifies the length of the array.\n
        't' specifies the size in 'size_t' units (characters) of each array
        element.

\EXIT:  'CreateArray1' returns a pointer to the array.  Checking for null is
         unnecessary, since this routine is guaranteed to return a valid
         pointer.  Elements of the array are NOT cleared to zero.\n
*/

void *CreateArray1 (int di, size_t t)
{
  Assert(di > 0);
  Assert(t  > 0);

  return Alloc(di * t);
}


/*----------------------------------------------------------------------------*
This routine destroys arrays allocated by 'CreateArray1'.

\ENTRY: 'a' specifies an array.

\EXIT:  'a' is undefined.
*/

void DestroyArray1 (void *a)
{
  Assert(a);

  Release(a);
}



/*----------------------------------------------------------------------------*
\Section{Create/Destroy Two-Dimensional Array}

   This routine allocates an array of a specified height and width and of a
specified element size.  The array is returned as a pointer into memory and
works on the principle that

\S x[i][j]

is shorthand for

\S *(*(x+i)+j)

where x is an array pointer and i and j are row and column indices,
respectively.

   The array is allocated as a single contiguous block of memory with the first
portion comprising a small array of pointers and the second portion comprising
all the array elements:

\R ____    ________________________
\S  0 |-> |   |   |   |   |   |   |
\R ____    ________________________
\S  1 |-> |   |   |   |   |   |   |
\R ____    ________________________
\S  2 |-> |   |   |   |   |   |   |
\R ____    ________________________
\S    |   |   |   |   |   |   |   |

\ENTRY: 'di' specifies the length of the major portion of the array.\n
        'dj' specifies the length of the minor portion of the array.\n
        't' specifies the size in 'size_t' units (characters) of each array
        element.

\EXIT:  'CreateArray2' returns a pointer to the array.  Checking for null is
         unnecessary, since this routine is guaranteed to return a valid
         pointer.  Elements of the array are NOT cleared to zero.\n
*/

void **CreateArray2 (int di, int dj, size_t t)
{
  int n, m, i;
  char **a, *b;

  Assert(di > 0);
  Assert(dj > 0);
  Assert(t  > 0);

  m = di * sizeof(char *);                   // Calculate the size of each row
  n = dj * t;                                // and the size of the pointer
                                             // section.

  a = (char **)Alloc(m + di*n);              // Allocate the entire array as a
                                             // single contiguous block.

  b = (char *)a + m;
  for (i = 0; i < di; i++)                   // Thread the row pointers.
  {
    a[i] = b;
    b += n;
  }

  return (void *) a;                         // Return the completed array.
}


/*----------------------------------------------------------------------------*
This routine destroys arrays allocated by 'CreateArray2'.

\ENTRY: 'a' specifies an array.

\EXIT:  'a' is undefined.
*/

void DestroyArray2 (void *a)
{
  Assert(a);

  Release(a);
}


/*----------------------------------------------------------------------------*
TODD S. LEHMAN, DECEMBER 1992.








##############################################################################
                          OBSOLETE CODE FOLLOWS
##############################################################################

   For convenience the height $\delta i$ and width $\delta j$ of
two-dimensional arrays are stored in memory immediately preceding the array
data itself.  The macros 'DI' and 'DJ' access these data.

\S for (i = 0; i < DI(x); i++)
\S for (j = 0; j < DJ(x); j++)
     (operation involving 'x[i][j]')

The macros can be used on l-values as well:

\S DI(x) = di;
\S DJ(x) = dj;

In the one-dimensional case, only 'DI' is used.

One-dimensional arrays:

\ENTRY:  'x' points to an array.

\EXIT:   'DI(x)' is the height of the array.

Two-dimensional arrays:

\ENTRY:  'x' points to an array.

\EXIT:   'DI(x)' is the height of the array.
         'DJ(x)' is the width of the array.
*/

#define  DI(x)  (((int *)(x))[-1])
#define  DJ(x)  (((int *)(x))[-2])