facil.io
0.6.x

#FIOBJ Array API

#Array creation API

#fiobj_ary_new

c
FIOBJ fiobj_ary_new(void);

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

#fiobj_ary_new2

c
FIOBJ fiobj_ary_new2(size_t capa);

Creates a mutable empty Array object with the requested capacity.

#Accessing Array Members / Data

#fiobj_ary_count

c
size_t fiobj_ary_count(FIOBJ ary);

Returns the number of elements in the Array.

#fiobj_ary_capa

c
size_t fiobj_ary_capa(FIOBJ ary);

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

#fiobj_ary2ptr

c
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_ary_index

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

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

#fiobj_ary_entry

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

Alias for fiobj_ary_index.

#Array push / shift API

#fiobj_ary_push

c
void fiobj_ary_push(FIOBJ ary, FIOBJ obj);

Pushes an object to the end of the Array.

#fiobj_ary_pop

c
FIOBJ fiobj_ary_pop(FIOBJ ary);

Pops an object from the end of the Array.

#fiobj_ary_unshift

c
void fiobj_ary_unshift(FIOBJ ary, FIOBJ obj);

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

#fiobj_ary_shift

c
FIOBJ fiobj_ary_shift(FIOBJ ary);

Shifts an object from the beginning of the Array.

#Find / Remove / Replace

#fiobj_ary_replace

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

#fiobj_ary_find

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

#fiobj_ary_remove

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

#fiobj_ary_remove2

c
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

#fiobj_ary_compact

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