📅 Mon, Jun 5, 2017 ⏲️ ~ 4 minutes

Arduino List Library

The List class implements a dynamic-size array, that is, a collection in which it is possible to add or remove elements, and the collection increases or decreases its capacity based on the number of stored elements.

The operation of the List class is similar to the C++ Vector class, but in a simple implementation that can be used on a processor like Arduino. However, the names of the methods and variables resemble the generic List class available in C#, which is more modern and updated.

The List class uses Templates to be able to contain any type of object or basic types.

The List class is initialized to a certain capacity, which by default is 4 elements. Internally, the class implements an array of the size of the list’s capacity.

The Count variable counts the number of elements occupied in the list. The list is full when the number of elements is equal to the list’s capacity.

In case of adding an element when the list is full, the internal array is copied to a new array with double the capacity of the initial array. The expansion process requires the creation of a new array and the copying of the elements, which adds additional time to a simple insertion.

Access to the elements of the list is done using the indexer [], as in the case of a normal array. Additionally, there are methods to add, insert, replace, or delete elements or series of elements.

The Trim methods allow adjusting the list’s capacity to the number of actually occupied elements, in order to reduce the memory occupied by the list. Like the expansion process, contraction requires additional time.

There are also methods to search for elements within the list, reverse the elements, and to copy the elements to and from an external array.

Finally, there are special methods to insert or remove elements in the first and last position, which allow for easily implementing LIFO (Stack) and FIFO (Queue) type structures.

For more information, see the entry Implementar un array de tamaño dinamico en Arduino.

User Manual

Constructor

The List class is instantiated through its constructor.

// Creates a new list with a capacity of 4
List();

// Creates a new list with a specified capacity
List(size_t capacity);

General methods

// Returns the capacity of the list
size_t Capacity() const;

// Returns the number of elements stored in the list
size_t Count() const;

// Returns true if the list is empty
// false otherwise
bool IsEmpty();

// Returns true if the list is full
// false otherwise
bool IsFull();

// Reverses the elements of the list
void Reverse();

Accessing elements

// List indexer allows accessing an element using list[index]
T& operator[](const size_t index);

// Returns the first element of the list
void First();

// Returns the last element of the list
void Last();

Adding elements

// Adds an element to the end of the list
void Add(T item);

// Adds a series of elements to the end of the list
void AddRange(T* items, size_t numItems);

Inserting elements

// Inserts an element at the beginning of the list
void Insert(T item);

// Inserts an element at the specified position
void Insert(size_t index, T item);

// Inserts a series of elements at the beginning of the list
void InsertRange(T* items, size_t numItems);

// Inserts a series of elements at the specified position
void InsertRange(size_t index, T* items, size_t numItems);

Replacing elements

// Replaces the element at the specified position
void Replace(size_t index, T item);

// Replaces a series of elements at the specified position
void ReplaceRange(size_t index, T* items, size_t numItems);

Deleting elements

// Removes all elements from the list
void Clear();

// Removes the first element from the list
void RemoveFirst();

// Removes the last element from the list
void RemoveLast();

// Removes the element at the specified position
void Remove(size_t index);

// Removes a series of elements at the specified position
void RemoveRange(size_t index, size_t numItems);

Reducing capacity

// Reduces the capacity of the list to the number of elements to reduce the memory used
void Trim();

// Reduces the capacity of the list to the number of elements
// plus a certain reserve capacity
void Trim(size_t reserve);

Searching for elements

// Returns true if the list contains an element, false otherwise
bool Contains(T item);

// Returns the index of the first occurrence of an element in the list
size_t IndexOf(T item);

Conversion to/from arrays

// Returns all elements of the list in a new array
T* ToArray();

// Returns a series of elements of the list in a new array
T* ToArray(size_t index, size_t numItems);

// Initializes a list by copying the elements from an existing array
void FromArray(T* items, size_t numItems);

// Copies all elements to an existing array
void CopyTo(T* items);

// Copies a series of elements to an existing array
void CopyTo(T* items, size_t index, size_t numItems);