Vectors#

pw_containers: Generic collections of objects for embedded devices

A vector is a one-dimensional array with a variable length.

pw::Vector#

pw::Vector class is similar to std::vector, except it is backed by a fixed-size buffer.

Vectors must be declared with an explicit maximum size (e.g. Vector<int, 10>) but vectors can be used and referred to without the max size template parameter (e.g. Vector<int>).

To allow referring to a pw::Vector without an explicit maximum size, all Vector classes inherit from the generic Vector<T>, which stores the maximum size in a variable. This allows Vectors to be used without having to know their maximum size at compile time. It also keeps code size small since function implementations are shared for all maximum sizes.

Example#

class Publisher {
 public:
  using Subscriber = pw::Function<void(const Message&)>;
  static constexpr size_t kMaxSubscribers = 10;

  pw::Status Subscribe(Subscriber&& subscriber) {
    // Check if the vector's fixed capacity has been exhausted.
    if (subscribers_.full()) {
      return pw::Status::ResourceExhausted();
    }

    // Add the subscriber to the vector.
    subscribers_.emplace_back(std::move(subscriber));
    return pw::OkStatus();
  }

  void Publish(const Message& message) {
    // Iterate over the vector.
    for (auto& subscriber : subscribers_) {
      subscriber(message);
    }
  }

 private:
  pw::Vector<Subscriber, kMaxSubscribers> subscribers_;
};

Size report#

The tables below illustrate the following scenarios:

The memory and code size cost incurred by a adding a single Vector.
The memory and code size cost incurred by adding another Vector with the same type as the first scenario, but with a different size. As Vector is templated on both type and size, a different size results in additional code being generated.
The memory and code size cost incurred by adding another Vector with the same size as the first scenario, but with a different type. As Vector is templated on both type and size, a different size results in additional code being generated.

Label

Segment

Delta

Vector

+712

+80

Additional Vector with the same item type but different size

+224

+44

Additional Vector with different item type but same size

+640

+172

pw::DynamicVector#

pw::DynamicVector is similar to pw::Vector, except that it uses pw::Allocator for memory operations.

pw::DynamicPtrVector#

pw::DynamicPtrVector behaves like a std::vector<T>, but stores pointers to objects of type T allocated using a pw::Allocator. This allows it to store objects that are not movable or copyable, or objects of polymorphic types, while still providing a vector-like interface.

To support this, pw::DynamicPtrVector differs from std::vector in a few ways:

Memory Management: It manages the lifetime of the objects it holds. When an element is removed (e.g., via pop_back, erase, or destruction of the vector), the object is destroyed and its memory deallocated.
Pointer Storage: The underlying storage is a DynamicVector<T*>. Functions like data() return T* const*.
Capacity: reserve_ptr and ptr_capacity refer to the capacity of the underlying pointer vector, not the objects themselves. Objects are allocated individually.
Emplace: emplace and emplace_back allow constructing derived classes (e.g. vec.emplace_back<Derived>(args...)).

API reference#

Moved: pw_containers_vectors