---
name: "IM_NEW"
section: "3"
platform: "linux"
package: "libvips-dev"
version: "7.20.7-1+b3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/IM_ARRAY"
---

# IM\_NEW(3)

memory allocation macros

Part of [IM\_ARRAY(3)](/IM_ARRAY/3.md).

## 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)](/im_malloc/3.md) 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)](/ARRAY/3.md) 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)](/ARRAY/3.md) 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_malloc/3.md), [im\_open\_local(3)](/im_open_local/3.md).

## AUTHOR

J. Cupitt - 23/7/93