# `./fio-stl/202 array.h` 30 public symbols. ### Macros #### `FIO_ARRAY_NOT_FOUND` ```c #define FIO_ARRAY_NOT_FOUND ((uint32_t)-1) ``` _Symbol type:_ `macro` #### `FIO_ARRAY_TYPE` ```c #define FIO_ARRAY_TYPE void * ``` The type for array elements (an array of FIO_ARRAY_TYPE) _Symbol type:_ `macro` #### `FIO_ARRAY_TYPE_INVALID` ```c #define FIO_ARRAY_TYPE_INVALID NULL ``` An invalid value for that type (if any). _Symbol type:_ `macro` #### `FIO_ARRAY_TYPE_INVALID_SIMPLE` ```c #define FIO_ARRAY_TYPE_INVALID_SIMPLE 0 ``` Is the FIO_ARRAY_TYPE_INVALID object memory is all zero? (yes = 1) _Symbol type:_ `macro` #### `FIO_ARRAY_TYPE_COPY` ```c #define FIO_ARRAY_TYPE_COPY(dest, src) (dest) = (src) ``` Handles a copy operation for an array's element. _Symbol type:_ `macro` #### `FIO_ARRAY_TYPE_DESTROY` ```c #define FIO_ARRAY_TYPE_DESTROY(obj) ``` Handles a destroy / free operation for an array's element. _Symbol type:_ `macro` #### `FIO_ARRAY_TYPE_CMP` ```c #define FIO_ARRAY_TYPE_CMP(a, b) (a) == (b) ``` Handles a comparison operation for an array's element. _Symbol type:_ `macro` #### `FIO_ARRAY_INIT` ```c #define FIO_ARRAY_INIT \ { 0 } ``` _Symbol type:_ `macro` #### `FIO_ARRAY_EACH` ```c #define FIO_ARRAY_EACH(array_name, array, pos) \ for (FIO_NAME(array_name, ____type_t) \ *first___ai = NULL, \ *pos = FIO_NAME(array_name, each_next)((array), &first___ai, NULL); \ pos; \ pos = FIO_NAME(array_name, each_next)((array), &first___ai, pos)) ``` Iterates through the array using a `for` loop. Access the object with the pointer `pos`. The `pos` variable can be named however you please. Avoid editing the array during a FOR loop, although I hope it's possible, I wouldn't count on it. **Note**: this variant supports automatic pointer tagging / untagging. _Symbol type:_ `macro` ### Types #### `fiobj_array_s` ```c struct fiobj_array_s { /* start common header (with embedded array type) */ /** the offset to the first item. */ uint32_t start; /** The offset to the first empty location the array. */ uint32_t end; /* end common header (with embedded array type) */ /** The array's capacity - limited to 32bits, but we use the extra padding. */ uint32_t capa; uint32_t padding__; /** a pointer to the array's memory (if not embedded) */ FIO_ARRAY_TYPE *ary; #if FIO_ARRAY_ENABLE_EMBEDDED > 1 /** Do we wanted larger small-array optimizations? */ FIO_ARRAY_TYPE extra_memory_for_embedded_arrays[(FIO_ARRAY_ENABLE_EMBEDDED - 1)] #endif } ``` an Array type. _Symbol type:_ `type` #### `fiobj_array_each_s` ```c struct fiobj_array_each_s { /** The array iterated. Once set, cannot be safely changed. */ FIO_ARRAY_PTR const parent; /** The current object's index */ uint64_t index; /** The callback / task called for each index, may be updated mid-cycle. */ int (*task)(struct FIO_NAME(FIO_ARRAY_NAME, each_s) * info); /** Opaque user data. */ void *udata; /** The object / value at the current index. */ FIO_ARRAY_TYPE value; /* memory padding used for FIOBJ */ uint64_t padding; } ``` Iteration information structure passed to the callback. _Symbol type:_ `type` ### Functions #### `fiobj_array_destroy` ```c void fiobj_array_destroy(FIO_ARRAY_PTR ary) ``` _Symbol type:_ `function` #### `fiobj_array_count` ```c inline uint32_t fiobj_array_count(FIO_ARRAY_PTR ary) ``` Returns the number of elements in the Array. _Symbol type:_ `function` #### `fiobj_array_capa` ```c inline uint32_t fiobj_array_capa(FIO_ARRAY_PTR ary) ``` Returns the current, temporary, array capacity (it's dynamic). _Symbol type:_ `function` #### `fiobj_array_is_embedded` ```c inline int fiobj_array_is_embedded(FIO_ARRAY_PTR ary) ``` Returns 1 if the array is embedded, 0 if it has memory allocated and -1 on an error. _Symbol type:_ `function` #### `fiobj_array2ptr` ```c inline FIO_ARRAY_TYPE *fiobj_array2ptr(FIO_ARRAY_PTR ary) ``` Returns a pointer to the C array containing the objects. _Symbol type:_ `function` #### `fiobj_array_reserve` ```c uint32_t fiobj_array_reserve(FIO_ARRAY_PTR ary, int64_t capa) ``` Reserves a minimal capacity for additional elements to be added to the array. If `capa` is negative, new memory will be allocated at the beginning of the array rather then it's end. Returns the array's new capacity. _Symbol type:_ `function` #### `fiobj_array_concat` ```c FIO_ARRAY_PTR fiobj_array_concat(FIO_ARRAY_PTR dest, FIO_ARRAY_PTR src) ``` Adds all the items in the `src` Array to the end of the `dest` Array. The `src` Array remain untouched. Always returns the destination array (`dest`). _Symbol type:_ `function` #### `fiobj_array_set` ```c FIO_ARRAY_TYPE *fiobj_array_set(FIO_ARRAY_PTR ary, int64_t index, FIO_ARRAY_TYPE data, FIO_ARRAY_TYPE *old) ``` Sets `index` to the value in `data`. If `index` is negative, it will be counted from the end of the Array (-1 == last element). If `old` isn't NULL, the existing data will be copied to the location pointed to by `old` before the copy in the Array is destroyed. Returns a pointer to the new object, or NULL on error. _Symbol type:_ `function` #### `fiobj_array_get` ```c inline FIO_ARRAY_TYPE fiobj_array_get(FIO_ARRAY_PTR ary, int64_t index) ``` Returns the value located at `index` (no copying is performed). If `index` is negative, it will be counted from the end of the Array (-1 == last element). _Symbol type:_ `function` #### `fiobj_array_find` ```c uint32_t fiobj_array_find(FIO_ARRAY_PTR ary, FIO_ARRAY_TYPE data, int64_t start_at) ``` Returns the index of the object or (uint32_t)-1 if the object wasn't found. If `start_at` is negative (i.e., -1), than seeking will be performed in reverse, where -1 == last index (-2 == second to last, etc'). _Symbol type:_ `function` #### `fiobj_array_remove` ```c int fiobj_array_remove(FIO_ARRAY_PTR ary, int64_t index, FIO_ARRAY_TYPE *old) ``` Removes an object from the array, MOVING all the other objects to prevent "holes" in the data. If `old` is set, the data is copied to the location pointed to by `old` before the data in the array is destroyed. Returns 0 on success and -1 on error. This action is O(n) where n in the length of the array. It could get expensive. _Symbol type:_ `function` #### `fiobj_array_remove2` ```c uint32_t fiobj_array_remove2(FIO_ARRAY_PTR ary, FIO_ARRAY_TYPE data) ``` Removes all occurrences of an object from the array (if any), MOVING all the existing objects to prevent "holes" in the data. Returns the number of items removed. This action is O(n) where n in the length of the array. It could get expensive. _Symbol type:_ `function` #### `fiobj_array_compact` ```c void fiobj_array_compact(FIO_ARRAY_PTR ary) ``` Attempts to lower the array's memory consumption. _Symbol type:_ `function` #### `fiobj_array_push` ```c FIO_ARRAY_TYPE *fiobj_array_push(FIO_ARRAY_PTR ary, FIO_ARRAY_TYPE data) ``` Pushes an object to the end of the Array. Returns a pointer to the new object or NULL on error. _Symbol type:_ `function` #### `fiobj_array_pop` ```c int fiobj_array_pop(FIO_ARRAY_PTR ary, FIO_ARRAY_TYPE *old) ``` Removes an object from the end of the Array. If `old` is set, the data is copied to the location pointed to by `old` before the data in the array is destroyed. Returns -1 on error (Array is empty) and 0 on success. _Symbol type:_ `function` #### `fiobj_array_unshift` ```c FIO_ARRAY_TYPE *fiobj_array_unshift(FIO_ARRAY_PTR ary, FIO_ARRAY_TYPE data) ``` Unshifts an object to the beginning of the Array. Returns a pointer to the new object or NULL on error. This could be expensive, causing `memmove`. _Symbol type:_ `function` #### `fiobj_array_shift` ```c int fiobj_array_shift(FIO_ARRAY_PTR ary, FIO_ARRAY_TYPE *old) ``` Removes an object from the beginning of the Array. If `old` is set, the data is copied to the location pointed to by `old` before the data in the array is destroyed. Returns -1 on error (Array is empty) and 0 on success. _Symbol type:_ `function` #### `fiobj_array_each` ```c uint32_t fiobj_array_each(FIO_ARRAY_PTR ary, int (*task)(FIO_NAME(FIO_ARRAY_NAME, each_s) * info), void *udata, int64_t start_at) ``` Iteration using a callback for each entry in the array. The callback task function must accept an each_s pointer, see above. If the callback returns -1, the loop is broken. Any other value is ignored. Returns the relative "stop" position, i.e., the number of items processed + the starting point. _Symbol type:_ `function` #### `fiobj_array_each_next` ```c inline FIO_ARRAY_TYPE *fiobj_array_each_next(FIO_ARRAY_PTR ary, FIO_ARRAY_TYPE **first, FIO_ARRAY_TYPE *pos) ``` Returns a pointer to the (next) object in the array. Returns a pointer to the first object if `pos == NULL` and there are objects in the array. The first pointer is automatically set and it allows object insertions and memory effecting functions to be called from within the loop. If the object in `pos` (or an object before it) were removed, consider passing `pos-1` to the function, to avoid skipping any elements while looping. Returns the next object if both `first` and `pos` are valid. Returns NULL if `pos` was the last object or no object exist. Returns the first object if either `first` or `pos` are invalid. _Symbol type:_ `function` -----------------------------------------------------