facil.io
API Reference

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