Array

Library Information

Name

Array

Version

1.4.0

License

BSD

URL

https://github.com/janelia-arduino/Array

Author

Peter Polidoro

Email

peter@polidoro.io

Description

Arduino container library similar to std::array, with a variable logical size and several vector-style helper methods.

The container owns a fixed-capacity statically allocated C array internally, so no dynamic allocation is required. The maximum capacity is part of the type, while the current size still changes as values are pushed, popped, or assigned.

The library is explicitly header-only. Include Array.h and no separate compilation unit is required.

This library pairs naturally with Vector. Array stores its elements internally and encodes the maximum size in the type. Vector stores its elements in external storage and leaves the capacity outside the type.

Quick Start

Basic setup

#include <Array.h>

constexpr size_t ELEMENT_COUNT_MAX = 5;
Array<int, ELEMENT_COUNT_MAX> array;

void setup() {
  array.push_back(21);
  array.push_back(42);
  array.push_back(84);
}

You can also initialize from a single value or an existing array:

Array<int, 4> filled_array(7);

const int values[] = {1, 2, 3};
Array<int, 4> copied_array(values);

Common operations

Representative APIs:

• push_back(value)
• pop_back()
• remove(index)
• clear()
• fill(value)
• assign(n, value)
• size()
• max_size()
• empty()
• full()
• front()
• back()
• data()
• begin() and end()

Storage and bounds notes

• push_back() is ignored when the array is already full.
• pop_back() is ignored when the array is empty.
• remove(index) only changes the container when index < size().
• operator[](), at(), front(), and back() do not perform bounds checking.
• Define ARRAY_ENABLE_BOUNDS_CHECKS before including Array.h to enable assertion-backed access checks in those methods, or override ARRAY_ACCESS_CHECK(condition) with a custom hook.
• Capacity is fixed by the template argument and cannot be changed at runtime.

Array vs Vector

Array

constexpr size_t ELEMENT_COUNT_MAX = 5;
Array<int, ELEMENT_COUNT_MAX> array;
array.push_back(77);

Vector

constexpr size_t ELEMENT_COUNT_MAX = 5;
int storage[ELEMENT_COUNT_MAX];
Vector<int> vector(storage);
vector.push_back(77);

Choose Array when the container should own its fixed-capacity storage directly. Choose Vector when the storage already exists elsewhere or when you want the capacity decided outside the type.

Build and Examples

Representative examples:

• examples/ArrayTester/ArrayTester.ino
• examples/ConstTester/ConstTester.ino

Preferred local workflow with Pixi:

pixi install
pixi run pio-version
pixi run format-check
pixi run test
pixi run build examples/ArrayTester uno
pixi run build examples/ArrayTester pico
pixi run build examples/ConstTester pico
pixi run release-check

Pixi keeps the pio CLI and its Python runtime local to the repository. The build, upload, flash, and rebuild tasks select examples without editing platformio.ini. The default release-check uses a representative matrix of native tests plus uno and pico builds.

Useful commands:

pixi run ports
pixi run format-all
pixi run build examples/ArrayTester <env>
pixi run upload examples/ArrayTester <env> /dev/ttyACM0
pixi run monitor /dev/ttyACM0 115200
pixi run set-version -- 1.4.0

Sample environments: uno, mega, pico, teensy40.

Equivalent direct commands without Pixi:

make native-test
python3 tools/clang_format_all.py --check
python3 tools/version_sync.py check
python3 tools/pio_task.py build --example examples/ArrayTester --env uno
python3 tools/pio_task.py build --example examples/ArrayTester --env pico
python3 tools/pio_task.py build --example examples/ConstTester --env pico
python3 tools/pio_task.py upload --example examples/ArrayTester --env <env> --port /dev/ttyACM0

Release Checklist

Before tagging a release:

• Update CHANGELOG.md.
• Sync version metadata with python3 tools/version_sync.py set X.Y.Z.
• Run pixi run format-check.
• Run make native-test.
• Run pixi run release-check.
• Commit, tag, and push the release.