Asterisk - The Open Source Telephony Project GIT-master-3dae2cf
Data Structures | Macros | Enumerations | Functions
vector.h File Reference

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:

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

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 max(a, b)
Definition: f2c.h:198
static const char name[]
Definition: format_mp3.c:68
size_t current
Definition: main/cli.c:113
struct ast_cli_entry ** elems
Definition: main/cli.c:113

Define a vector structure.

Parameters
nameOptional vector struct name.
typeVector 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
vecSorted vector to add to.
elemElement to insert. Must not be an array type.
cmpA strcmp compatible compare function.
Return values
0on success.
Non-zeroon 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
vecVector to append to.
elemElement to append.
Return values
0on success.
Non-zeroon 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
vecVector to operate on.
callbackA callback that takes at least 1 argument (the element) plus number of optional arguments
default_valueA 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
vecVector to operate on.
callbackA 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);
#define AST_VECTOR_CALLBACK_MULTIPLE(vec, callback,...)
Execute a callback on every element in a vector returning the matching elements in a new vector.
Definition: vector.h:829
#define AST_VECTOR(name, type)
Define a vector structure.
Definition: vector.h:44

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);
#define NULL
Definition: resample.c:96

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
vecVector to operate on.
callbackA 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
vecVector to compact.
Return values
0on success.
Non-zeroon 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
vecVector to default.
sizeThe number of elements to default
valueThe 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
elemElement 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
elemElement to compare against
valueValue to compare with the vector element.
Return values
0if element does not match.
Non-zeroif 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
vecVector 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
vecVector to query.
idxIndex 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
vecVector to query.
idxIndex 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
vecVector to get from.
valueValue to pass into comparator.
cmpComparator 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
vecVector to get from.
valueValue to pass into comparator.
cmpComparator 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
vecVector to get from.
nthThe nth index to find
valueValue to pass into comparator.
cmpComparator 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
vecVector to initialize.
sizeInitial size of the vector.
Return values
0on success.
Non-zeroon 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
vecVector to insert into.
idxPosition to insert at.
elemElement to insert.
Return values
0on success.
Non-zeroon 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
elementElement to compare against
Return values
CMP_MATCHalways.

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
vecVector 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
vecPointer 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
vecVector to remove from.
idxIndex of the element to remove.
preserve_orderedPreserve 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
vecVector to remove from.
valueValue to pass into comparator.
cmpComparator function/macros (called as cmp(elem, value))
cleanupHow 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
vecVector to remove from.
valueValue to pass into comparator.
cmpComparator function/macros (called as cmp(elem, value))
cleanupHow 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
vecVector to remove from.
valueValue to pass into comparator.
cmpComparator function/macros (called as cmp(elem, value))
cleanupHow to cleanup a removed element macro/function.
Return values
0if element was removed.
Non-zeroif 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
vecVector to remove from.
valueValue to pass into comparator.
cmpComparator function/macros (called as cmp(elem, value))
cleanupHow to cleanup a removed element macro/function.
Return values
0if element was removed.
Non-zeroif 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), \
})
static void * cleanup(void *unused)
Definition: pbx_realtime.c:124
#define AST_VECTOR_ELEM_DEFAULT_CMP(elem, value)
Default comparator for AST_VECTOR_REMOVE_ELEM_UNORDERED()
Definition: vector.h:564

Remove an element from a vector while maintaining order.

Parameters
vecVector to remove from.
elemElement to remove
cleanupHow to cleanup a removed element macro/function.
Return values
0if element was removed.
Non-zeroif 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), \
})

Remove an element from a vector.

Parameters
vecVector to remove from.
elemElement to remove
cleanupHow to cleanup a removed element macro/function.
Return values
0if element was removed.
Non-zeroif 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
vecVector to remove from.
idxIndex 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
vecVector to remove from.
idxIndex 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
vecVector to replace into.
idxPosition to replace.
elemElement to replace.
Return values
0on success.
Non-zeroon 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
vecVector to reset.
cleanupA 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
nameOptional vector struct name.
typeVector 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)
ast_mutex_t lock
Definition: app_sla.c:331

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
vecVector 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
vecVector to initialize.
sizeInitial size of the vector.
Return values
0on success.
Non-zeroon 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
vecPointer 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
vecVector to operate on.
Return values
0if success
Non-zeroif 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
vecVector to operate on.
timespec
Return values
0if success
Non-zeroif 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
vecVector to operate on.
Return values
0if success
Non-zeroif 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
vecVector to operate on.
Return values
0if success
Non-zeroif 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
vecVector to operate on.
Return values
0if success
Non-zeroif 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
vecVector to operate on.
timespec
Return values
0if success
Non-zeroif 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
vecVector to operate on.
Return values
0if success
Non-zeroif 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
vecVector 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); \
})
typedef typeof(dummy_tv_var_for_types.tv_sec) ast_time_t

Sort a vector in-place.

Parameters
vecVector to sort
cmpA 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
vecVector 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

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.

59 {
60 /*! Do not trim whitespace from values. */
62 /*! Append empty strings to the vector. */
64};
@ AST_VECTOR_STRING_SPLIT_NO_TRIM
Definition: vector.h:61
@ AST_VECTOR_STRING_SPLIT_ALLOW_EMPTY
Definition: vector.h:63

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
destPointer to an initialized vector.
inputString buffer to split.
delimString delimeter passed to strsep.
flagsProcessing options defined by ast_vector_string_split_flags.
excludes_cmpNULL or a function like strcmp to exclude duplicate strings.
Return values
0Success
-1Failure
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.

395{
396 char *buf;
397 char *cur;
398 int no_trim = flags & AST_VECTOR_STRING_SPLIT_NO_TRIM;
399 int allow_empty = flags & AST_VECTOR_STRING_SPLIT_ALLOW_EMPTY;
400
401 ast_assert(dest != NULL);
403
404 if (ast_strlen_zero(input)) {
405 return 0;
406 }
407
409 while ((cur = strsep(&buf, delim))) {
410 if (!no_trim) {
411 cur = ast_strip(cur);
412 }
413
414 if (!allow_empty && ast_strlen_zero(cur)) {
415 continue;
416 }
417
418 if (excludes_cmp && AST_VECTOR_GET_CMP(dest, cur, !excludes_cmp)) {
419 continue;
420 }
421
422 cur = ast_strdup(cur);
423 if (!cur || AST_VECTOR_APPEND(dest, cur)) {
424 ast_free(cur);
425
426 return -1;
427 }
428 }
429
430 return 0;
431}
static int input(yyscan_t yyscanner)
Definition: ast_expr2f.c:1570
#define ast_free(a)
Definition: astmm.h:180
#define ast_strdup(str)
A wrapper for strdup()
Definition: astmm.h:241
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
char * strsep(char **str, const char *delims)
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
char * ast_strip(char *s)
Strip leading/trailing whitespace from a string.
Definition: strings.h:223
#define ast_assert(a)
Definition: utils.h:739
#define AST_VECTOR_GET_CMP(vec, value, cmp)
Get an element from a vector that matches the given comparison.
Definition: vector.h:731
#define AST_VECTOR_APPEND(vec, elem)
Append an element to a vector, growing the vector if needed.
Definition: vector.h:256

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().