2 * Copyright (c) 2015 Cisco and/or its affiliates.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at:
7 * http://www.apache.org/licenses/LICENSE-2.0
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
16 Copyright (c) 2001, 2002, 2003 Eliot Dresselhaus
18 Permission is hereby granted, free of charge, to any person obtaining
19 a copy of this software and associated documentation files (the
20 "Software"), to deal in the Software without restriction, including
21 without limitation the rights to use, copy, modify, merge, publish,
22 distribute, sublicense, and/or sell copies of the Software, and to
23 permit persons to whom the Software is furnished to do so, subject to
24 the following conditions:
26 The above copyright notice and this permission notice shall be
27 included in all copies or substantial portions of the Software.
29 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
30 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
31 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
32 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
33 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
34 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
35 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
38 #ifndef included_vec_h
39 #define included_vec_h
41 #include <vppinfra/clib.h> /* word, etc */
42 #include <vppinfra/mem.h> /* clib_mem_free */
43 #include <vppinfra/string.h> /* memcpy, memmove */
44 #include <vppinfra/vec_bootstrap.h>
48 CLIB vectors are ubiquitous dynamically resized arrays with by user
49 defined "headers". Many CLIB data structures (e.g. hash, heap,
50 pool) are vectors with various different headers.
52 The memory layout looks like this:
55 user header (aligned to uword boundary)
56 vector length: number of elements
57 user's pointer-> vector element #0
62 The user pointer contains the address of vector element # 0. Null
63 pointer vectors are valid and mean a zero length vector.
65 You can reset the length of an allocated vector to zero via the
66 vec_reset_length(v) macro, or by setting the vector length field to
67 zero (e.g. _vec_len (v) = 0). Vec_reset_length(v) preferred: it
68 understands Null pointers.
70 Typically, the header is not present. Headers allow for other
71 data structures to be built atop CLIB vectors.
73 Users may specify the alignment for data elements via the
76 Vectors elements can be any C type e.g. (int, double, struct bar).
77 This is also true for data types built atop vectors (e.g. heap,
80 Many macros have _a variants supporting alignment of vector data
81 and _h variants supporting non zero length vector headers.
82 The _ha variants support both.
84 Standard programming error: memorize a pointer to the ith element
85 of a vector then expand it. Vectors expand by 3/2, so such code
86 may appear to work for a period of time. Memorize vector indices
90 /** \brief Low-level resize allocation function, usually not called directly
92 @param v pointer to a vector
93 @param length_increment length increment in elements
94 @param data_bytes requested size in bytes
95 @param header_bytes header size in bytes (may be zero)
96 @param data_align alignment (may be zero)
97 @return v_prime pointer to resized vector, may or may not equal v
99 void *vec_resize_allocate_memory (void *v,
100 word length_increment,
102 uword header_bytes, uword data_align);
104 /** \brief Low-level vector resize function, usually not called directly
106 @param v pointer to a vector
107 @param length_increment length increment in elements
108 @param data_bytes requested size in bytes
109 @param header_bytes header size in bytes (may be zero)
110 @param data_align alignment (may be zero)
111 @return v_prime pointer to resized vector, may or may not equal v
115 _vec_resize (void *v,
116 word length_increment,
117 uword data_bytes, uword header_bytes, uword data_align)
119 vec_header_t *vh = _vec_find (v);
120 uword new_data_bytes, aligned_header_bytes;
122 aligned_header_bytes = vec_header_bytes (header_bytes);
124 new_data_bytes = data_bytes + aligned_header_bytes;
126 if (PREDICT_TRUE (v != 0))
128 void *p = v - aligned_header_bytes;
130 /* Vector header must start heap object. */
131 ASSERT (clib_mem_is_heap_object (p));
133 /* Typically we'll not need to resize. */
134 if (new_data_bytes <= clib_mem_size (p))
136 vh->len += length_increment;
141 /* Slow path: call helper function. */
142 return vec_resize_allocate_memory (v, length_increment, data_bytes,
144 clib_max (sizeof (vec_header_t),
148 /** \brief Low-level vector resize predicate
150 @param v pointer to a vector
151 @param length_increment length increment in elements
152 @param data_bytes requested size in bytes
153 @param header_bytes header size in bytes (may be zero)
154 @param data_align alignment (may be zero)
155 @return v_prime pointer to resized vector, may or may not equal v
159 _vec_resize_will_expand (void *v,
160 word length_increment,
161 uword data_bytes, uword header_bytes,
164 vec_header_t *vh = _vec_find (v);
165 uword new_data_bytes, aligned_header_bytes;
167 aligned_header_bytes = vec_header_bytes (header_bytes);
169 new_data_bytes = data_bytes + aligned_header_bytes;
171 if (PREDICT_TRUE (v != 0))
173 void *p = v - aligned_header_bytes;
175 /* Vector header must start heap object. */
176 ASSERT (clib_mem_is_heap_object (p));
178 /* Typically we'll not need to resize. */
179 if (new_data_bytes <= clib_mem_size (p))
181 vh->len += length_increment;
188 /** \brief Predicate function, says whether the supplied vector is a clib heap
189 object (general version).
191 @param v pointer to a vector
192 @param header_bytes vector header size in bytes (may be zero)
195 uword clib_mem_is_vec_h (void *v, uword header_bytes);
198 /** \brief Predicate function, says whether the supplied vector is a clib heap
201 @param v pointer to a vector
205 clib_mem_is_vec (void *v)
207 return clib_mem_is_vec_h (v, 0);
210 /* Local variable naming macro (prevents collisions with other macro naming). */
211 #define _v(var) _vec_##var
213 /** \brief Resize a vector (general version).
214 Add N elements to end of given vector V, return pointer to start of vector.
215 Vector will have room for H header bytes and will have user's data aligned
216 at alignment A (rounded to next power of 2).
218 @param V pointer to a vector
219 @param N number of elements to add
220 @param H header size in bytes (may be zero)
221 @param A alignment (may be zero)
222 @return V (value-result macro parameter)
225 #define vec_resize_ha(V,N,H,A) \
228 word _v(l) = vec_len (V); \
229 V = _vec_resize ((V), _v(n), (_v(l) + _v(n)) * sizeof ((V)[0]), (H), (A)); \
232 /** \brief Resize a vector (no header, unspecified alignment)
233 Add N elements to end of given vector V, return pointer to start of vector.
234 Vector will have room for H header bytes and will have user's data aligned
235 at alignment A (rounded to next power of 2).
237 @param V pointer to a vector
238 @param N number of elements to add
239 @return V (value-result macro parameter)
241 #define vec_resize(V,N) vec_resize_ha(V,N,0,0)
243 /** \brief Resize a vector (no header, alignment specified).
244 Add N elements to end of given vector V, return pointer to start of vector.
245 Vector will have room for H header bytes and will have user's data aligned
246 at alignment A (rounded to next power of 2).
248 @param V pointer to a vector
249 @param N number of elements to add
250 @param A alignment (may be zero)
251 @return V (value-result macro parameter)
254 #define vec_resize_aligned(V,N,A) vec_resize_ha(V,N,0,A)
256 /** \brief Allocate space for N more elements
258 @param V pointer to a vector
259 @param N number of elements to add
260 @param H header size in bytes (may be zero)
261 @param A alignment (may be zero)
262 @return V (value-result macro parameter)
265 #define vec_alloc_ha(V,N,H,A) \
267 uword _v(l) = vec_len (V); \
268 vec_resize_ha (V, N, H, A); \
269 _vec_len (V) = _v(l); \
272 /** \brief Allocate space for N more elements
273 (no header, unspecified alignment)
275 @param V pointer to a vector
276 @param N number of elements to add
277 @return V (value-result macro parameter)
279 #define vec_alloc(V,N) vec_alloc_ha(V,N,0,0)
281 /** \brief Allocate space for N more elements (no header, given alignment)
282 @param V pointer to a vector
283 @param N number of elements to add
284 @param A alignment (may be zero)
285 @return V (value-result macro parameter)
288 #define vec_alloc_aligned(V,N,A) vec_alloc_ha(V,N,0,A)
290 /** \brief Create new vector of given type and length (general version).
291 @param T type of elements in new vector
292 @param N number of elements to add
293 @param H header size in bytes (may be zero)
294 @param A alignment (may be zero)
297 #define vec_new_ha(T,N,H,A) \
300 _vec_resize ((T *) 0, _v(n), _v(n) * sizeof (T), (H), (A)); \
303 /** \brief Create new vector of given type and length
304 (unspecified alignment, no header).
306 @param T type of elements in new vector
307 @param N number of elements to add
310 #define vec_new(T,N) vec_new_ha(T,N,0,0)
311 /** \brief Create new vector of given type and length
312 (alignment specified, no header).
314 @param T type of elements in new vector
315 @param N number of elements to add
316 @param A alignment (may be zero)
319 #define vec_new_aligned(T,N,A) vec_new_ha(T,N,0,A)
321 /** \brief Free vector's memory (general version)
323 @param V pointer to a vector
324 @param H size of header in bytes
325 @return V (value-result parameter, V=0)
327 #define vec_free_h(V,H) \
331 clib_mem_free (vec_header ((V), (H))); \
336 /** \brief Free vector's memory (no header).
337 @param V pointer to a vector
338 @return V (value-result parameter, V=0)
340 #define vec_free(V) vec_free_h(V,0)
342 /**\brief Free vector user header (syntactic sugar)
343 @param h vector header
346 #define vec_free_header(h) clib_mem_free (h)
348 /** \brief Return copy of vector (general version).
350 @param V pointer to a vector
351 @param H size of header in bytes
352 @param A alignment (may be zero)
354 @return Vdup copy of vector
357 #define vec_dup_ha(V,H,A) \
359 __typeof__ ((V)[0]) * _v(v) = 0; \
360 uword _v(l) = vec_len (V); \
363 vec_resize_ha (_v(v), _v(l), (H), (A)); \
364 clib_memcpy (_v(v), (V), _v(l) * sizeof ((V)[0]));\
369 /** \brief Return copy of vector (no header, no alignment)
371 @param V pointer to a vector
372 @return Vdup copy of vector
374 #define vec_dup(V) vec_dup_ha(V,0,0)
376 /** \brief Return copy of vector (no header, alignment specified).
378 @param V pointer to a vector
379 @param A alignment (may be zero)
381 @return Vdup copy of vector
383 #define vec_dup_aligned(V,A) vec_dup_ha(V,0,A)
385 /** \brief Copy a vector, memcpy wrapper. Assumes sizeof(SRC[0]) ==
388 @param DST destination
391 #define vec_copy(DST,SRC) clib_memcpy (DST, SRC, vec_len (DST) * \
394 /** \brief Clone a vector. Make a new vector with the
395 same size as a given vector but possibly with a different type.
397 @param NEW_V pointer to new vector
398 @param OLD_V pointer to old vector
400 #define vec_clone(NEW_V,OLD_V) \
403 (NEW_V) = _vec_resize ((NEW_V), vec_len (OLD_V), \
404 vec_len (OLD_V) * sizeof ((NEW_V)[0]), (0), (0)); \
407 /** \brief Make sure vector is long enough for given index (general version).
409 @param V (possibly NULL) pointer to a vector.
410 @param I vector index which will be valid upon return
411 @param H header size in bytes (may be zero)
412 @param A alignment (may be zero)
413 @return V (value-result macro parameter)
416 #define vec_validate_ha(V,I,H,A) \
419 word _v(l) = vec_len (V); \
420 if (_v(i) >= _v(l)) \
422 vec_resize_ha ((V), 1 + (_v(i) - _v(l)), (H), (A)); \
423 /* Must zero new space since user may have previously \
424 used e.g. _vec_len (v) -= 10 */ \
425 memset ((V) + _v(l), 0, (1 + (_v(i) - _v(l))) * sizeof ((V)[0])); \
429 /** \brief Make sure vector is long enough for given index
430 (no header, unspecified alignment)
432 @param V (possibly NULL) pointer to a vector.
433 @param I vector index which will be valid upon return
434 @return V (value-result macro parameter)
436 #define vec_validate(V,I) vec_validate_ha(V,I,0,0)
438 /** \brief Make sure vector is long enough for given index
439 (no header, specified alignment)
441 @param V (possibly NULL) pointer to a vector.
442 @param I vector index which will be valid upon return
443 @param A alignment (may be zero)
444 @return V (value-result macro parameter)
447 #define vec_validate_aligned(V,I,A) vec_validate_ha(V,I,0,A)
449 /** \brief Make sure vector is long enough for given index
450 and initialize empty space (general version)
452 @param V (possibly NULL) pointer to a vector.
453 @param I vector index which will be valid upon return
454 @param INIT initial value (can be a complex expression!)
455 @param H header size in bytes (may be zero)
456 @param A alignment (may be zero)
457 @return V (value-result macro parameter)
459 #define vec_validate_init_empty_ha(V,I,INIT,H,A) \
462 word _v(l) = vec_len (V); \
463 if (_v(i) >= _v(l)) \
465 vec_resize_ha ((V), 1 + (_v(i) - _v(l)), (H), (A)); \
466 while (_v(l) <= _v(i)) \
468 (V)[_v(l)] = (INIT); \
474 /** \brief Make sure vector is long enough for given index
475 and initialize empty space (no header, unspecified alignment)
477 @param V (possibly NULL) pointer to a vector.
478 @param I vector index which will be valid upon return
479 @param INIT initial value (can be a complex expression!)
480 @param H header size in bytes (may be zero)
481 @param A alignment (may be zero)
482 @return V (value-result macro parameter)
485 #define vec_validate_init_empty(V,I,INIT) \
486 vec_validate_init_empty_ha(V,I,INIT,0,0)
488 /** \brief Make sure vector is long enough for given index
489 and initialize empty space (no header, alignment alignment)
491 @param V (possibly NULL) pointer to a vector.
492 @param I vector index which will be valid upon return
493 @param INIT initial value (can be a complex expression!)
494 @param H header size in bytes (may be zero)
495 @param A alignment (may be zero)
496 @return V (value-result macro parameter)
498 #define vec_validate_init_empty_aligned(V,I,A) \
499 vec_validate_init_empty_ha(V,I,INIT,0,A)
501 /** \brief Add 1 element to end of vector (general version).
503 @param V pointer to a vector
504 @param E element to add
505 @param H header size in bytes (may be zero)
506 @param A alignment (may be zero)
507 @return V (value-result macro parameter)
509 #define vec_add1_ha(V,E,H,A) \
511 word _v(l) = vec_len (V); \
512 V = _vec_resize ((V), 1, (_v(l) + 1) * sizeof ((V)[0]), (H), (A)); \
516 /** \brief Add 1 element to end of vector (unspecified alignment).
518 @param V pointer to a vector
519 @param E element to add
520 @return V (value-result macro parameter)
522 #define vec_add1(V,E) vec_add1_ha(V,E,0,0)
524 /** \brief Add 1 element to end of vector (alignment specified).
526 @param V pointer to a vector
527 @param E element to add
528 @param H header size in bytes (may be zero)
529 @param A alignment (may be zero)
530 @return V (value-result macro parameter)
532 #define vec_add1_aligned(V,E,A) vec_add1_ha(V,E,0,A)
534 /** \brief Add N elements to end of vector V,
535 return pointer to new elements in P. (general version)
537 @param V pointer to a vector
538 @param P pointer to new vector element(s)
539 @param N number of elements to add
540 @param H header size in bytes (may be zero)
541 @param A alignment (may be zero)
542 @return V and P (value-result macro parameters)
544 #define vec_add2_ha(V,P,N,H,A) \
547 word _v(l) = vec_len (V); \
548 V = _vec_resize ((V), _v(n), (_v(l) + _v(n)) * sizeof ((V)[0]), (H), (A)); \
552 /** \brief Add N elements to end of vector V,
553 return pointer to new elements in P. (no header, unspecified alignment)
555 @param V pointer to a vector
556 @param P pointer to new vector element(s)
557 @param N number of elements to add
558 @return V and P (value-result macro parameters)
561 #define vec_add2(V,P,N) vec_add2_ha(V,P,N,0,0)
563 /** \brief Add N elements to end of vector V,
564 return pointer to new elements in P. (no header, alignment specified)
566 @param V pointer to a vector
567 @param P pointer to new vector element(s)
568 @param N number of elements to add
569 @param A alignment (may be zero)
570 @return V and P (value-result macro parameters)
573 #define vec_add2_aligned(V,P,N,A) vec_add2_ha(V,P,N,0,A)
575 /** \brief Add N elements to end of vector V (general version)
577 @param V pointer to a vector
578 @param E pointer to element(s) to add
579 @param N number of elements to add
580 @param H header size in bytes (may be zero)
581 @param A alignment (may be zero)
582 @return V (value-result macro parameter)
584 #define vec_add_ha(V,E,N,H,A) \
587 word _v(l) = vec_len (V); \
588 V = _vec_resize ((V), _v(n), (_v(l) + _v(n)) * sizeof ((V)[0]), (H), (A)); \
589 clib_memcpy ((V) + _v(l), (E), _v(n) * sizeof ((V)[0])); \
592 /** \brief Add N elements to end of vector V (no header, unspecified alignment)
594 @param V pointer to a vector
595 @param E pointer to element(s) to add
596 @param N number of elements to add
597 @return V (value-result macro parameter)
599 #define vec_add(V,E,N) vec_add_ha(V,E,N,0,0)
601 /** \brief Add N elements to end of vector V (no header, specified alignment)
603 @param V pointer to a vector
604 @param E pointer to element(s) to add
605 @param N number of elements to add
606 @param A alignment (may be zero)
607 @return V (value-result macro parameter)
609 #define vec_add_aligned(V,E,N,A) vec_add_ha(V,E,N,0,A)
611 /** \brief Returns last element of a vector and decrements its length
613 @param V pointer to a vector
614 @return E element removed from the end of the vector
618 uword _v(l) = vec_len (V); \
619 ASSERT (_v(l) > 0); \
621 _vec_len (V) = _v (l); \
625 /** \brief Set E to the last element of a vector, decrement vector length
626 @param V pointer to a vector
627 @param E pointer to the last vector element
628 @return E element removed from the end of the vector
629 (value-result macro parameter
632 #define vec_pop2(V,E) \
634 uword _v(l) = vec_len (V); \
635 if (_v(l) > 0) (E) = vec_pop (V); \
639 /** \brief Insert N vector elements starting at element M,
640 initialize new elements (general version).
642 @param V (possibly NULL) pointer to a vector.
643 @param N number of elements to insert
644 @param M insertion point
645 @param INIT initial value (can be a complex expression!)
646 @param H header size in bytes (may be zero)
647 @param A alignment (may be zero)
648 @return V (value-result macro parameter)
650 #define vec_insert_init_empty_ha(V,N,M,INIT,H,A) \
652 word _v(l) = vec_len (V); \
655 V = _vec_resize ((V), \
657 (_v(l) + _v(n))*sizeof((V)[0]), \
659 ASSERT (_v(m) <= _v(l)); \
660 memmove ((V) + _v(m) + _v(n), \
662 (_v(l) - _v(m)) * sizeof ((V)[0])); \
663 memset ((V) + _v(m), INIT, _v(n) * sizeof ((V)[0])); \
666 /** \brief Insert N vector elements starting at element M,
667 initialize new elements to zero (general version)
669 @param V (possibly NULL) pointer to a vector.
670 @param N number of elements to insert
671 @param M insertion point
672 @param H header size in bytes (may be zero)
673 @param A alignment (may be zero)
674 @return V (value-result macro parameter)
676 #define vec_insert_ha(V,N,M,H,A) vec_insert_init_empty_ha(V,N,M,0,H,A)
678 /** \brief Insert N vector elements starting at element M,
679 initialize new elements to zero (no header, unspecified alignment)
681 @param V (possibly NULL) pointer to a vector.
682 @param N number of elements to insert
683 @param M insertion point
684 @return V (value-result macro parameter)
686 #define vec_insert(V,N,M) vec_insert_ha(V,N,M,0,0)
688 /** \brief Insert N vector elements starting at element M,
689 initialize new elements to zero (no header, alignment specified)
691 @param V (possibly NULL) pointer to a vector.
692 @param N number of elements to insert
693 @param M insertion point
694 @param A alignment (may be zero)
695 @return V (value-result macro parameter)
697 #define vec_insert_aligned(V,N,M,A) vec_insert_ha(V,N,M,0,A)
699 /** \brief Insert N vector elements starting at element M,
700 initialize new elements (no header, unspecified alignment)
702 @param V (possibly NULL) pointer to a vector.
703 @param N number of elements to insert
704 @param M insertion point
705 @param INIT initial value (can be a complex expression!)
706 @return V (value-result macro parameter)
709 #define vec_insert_init_empty(V,N,M,INIT) \
710 vec_insert_init_empty_ha(V,N,M,INIT,0,0)
711 /* Resize vector by N elements starting from element M, initialize new elements to INIT (alignment specified, no header). */
713 /** \brief Insert N vector elements starting at element M,
714 initialize new elements (no header, specified alignment)
716 @param V (possibly NULL) pointer to a vector.
717 @param N number of elements to insert
718 @param M insertion point
719 @param INIT initial value (can be a complex expression!)
720 @param A alignment (may be zero)
721 @return V (value-result macro parameter)
723 #define vec_insert_init_empty_aligned(V,N,M,INIT,A) \
724 vec_insert_init_empty_ha(V,N,M,INIT,0,A)
726 /** \brief Insert N vector elements starting at element M,
727 insert given elements (general version)
729 @param V (possibly NULL) pointer to a vector.
730 @param E element(s) to insert
731 @param N number of elements to insert
732 @param M insertion point
733 @param H header size in bytes (may be zero)
734 @param A alignment (may be zero)
735 @return V (value-result macro parameter)
738 #define vec_insert_elts_ha(V,E,N,M,H,A) \
740 word _v(l) = vec_len (V); \
743 V = _vec_resize ((V), \
745 (_v(l) + _v(n))*sizeof((V)[0]), \
747 ASSERT (_v(m) <= _v(l)); \
748 memmove ((V) + _v(m) + _v(n), \
750 (_v(l) - _v(m)) * sizeof ((V)[0])); \
751 clib_memcpy ((V) + _v(m), (E), \
752 _v(n) * sizeof ((V)[0])); \
755 /** \brief Insert N vector elements starting at element M,
756 insert given elements (no header, unspecified alignment)
758 @param V (possibly NULL) pointer to a vector.
759 @param E element(s) to insert
760 @param N number of elements to insert
761 @param M insertion point
762 @return V (value-result macro parameter)
764 #define vec_insert_elts(V,E,N,M) vec_insert_elts_ha(V,E,N,M,0,0)
766 /** \brief Insert N vector elements starting at element M,
767 insert given elements (no header, specified alignment)
769 @param V (possibly NULL) pointer to a vector.
770 @param E element(s) to insert
771 @param N number of elements to insert
772 @param M insertion point
773 @param A alignment (may be zero)
774 @return V (value-result macro parameter)
776 #define vec_insert_elts_aligned(V,E,N,M,A) vec_insert_elts_ha(V,E,N,M,0,A)
778 /** \brief Delete N elements starting at element M
780 @param V pointer to a vector
781 @param N number of elements to delete
782 @param M first element to delete
783 @return V (value-result macro parameter)
785 #define vec_delete(V,N,M) \
787 word _v(l) = vec_len (V); \
790 /* Copy over deleted elements. */ \
791 if (_v(l) - _v(n) - _v(m) > 0) \
792 memmove ((V) + _v(m), (V) + _v(m) + _v(n), \
793 (_v(l) - _v(n) - _v(m)) * sizeof ((V)[0])); \
794 /* Zero empty space at end (for future re-allocation). */ \
796 memset ((V) + _v(l) - _v(n), 0, _v(n) * sizeof ((V)[0])); \
797 _vec_len (V) -= _v(n); \
800 /** \brief Delete the element at index I
802 @param V pointer to a vector
803 @param I index to delete
805 #define vec_del1(v,i) \
807 uword _vec_del_l = _vec_len (v) - 1; \
808 uword _vec_del_i = (i); \
809 if (_vec_del_i < _vec_del_l) \
810 (v)[_vec_del_i] = (v)[_vec_del_l]; \
811 _vec_len (v) = _vec_del_l; \
814 /** \brief Append v2 after v1. Result in v1.
815 @param V1 target vector
816 @param V2 vector to append
819 #define vec_append(v1,v2) \
821 uword _v(l1) = vec_len (v1); \
822 uword _v(l2) = vec_len (v2); \
824 v1 = _vec_resize ((v1), _v(l2), \
825 (_v(l1) + _v(l2)) * sizeof ((v1)[0]), 0, 0); \
826 clib_memcpy ((v1) + _v(l1), (v2), _v(l2) * sizeof ((v2)[0])); \
829 /** \brief Append v2 after v1. Result in v1. Specified alignment.
830 @param V1 target vector
831 @param V2 vector to append
832 @param align required alignment
835 #define vec_append_aligned(v1,v2,align) \
837 uword _v(l1) = vec_len (v1); \
838 uword _v(l2) = vec_len (v2); \
840 v1 = _vec_resize ((v1), _v(l2), \
841 (_v(l1) + _v(l2)) * sizeof ((v1)[0]), 0, align); \
842 clib_memcpy ((v1) + _v(l1), (v2), _v(l2) * sizeof ((v2)[0])); \
845 /** \brief Prepend v2 before v1. Result in v1.
846 @param V1 target vector
847 @param V2 vector to prepend
850 #define vec_prepend(v1,v2) \
852 uword _v(l1) = vec_len (v1); \
853 uword _v(l2) = vec_len (v2); \
855 v1 = _vec_resize ((v1), _v(l2), \
856 (_v(l1) + _v(l2)) * sizeof ((v1)[0]), 0, 0); \
857 memmove ((v1) + _v(l2), (v1), _v(l1) * sizeof ((v1)[0])); \
858 clib_memcpy ((v1), (v2), _v(l2) * sizeof ((v2)[0])); \
861 /** \brief Prepend v2 before v1. Result in v1. Specified alignment
862 @param V1 target vector
863 @param V2 vector to prepend
864 @param align required alignment
867 #define vec_prepend_aligned(v1,v2,align) \
869 uword _v(l1) = vec_len (v1); \
870 uword _v(l2) = vec_len (v2); \
872 v1 = _vec_resize ((v1), _v(l2), \
873 (_v(l1) + _v(l2)) * sizeof ((v1)[0]), 0, align); \
874 memmove ((v1) + _v(l2), (v1), _v(l1) * sizeof ((v1)[0])); \
875 clib_memcpy ((v1), (v2), _v(l2) * sizeof ((v2)[0])); \
879 /** \brief Zero all vector elements. Null-pointer tolerant.
880 @param var Vector to zero
882 #define vec_zero(var) \
885 memset ((var), 0, vec_len (var) * sizeof ((var)[0])); \
888 /** \brief Set all vector elements to given value. Null-pointer tolerant.
889 @param v vector to set
890 @param val value for each vector element
892 #define vec_set(v,val) \
895 __typeof__ ((v)[0]) _val = (val); \
896 for (_v(i) = 0; _v(i) < vec_len (v); _v(i)++) \
901 #include <stdlib.h> /* for qsort */
904 /** \brief Compare two vectors, not NULL-pointer tolerant
906 @param v1 Pointer to a vector
907 @param v2 Pointer to a vector
908 @return 1 if equal, 0 if unequal
910 #define vec_is_equal(v1,v2) \
911 (vec_len (v1) == vec_len (v2) && ! memcmp ((v1), (v2), vec_len (v1) * sizeof ((v1)[0])))
913 /** \brief Compare two vectors (only applicable to vectors of signed numbers).
914 Used in qsort compare functions.
916 @param v1 Pointer to a vector
917 @param v2 Pointer to a vector
920 #define vec_cmp(v1,v2) \
922 word _v(i), _v(cmp), _v(l); \
923 _v(l) = clib_min (vec_len (v1), vec_len (v2)); \
925 for (_v(i) = 0; _v(i) < _v(l); _v(i)++) { \
926 _v(cmp) = (v1)[_v(i)] - (v2)[_v(i)]; \
930 if (_v(cmp) == 0 && _v(l) > 0) \
931 _v(cmp) = vec_len(v1) - vec_len(v2); \
932 (_v(cmp) < 0 ? -1 : (_v(cmp) > 0 ? +1 : 0)); \
935 /** \brief Search a vector for the index of the entry that matches.
937 @param v1 Pointer to a vector
938 @param v2 Entry to match
939 @return index of match or ~0
941 #define vec_search(v,E) \
944 while (_v(i) < vec_len(v)) \
950 if (_v(i) == vec_len(v)) \
955 /** \brief Sort a vector using the supplied element comparison function
957 @param vec vector to sort
958 @param f comparison function
960 #define vec_sort_with_function(vec,f) \
962 qsort (vec, vec_len (vec), sizeof (vec[0]), (void *) (f)); \
965 /** \brief Make a vector containing a NULL terminated c-string.
967 @param V (possibly NULL) pointer to a vector.
968 @param S pointer to string buffer.
969 @param L string length (NOT including the terminating NULL; a la strlen())
971 #define vec_validate_init_c_string(V, S, L) \
973 vec_reset_length (V); \
974 vec_validate ((V), (L)); \
976 clib_memcpy ((V), (S), (L)); \
981 /** \brief Test whether a vector is a NULL terminated c-string.
983 @param V (possibly NULL) pointer to a vector.
984 @return BOOLEAN indicating if the vector c-string is null terminated.
986 #define vec_c_string_is_terminated(V) \
987 (((V) != 0) && (vec_len (V) != 0) && ((V)[vec_len ((V)) - 1] == 0))
989 /** \brief (If necessary) NULL terminate a vector containing a c-string.
991 @param V (possibly NULL) pointer to a vector.
992 @return V (value-result macro parameter)
994 #define vec_terminate_c_string(V) \
996 u32 vl = vec_len ((V)); \
997 if (!vec_c_string_is_terminated(V)) \
999 vec_validate ((V), vl); \
1004 #endif /* included_vec_h */
1008 * fd.io coding-style-patch-verification: ON
1011 * eval: (c-set-style "gnu")