coll_arraylist.h File Reference

#include <stdlib.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	arraylist_t

Macros
#define	ARRAYLIST_DEFAULT_SIZE   50
#define	E_ARRAYLIST_UNABLE_TO_ALLOCATE_ARRAY   1
#define	E_ARRAYLIST_INDEX_BEYOND_CAPACITY   2
#define	E_ARRAYLIST_INDEX_NOT_FOUND   3
#define	MAX_VOIDPTR_ALLOCATE   (SIZE_MAX / sizeof(void*))

Typedefs
typedef void()	arraylist_free_function(void *data)
typedef struct arraylist_t	arraylist

Functions
int	arraylist_new (arraylist **l, arraylist_free_function *free_fn)
int	arraylist_new_with_capacity (arraylist **l, size_t capacity, arraylist_free_function *free_fn)
size_t	arraylist_length (arraylist *l)
int	arraylist_insert (arraylist *l, size_t loc, void *item)
int	arraylist_add (arraylist *l, void *item)
int	arraylist_set (arraylist *l, size_t loc, void *item)
void *	arraylist_get (arraylist *l, size_t loc)
void	arraylist_clear (arraylist *l)
int	arraylist_delete (arraylist *l, size_t loc)
void	arraylist_free (arraylist *l)
void	arraylist_print (arraylist *l, void(*item_print)(void *item))

Detailed Description

ArrayList: This is a datastructure which implements the abstract datatype (ADT) list, using a fixed length array. The internal array is resized when it reaches capacity, and it's capacity is increased.

A list has the following operations:

1. Insert/Put at location l 1.1 Push/Add at the end of the list
2. Locate/Find item with value x
3. Retrieve/Get value at location l
4. Delete the value at location l
5. Next - get the next location given location l
6. Previous - get the previous location given location l (Next and Previous are trivial indexing operations in an arraylist)
7. Makenull - empty the list
8. First - gets the first location of the list (this is always 0 in an arraylist)
9. PrintList - prints the list to the console/ to a string.
10. Free - destructor/cleanup the list.

Typedef Documentation

arraylist

typedef struct arraylist_t arraylist

This struct represents the ArrayList and its pointer is the user's handle to the arraylist.

The values in the struct should be considered readonly, and should not be modified by user of the arraylist. User should always use the public methods of this implementation.

The capacity member of the struct shows the maximum number of items this arraylist can hold. This number should be carefully chosen at the time of creation of the arraylist.

The size holds the count of items currently in the list.

The array member is a pointer to an array of void pointers, each of which point to one value. Each value inserted in the array must be allocated by the caller and the function to free the items must be passed to the constructor.

Function Documentation

arraylist_add()

int arraylist_add	(	arraylist *	l,
		void *	item
	)

Insert an item at the end of the arraylist equivalent to arraylist_insert(l, arraylist_length(l), item) If the size of current arraylist has already reached MAX_VOIDPTR_ALLOCATE, then returns E_ARRAYLIST_INDEX_BEYOND_CAPACITY. If reallocation of arraylist to accomodate new item fails, then returns E_ARRAYLIST_UNABLE_TO_ALLOCATE_ARRAY.

Parameters

l	the arraylist
item	item to insert

Returns

error code

arraylist_clear()

void arraylist_clear

(

arraylist *

l

)

Clear the array of all elements, but do not de-allocate.

Parameters

l	the arraylist

arraylist_delete()

int arraylist_delete	(	arraylist *	l,
		size_t	loc
	)

Deletes the item at location loc of the arraylist. NOTE: Deleted item is not freed, user must free if needed.

Parameters

l	the arraylist
loc	location to delete at

Returns

item the deleted item (NULL if unable to delete or value was NULL)

arraylist_free()

void arraylist_free

(

arraylist *

l

)

Free the arraylist. (Calls free_fn to free existing items if provided at creation).

Parameters

l	the arraylist

arraylist_get()

void* arraylist_get	(	arraylist *	l,
		size_t	loc
	)

Get the item at location loc of the arraylist. Returns NULL if the location is beyond the length of the arraylist

Parameters

l	the arraylist
loc	location to insert at

Returns

item

arraylist_insert()

int arraylist_insert	(	arraylist *	l,
		size_t	loc,
		void *	item
	)

Insert item at location loc of the arraylist. Can insert at any location inclusive of 0 to length of array (that is one beyond the last element).

If loc is greater than current size, then returns E_ARRAYLIST_INDEX_NOT_FOUND. If the size of current arraylist has already reached MAX_VOIDPTR_ALLOCATE, then returns E_ARRAYLIST_INDEX_BEYOND_CAPACITY. If reallocation of arraylist to accomodate new item fails, then returns E_ARRAYLIST_UNABLE_TO_ALLOCATE_ARRAY.

Parameters

l	the arraylist
loc	location to insert at
item	item to insert

Returns

error code

arraylist_length()

size_t arraylist_length

(

arraylist *

l

)

Return the size/length of the arraylist

Parameters

l	the arraylist

Returns

length/size of the array.

arraylist_new()

int arraylist_new	(	arraylist **	l,
		arraylist_free_function *	free_fn
	)

Create a new arraylist with the default initial capacity.

Parameters

l	an uninitialized arraylist pointer, which will be created by the constructor.
free	the function used to free the items in the arraylist

Returns

value indicating success or failure (0 is success)

arraylist_new_with_capacity()

int arraylist_new_with_capacity	(	arraylist **	l,
		size_t	capacity,
		arraylist_free_function *	free_fn
	)

Create a new arraylist with the specified initial capacity.

Parameters

l	an uninitialized arraylist pointer, which will be created by the constructor.
capacity	total capacity of the arraylist (0 will set capacity to default)
free	the function used to free the items in the arraylist

Returns

value indicating success or falilure (0 is success)

arraylist_print()

void arraylist_print	(	arraylist *	l,
		void(*)(void *item)	item_print
	)

Print the arraylist on the console.

Parameters

l	the arraylist
item_print	fn pointer which prints a single item

Returns

void

arraylist_set()

int arraylist_set	(	arraylist *	l,
		size_t	loc,
		void *	item
	)

Set the item at location loc of the arraylist. If the location specified is greater than MAX_VOIDPTR_ALLOCATE, then an error code E_ARRAYLIST_INDEX_BEYOND_CAPACITY is returned. If loc is greater than current length of the arraylist, then E_ARRAYLIST_INDEX_NOT_FOUND is returned.

Parameters

l	the arraylist
loc	location to insert at
item	item to insert

Returns

error code