1IM_ARRAY(3)                Library Functions Manual                IM_ARRAY(3)
2
3
4

NAME

6       IM_ARRAY, IM_NEW, IM_NUMBER - memory allocation macros
7

SYNOPSIS

9       #include <vips/vips.h>
10       #include <vips/util.h>
11
12       type-name *IM_NEW( IMAGE *im, type-name )
13       type-name *IM_ARRAY( IMAGE *im, int number, type-name )
14       int IM_NUMBER( array )
15
16

DESCRIPTION

18       NEW,  NUMBER and ARRAY are macros built on im_malloc(3) which make mem‐
19       ory allocation slightly easier.  Given  a  type  name,  NEW  returns  a
20       pointer  to  a  piece  of memory large enough to hold an object of that
21       type. ARRAY works as NEW, but allocates space for a number of  objects.
22       Given an array, NUMBER returns the number of elements in that array.
23
24         #define IM_NEW(IM,A) ((A *)im_malloc((IM),sizeof(A)))
25         #define IM_NUMBER(R) (sizeof(R)/sizeof(R[0]))
26         #define IM_ARRAY(IM,N,T) ((T *)im_malloc((IM),(N),sizeof(T)))
27
28       Both IM_ARRAY and IM_NEW take an image descriptor as their first param‐
29       eter. Memory is allocated local to this descriptor, that is,  when  the
30       descriptor is closed, the memory is automatically freed for you. If you
31       pass NULL instead of an image descriptor, memory is allocated  globally
32       and is not automatically freed.
33
34       (NOTE: in versions of VIPS before 7.3, NEW(3) and ARRAY(3) did not have
35       the initial IMAGE parameter. If you are converting an old VIPS7.2  pro‐
36       gram,  you will need to add a NULL parameter to the start of all NEW(3)
37       and ARRAY(3) parameter lists.)
38
39       Both functions return NULL on error, setting im_errorstring.
40
41       Example:
42
43         #include <vips/vips.h>
44         #include <vips/util.h>
45
46         /* A structure we want to carry about.
47          */
48         typedef struct {
49           ...
50         } Wombat;
51
52         /* A static array of them.
53          */
54         static Wombat swarm[] = {
55           { ... },
56           { ... },
57           { ... }
58         };
59         static int swarm_size = IM_NUMBER( swarm );
60
61         int
62         transform_wombat( IMAGE *in, IMAGE *out )
63         {
64           /* Allocate space for a Wombat.
65            */
66           Wombat *mar = IM_NEW( out, Wombat );
67
68           /* Allocate space for a copy of swarm.
69            */
70           Wombat *mar = IM_ARRAY( out, swarm_size, Wombat );
71
72           ....
73         }
74
75

77       National Gallery, 1993
78

SEE ALSO

80       im_malloc(3), im_open_local(3), `VIPS Library  Programmers'  Guide'  in
81       accompanying documentation.
82

AUTHOR

84       J. Cupitt - 23/7/93
85
86
87
88                                 11 April 1993                     IM_ARRAY(3)
Impressum