arraylist.h File Reference

This header file contains the structures and functions need to work with array lists (lists implemented using C arrays). More...

Typedefs
typedef arraylist_adt *	ArrayList
	Structure representing an array-list.
typedef int	ArrayListIterator
	Array-list iterator definition.
Functions
ArrayList	AL_New (int initcap)
	Creates a new array list with the specified initial capacity.
void	AL_Free (ArrayList list)
	Destroys the specified array list.
int	AL_Empty (ArrayList list)
	Determines if the list is empty (has no elements) or not.
int	AL_Size (ArrayList list)
	Returns the size of the array list.
void *	AL_Get (ArrayList list, ArrayListIterator it)
	Gets the data stored at a given position.
void	AL_Update (ArrayList list, ArrayListIterator it, void *el)
	Updates the data contained in the specified position from the list.
ArrayListIterator	AL_Find (ArrayList list, void *el)
	Searches for data in the list.
void *	AL_Remove (ArrayList list, ArrayListIterator it)
	Removes the specified element from the list.
void	AL_Add (ArrayList list, ArrayListIterator it, void *el)
	Inserts data in the list, before the specified position.
ArrayListIterator	AL_Begin (ArrayList list)
	Returns an iterator to the first element in the list.
ArrayListIterator	AL_End (ArrayList list)
	Returns an interator after the last element in the list.
ArrayListIterator	AL_Next (ArrayList list, ArrayListIterator it)
	Returns an iterator to the next element in the list.

---

Detailed Description

This header file contains the structures and functions need to work with array lists (lists implemented using C arrays).

Author:

Stefan Bucur

It contains functions for creating an array list, destroying it, manipulating elements, finding an element, as well as checking a list's size.

---

Typedef Documentation

typedef struct arraylist_adt* ArrayList

Structure representing an array-list.

The structure contains pointers to the data stored in the list. The number of elements and current capacity of the list are also stored. Directly modiying structure memebers is not recommended. To manipulate data in the list, use the appropriate functions.

Element data is stored using a void pointer. Thus, one should note that there is no way to tell what kind of data is stored in the list or in a particular element of the list.

See also:

AL_New(), AL_Free()

typedef int ArrayListIterator

Array-list iterator definition.

Although in this implementation the array list iterator is an int one should not use int directly, as this might change without notice in future versions of the file (e.g. using long for a x64 edition of the library).

See also:

AL_Find(), AL_Begin, AL_End(), AL_Next(), AL_Add(), AL_Remove()

---

Function Documentation

void AL_Add	(	ArrayList	list,
		ArrayListIterator	it,
		void *	el
	)

Inserts data in the list, before the specified position.

The function adds the data specified by the el void* pointer in the list, at the position specified by the it iterator. A new element is created and inserted before it .

The el pointer must point to a memory zone which has been already initialized and holds the data to be stored in the list. The function doesn't make any kind of verifications regarding the value of el .

Parameters:

	list	the list in which to add.
	it	iterator specifying the position to add.
	*el	element data.

ArrayListIterator AL_Begin

(

ArrayList

list

)

Returns an iterator to the first element in the list.

The functions returns an iterator to the first element in the list.

Parameters:

list

list to get the iterator to the first element of.

Returns:

an ArrayListIterator to the first element in the list. It will have the value -1 if the list is NULL.

int AL_Empty

(

ArrayList

list

)

Determines if the list is empty (has no elements) or not.

The function returns the value of count==0. The function returns regardless of the list capacity.

Parameters:

list

the list to be tested.

Returns:

-1 if the list pointer is null (list ), 1 if the list is empty, 0 otherwise.

ArrayListIterator AL_End

(

ArrayList

list

)

Returns an interator after the last element in the list.

The function returns an iterator at the end of the list. This iterator can be used to insert data at the end of the list.

Parameters:

list

an iterator for this list will be returned.

Returns:

ArrayListIterator . The value (integer) is the same as the result of AL_Size() for the specified list.

ArrayListIterator AL_Find	(	ArrayList	list,
		void *	el
	)

Searches for data in the list.

The function searches for the data specified by the el in the given list.

Note:

This version of ArrayList uses for comparision strict pointer comparison. Further versions may include the possibilty to specify a comparator to provide more flexible searching.

Parameters:

	list	the list in which to search.
	*el	data to search for.

Returns:

returns an ArrayListIterator pointing to the position in the list where the data was found, or NULL otherwise.

void AL_Free

(

ArrayList

list

)

Destroys the specified array list.

This function destroys an array list and frees the memory used by it. Also, it frees the memory used by the data stored in the list, so trying to access the data in a destroyed list (e.g. through a pointer) will most likely result in a Access violation / segfault.

Parameters:

list

the list to be destroyed. A ArrayList structure.

void* AL_Get	(	ArrayList	list,
		ArrayListIterator	it
	)

Gets the data stored at a given position.

The function returns the data stored at the position given by the iterator it As void* is used to store data, a cast is needed to obtain the actual data.

Parameters:

	list	the list to retrieve data from.
	it	list iterator specifying the position to get data from.

Returns:

the pointer to the data, or NULL if list is NULL or it does not belong to the list.

ArrayList AL_New

(

int

initcap

)

Creates a new array list with the specified initial capacity.

This function creates a new array list and reserves space for initcap elements. If, during usage, the initial capacity is exceeded, then the arraylist automatically resizes in order to accomodate the elements.

Parameters:

initcap

initial capacity of the list.

Returns:

newly created array list.

ArrayListIterator AL_Next	(	ArrayList	list,
		ArrayListIterator	it
	)

Returns an iterator to the next element in the list.

The function returns an iterator to the next element in the list. The current element is given through an interator, obtained through a call to AL_Begin() or subsequent calls to AL_Next().

Parameters:

	list	the list for which the next element is required.
	it	iterator specifying current position in the list.

Returns:

an iterator to the next element in the list or the value -1 if either the iterator points to LL_End() or the list is NULL.

void* AL_Remove	(	ArrayList	list,
		ArrayListIterator	it
	)

Removes the specified element from the list.

The function removes the element specified by the iterator it from the list list. The memory for the data stored in the element is not freed.

Parameters:

	list	the list from which to remove the element.
	it	iterator specifying the position of the element to be removed.

Returns:

the data stored at the location specified by the iterator. If the iterator does not exist in the list, points to the end of the list, or list is NULL the function returns NULL.

int AL_Size

(

ArrayList

list

)

Returns the size of the array list.

The functions returns the number of elements in the array list. At any given time count < capacity.

Parameters:

list

list to be tested.

Returns:

the number of elements in the list, or -1 if the list is NULL.

void AL_Update	(	ArrayList	list,
		ArrayListIterator	it,
		void *	el
	)

Updates the data contained in the specified position from the list.

The function updates the data of the element specified by the iterator it . The old data is discared and the element will point to the new data.

Parameters:

	list	the list to update data in.
	it	iterator giving the position of the element whose data is to be updated.
	*el	void* pointer to a memory location containing new data.

---