facil.io - FIOBJ Array API

Array creation API


FIOBJ fiobj_ary_new(void);

Creates a mutable empty Array object. Use fiobj_free when done.


FIOBJ fiobj_ary_new2(size_t capa);

Creates a mutable empty Array object with the requested capacity.

Accessing Array Members / Data


size_t fiobj_ary_count(FIOBJ ary);

Returns the number of elements in the Array.


size_t fiobj_ary_capa(FIOBJ ary);

Returns the current, temporary, array capacity (it's dynamic).


FIOBJ *fiobj_ary2ptr(FIOBJ ary);

Returns a TEMPORARY pointer to the beginning of the array.

This pointer can be used for sorting and other direct access operations as long as no other actions (insertion/deletion) are performed on the array.


FIOBJ fiobj_ary_index(FIOBJ ary, int64_t pos);

Returns a temporary object owned by the Array.

Wrap this function call within fiobj_dup to get a persistent handle. i.e.:

fiobj_dup(fiobj_ary_index(array, 0));

Negative values are retrieved from the end of the array. i.e., -1 is the last item.

/** */

/** Sets an object at the requested position. / void fiobj_ary_set(FIOBJ ary, FIOBJ obj, int64_t pos);


#define fiobj_ary_entry(a, p) fiobj_ary_index((a), (p))

Alias for fiobj_ary_index.

Array push / shift API


void fiobj_ary_push(FIOBJ ary, FIOBJ obj);

Pushes an object to the end of the Array.


FIOBJ fiobj_ary_pop(FIOBJ ary);

Pops an object from the end of the Array.


void fiobj_ary_unshift(FIOBJ ary, FIOBJ obj);

Unshifts an object to the beginning of the Array. This could be expensive.


FIOBJ fiobj_ary_shift(FIOBJ ary);

Shifts an object from the beginning of the Array.

Find / Remove / Replace


FIOBJ fiobj_ary_replace(FIOBJ ary, FIOBJ obj, int64_t pos);

Replaces the object at a specific position, returning the old object - remember to fiobj_free the old object.


int64_t fiobj_ary_find(FIOBJ ary, FIOBJ data);

Finds the index of a specifide object (if any). Returns -1 if the object isn't found.


int fiobj_ary_remove(FIOBJ ary, int64_t pos);

Removes the object at the index (if valid), changing the index of any following objects.

Returns 0 on success or -1 (if no object or out of bounds).


int fiobj_ary_remove2(FIOBJ ary, FIOBJ data);

Removes the first instance of an object from the Array (if any), changing the index of any following objects.

Returns 0 on success or -1 (if the object wasn't found).

Array Compacting


void fiobj_ary_compact(FIOBJ ary);

Removes any NULL pointers from an Array, keeping all Objects (including explicit NULL objects) in the array.

This action is O(n) where n in the length of the array. It could get expensive.