facil.io - FIOBJ Array 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.

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

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

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.