Man Linux: Main Page and Category List

NAME

       IM_ARRAY, IM_NEW, IM_NUMBER - memory allocation macros

SYNOPSIS

       #include <vips/vips.h>

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

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 );

           ....
         }

COPYRIGHT

       National Gallery, 1993

SEE ALSO

       im_malloc(3), im_open_local(3).

AUTHOR

       J. Cupitt - 23/7/93

                                 11 April 1993                     IM_ARRAY(3)