* config/i860/i860-protos.h (i860_va_arg): Remove.
[official-gcc.git] / gcc / vec.h
blob84b8dbf978b90f30e00cffeeea971f94e05f03e0
1 /* Vector API for GNU compiler.
2 Copyright (C) 2004 Free Software Foundation, Inc.
3 Contributed by Nathan Sidwell <nathan@codesourcery.com>
5 This file is part of GCC.
7 GCC is free software; you can redistribute it and/or modify it under
8 the terms of the GNU General Public License as published by the Free
9 Software Foundation; either version 2, or (at your option) any later
10 version.
12 GCC is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 for more details.
17 You should have received a copy of the GNU General Public License
18 along with GCC; see the file COPYING. If not, write to the Free
19 Software Foundation, 59 Temple Place - Suite 330, Boston, MA
20 02111-1307, USA. */
22 #ifndef GCC_VEC_H
23 #define GCC_VEC_H
25 /* The macros here implement a set of templated vector types and
26 associated interfaces. These templates are implemented with
27 macros, as we're not in C++ land. The interface functions are
28 typesafe and use static inline functions, sometimes backed by
29 out-of-line generic functions. The vectors are designed to
30 interoperate with the GTY machinery.
32 Because of the different behaviour of objects and of pointers to
33 objects, there are two flavours. One to deal with a vector of
34 pointers to objects, and one to deal with a vector of objects
35 themselves. Both of these pass pointers to objects around -- in
36 the former case the pointers are stored into the vector and in the
37 latter case the pointers are dereferenced and the objects copied
38 into the vector. Therefore, when using a vector of pointers, the
39 objects pointed to must be long lived, but when dealing with a
40 vector of objects, the source objects need not be.
42 The vectors are implemented using the trailing array idiom, thus
43 they are not resizeable without changing the address of the vector
44 object itself. This means you cannot have variables or fields of
45 vector type -- always use a pointer to a vector. The one exception
46 is the final field of a structure, which could be a vector type.
47 You will have to use the embedded_size & embedded_init calls to
48 create such objects, and they will probably not be resizeable (so
49 don't use the 'safe' allocation variants). The trailing array
50 idiom is used (rather than a pointer to an array of data), because,
51 if we allow NULL to also represent an empty vector, empty vectors
52 occupy minimal space in the structure containing them.
54 Each operation that increases the number of active elements is
55 available in 'quick' and 'safe' variants. The former presumes that
56 there is sufficient allocated space for the operation to succeed
57 (it aborts if there is not). The latter will reallocate the
58 vector, if needed. Reallocation causes an exponential increase in
59 vector size. If you know you will be adding N elements, it would
60 be more efficient to use the reserve operation before adding the
61 elements with the 'quick' operation. You may also use the reserve
62 operation with a -1 operand, to gain control over exactly when
63 reallocation occurs.
65 You should prefer the push and pop operations, as they append and
66 remove from the end of the vector. If you need to remove several
67 items in one go, use the truncate operation. The insert and remove
68 operations allow you to change elements in the middle of the
69 vector. There are two remove operations, one which preserves the
70 element ordering 'ordered_remove', and one which does not
71 'unordered_remove'. The latter function copies the end element
72 into the removed slot, rather than invoke a memmove operation.
74 Vector types are defined using a DEF_VEC_x(TYPEDEF) macro, and
75 variables of vector type are declared using a VEC(TYPEDEF)
76 macro. The 'x' letter indicates whether TYPEDEF is a pointer (P) or
77 object (O) type.
79 An example of their use would be,
81 DEF_VEC_P(tree); // define a vector of tree pointers. This must
82 // appear at file scope.
84 struct my_struct {
85 VEC(tree) *v; // A (pointer to) a vector of tree pointers.
88 struct my_struct *s;
90 if (VEC_length(tree,s->v)) { we have some contents }
91 VEC_safe_push(tree,s->v,decl); // append some decl onto the end
92 for (ix = 0; (t = VEC_iterate(tree,s->v,ix)); ix++)
93 { do something with t }
97 /* Macros to invoke API calls. A single macro works for both pointer
98 and object vectors, but the argument and return types might well be
99 different. In each macro, TDEF is the typedef of the vector
100 elements. Some of these macros pass the vector, V, by reference
101 (by taking its address), this is noted in the descriptions. */
103 /* Length of vector
104 size_t VEC_T_length(const VEC(T) *v);
106 Return the number of active elements in V. V can be NULL, in which
107 case zero is returned. */
108 #define VEC_length(TDEF,V) (VEC_OP(TDEF,length)(V))
110 /* Get the final element of the vector.
111 T VEC_T_last(VEC(T) *v); // Pointer
112 T *VEC_T_last(VEC(T) *v); // Object
114 Return the final element. If V is empty, abort. */
115 #define VEC_last(TDEF,V) (VEC_OP(TDEF,last)(V))
117 /* Index into vector
118 T VEC_T_index(VEC(T) *v, size_t ix); // Pointer
119 T *VEC_T_index(VEC(T) *v, size_t ix); // Object
121 Return the IX'th element. If IX is outside the domain of V,
122 abort. */
123 #define VEC_index(TDEF,V,I) (VEC_OP(TDEF,index)(V,I))
125 /* Iterate over vector
126 T VEC_T_index(VEC(T) *v, size_t ix); // Pointer
127 T *VEC_T_index(VEC(T) *v, size_t ix); // Object
129 Return the IX'th element or NULL. Use this to iterate over the
130 elements of a vector as follows,
132 for (ix = 0; (ptr = VEC_iterate(T,v,ix)); ix++)
133 continue; */
134 #define VEC_iterate(TDEF,V,I) (VEC_OP(TDEF,iterate)(V,I))
136 /* Allocate new vector.
137 VEC(T) *VEC_T_alloc(int reserve);
139 Allocate a new vector with space for RESERVE objects. If RESERVE
140 is <= 0, a default number of slots are created. */
141 #define VEC_alloc(TDEF,A) (VEC_OP(TDEF,alloc)(A MEM_STAT_INFO))
143 /* Use these to determine the required size and initialization of a
144 vector embedded within another structure (as the final member).
146 size_t VEC_T_embedded_size(int reserve);
147 void VEC_T_embedded_init(VEC(T) *v, int reserve);
149 These allow the caller to perform the memory allocation. */
150 #define VEC_embedded_size(TDEF,A) (VEC_OP(TDEF,embedded_size)(A))
151 #define VEC_embedded_init(TDEF,O,A) (VEC_OP(TDEF,embedded_init)(O,A))
153 /* Reserve space.
154 int VEC_T_reserve(VEC(T) *&v, int reserve);
156 Ensure that V has at least RESERVE slots available, if RESERVE is
157 >= 0. If RESERVE < 0, ensure that there is at least one spare
158 slot. These differ in their reallocation behaviour, the first will
159 not create additionsl headroom, but the second mechanism will
160 perform the usual exponential headroom increase. Note this can
161 cause V to be reallocated. Returns non-zero iff reallocation
162 actually occurred. */
163 #define VEC_reserve(TDEF,V,R) (VEC_OP(TDEF,reserve)(&(V),R MEM_STAT_INFO))
165 /* Push object with no reallocation
166 T *VEC_T_quick_push (VEC(T) *v, T obj); // Pointer
167 T *VEC_T_quick_push (VEC(T) *v, T *obj); // Object
169 Push a new element onto the end, returns a pointer to the slot
170 filled in. For object vectors, the new value can be NULL, in which
171 case NO initialization is performed. Aborts if there is
172 insufficient space in the vector. */
173 #define VEC_quick_push(TDEF,V,O) (VEC_OP(TDEF,quick_push)(V,O))
175 /* Push object with reallocation
176 T *VEC_T_safe_push (VEC(T) *&v, T obj); // Pointer
177 T *VEC_T_safe_push (VEC(T) *&v, T *obj); // Object
179 Push a new element onto the end, returns a pointer to the slot
180 filled in. For object vectors, the new value can be NULL, in which
181 case NO initialization is performed. Reallocates V, if needed. */
182 #define VEC_safe_push(TDEF,V,O) (VEC_OP(TDEF,safe_push)(&(V),O MEM_STAT_INFO))
184 /* Pop element off end
185 T VEC_T_pop (VEC(T) *v); // Pointer
186 void VEC_T_pop (VEC(T) *v); // Object
188 Pop the last element off the end. Returns the element popped, for
189 pointer vectors. */
190 #define VEC_pop(TDEF,V) (VEC_OP(TDEF,pop)(V))
192 /* Truncate to specific length
193 void VEC_T_truncate (VEC(T) *v, size_t len);
195 Set the length as specified. This is an O(1) operation. */
196 #define VEC_truncate(TDEF,V,I) (VEC_OP(TDEF,truncate)(V,I))
198 /* Replace element
199 T VEC_T_replace (VEC(T) *v, size_t ix, T val); // Pointer
200 T *VEC_T_replace (VEC(T) *v, size_t ix, T *val); // Object
202 Replace the IXth element of V with a new value, VAL. For pointer
203 vectors returns the original value. For object vectors returns a
204 pointer to the new value. For object vectors the new value can be
205 NULL, in which case no overwriting of the slot is actually
206 performed. */
207 #define VEC_replace(TDEF,V,I,O) (VEC_OP(TDEF,replace)(V,I,O))
209 /* Insert object with no reallocation
210 T *VEC_T_quick_insert (VEC(T) *v, size_t ix, T val); // Pointer
211 T *VEC_T_quick_insert (VEC(T) *v, size_t ix, T *val); // Object
213 Insert an element, VAL, at the IXth position of V. Return a pointer
214 to the slot created. For vectors of object, the new value can be
215 NULL, in which case no initialization of the inserted slot takes
216 place. Aborts if there is insufficient space. */
217 #define VEC_quick_insert(TDEF,V,I,O) (VEC_OP(TDEF,quick_insert)(V,I,O))
219 /* Insert object with reallocation
220 T *VEC_T_safe_insert (VEC(T) *&v, size_t ix, T val); // Pointer
221 T *VEC_T_safe_insert (VEC(T) *&v, size_t ix, T *val); // Object
223 Insert an element, VAL, at the IXth position of V. Return a pointer
224 to the slot created. For vectors of object, the new value can be
225 NULL, in which case no initialization of the inserted slot takes
226 place. Reallocate V, if necessary. */
227 #define VEC_safe_insert(TDEF,V,I,O) (VEC_OP(TDEF,safe_insert)(&(V),I,O MEM_STAT_INFO))
229 /* Remove element retaining order
230 T VEC_T_ordered_remove (VEC(T) *v, size_t ix); // Pointer
231 void VEC_T_ordered_remove (VEC(T) *v, size_t ix); // Object
233 Remove an element from the IXth position of V. Ordering of
234 remaining elements is preserverd. For pointer vectors returns the
235 removed object. This is an O(N) operation due to a memmove. */
236 #define VEC_ordered_remove(TDEF,V,I) (VEC_OP(TDEF,ordered_remove)(V,I))
238 /* Remove element destroying order
239 T VEC_T_unordered_remove (VEC(T) *v, size_t ix); // Pointer
240 void VEC_T_unordered_remove (VEC(T) *v, size_t ix); // Object
242 Remove an element from the IXth position of V. Ordering of
243 remaining elements is destroyed. For pointer vectors returns the
244 removed object. This is an O(1) operation. */
245 #define VEC_unordered_remove(TDEF,V,I) (VEC_OP(TDEF,unordered_remove)(V,I))
247 #if !IN_GENGTYPE
248 /* Reallocate an array of elements with prefix. */
249 extern void *vec_p_reserve (void *, int MEM_STAT_DECL);
250 extern void *vec_o_reserve (void *, int, size_t, size_t MEM_STAT_DECL);
252 #if ENABLE_CHECKING
253 extern void vec_assert_fail (const char *, const char *,
254 const char *, size_t, const char *)
255 ATTRIBUTE_NORETURN;
256 #define VEC_ASSERT_FAIL(OP,VEC) \
257 vec_assert_fail (OP,#VEC,__FILE__,__LINE__,__FUNCTION__)
259 #define VEC_ASSERT(EXPR,OP,TDEF) \
260 (void)((EXPR) ? 0 : (VEC_ASSERT_FAIL(OP,VEC(TDEF)), 0))
261 #else
262 #define VEC_ASSERT(EXPR,OP,TYPE) (void)(EXPR)
263 #endif
265 #define VEC(TDEF) VEC_##TDEF
266 #define VEC_OP(TDEF,OP) VEC_OP_(VEC(TDEF),OP)
267 #define VEC_OP_(VEC,OP) VEC_OP__(VEC,OP)
268 #define VEC_OP__(VEC,OP) VEC ## _ ## OP
269 #else /* IN_GENGTYPE */
270 #define VEC(TDEF) VEC_ TDEF
271 #define VEC_STRINGIFY(X) VEC_STRINGIFY_(X)
272 #define VEC_STRINGIFY_(X) #X
273 #undef GTY
274 #endif /* IN_GENGTYPE */
276 #define VEC_TDEF(TDEF) \
277 typedef struct VEC (TDEF) GTY(()) \
279 size_t num; \
280 size_t alloc; \
281 TDEF GTY ((length ("%h.num"))) vec[1]; \
282 } VEC (TDEF)
284 /* Vector of pointer to object. */
285 #if IN_GENGTYPE
286 {"DEF_VEC_P", VEC_STRINGIFY (VEC_TDEF (#)) ";", NULL},
287 #else
289 #define DEF_VEC_P(TDEF) \
290 VEC_TDEF (TDEF); \
292 static inline size_t VEC_OP (TDEF,length) \
293 (const VEC (TDEF) *vec_) \
295 return vec_ ? vec_->num : 0; \
298 static inline TDEF VEC_OP (TDEF,last) \
299 (const VEC (TDEF) *vec_) \
301 VEC_ASSERT (vec_ && vec_->num, "last", TDEF); \
303 return vec_->vec[vec_->num - 1]; \
306 static inline TDEF VEC_OP (TDEF,index) \
307 (const VEC (TDEF) *vec_, size_t ix_) \
309 VEC_ASSERT (vec_ && ix_ < vec_->num, "index", TDEF); \
311 return vec_->vec[ix_]; \
314 static inline TDEF VEC_OP (TDEF,iterate) \
315 (const VEC (TDEF) *vec_, size_t ix_) \
317 return vec_ && ix_ < vec_->num ? vec_->vec[ix_] : NULL; \
320 static inline VEC (TDEF) *VEC_OP (TDEF,alloc MEM_STAT_DECL) \
321 (int alloc_) \
323 return vec_p_reserve (NULL, alloc_ - !alloc_ PASS_MEM_STAT); \
326 static inline size_t VEC_OP (TDEF,embedded_size) \
327 (int alloc_) \
329 return offsetof (VEC(TDEF),vec) + alloc_ * sizeof(TDEF); \
332 static inline void VEC_OP (TDEF,embedded_init) \
333 (VEC (TDEF) *vec_, int alloc_) \
335 vec_->num = 0; \
336 vec_->alloc = alloc_; \
339 static inline int VEC_OP (TDEF,reserve) \
340 (VEC (TDEF) **vec_, int alloc_ MEM_STAT_DECL) \
342 int extend = !*vec_ || ((*vec_)->alloc - (*vec_)->num \
343 < (size_t)(alloc_ < 0 ? 1 : alloc_)); \
345 if (extend) \
346 *vec_ = vec_p_reserve (*vec_, alloc_ PASS_MEM_STAT); \
348 return extend; \
351 static inline TDEF *VEC_OP (TDEF,quick_push) \
352 (VEC (TDEF) *vec_, TDEF obj_) \
354 TDEF *slot_; \
356 VEC_ASSERT (vec_->num < vec_->alloc, "push", TDEF); \
357 slot_ = &vec_->vec[vec_->num++]; \
358 *slot_ = obj_; \
360 return slot_; \
363 static inline TDEF *VEC_OP (TDEF,safe_push) \
364 (VEC (TDEF) **vec_, TDEF obj_ MEM_STAT_DECL) \
366 VEC_OP (TDEF,reserve) (vec_, -1 PASS_MEM_STAT); \
368 return VEC_OP (TDEF,quick_push) (*vec_, obj_); \
371 static inline TDEF VEC_OP (TDEF,pop) \
372 (VEC (TDEF) *vec_) \
374 TDEF obj_; \
376 VEC_ASSERT (vec_->num, "pop", TDEF); \
377 obj_ = vec_->vec[--vec_->num]; \
379 return obj_; \
382 static inline void VEC_OP (TDEF,truncate) \
383 (VEC (TDEF) *vec_, size_t size_) \
385 VEC_ASSERT (vec_->num >= size_, "truncate", TDEF); \
386 vec_->num = size_; \
389 static inline TDEF VEC_OP (TDEF,replace) \
390 (VEC (TDEF) *vec_, size_t ix_, TDEF obj_) \
392 TDEF old_obj_; \
394 VEC_ASSERT (ix_ < vec_->num, "replace", TDEF); \
395 old_obj_ = vec_->vec[ix_]; \
396 vec_->vec[ix_] = obj_; \
398 return old_obj_; \
401 static inline TDEF *VEC_OP (TDEF,quick_insert) \
402 (VEC (TDEF) *vec_, size_t ix_, TDEF obj_) \
404 TDEF *slot_; \
406 VEC_ASSERT (vec_->num < vec_->alloc, "insert", TDEF); \
407 VEC_ASSERT (ix_ <= vec_->num, "insert", TDEF); \
408 slot_ = &vec_->vec[ix_]; \
409 memmove (slot_ + 1, slot_, vec_->num++ - ix_); \
410 *slot_ = obj_; \
412 return slot_; \
415 static inline TDEF *VEC_OP (TDEF,safe_insert) \
416 (VEC (TDEF) **vec_, size_t ix_, TDEF obj_ MEM_STAT_DECL) \
418 VEC_OP (TDEF,reserve) (vec_, -1 PASS_MEM_STAT); \
420 return VEC_OP (TDEF,quick_insert) (*vec_, ix_, obj_); \
423 static inline TDEF VEC_OP (TDEF,ordered_remove) \
424 (VEC (TDEF) *vec_, size_t ix_) \
426 TDEF *slot_; \
427 TDEF obj_; \
429 VEC_ASSERT (ix_ < vec_->num, "remove", TDEF); \
430 slot_ = &vec_->vec[ix_]; \
431 obj_ = *slot_; \
432 memmove (slot_, slot_ + 1, --vec_->num - ix_); \
434 return obj_; \
437 static inline TDEF VEC_OP (TDEF,unordered_remove) \
438 (VEC (TDEF) *vec_, size_t ix_) \
440 TDEF *slot_; \
441 TDEF obj_; \
443 VEC_ASSERT (ix_ < vec_->num, "remove", TDEF); \
444 slot_ = &vec_->vec[ix_]; \
445 obj_ = *slot_; \
446 *slot_ = vec_->vec[--vec_->num]; \
448 return obj_; \
451 struct vec_swallow_trailing_semi
452 #endif
454 /* Vector of object. */
455 #if IN_GENGTYPE
456 {"DEF_VEC_O", VEC_STRINGIFY (VEC_TDEF (#)) ";", NULL},
457 #else
459 #define DEF_VEC_O(TDEF) \
460 VEC_TDEF (TDEF); \
462 static inline size_t VEC_OP (TDEF,length) \
463 (const VEC (TDEF) *vec_) \
465 return vec_ ? vec_->num : 0; \
468 static inline TDEF *VEC_OP (TDEF,last) \
469 (VEC (TDEF) *vec_) \
471 VEC_ASSERT (vec_ && vec_->num, "last", TDEF); \
473 return &vec_->vec[vec_->num - 1]; \
476 static inline TDEF *VEC_OP (TDEF,index) \
477 (VEC (TDEF) *vec_, size_t ix_) \
479 VEC_ASSERT (vec_ && ix_ < vec_->num, "index", TDEF); \
481 return &vec_->vec[ix_]; \
484 static inline TDEF *VEC_OP (TDEF,iterate) \
485 (VEC (TDEF) *vec_, size_t ix_) \
487 return vec_ && ix_ < vec_->num ? &vec_->vec[ix_] : NULL; \
490 static inline VEC (TDEF) *VEC_OP (TDEF,alloc) \
491 (int alloc_ MEM_STAT_DECL) \
493 return vec_o_reserve (NULL, alloc_ - !alloc_, \
494 offsetof (VEC(TDEF),vec), sizeof (TDEF) \
495 PASS_MEM_STAT); \
498 static inline size_t VEC_OP (TDEF,embedded_size) \
499 (int alloc_) \
501 return offsetof (VEC(TDEF),vec) + alloc_ * sizeof(TDEF); \
504 static inline void VEC_OP (TDEF,embedded_init) \
505 (VEC (TDEF) *vec_, int alloc_) \
507 vec_->num = 0; \
508 vec_->alloc = alloc_; \
511 static inline int VEC_OP (TDEF,reserve) \
512 (VEC (TDEF) **vec_, int alloc_ MEM_STAT_DECL) \
514 int extend = !*vec_ || ((*vec_)->alloc - (*vec_)->num \
515 < (size_t)(alloc_ < 0 ? 1 : alloc_)); \
517 if (extend) \
518 *vec_ = vec_o_reserve (*vec_, alloc_, \
519 offsetof (VEC(TDEF),vec), sizeof (TDEF) \
520 PASS_MEM_STAT); \
522 return extend; \
525 static inline TDEF *VEC_OP (TDEF,quick_push) \
526 (VEC (TDEF) *vec_, const TDEF *obj_) \
528 TDEF *slot_; \
530 VEC_ASSERT (vec_->num < vec_->alloc, "push", TDEF); \
531 slot_ = &vec_->vec[vec_->num++]; \
532 if (obj_) \
533 *slot_ = *obj_; \
535 return slot_; \
538 static inline TDEF *VEC_OP (TDEF,safe_push) \
539 (VEC (TDEF) **vec_, const TDEF *obj_ MEM_STAT_DECL) \
541 VEC_OP (TDEF,reserve) (vec_, -1 PASS_MEM_STAT); \
543 return VEC_OP (TDEF,quick_push) (*vec_, obj_); \
546 static inline void VEC_OP (TDEF,pop) \
547 (VEC (TDEF) *vec_) \
549 VEC_ASSERT (vec_->num, "pop", TDEF); \
550 --vec_->num; \
553 static inline void VEC_OP (TDEF,truncate) \
554 (VEC (TDEF) *vec_, size_t size_) \
556 VEC_ASSERT (vec_->num >= size_, "truncate", TDEF); \
557 vec_->num = size_; \
560 static inline TDEF *VEC_OP (TDEF,replace) \
561 (VEC (TDEF) *vec_, size_t ix_, const TDEF *obj_) \
563 TDEF *slot_; \
565 VEC_ASSERT (ix_ < vec_->num, "replace", TDEF); \
566 slot_ = &vec_->vec[ix_]; \
567 if (obj_) \
568 *slot_ = *obj_; \
570 return slot_; \
573 static inline TDEF *VEC_OP (TDEF,quick_insert) \
574 (VEC (TDEF) *vec_, size_t ix_, const TDEF *obj_) \
576 TDEF *slot_; \
578 VEC_ASSERT (vec_->num < vec_->alloc, "insert", TDEF); \
579 VEC_ASSERT (ix_ <= vec_->num, "insert", TDEF); \
580 slot_ = &vec_->vec[ix_]; \
581 memmove (slot_ + 1, slot_, vec_->num++ - ix_); \
582 if (obj_) \
583 *slot_ = *obj_; \
585 return slot_; \
588 static inline TDEF *VEC_OP (TDEF,safe_insert) \
589 (VEC (TDEF) **vec_, size_t ix_, const TDEF *obj_ MEM_STAT_DECL) \
591 VEC_OP (TDEF,reserve) (vec_, -1 PASS_MEM_STAT); \
593 return VEC_OP (TDEF,quick_insert) (*vec_, ix_, obj_); \
596 static inline void VEC_OP (TDEF,ordered_remove) \
597 (VEC (TDEF) *vec_, size_t ix_) \
599 TDEF *slot_; \
601 VEC_ASSERT (ix_ < vec_->num, "remove", TDEF); \
602 slot_ = &vec_->vec[ix_]; \
603 memmove (slot_, slot_ + 1, --vec_->num - ix_); \
606 static inline void VEC_OP (TDEF,unordered_remove) \
607 (VEC (TDEF) *vec_, size_t ix_) \
609 VEC_ASSERT (ix_ < vec_->num, "remove", TDEF); \
610 vec_->vec[ix_] = vec_->vec[--vec_->num]; \
613 struct vec_swallow_trailing_semi
614 #endif
616 #endif /* GCC_VEC_H */