arraylist.h File Reference

Automatically resizing array. More...

Data Structures
struct	_ArrayList
	Definition of an ArrayList. More...
Typedefs
typedef void *	ArrayListValue
	A value to be stored in an ArrayList.
typedef struct _ArrayList	ArrayList
	An ArrayList structure.
typedef int(*	ArrayListEqualFunc )(ArrayListValue value1, ArrayListValue value2)
	Compare two values in an arraylist to determine if they are equal.
typedef int(*	ArrayListCompareFunc )(ArrayListValue value1, ArrayListValue value2)
	Compare two values in an arraylist.
Functions
ArrayList *	arraylist_new (int length)
	Allocate a new ArrayList for use.
void	arraylist_free (ArrayList *arraylist)
	Destroy an ArrayList and free back the memory it uses.
int	arraylist_append (ArrayList *arraylist, ArrayListValue data)
	Append a value to the end of an ArrayList.
int	arraylist_prepend (ArrayList *arraylist, ArrayListValue data)
	Prepend a value to the beginning of an ArrayList.
void	arraylist_remove (ArrayList *arraylist, int index)
	Remove the entry at the specified location in an ArrayList.
void	arraylist_remove_range (ArrayList *arraylist, int index, int length)
	Remove a range of entries at the specified location in an ArrayList.
int	arraylist_insert (ArrayList *arraylist, int index, ArrayListValue data)
	Insert a value at the specified index in an ArrayList.
int	arraylist_index_of (ArrayList *arraylist, ArrayListEqualFunc callback, ArrayListValue data)
	Find the index of a particular value in an ArrayList.
void	arraylist_clear (ArrayList *arraylist)
	Remove all entries from an ArrayList.
void	arraylist_sort (ArrayList *arraylist, ArrayListCompareFunc compare_func)
	Sort the values in an ArrayList.

---

Detailed Description

Automatically resizing array.

ArrayLists are arrays of pointers which automatically increase in size.

To create an ArrayList, use arraylist_new. To destroy an ArrayList, use arraylist_free.

To add a value to an ArrayList, use arraylist_prepend, arraylist_append, or arraylist_insert.

To remove a value from an ArrayList, use arraylist_remove or arraylist_remove_range.

---

Typedef Documentation

typedef struct _ArrayList ArrayList

An ArrayList structure.

New ArrayLists can be created using the arraylist_new function.

See also:

arraylist_new

typedef int(* ArrayListCompareFunc)(ArrayListValue value1, ArrayListValue value2)

Compare two values in an arraylist.

Used by arraylist_sort when sorting values.

Parameters:

	value1	The first value.
	value2	The second value.

Returns:

A negative number if value1 should be sorted before value2, a positive number if value2 should be sorted before value1, zero if the two values are equal.

typedef int(* ArrayListEqualFunc)(ArrayListValue value1, ArrayListValue value2)

Compare two values in an arraylist to determine if they are equal.

Returns:

Non-zero if the values are not equal, zero if they are equal.

---

Function Documentation

int arraylist_append	(	ArrayList *	arraylist,
		ArrayListValue	data
	)

Append a value to the end of an ArrayList.

Parameters:

	arraylist	The ArrayList.
	data	The value to append.

Returns:

Non-zero if the request was successful, zero if it was not possible to allocate more memory for the new entry.

void arraylist_clear

(

ArrayList *

arraylist

)

Remove all entries from an ArrayList.

Parameters:

arraylist

The ArrayList.

void arraylist_free

(

ArrayList *

arraylist

)

Destroy an ArrayList and free back the memory it uses.

Parameters:

arraylist

The ArrayList to free.

int arraylist_index_of	(	ArrayList *	arraylist,
		ArrayListEqualFunc	callback,
		ArrayListValue	data
	)

Find the index of a particular value in an ArrayList.

Parameters:

	arraylist	The ArrayList to search.
	callback	Callback function to be invoked to compare values in the list with the value to be searched for.
	data	The value to search for.

Returns:

The index of the value if found, or -1 if not found.

int arraylist_insert	(	ArrayList *	arraylist,
		int	index,
		ArrayListValue	data
	)

Insert a value at the specified index in an ArrayList.

The index where the new value can be inserted is limited by the size of the ArrayList.

Parameters:

	arraylist	The ArrayList.
	index	The index at which to insert the value.
	data	The value.

Returns:

Returns zero if unsuccessful, else non-zero if successful (due to an invalid index or if it was impossible to allocate more memory).

ArrayList* arraylist_new

(

int

length

)

Allocate a new ArrayList for use.

Parameters:

length

Hint to the initialise function as to the amount of memory to allocate initially to the ArrayList.

Returns:

A new arraylist, or NULL if it was not possible to allocate the memory.

See also:

arraylist_free

int arraylist_prepend	(	ArrayList *	arraylist,
		ArrayListValue	data
	)

Prepend a value to the beginning of an ArrayList.

Parameters:

	arraylist	The ArrayList.
	data	The value to prepend.

Returns:

Non-zero if the request was successful, zero if it was not possible to allocate more memory for the new entry.

void arraylist_remove	(	ArrayList *	arraylist,
		int	index
	)

Remove the entry at the specified location in an ArrayList.

Parameters:

	arraylist	The ArrayList.
	index	The index of the entry to remove.

void arraylist_remove_range	(	ArrayList *	arraylist,
		int	index,
		int	length
	)

Remove a range of entries at the specified location in an ArrayList.

Parameters:

	arraylist	The ArrayList.
	index	The index of the start of the range to remove.
	length	The length of the range to remove.

void arraylist_sort	(	ArrayList *	arraylist,
		ArrayListCompareFunc	compare_func
	)

Sort the values in an ArrayList.

Parameters:

	arraylist	The ArrayList.
	compare_func	Function used to compare values in sorting.