Array List¶

An array based implementation of the list interface.

arraylist.c provides an array implementation of the list interface. It has its own set of functions, prefixed with al_*, that do the same operations as the linked list ones. It also supports the use of the generic list interface, so both array lists and linked lists can be used interchangeably, in C!

Author: Stephen Brennan
Date: Created Sunday, 3 August 2014

Copyright: Copyright (c) 2013-2016, Stephen Brennan. Released under the Revised BSD License. See the LICENSE.txt file for details.

Typedefs

typedef smb_al¶

The actual array list data type.

“Bare” functions return a pointer to this structure. You should not use any of the members, as they are implementation specific and subject to change.

Functions

void al_init(smb_al * list)¶

Initialize an empty array list in memory already allocated.

This function is useful if you would like to declare your array list on the stack and initialize it, rather than allocating space on the heap.

smb_al* al_create()¶

Allocate and initialize an empty array list.

Return: A pointer to the new array list.

void al_destroy(smb_al * list)¶

Free the resources used by the array list, but don’t actually free the pointer given.

This is useful if you have a stack-allocated array list.

Parameters

list: A pointer to the list to ‘destroy.’

void al_delete(smb_al * list)¶

Free the resources and the pointer to the array list.

Parameters

list: A pointer to the list to delete.

smb_list al_create_list()¶

Create a generic list as an array list.

Return: A generic list pointing to a new array list.

smb_list al_cast_to_list(smb_al * list)¶

Cast an array list to a generic list.

Return

A generic list pointing to the same array list.

Parameters

list: The list to cast.

void al_append(smb_al * list, DATA newData)¶

Append an item to the end of a list.

Parameters

list: A pointer to the list to append to.
newData: The data to append

void al_prepend(smb_al * list, DATA newData)¶

Prepend an item to the beginning of the list.

Parameters

list: A pointer to the list to prepend to.
newData: The data to prepend.

DATA al_get(const smb_al * list, int index, smb_status * status)¶

Return the data at a specified index.

Return

The data at the specified index.

Parameters

list: A pointer to the list to get from.
index: The index to get from the list.
status: Status variable.

Exceptions

SMB_INDEX_ERROR: If the specified index was out of range.

void al_remove(smb_al * list, int index, smb_status * status)¶

Removes the node at the given index, if the index exists.

Parameters

list: A pointer to the list to remove from.
index: The index to remove from the list.
status: Status variable.

Exceptions

SMB_INDEX_ERROR: If the specified index was out of range.

void al_insert(smb_al * list, int index, DATA newData)¶

Inserts an item at the specified location in the list.

If the location is not the end of the list, every item at the given index is shifted up one index. If the provided location is less than 0, the location will be treated as 0. If the provided location is greater than the length of the list, the item will be added to the end of the list.

Parameters

list: A pointer to the list to insert into.
index: The index to insert at.
newData: The data to insert.

void al_set(smb_al * list, int index, DATA newData, smb_status * status)¶

Sets the item at the given index.

This can only be used to set *existing* indices. If the list is of size 10 and you try to set element 10 in order to expand it, you will fail. You need to use al_insert or al_append for that.

Parameters

list: A pointer to the list to modify.
index: The index to set.
newData: The new data.
status: Status variable.

Exceptions

SMB_INDEX_ERROR: If the provided index was out of range.

void al_push_back(smb_al * list, DATA newData)¶

Push the data to the back of the list. An alias for al_append. See ll_push_back() if you don’t know the what ‘push’ means.

Parameters

list: A pointer to the list to push to.
newData: The data to push to the back.

DATA al_pop_back(smb_al * list, smb_status * status)¶

Pop the data from the back of the list. See ll_pop_back() if you don’t know what ‘pop’ means.

Return

The data from the back of the list.

Parameters

list: A pointer to the list to pop from.
status: Status variable.

Exceptions

SMB_INDEX_ERROR: if the list is empty.

DATA al_peek_back(smb_al * list, smb_status * status)¶

Peeks at the data from the back of the list. See ll_peek_back() if you don’t know what ‘peek’ means.

Return

The data at the back of the list.

Parameters

list: A pointer to the list to peek from.
status: Status variable.

Exceptions

SMB_INDEX_ERROR: if the list is empty.

void al_push_front(smb_al * list, DATA data)¶

Push the data to the front of the list. Alias for al_prepend. See ll_push_back() if you don’t know what ‘push’ means.

Parameters

list: A pointer to the list to push to.
data: The data to push to the front.

DATA al_pop_front(smb_al * list, smb_status * status)¶

Pop the data from the front of the list. See ll_pop_back() if you don’t know what ‘pop’ means.

Return

The data from the front of the list.

Parameters

list: A pointer to the list to pop from.
status: Status variable.

Exceptions

SMB_INDEX_ERROR: If the list is empty.

DATA al_peek_front(smb_al * list, smb_status * status)¶

Peek at the data from the front of the list. See ll_peek_back() if you don’t know what ‘peek’ means.

Return

The data from the front of the list.

Parameters

list: A pointer to the list to peek from.
status: Status variable.

Exceptions

SMB_INDEX_ERROR: if the list is empty.

int al_length(const smb_al * list)¶

Returns the length of the list.

Return

The length of the list.

Parameters

list: A pointer to the list.

int al_index_of(const smb_al * list, DATA d, DATA_COMPARE comp)¶

Returns the index of the item in the array.

Return

Index of the item, or -1 if it’s not in the list.

Parameters

list: A pointer to the list
d: The item to search for
comp: The comparator to use. NULL for bit comparison.

smb_iter al_get_iter(const smb_al * list)¶

Return an iterator on the array list.

Return

The smb_iter to the list.

Parameters

list: A pointer to the list.

struct smb_al

#include <al.h>

The actual array list data type.

“Bare” functions return a pointer to this structure. You should not use any of the members, as they are implementation specific and subject to change.

Public Members

DATA* data¶: The area of memory containing the data.

int length¶: The number of items in the list.

int allocated¶: The space allocated for the list.