array.h File Reference

Array subsystem that mimics the flexibility and ease of Perl-style arrays. More...

Go to the source code of this file.

Classes
struct	Array
Functions
EXTERN_C_BEGIN LIBGIFT_EXPORT Array *	array_new (void *first,...)
LIBGIFT_EXPORT void	array_unset (Array **a)
LIBGIFT_EXPORT void *	array_push (Array **a, void *element)
LIBGIFT_EXPORT void *	array_pop (Array **a)
LIBGIFT_EXPORT void *	array_shift (Array **a)
LIBGIFT_EXPORT void *	array_unshift (Array **a, void *element)
LIBGIFT_EXPORT void *	array_index (Array **a, int index)
LIBGIFT_EXPORT size_t	array_count (Array **a)
LIBGIFT_EXPORT void *	array_splice (Array **a, int offset, int length, void *first,...)
LIBGIFT_EXPORT int	array_list (Array **a,...)

---

Detailed Description

Array subsystem that mimics the flexibility and ease of Perl-style arrays.

This is the only libgift subsystem which doesn't prefix it's name for function namespacing. This is done to provide the absolute shortest possible function names.

Example:

 Array *a = array ("foo", "bar", NULL);

 array_splice (&a, 0, 1, "FOO", NULL);
 array_splice (&a, 1, 1, "Bar", NULL);

 array_push (&a, "baz");
 array_push (&a, "test");
 array_push (&a, "ing");

 str1 = pop (&a);
 str2 = pop (&a);

 printf ("the %s is work%s\n", str2, str1);

 array_unset (&a);

---

Function Documentation

LIBGIFT_EXPORT size_t array_count (  Array **  a  )

Return the number of elements in the array. This expensive can be considered inexpensive.

LIBGIFT_EXPORT void* array_index (  Array **  a, int  index )

Access the array member at the supplied index. In effective this is the same as calling: array_splice (a, index, 0, NULL);

LIBGIFT_EXPORT int array_list (  Array **  a,   ... )

Access the elements in the list sequentially with a single function call. This replaces the need to call splice multiple times in order to access incremental values in the list. Example: Array *ar = array ("a", "b", "c", NULL); char *a, *b, *c; array_list (&ar, &a, &b, &foo, NULL); ... Parameters: a  ...  NULL-terminated list of addresses to set. It is safe to supply a list of a different size (including one larger) than the number of elements in the supplied array. All additional values will be set to NULL as a convenience to the user. Returns: Number of elements successfully accessed. This is usually the number of elements supplied.

EXTERN_C_BEGIN LIBGIFT_EXPORT Array* array_new (  void *  first,   ... )

Construct an array a'la PHP. The parameter list is NULL terminated. Parameters: first  Beginning of a list of elements to construct the array with. NULL terminate the following variable argument list. Returns: Allocate memory that must be cleaned up with ::unset.

LIBGIFT_EXPORT void* array_pop (  Array **  a  )

Pop an element off the array. Returns: Pointer to the inserted element or NULL if there is no element available (the array is empty).

LIBGIFT_EXPORT void* array_push (  Array **  a, void *  element )

Push a single element on to the end of the array. Returns: If successful, element is returned, otherwise NULL.

LIBGIFT_EXPORT void* array_shift (  Array **  a  )

Shift an element off the beginning of the array and return it. Returns: Identical to ::pop.

LIBGIFT_EXPORT void* array_splice (  Array **  a, int  offset, int  length, void *  first,   ... )

Splice an array. It's probably best to lookup perldoc -f splice in order to see what inspired this interface. The implementation details may make this interface more clear as well. Parameters: a  offset  Array index to begin operation from. length  Number of elements to remove following `offset'. first  First element to add to the offset position (after removal). The following variable argument list should be NULL terminated if this parameter is non-NULL. Returns: The last affected element is returned. This is inconsistent with perl's splice implementation.

LIBGIFT_EXPORT void array_unset (  Array **  a  )

Clear all memory used by the array object and set the value at the object's reference to NULL. Parameters: a  Address of the pointer returned from ::array.

LIBGIFT_EXPORT void* array_unshift (  Array **  a, void *  element )

Add a new element to the beginning of the array. Returns: Identical to ::push.

---