Vector

Library Information

Name

Vector

Version

1.4.0

License

BSD

URL

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

Author

Peter Polidoro

Email

peter@polidoro.io

Description

Arduino container library similar to std::vector, but backed by caller-provided static storage instead of dynamic allocation.

The container tracks a variable logical size while the maximum capacity comes from the storage array you attach with the constructor or setStorage(). That avoids heap usage on small embedded targets, but it also means your sketch must provide valid backing storage before accessing elements.

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

This library pairs naturally with Array. Vector stores its elements in external storage and does not need the maximum size as a template argument. Array stores its elements internally and encodes the maximum size in the type.

Quick Start

Basic setup

#include <Vector.h>

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

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

You can also attach storage later:

Vector<int> vector;
int storage[8];

void setup() { vector.setStorage(storage, 0); }

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

• The default constructor leaves the container unattached to storage until setStorage() is called.
• push_back() is ignored when the vector is already full.
• pop_back() is ignored when the vector is empty.
• remove(index) only changes the container when index < size().
• operator[](), at(), front(), and back() do not perform bounds checking.
• Define VECTOR_ENABLE_BOUNDS_CHECKS before including Vector.h to enable assertion-backed access checks in those methods, or override VECTOR_ACCESS_CHECK(condition) with a custom hook.

Vector vs Array

Vector

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

Array

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

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

Build and Examples

Representative examples:

• examples/VectorTester/VectorTester.ino
• examples/PlatformIO/src/main.cpp

Preferred local workflow with Pixi:

pixi install
pixi run pio-version
pixi run format-check
pixi run test
pixi run build examples/VectorTester uno
pixi run build examples/VectorTester 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/VectorTester <env>
pixi run upload examples/VectorTester <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/VectorTester --env uno
python3 tools/pio_task.py build --example examples/VectorTester --env pico
python3 tools/pio_task.py upload --example examples/VectorTester --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.