.TH IM_ARRAY 3 "11 April 1993"
.SH NAME
IM_ARRAY, IM_NEW, IM_NUMBER \- memory allocation macros
.SH SYNOPSIS

#include <vips/vips.h>

type-name *IM_NEW( IMAGE *im, type-name )
.br
type-name *IM_ARRAY( IMAGE *im, int number, type-name )
.br
int IM_NUMBER( array )

.SH DESCRIPTION

NEW, NUMBER and ARRAY are macros built on im_malloc(3) which make memory
allocation slightly easier.  Given a type name, NEW returns a pointer to a
piece of memory large enough to hold an object of that type. ARRAY works as
NEW, but allocates space for a number of objects. Given an array, NUMBER
returns the number of elements in that array.

  #define IM_NEW(IM,A) ((A *)im_malloc((IM),sizeof(A)))
  #define IM_NUMBER(R) (sizeof(R)/sizeof(R[0]))
  #define IM_ARRAY(IM,N,T) ((T *)im_malloc((IM),(N) * sizeof(T)))

Both IM_ARRAY and IM_NEW take an image descriptor as their first
parameter. Memory is allocated local to this descriptor, that is, when the
descriptor is closed, the memory is automatically freed for you. If you
pass NULL instead of an image descriptor, memory is allocated globally and
is not automatically freed.

(NOTE: in versions of VIPS before 7.3, NEW(3) and ARRAY(3) did not have the
initial IMAGE parameter. If you are converting an old VIPS7.2 program, you
will need to add a NULL parameter to the start of all NEW(3) and ARRAY(3)
parameter lists.)

Both functions return NULL on error, setting im_errorstring.

Example:

  #include <vips/vips.h>

  /* A structure we want to carry about.
   */
  typedef struct {
    ...
  } Wombat;

  /* A static array of them.
   */
  static Wombat swarm[] = {
    { ... },
    { ... },
    { ... }
  };
  static int swarm_size = IM_NUMBER( swarm );

  int
  transform_wombat( IMAGE *in, IMAGE *out )
  {
    /* Allocate space for a Wombat.
     */
    Wombat *mar = IM_NEW( out, Wombat );

    /* Allocate space for a copy of swarm.
     */
    Wombat *mar = IM_ARRAY( out, swarm_size, Wombat );

    ....
  }

.SH COPYRIGHT
National Gallery, 1993
.SH SEE ALSO
im_malloc(3), im_open_local(3).
.SH AUTHOR
J. Cupitt \- 23/7/93