Vector container support. More...

#include "asterisk/lock.h"

Include dependency graph for vector.h:

This graph shows which files directly or indirectly include 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. More...

#define	AST_VECTOR_ADD_SORTED(vec, elem, cmp)
	Add an element into a sorted vector. More...

#define	AST_VECTOR_APPEND(vec, elem)
	Append an element to a vector, growing the vector if needed. More...

#define	AST_VECTOR_CALLBACK(vec, callback, default_value, ...)
	Execute a callback on every element in a vector returning the first matched. More...

#define	AST_VECTOR_CALLBACK_MULTIPLE(vec, callback, ...)
	Execute a callback on every element in a vector returning the matching elements in a new vector. More...

#define	AST_VECTOR_CALLBACK_VOID(vec, callback, ...)
	Execute a callback on every element in a vector disregarding callback return. More...

#define	AST_VECTOR_COMPACT(vec)
	Resize a vector so that its capacity is the same as its size. More...

#define	AST_VECTOR_DEFAULT(vec, size, value)
	Default a vector up to size with the given value. More...

#define	AST_VECTOR_ELEM_CLEANUP_NOOP(elem)
	Vector element cleanup that does nothing. More...

#define	AST_VECTOR_ELEM_DEFAULT_CMP(elem, value) ((elem) == (value))
	Default comparator for AST_VECTOR_REMOVE_ELEM_UNORDERED() More...

#define	AST_VECTOR_FREE(vec)
	Deallocates this vector. More...

#define	AST_VECTOR_GET(vec, idx)
	Get an element from a vector. More...

#define	AST_VECTOR_GET_ADDR(vec, idx)
	Get an address of element in a vector. More...

#define	AST_VECTOR_GET_CMP(vec, value, cmp)
	Get an element from a vector that matches the given comparison. More...

#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. More...

#define	AST_VECTOR_GET_INDEX_NTH(vec, nth, value, cmp)
	Get the nth index from a vector that matches the given comparison. More...

#define	AST_VECTOR_INIT(vec, size)
	Initialize a vector. More...

#define	AST_VECTOR_INSERT_AT(vec, idx, elem)
	Insert an element at a specific position in a vector, growing the vector if needed. More...

#define	AST_VECTOR_MATCH_ALL(element) (CMP_MATCH)
	Default callback for AST_VECTOR_CALLBACK() More...

#define	AST_VECTOR_MAX_SIZE(vec) (vec)->max
	Get the maximum number of elements the vector can currently hold. More...

#define	AST_VECTOR_PTR_FREE(vec)
	Deallocates this vector pointer. More...

#define	AST_VECTOR_REMOVE(vec, idx, preserve_ordered)
	Remove an element from a vector by index. More...

#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. More...

#define	AST_VECTOR_REMOVE_ALL_CMP_UNORDERED(vec, value, cmp, cleanup)
	Remove all elements from a vector that matches the given comparison. More...

#define	AST_VECTOR_REMOVE_CMP_ORDERED(vec, value, cmp, cleanup)
	Remove an element from a vector that matches the given comparison while maintaining order. More...

#define	AST_VECTOR_REMOVE_CMP_UNORDERED(vec, value, cmp, cleanup)
	Remove an element from a vector that matches the given comparison. More...

#define	AST_VECTOR_REMOVE_ELEM_ORDERED(vec, elem, cleanup)
	Remove an element from a vector while maintaining order. More...

#define	AST_VECTOR_REMOVE_ELEM_UNORDERED(vec, elem, cleanup)
	Remove an element from a vector. More...

#define	AST_VECTOR_REMOVE_ORDERED(vec, idx) AST_VECTOR_REMOVE(vec, idx, 1)
	Remove an element from a vector by index while maintaining order. More...

#define	AST_VECTOR_REMOVE_UNORDERED(vec, idx) AST_VECTOR_REMOVE(vec, idx, 0)
	Remove an element from an unordered vector by index. More...

#define	AST_VECTOR_REPLACE(vec, idx, elem)
	Replace an element at a specific position in a vector, growing the vector if needed. More...

#define	AST_VECTOR_RESET(vec, cleanup)
	Reset vector. More...

#define	AST_VECTOR_RW(name, type)
	Define a vector structure with a read/write lock. More...

#define	AST_VECTOR_RW_FREE(vec)
	Deallocates this locked vector. More...

#define	AST_VECTOR_RW_INIT(vec, size)
	Initialize a vector with a read/write lock. More...

#define	AST_VECTOR_RW_PTR_FREE(vec)
	Deallocates this locked vector pointer. More...

#define	AST_VECTOR_RW_RDLOCK(vec) ast_rwlock_rdlock(&(vec)->lock)
	Obtain read lock on vector. More...

#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. More...

#define	AST_VECTOR_RW_RDLOCK_TRY(vec) ast_rwlock_tryrdlock(&(vec)->lock)
	Try to obtain read lock on vector failing immediately if unable. More...

#define	AST_VECTOR_RW_UNLOCK(vec) ast_rwlock_unlock(&(vec)->lock)
	Unlock vector. More...

#define	AST_VECTOR_RW_WRLOCK(vec) ast_rwlock_wrlock(&(vec)->lock)
	Obtain write lock on vector. More...

#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. More...

#define	AST_VECTOR_RW_WRLOCK_TRY(vec) ast_rwlock_trywrlock(&(vec)->lock)
	Try to obtain write lock on vector failing immediately if unable. More...

#define	AST_VECTOR_SIZE(vec) (vec)->current
	Get the number of elements in a vector. More...

#define	AST_VECTOR_SORT(vec, cmp)
	Sort a vector in-place. More...

#define	AST_VECTOR_STEAL_ELEMENTS(vec)
	Steal the elements from a vector and reinitialize. More...

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

Functions
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. More...

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 223 of file vector.h.

◆ 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.

◆ 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 371 of file vector.h.

◆ 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 256 of file vector.h.

◆ 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 765 of file vector.h.

◆ 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 829 of file vector.h.

◆ 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 862 of file vector.h.

◆ 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 638 of file vector.h.

◆ 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 309 of file vector.h.

◆ 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 571 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 564 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 174 of file vector.h.

◆ 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 680 of file vector.h.

◆ 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 668 of file vector.h.

◆ 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 731 of file vector.h.

◆ 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 719 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 696 of file vector.h.

◆ 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 113 of file vector.h.

◆ 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 338 of file vector.h.

◆ 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 751 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 617 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 189 of file vector.h.

◆ 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 412 of file vector.h.

◆ 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 513 of file vector.h.

◆ 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 461 of file vector.h.

◆ 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 540 of file vector.h.

◆ 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 488 of file vector.h.

◆ 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 598 of file vector.h.

◆ 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 583 of file vector.h.

◆ 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 448 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 438 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 284 of file vector.h.

◆ 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 625 of file vector.h.

◆ 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 93 of file vector.h.

◆ 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 202 of file vector.h.

◆ 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 158 of file vector.h.

◆ 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 215 of file vector.h.

◆ 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 877 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 928 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 907 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 897 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 887 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 939 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 917 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 609 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 396 of file vector.h.

◆ 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 140 of file vector.h.

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_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 392 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, input(), NULL, and strsep().

Referenced by module_post_register().

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ __make_room

◆ AST_VECTOR

◆ AST_VECTOR_ADD_SORTED

◆ AST_VECTOR_APPEND

◆ AST_VECTOR_CALLBACK

◆ AST_VECTOR_CALLBACK_MULTIPLE

◆ AST_VECTOR_CALLBACK_VOID

◆ AST_VECTOR_COMPACT

◆ AST_VECTOR_DEFAULT

◆ AST_VECTOR_ELEM_CLEANUP_NOOP

◆ AST_VECTOR_ELEM_DEFAULT_CMP

◆ AST_VECTOR_FREE

◆ AST_VECTOR_GET

◆ AST_VECTOR_GET_ADDR

◆ AST_VECTOR_GET_CMP

◆ AST_VECTOR_GET_INDEX

◆ AST_VECTOR_GET_INDEX_NTH

◆ AST_VECTOR_INIT

◆ AST_VECTOR_INSERT_AT

◆ AST_VECTOR_MATCH_ALL

◆ AST_VECTOR_MAX_SIZE

◆ AST_VECTOR_PTR_FREE

◆ AST_VECTOR_REMOVE

◆ AST_VECTOR_REMOVE_ALL_CMP_ORDERED

◆ AST_VECTOR_REMOVE_ALL_CMP_UNORDERED

◆ AST_VECTOR_REMOVE_CMP_ORDERED

◆ AST_VECTOR_REMOVE_CMP_UNORDERED

◆ AST_VECTOR_REMOVE_ELEM_ORDERED

◆ AST_VECTOR_REMOVE_ELEM_UNORDERED

◆ AST_VECTOR_REMOVE_ORDERED

◆ AST_VECTOR_REMOVE_UNORDERED

◆ AST_VECTOR_REPLACE

◆ AST_VECTOR_RESET

◆ AST_VECTOR_RW

◆ AST_VECTOR_RW_FREE

◆ AST_VECTOR_RW_INIT

◆ AST_VECTOR_RW_PTR_FREE

◆ AST_VECTOR_RW_RDLOCK

◆ AST_VECTOR_RW_RDLOCK_TIMED

◆ AST_VECTOR_RW_RDLOCK_TRY

◆ AST_VECTOR_RW_UNLOCK

◆ AST_VECTOR_RW_WRLOCK

◆ AST_VECTOR_RW_WRLOCK_TIMED

◆ AST_VECTOR_RW_WRLOCK_TRY

◆ AST_VECTOR_SIZE

◆ AST_VECTOR_SORT

◆ AST_VECTOR_STEAL_ELEMENTS

Enumeration Type Documentation

◆ ast_vector_string_split_flags

Function Documentation

◆ ast_vector_string_split()