vector.h File Reference

Vector container support. More...

#include "asterisk/lock.h"

Include dependency graph for vector.h:

Go to the source code of this file.

Data Structures
struct	ast_vector_const_string
struct	ast_vector_int
	Integer vector definition. More...
struct	ast_vector_string
	String vector definitions. More...

Macros
#define	__make_room(idx, vec)
#define	AST_VECTOR(name, type)
	Define a vector structure.
#define	AST_VECTOR_ADD_SORTED(vec, elem, cmp)
	Add an element into a sorted vector.
#define	AST_VECTOR_APPEND(vec, elem)
	Append an element to a vector, growing the vector if needed.
#define	AST_VECTOR_CALLBACK(vec, callback, default_value, ...)
	Execute a callback on every element in a vector returning the first matched.
#define	AST_VECTOR_CALLBACK_MULTIPLE(vec, callback, ...)
	Execute a callback on every element in a vector returning the matching elements in a new vector.
#define	AST_VECTOR_CALLBACK_VOID(vec, callback, ...)
	Execute a callback on every element in a vector disregarding callback return.
#define	AST_VECTOR_COMPACT(vec)
	Resize a vector so that its capacity is the same as its size.
#define	AST_VECTOR_DEFAULT(vec, size, value)
	Default a vector up to size with the given value.
#define	AST_VECTOR_ELEM_CLEANUP_NOOP(elem)
	Vector element cleanup that does nothing.
#define	AST_VECTOR_ELEM_DEFAULT_CMP(elem, value)   ((elem) == (value))
	Default comparator for AST_VECTOR_REMOVE_ELEM_UNORDERED()
#define	AST_VECTOR_FREE(vec)
	Deallocates this vector.
#define	AST_VECTOR_GET(vec, idx)
	Get an element from a vector.
#define	AST_VECTOR_GET_ADDR(vec, idx)
	Get an address of element in a vector.
#define	AST_VECTOR_GET_CMP(vec, value, cmp)
	Get an element from a vector that matches the given comparison.
#define	AST_VECTOR_GET_INDEX(vec, value, cmp)    AST_VECTOR_GET_INDEX_NTH(vec, 1, value, cmp)
	Get the 1st index from a vector that matches the given comparison.
#define	AST_VECTOR_GET_INDEX_NTH(vec, nth, value, cmp)
	Get the nth index from a vector that matches the given comparison.
#define	AST_VECTOR_INIT(vec, size)
	Initialize a vector.
#define	AST_VECTOR_INSERT_AT(vec, idx, elem)
	Insert an element at a specific position in a vector, growing the vector if needed.
#define	AST_VECTOR_MATCH_ALL(element)   (CMP_MATCH)
	Default callback for AST_VECTOR_CALLBACK()
#define	AST_VECTOR_MAX_SIZE(vec)   (vec)->max
	Get the maximum number of elements the vector can currently hold.
#define	AST_VECTOR_PTR_FREE(vec)
	Deallocates this vector pointer.
#define	AST_VECTOR_REMOVE(vec, idx, preserve_ordered)
	Remove an element from a vector by index.
#define	AST_VECTOR_REMOVE_ALL_CMP_ORDERED(vec, value, cmp, cleanup)
	Remove all elements from a vector that matches the given comparison while maintaining order.
#define	AST_VECTOR_REMOVE_ALL_CMP_UNORDERED(vec, value, cmp, cleanup)
	Remove all elements from a vector that matches the given comparison.
#define	AST_VECTOR_REMOVE_CMP_ORDERED(vec, value, cmp, cleanup)
	Remove an element from a vector that matches the given comparison while maintaining order.
#define	AST_VECTOR_REMOVE_CMP_UNORDERED(vec, value, cmp, cleanup)
	Remove an element from a vector that matches the given comparison.
#define	AST_VECTOR_REMOVE_ELEM_ORDERED(vec, elem, cleanup)
	Remove an element from a vector while maintaining order.
#define	AST_VECTOR_REMOVE_ELEM_UNORDERED(vec, elem, cleanup)
	Remove an element from a vector.
#define	AST_VECTOR_REMOVE_ORDERED(vec, idx)    AST_VECTOR_REMOVE(vec, idx, 1)
	Remove an element from a vector by index while maintaining order.
#define	AST_VECTOR_REMOVE_UNORDERED(vec, idx)    AST_VECTOR_REMOVE(vec, idx, 0)
	Remove an element from an unordered vector by index.
#define	AST_VECTOR_REPLACE(vec, idx, elem)
	Replace an element at a specific position in a vector, growing the vector if needed.
#define	AST_VECTOR_RESET(vec, cleanup)
	Reset vector.
#define	AST_VECTOR_RW(name, type)
	Define a vector structure with a read/write lock.
#define	AST_VECTOR_RW_FREE(vec)
	Deallocates this locked vector.
#define	AST_VECTOR_RW_INIT(vec, size)
	Initialize a vector with a read/write lock.
#define	AST_VECTOR_RW_PTR_FREE(vec)
	Deallocates this locked vector pointer.
#define	AST_VECTOR_RW_RDLOCK(vec)   ast_rwlock_rdlock(&(vec)->lock)
	Obtain read lock on vector.
#define	AST_VECTOR_RW_RDLOCK_TIMED(vec, timespec)   ast_rwlock_timedrdlock(&(vec)->lock, timespec)
	Try to obtain read lock on vector failing after timeout if unable.
#define	AST_VECTOR_RW_RDLOCK_TRY(vec)   ast_rwlock_tryrdlock(&(vec)->lock)
	Try to obtain read lock on vector failing immediately if unable.
#define	AST_VECTOR_RW_UNLOCK(vec)   ast_rwlock_unlock(&(vec)->lock)
	Unlock vector.
#define	AST_VECTOR_RW_WRLOCK(vec)   ast_rwlock_wrlock(&(vec)->lock)
	Obtain write lock on vector.
#define	AST_VECTOR_RW_WRLOCK_TIMED(vec, timespec)   ast_rwlock_timedwrlock(&(vec)->lock, timespec)
	Try to obtain write lock on vector failing after timeout if unable.
#define	AST_VECTOR_RW_WRLOCK_TRY(vec)   ast_rwlock_trywrlock(&(vec)->lock)
	Try to obtain write lock on vector failing immediately if unable.
#define	AST_VECTOR_SIZE(vec)   (vec)->current
	Get the number of elements in a vector.
#define	AST_VECTOR_SORT(vec, cmp)
	Sort a vector in-place.
#define	AST_VECTOR_STEAL_ELEMENTS(vec)
	Steal the elements from a vector and reinitialize.

Enumerations
enum	ast_vector_string_split_flags { AST_VECTOR_STRING_SPLIT_NO_TRIM = 0x01 , AST_VECTOR_STRING_SPLIT_ALLOW_EMPTY = 0x02 }

Functions
char *	ast_vector_string_join (struct ast_vector_string *vec, const char *delim)
	Join the elements of a string vector into a single string.
int	ast_vector_string_split (struct ast_vector_string *dest, const char *input, const char *delim, int flags, int(*excludes_cmp)(const char *s1, const char *s2))
	Append a string vector by splitting a string.

Detailed Description

Vector container support.

A vector is a variable length array, with properties that can be useful when order doesn't matter.

• Appends are asymptotically constant time.
• Unordered removes are constant time.
• Search is linear time

Author

David M. Lee, II dlee@.nosp@m.digi.nosp@m.um.co.nosp@m.m

Since

12

Definition in file vector.h.

Macro Definition Documentation

__make_room

#define __make_room	(		idx,
			vec
	)

Definition at line 234 of file vector.h.

                               { \
    int res = 0;                                \
    do {                                                        \
        if ((idx) >= (vec)->max) {                              \
            size_t new_max = ((idx) + 1) * 2;               \
            typeof((vec)->elems) new_elems = ast_calloc(1,      \
                new_max * sizeof(*new_elems));                  \
            if (new_elems) {                                    \
                if ((vec)->elems) {                             \
                    memcpy(new_elems, (vec)->elems,             \
                        (vec)->current * sizeof(*new_elems));   \
                    ast_free((vec)->elems);                     \
                }                                               \
                (vec)->elems = new_elems;                       \
                (vec)->max = new_max;                           \
            } else {                                            \
                res = -1;                                       \
                break;                                          \
            }                                                   \
        }                                                       \
    } while(0);                                                 \
    res;                                                        \
})

AST_VECTOR

#define AST_VECTOR	(		name,
			type
	)

Value:

    struct name {               \
        type *elems;            \
        size_t max;         \
        size_t current;         \
    }

Define a vector structure.

Parameters

name	Optional vector struct name.
type	Vector element type.

Definition at line 44 of file vector.h.

                {               \
        type *elems;            \
        size_t max;         \
        size_t current;         \
    }

AST_VECTOR_ADD_SORTED

#define AST_VECTOR_ADD_SORTED	(		vec,
			elem,
			cmp
	)

Add an element into a sorted vector.

Parameters

vec	Sorted vector to add to.
elem	Element to insert. Must not be an array type.
cmp	A strcmp compatible compare function.

Return values

0	on success.
Non-zero	on failure.

Warning

Use of this macro on an unsorted vector will produce unpredictable results

'elem' must not be an array type so passing 'x' where 'x' is defined as 'char x[4]' will fail to compile. However casting 'x' as 'char *' does result in a value that CAN be used.

Definition at line 382 of file vector.h.

                                               { \
    int res = 0; \
    size_t __idx = (vec)->current; \
    typeof(elem) __elem = (elem); \
    do { \
        if (__make_room((vec)->current, vec) != 0) { \
            res = -1; \
            break; \
        } \
        while (__idx > 0 && (cmp((vec)->elems[__idx - 1], __elem) > 0)) { \
            (vec)->elems[__idx] = (vec)->elems[__idx - 1]; \
            __idx--; \
        } \
        (vec)->elems[__idx] = __elem; \
        (vec)->current++; \
    } while (0); \
    res; \
})

AST_VECTOR_APPEND

#define AST_VECTOR_APPEND	(		vec,
			elem
	)

Append an element to a vector, growing the vector if needed.

Parameters

vec	Vector to append to.
elem	Element to append.

Return values

0	on success.
Non-zero	on failure.

Definition at line 267 of file vector.h.

                                      {                     \
    int res = 0;                                            \
    do {                                                    \
        if (__make_room((vec)->current, vec) != 0) {        \
            res = -1;                                       \
            break;                                          \
        }                                                   \
        (vec)->elems[(vec)->current++] = (elem);            \
    } while (0);                                            \
    res;                                                    \
})

AST_VECTOR_CALLBACK

#define AST_VECTOR_CALLBACK	(		vec,
			callback,
			default_value,
			...
	)

Execute a callback on every element in a vector returning the first matched.

Parameters

vec	Vector to operate on.
callback	A callback that takes at least 1 argument (the element) plus number of optional arguments
default_value	A default value to return if no elements matched

Returns

the first element matched before CMP_STOP was returned or the end of the vector was reached. Otherwise, default_value

Definition at line 776 of file vector.h.

                                                                { \
    size_t idx; \
    typeof((vec)->elems[0]) res = default_value;                \
    for (idx = 0; idx < (vec)->current; idx++) { \
        int rc = callback((vec)->elems[idx], ##__VA_ARGS__);    \
        if (rc & CMP_MATCH) { \
            res = (vec)->elems[idx]; \
            break; \
        }\
        if (rc & CMP_STOP) { \
            break; \
        }\
    } \
    res; \
})

AST_VECTOR_CALLBACK_MULTIPLE

#define AST_VECTOR_CALLBACK_MULTIPLE	(		vec,
			callback,
			...
	)

Execute a callback on every element in a vector returning the matching elements in a new vector.

This macro basically provides a filtered clone.

Parameters

vec	Vector to operate on.
callback	A callback that takes at least 1 argument (the element) plus number of optional arguments

Returns

a vector containing the elements matched before CMP_STOP was returned or the end of the vector was reached. The vector may be empty and could be NULL if there was not enough memory to allocate it's control structure.

Warning

The returned vector must have AST_VECTOR_PTR_FREE() called on it after you've finished with it.

Note

The type of the returned vector must be traceable to the original vector.

The following will result in "error: assignment from incompatible pointer type" because these declare 2 different structures.

AST_VECTOR(, char *) vector_1;
AST_VECTOR(, char *) *vector_2;
 
vector_2 = AST_VECTOR_CALLBACK_MULTIPLE(&vector_1, callback);

This will work because you're using the type of the first to declare the second:

AST_VECTOR(mytype, char *) vector_1;
struct mytype *vector_2 = NULL;
 
vector_2 = AST_VECTOR_CALLBACK_MULTIPLE(&vector_1, callback);

This will also work because you're declaring both vector_1 and vector_2 from the same definition.

AST_VECTOR(, char *) vector_1, *vector_2 = NULL;
 
vector_2 = AST_VECTOR_CALLBACK_MULTIPLE(&vector_1, callback);

Definition at line 840 of file vector.h.

                                                          { \
    size_t idx; \
    typeof((vec)) new_vec; \
    do { \
        new_vec = ast_malloc(sizeof(*new_vec)); \
        if (!new_vec) { \
            break; \
        } \
        if (AST_VECTOR_INIT(new_vec, AST_VECTOR_SIZE((vec))) != 0) { \
            ast_free(new_vec); \
            new_vec = NULL; \
            break; \
        } \
        for (idx = 0; idx < (vec)->current; idx++) { \
            int rc = callback((vec)->elems[idx], ##__VA_ARGS__);    \
            if (rc & CMP_MATCH) { \
                AST_VECTOR_APPEND(new_vec, (vec)->elems[idx]); \
            } \
            if (rc & CMP_STOP) { \
                break; \
            }\
        } \
    } while(0); \
    new_vec; \
})

AST_VECTOR_CALLBACK_VOID

#define AST_VECTOR_CALLBACK_VOID	(		vec,
			callback,
			...
	)

Execute a callback on every element in a vector disregarding callback return.

Parameters

vec	Vector to operate on.
callback	A callback that takes at least 1 argument (the element) plus number of optional arguments

Definition at line 873 of file vector.h.

                                                      { \
    size_t idx; \
    for (idx = 0; idx < (vec)->current; idx++) { \
        callback((vec)->elems[idx], ##__VA_ARGS__); \
    } \
})

AST_VECTOR_COMPACT

#define AST_VECTOR_COMPACT

(

vec

)

Resize a vector so that its capacity is the same as its size.

Parameters

vec	Vector to compact.

Return values

0	on success.
Non-zero	on failure.

Definition at line 649 of file vector.h.

                                 {                  \
    int res = 0;                            \
    do {                                \
        size_t new_max = (vec)->current;            \
        if (new_max == 0) {                 \
            ast_free((vec)->elems);             \
            (vec)->elems = NULL;                \
            (vec)->max = 0;                 \
        } else if ((vec)->max > new_max) {          \
            typeof((vec)->elems) new_elems = ast_realloc(   \
                (vec)->elems,               \
                new_max * sizeof(*new_elems));      \
            if (new_elems) {                \
                (vec)->elems = new_elems;       \
                (vec)->max = new_max;           \
            } else {                    \
                res = -1;               \
                break;                  \
            }                       \
        }                           \
    } while(0);                         \
    res;                                \
})

AST_VECTOR_DEFAULT

#define AST_VECTOR_DEFAULT	(		vec,
			size,
			value
	)

Default a vector up to size with the given value.

Note

If a size of 0 is given then all elements in the given vector are set.

The vector will grow to the given size if needed.

Parameters

vec	Vector to default.
size	The number of elements to default
value	The default value to set each element to

Definition at line 320 of file vector.h.

                                              { \
    int res = 0;                            \
    typeof((size)) __size = (size) ? (size) : AST_VECTOR_SIZE(vec); \
    size_t idx;                         \
    for (idx = 0; idx < __size; ++idx) {                \
        res = AST_VECTOR_REPLACE(vec, idx, value);      \
        if (res == -1) {                    \
            break;                      \
        }                           \
    }                               \
    res;                                \
})

AST_VECTOR_ELEM_CLEANUP_NOOP

#define AST_VECTOR_ELEM_CLEANUP_NOOP

(

elem

)

Vector element cleanup that does nothing.

Parameters

elem	Element to cleanup

Definition at line 582 of file vector.h.

AST_VECTOR_ELEM_DEFAULT_CMP

#define AST_VECTOR_ELEM_DEFAULT_CMP	(		elem,
			value
	)		((elem) == (value))

Default comparator for AST_VECTOR_REMOVE_ELEM_UNORDERED()

Parameters

elem	Element to compare against
value	Value to compare with the vector element.

Return values

0	if element does not match.
Non-zero	if element matches.

Definition at line 575 of file vector.h.

AST_VECTOR_FREE

#define AST_VECTOR_FREE

(

vec

)

Deallocates this vector.

If any code to free the elements of this vector needs to be run, that should be done prior to this call.

Parameters

vec	Vector to deallocate.

Definition at line 185 of file vector.h.

                                {       \
    ast_free((vec)->elems);         \
    (vec)->elems = NULL;            \
    (vec)->max = 0;             \
    (vec)->current = 0;         \
} while (0)

AST_VECTOR_GET

#define AST_VECTOR_GET	(		vec,
			idx
	)

Value:

    ({      \
    size_t __idx = (idx);           \
    ast_assert(__idx < (vec)->current); \
    (vec)->elems[__idx];            \
})

Get an element from a vector.

Parameters

vec	Vector to query.
idx	Index of the element to get.

Definition at line 691 of file vector.h.

                                  {     \
    size_t __idx = (idx);           \
    ast_assert(__idx < (vec)->current); \
    (vec)->elems[__idx];            \
})

AST_VECTOR_GET_ADDR

#define AST_VECTOR_GET_ADDR	(		vec,
			idx
	)

Value:

    ({  \
    size_t __idx = (idx);           \
    ast_assert(__idx < (vec)->current); \
    &(vec)->elems[__idx];           \
})

Get an address of element in a vector.

Parameters

vec	Vector to query.
idx	Index of the element to get address of.

Definition at line 679 of file vector.h.

                                       {    \
    size_t __idx = (idx);           \
    ast_assert(__idx < (vec)->current); \
    &(vec)->elems[__idx];           \
})

AST_VECTOR_GET_CMP

#define AST_VECTOR_GET_CMP	(		vec,
			value,
			cmp
	)

Get an element from a vector that matches the given comparison.

Parameters

vec	Vector to get from.
value	Value to pass into comparator.
cmp	Comparator function/macros (called as cmp(elem, value))

Returns

a pointer to the element that was found or NULL

Definition at line 742 of file vector.h.

                                             { \
    void *res = NULL; \
    size_t idx; \
    typeof(value) __value = (value); \
    for (idx = 0; idx < (vec)->current; ++idx) { \
        if (cmp((vec)->elems[idx], __value)) { \
            res = &(vec)->elems[idx]; \
            break; \
        } \
    } \
    res; \
})

AST_VECTOR_GET_INDEX

#define AST_VECTOR_GET_INDEX	(		vec,
			value,
			cmp
	)		AST_VECTOR_GET_INDEX_NTH(vec, 1, value, cmp)

Get the 1st index from a vector that matches the given comparison.

Parameters

vec	Vector to get from.
value	Value to pass into comparator.
cmp	Comparator function/macros (called as cmp(elem, value))

Returns

a pointer to the element that was found or NULL

Definition at line 730 of file vector.h.

AST_VECTOR_GET_INDEX_NTH

#define AST_VECTOR_GET_INDEX_NTH	(		vec,
			nth,
			value,
			cmp
	)

Get the nth index from a vector that matches the given comparison.

Parameters

vec	Vector to get from.
nth	The nth index to find
value	Value to pass into comparator.
cmp	Comparator function/macros (called as cmp(elem, value))

Returns

a pointer to the element that was found or NULL

Definition at line 707 of file vector.h.

                                                        { \
    int res = -1; \
    size_t idx; \
    typeof(nth) __nth = (nth); \
    typeof(value) __value = (value); \
    for (idx = 0; idx < (vec)->current; ++idx) { \
        if (cmp((vec)->elems[idx], __value) && !(--__nth)) {    \
            res = (int)idx;                 \
            break; \
        } \
    } \
    res; \
})

AST_VECTOR_INIT

#define AST_VECTOR_INIT	(		vec,
			size
	)

Initialize a vector.

If size is 0, then no space will be allocated until the vector is appended to.

Parameters

vec	Vector to initialize.
size	Initial size of the vector.

Return values

0	on success.
Non-zero	on failure.

Definition at line 124 of file vector.h.

                                    {                   \
    size_t __size = (size);                     \
    size_t alloc_size = __size * sizeof(*((vec)->elems));       \
    (vec)->elems = alloc_size ? ast_calloc(1, alloc_size) : NULL;   \
    (vec)->current = 0;                     \
    if ((vec)->elems) {                     \
        (vec)->max = __size;                    \
    } else {                            \
        (vec)->max = 0;                     \
    }                               \
    (alloc_size == 0 || (vec)->elems != NULL) ? 0 : -1;     \
})

AST_VECTOR_INSERT_AT

#define AST_VECTOR_INSERT_AT	(		vec,
			idx,
			elem
	)

Insert an element at a specific position in a vector, growing the vector if needed.

Parameters

vec	Vector to insert into.
idx	Position to insert at.
elem	Element to insert.

Return values

0	on success.
Non-zero	on failure.

Warning

This macro will shift existing elements right to make room for the new element.

Use of this macro with the expectation that the element will remain at the provided index means you can not use the UNORDERED assortment of macros. These macros alter the ordering of the vector itself.

Definition at line 349 of file vector.h.

                                              { \
    int res = 0; \
    size_t __move; \
    do { \
        if (__make_room(((idx) > (vec)->current ? (idx) : (vec)->current), vec) != 0) {                         \
            res = -1;                                       \
            break;                                          \
        }                                                       \
        if ((vec)->current > 0 && (idx) < (vec)->current) { \
            __move = ((vec)->current - (idx)) * sizeof(typeof((vec)->elems[0])); \
            memmove(&(vec)->elems[(idx) + 1], &(vec)->elems[(idx)], __move); \
        } \
        (vec)->elems[(idx)] = (elem); \
        (vec)->current = ((idx) > (vec)->current ? (idx) : (vec)->current) + 1; \
    } while (0); \
    res; \
})

AST_VECTOR_MATCH_ALL

#define AST_VECTOR_MATCH_ALL

(

element

)

(CMP_MATCH)

Default callback for AST_VECTOR_CALLBACK()

Parameters

element

Element to compare against

Return values

CMP_MATCH

always.

Definition at line 762 of file vector.h.

AST_VECTOR_MAX_SIZE

#define AST_VECTOR_MAX_SIZE

(

vec

)

(vec)->max

Get the maximum number of elements the vector can currently hold.

Parameters

vec	Vector to query.

Returns

Maximum number of elements the vector can currently hold.

Definition at line 628 of file vector.h.

AST_VECTOR_PTR_FREE

#define AST_VECTOR_PTR_FREE

(

vec

)

Value:

    do { \
    AST_VECTOR_FREE(vec); \
    ast_free(vec); \
} while (0)

Deallocates this vector pointer.

If any code to free the elements of this vector need to be run, that should be done prior to this call.

Parameters

vec	Pointer to a malloc'd vector structure.

Definition at line 200 of file vector.h.

                                    { \
    AST_VECTOR_FREE(vec); \
    ast_free(vec); \
} while (0)

AST_VECTOR_REMOVE

#define AST_VECTOR_REMOVE	(		vec,
			idx,
			preserve_ordered
	)

Remove an element from a vector by index.

Note that elements in the vector may be reordered, so that the remove can happen in constant time.

Parameters

vec	Vector to remove from.
idx	Index of the element to remove.
preserve_ordered	Preserve the vector order.

Returns

The element that was removed.

Definition at line 423 of file vector.h.

                                                       { \
    typeof((vec)->elems[0]) res; \
    size_t __idx = (idx); \
    ast_assert(__idx < (vec)->current); \
    res = (vec)->elems[__idx]; \
    if ((preserve_ordered)) { \
        size_t __move; \
        __move = ((vec)->current - (__idx) - 1) * sizeof(typeof((vec)->elems[0])); \
        memmove(&(vec)->elems[__idx], &(vec)->elems[__idx + 1], __move); \
        (vec)->current--; \
    } else { \
        (vec)->elems[__idx] = (vec)->elems[--(vec)->current];   \
    }; \
    res;                            \
})

AST_VECTOR_REMOVE_ALL_CMP_ORDERED

#define AST_VECTOR_REMOVE_ALL_CMP_ORDERED	(		vec,
			value,
			cmp,
			cleanup
	)

Remove all elements from a vector that matches the given comparison while maintaining order.

Parameters

vec	Vector to remove from.
value	Value to pass into comparator.
cmp	Comparator function/macros (called as cmp(elem, value))
cleanup	How to cleanup a removed element macro/function.

Returns

the number of deleted elements.

Definition at line 524 of file vector.h.

                                                                     {  \
    int count = 0;                          \
    size_t idx;                         \
    typeof(value) __value = (value);                \
    for (idx = 0; idx < (vec)->current; ) {             \
        if (cmp((vec)->elems[idx], __value)) {          \
            cleanup((vec)->elems[idx]);         \
            AST_VECTOR_REMOVE_ORDERED((vec), idx);      \
            ++count;                    \
        } else {                        \
            ++idx;                      \
        }                           \
    }                               \
    count;                              \
})

AST_VECTOR_REMOVE_ALL_CMP_UNORDERED

#define AST_VECTOR_REMOVE_ALL_CMP_UNORDERED	(		vec,
			value,
			cmp,
			cleanup
	)

Remove all elements from a vector that matches the given comparison.

Parameters

vec	Vector to remove from.
value	Value to pass into comparator.
cmp	Comparator function/macros (called as cmp(elem, value))
cleanup	How to cleanup a removed element macro/function.

Returns

the number of deleted elements.

Definition at line 472 of file vector.h.

                                                                       {    \
    int count = 0;                          \
    size_t idx;                         \
    typeof(value) __value = (value);                \
    for (idx = 0; idx < (vec)->current; ) {             \
        if (cmp((vec)->elems[idx], __value)) {          \
            cleanup((vec)->elems[idx]);         \
            AST_VECTOR_REMOVE_UNORDERED((vec), idx);    \
            ++count;                    \
        } else {                        \
            ++idx;                      \
        }                           \
    }                               \
    count;                              \
})

AST_VECTOR_REMOVE_CMP_ORDERED

#define AST_VECTOR_REMOVE_CMP_ORDERED	(		vec,
			value,
			cmp,
			cleanup
	)

Remove an element from a vector that matches the given comparison while maintaining order.

Parameters

vec	Vector to remove from.
value	Value to pass into comparator.
cmp	Comparator function/macros (called as cmp(elem, value))
cleanup	How to cleanup a removed element macro/function.

Return values

0	if element was removed.
Non-zero	if element was not in the vector.

Definition at line 551 of file vector.h.

                                                                 {  \
    int res = -1;                           \
    size_t idx;                         \
    typeof(value) __value = (value);                \
    for (idx = 0; idx < (vec)->current; ++idx) {            \
        if (cmp((vec)->elems[idx], __value)) {          \
            cleanup((vec)->elems[idx]);         \
            AST_VECTOR_REMOVE_ORDERED((vec), idx);      \
            res = 0;                    \
            break;                      \
        }                           \
    }                               \
    res;                                \
})

AST_VECTOR_REMOVE_CMP_UNORDERED

#define AST_VECTOR_REMOVE_CMP_UNORDERED	(		vec,
			value,
			cmp,
			cleanup
	)

Remove an element from a vector that matches the given comparison.

Parameters

vec	Vector to remove from.
value	Value to pass into comparator.
cmp	Comparator function/macros (called as cmp(elem, value))
cleanup	How to cleanup a removed element macro/function.

Return values

0	if element was removed.
Non-zero	if element was not in the vector.

Definition at line 499 of file vector.h.

                                                                   {    \
    int res = -1;                           \
    size_t idx;                         \
    typeof(value) __value = (value);                \
    for (idx = 0; idx < (vec)->current; ++idx) {            \
        if (cmp((vec)->elems[idx], __value)) {          \
            cleanup((vec)->elems[idx]);         \
            AST_VECTOR_REMOVE_UNORDERED((vec), idx);    \
            res = 0;                    \
            break;                      \
        }                           \
    }                               \
    res;                                \
})

AST_VECTOR_REMOVE_ELEM_ORDERED

#define AST_VECTOR_REMOVE_ELEM_ORDERED	(		vec,
			elem,
			cleanup
	)

Value:

    ({  \
    AST_VECTOR_REMOVE_CMP_ORDERED((vec), (elem),        \
        AST_VECTOR_ELEM_DEFAULT_CMP, cleanup);      \
})

Remove an element from a vector while maintaining order.

Parameters

vec	Vector to remove from.
elem	Element to remove
cleanup	How to cleanup a removed element macro/function.

Return values

0	if element was removed.
Non-zero	if element was not in the vector.

Definition at line 609 of file vector.h.

                                                            {   \
    AST_VECTOR_REMOVE_CMP_ORDERED((vec), (elem),        \
        AST_VECTOR_ELEM_DEFAULT_CMP, cleanup);      \
})

AST_VECTOR_REMOVE_ELEM_UNORDERED

#define AST_VECTOR_REMOVE_ELEM_UNORDERED	(		vec,
			elem,
			cleanup
	)

Value:

    ({  \
    AST_VECTOR_REMOVE_CMP_UNORDERED((vec), (elem),      \
        AST_VECTOR_ELEM_DEFAULT_CMP, cleanup);      \
})

Remove an element from a vector.

Parameters

vec	Vector to remove from.
elem	Element to remove
cleanup	How to cleanup a removed element macro/function.

Return values

0	if element was removed.
Non-zero	if element was not in the vector.

Definition at line 594 of file vector.h.

                                                              { \
    AST_VECTOR_REMOVE_CMP_UNORDERED((vec), (elem),      \
        AST_VECTOR_ELEM_DEFAULT_CMP, cleanup);      \
})

AST_VECTOR_REMOVE_ORDERED

#define AST_VECTOR_REMOVE_ORDERED	(		vec,
			idx
	)		AST_VECTOR_REMOVE(vec, idx, 1)

Remove an element from a vector by index while maintaining order.

Parameters

vec	Vector to remove from.
idx	Index of the element to remove.

Returns

The element that was removed.

Definition at line 459 of file vector.h.

AST_VECTOR_REMOVE_UNORDERED

#define AST_VECTOR_REMOVE_UNORDERED	(		vec,
			idx
	)		AST_VECTOR_REMOVE(vec, idx, 0)

Remove an element from an unordered vector by index.

Note that elements in the vector may be reordered, so that the remove can happen in constant time.

Parameters

vec	Vector to remove from.
idx	Index of the element to remove.

Returns

The element that was removed.

Definition at line 449 of file vector.h.

AST_VECTOR_REPLACE

#define AST_VECTOR_REPLACE	(		vec,
			idx,
			elem
	)

Replace an element at a specific position in a vector, growing the vector if needed.

Parameters

vec	Vector to replace into.
idx	Position to replace.
elem	Element to replace.

Return values

0	on success.
Non-zero	on failure.

Warning

This macro will overwrite anything already present at the position provided.

Use of this macro with the expectation that the element will remain at the provided index means you can not use the UNORDERED assortment of macros. These macros alter the ordering of the vector itself.

Definition at line 295 of file vector.h.

                                            {       \
    int res = 0;                                    \
    do {                                            \
        if (__make_room((idx), vec) != 0) {         \
            res = -1;                               \
            break;                                  \
        }                                           \
        (vec)->elems[(idx)] = (elem);               \
        if (((idx) + 1) > (vec)->current) {         \
            (vec)->current = (idx) + 1;             \
        }                                           \
    } while(0);                                     \
    res;                                            \
})

AST_VECTOR_RESET

#define AST_VECTOR_RESET	(		vec,
			cleanup
	)

Value:

    ({ \
    AST_VECTOR_CALLBACK_VOID(vec, cleanup); \
    (vec)->current = 0; \
})

Reset vector.

Parameters

vec	Vector to reset.
cleanup	A cleanup callback or AST_VECTOR_ELEM_CLEANUP_NOOP.

Definition at line 636 of file vector.h.

                                        { \
    AST_VECTOR_CALLBACK_VOID(vec, cleanup); \
    (vec)->current = 0; \
})

AST_VECTOR_RW

#define AST_VECTOR_RW	(		name,
			type
	)

Define a vector structure with a read/write lock.

Parameters

name	Optional vector struct name.
type	Vector element type.

Definition at line 104 of file vector.h.

                {            \
        type *elems;         \
        size_t max;          \
        size_t current;      \
        ast_rwlock_t lock;   \
    }

AST_VECTOR_RW_FREE

#define AST_VECTOR_RW_FREE

(

vec

)

Value:

    do { \
    AST_VECTOR_FREE(vec); \
    ast_rwlock_destroy(&(vec)->lock); \
} while(0)

Deallocates this locked vector.

If any code to free the elements of this vector need to be run, that should be done prior to this call.

Parameters

vec	Vector to deallocate.

Definition at line 213 of file vector.h.

                                   { \
    AST_VECTOR_FREE(vec); \
    ast_rwlock_destroy(&(vec)->lock); \
} while(0)

AST_VECTOR_RW_INIT

#define AST_VECTOR_RW_INIT	(		vec,
			size
	)

Initialize a vector with a read/write lock.

If size is 0, then no space will be allocated until the vector is appended to.

Parameters

vec	Vector to initialize.
size	Initial size of the vector.

Return values

0	on success.
Non-zero	on failure.

Definition at line 169 of file vector.h.

                                       { \
    int res = -1; \
    if (AST_VECTOR_INIT(vec, size) == 0) { \
        res = ast_rwlock_init(&(vec)->lock); \
    } \
    res; \
})

AST_VECTOR_RW_PTR_FREE

#define AST_VECTOR_RW_PTR_FREE

(

vec

)

Value:

    do { \
    AST_VECTOR_RW_FREE(vec); \
    ast_free(vec); \
} while(0)

Deallocates this locked vector pointer.

If any code to free the elements of this vector need to be run, that should be done prior to this call.

Parameters

vec	Pointer to a malloc'd vector structure.

Definition at line 226 of file vector.h.

                                       { \
    AST_VECTOR_RW_FREE(vec); \
    ast_free(vec); \
} while(0)

AST_VECTOR_RW_RDLOCK

#define AST_VECTOR_RW_RDLOCK

(

vec

)

ast_rwlock_rdlock(&(vec)->lock)

Obtain read lock on vector.

Parameters

vec	Vector to operate on.

Return values

0	if success
Non-zero	if error

Definition at line 888 of file vector.h.

AST_VECTOR_RW_RDLOCK_TIMED

#define AST_VECTOR_RW_RDLOCK_TIMED	(		vec,
			timespec
	)		ast_rwlock_timedrdlock(&(vec)->lock, timespec)

Try to obtain read lock on vector failing after timeout if unable.

Parameters

vec	Vector to operate on.
timespec

Return values

0	if success
Non-zero	if error

Definition at line 939 of file vector.h.

AST_VECTOR_RW_RDLOCK_TRY

#define AST_VECTOR_RW_RDLOCK_TRY

(

vec

)

ast_rwlock_tryrdlock(&(vec)->lock)

Try to obtain read lock on vector failing immediately if unable.

Parameters

vec	Vector to operate on.

Return values

0	if success
Non-zero	if error

Definition at line 918 of file vector.h.

AST_VECTOR_RW_UNLOCK

#define AST_VECTOR_RW_UNLOCK

(

vec

)

ast_rwlock_unlock(&(vec)->lock)

Unlock vector.

Parameters

vec	Vector to operate on.

Return values

0	if success
Non-zero	if error

Definition at line 908 of file vector.h.

AST_VECTOR_RW_WRLOCK

#define AST_VECTOR_RW_WRLOCK

(

vec

)

ast_rwlock_wrlock(&(vec)->lock)

Obtain write lock on vector.

Parameters

vec	Vector to operate on.

Return values

0	if success
Non-zero	if error

Definition at line 898 of file vector.h.

AST_VECTOR_RW_WRLOCK_TIMED

#define AST_VECTOR_RW_WRLOCK_TIMED	(		vec,
			timespec
	)		ast_rwlock_timedwrlock(&(vec)->lock, timespec)

Try to obtain write lock on vector failing after timeout if unable.

Parameters

vec	Vector to operate on.
timespec

Return values

0	if success
Non-zero	if error

Definition at line 950 of file vector.h.

AST_VECTOR_RW_WRLOCK_TRY

#define AST_VECTOR_RW_WRLOCK_TRY

(

vec

)

ast_rwlock_trywrlock(&(vec)->lock)

Try to obtain write lock on vector failing immediately if unable.

Parameters

vec	Vector to operate on.

Return values

0	if success
Non-zero	if error

Definition at line 928 of file vector.h.

AST_VECTOR_SIZE

#define AST_VECTOR_SIZE

(

vec

)

(vec)->current

Get the number of elements in a vector.

Parameters

vec	Vector to query.

Returns

Number of elements in the vector.

Definition at line 620 of file vector.h.

AST_VECTOR_SORT

#define AST_VECTOR_SORT	(		vec,
			cmp
	)

Value:

    ({ \
    qsort((vec)->elems, (vec)->current, sizeof(typeof((vec)->elems[0])), cmp); \
})

Sort a vector in-place.

Parameters

vec	Vector to sort
cmp	A memcmp compatible compare function

Definition at line 407 of file vector.h.

                                   { \
    qsort((vec)->elems, (vec)->current, sizeof(typeof((vec)->elems[0])), cmp); \
})

AST_VECTOR_STEAL_ELEMENTS

#define AST_VECTOR_STEAL_ELEMENTS

(

vec

)

Value:

    ({ \
    typeof((vec)->elems) __elems = (vec)->elems; \
    AST_VECTOR_INIT((vec), 0); \
    (__elems); \
})

Steal the elements from a vector and reinitialize.

Parameters

vec	Vector to operate on.

This allows you to use vector.h to construct a list and use the data as a bare array.

Note

The stolen array must eventually be released using ast_free.

Warning

AST_VECTOR_SIZE and AST_VECTOR_MAX_SIZE are both reset to 0. If either are needed they must be saved to a local variable before stealing the elements.

Definition at line 151 of file vector.h.

                                        { \
    typeof((vec)->elems) __elems = (vec)->elems; \
    AST_VECTOR_INIT((vec), 0); \
    (__elems); \
})

Enumeration Type Documentation

ast_vector_string_split_flags

enum ast_vector_string_split_flags

Options to override default processing of ast_vector_string_split.

Enumerator
AST_VECTOR_STRING_SPLIT_NO_TRIM	Do not trim whitespace from values.
AST_VECTOR_STRING_SPLIT_ALLOW_EMPTY	Append empty strings to the vector.

Definition at line 59 of file vector.h.

                                   {
    /*! Do not trim whitespace from values. */
    AST_VECTOR_STRING_SPLIT_NO_TRIM = 0x01,
    /*! Append empty strings to the vector. */
    AST_VECTOR_STRING_SPLIT_ALLOW_EMPTY = 0x02,
};

Function Documentation

ast_vector_string_join()

char * ast_vector_string_join	(	struct ast_vector_string *	vec,
		const char *	delim
	)

Join the elements of a string vector into a single string.

Parameters

vec	Pointer to the vector.
delim	String to separate elements with.

Return values

Resulting

string. Must be freed with ast_free.

Definition at line 406 of file strings.c.

{
    struct ast_str *buf = ast_str_create(256);
    char *rtn;
    int i;
 
    if (!buf) {
        return NULL;
    }
 
    for (i = 0; i < AST_VECTOR_SIZE(vec); i++) {
        ast_str_append(&buf, 0, "%s%s", AST_VECTOR_GET(vec, i), delim);
    }
    ast_str_truncate(buf, -strlen(delim));
    rtn = ast_strdup(ast_str_buffer(buf));
    ast_free(buf);
    return rtn;
}

References ast_free, ast_str_append(), ast_str_buffer(), ast_str_create, ast_str_truncate(), ast_strdup, AST_VECTOR_GET, AST_VECTOR_SIZE, buf, and NULL.

Referenced by show_sessions_cb().

ast_vector_string_split()

int ast_vector_string_split	(	struct ast_vector_string *	dest,
		const char *	input,
		const char *	delim,
		int	flags,
		int(*)(const char *s1, const char *s2)	excludes_cmp
	)

Append a string vector by splitting a string.

Parameters

dest	Pointer to an initialized vector.
input	String buffer to split.
delim	String delimeter passed to strsep.
flags	Processing options defined by ast_vector_string_split_flags.
excludes_cmp	NULL or a function like strcmp to exclude duplicate strings.

Return values

0	Success
-1	Failure

Note

All elements added to the vector are allocated. The caller is always responsible for calling ast_free on each element in the vector even after failure. It's possible for this function to successfully add some elements before failing.

Definition at line 425 of file strings.c.

{
    char *buf;
    char *cur;
    int no_trim = flags & AST_VECTOR_STRING_SPLIT_NO_TRIM;
    int allow_empty = flags & AST_VECTOR_STRING_SPLIT_ALLOW_EMPTY;
 
    ast_assert(dest != NULL);
    ast_assert(!ast_strlen_zero(delim));
 
    if (ast_strlen_zero(input)) {
        return 0;
    }
 
    buf = ast_strdupa(input);
    while ((cur = strsep(&buf, delim))) {
        if (!no_trim) {
            cur = ast_strip(cur);
        }
 
        if (!allow_empty && ast_strlen_zero(cur)) {
            continue;
        }
 
        if (excludes_cmp && AST_VECTOR_GET_CMP(dest, cur, !excludes_cmp)) {
            continue;
        }
 
        cur = ast_strdup(cur);
        if (!cur || AST_VECTOR_APPEND(dest, cur)) {
            ast_free(cur);
 
            return -1;
        }
    }
 
    return 0;
}

References ast_assert, ast_free, ast_strdup, ast_strdupa, ast_strip(), ast_strlen_zero(), AST_VECTOR_APPEND, AST_VECTOR_GET_CMP, AST_VECTOR_STRING_SPLIT_ALLOW_EMPTY, AST_VECTOR_STRING_SPLIT_NO_TRIM, buf, NULL, and strsep().

Referenced by module_post_register(), and outbound_websocket_validate_cb().