Vectors¶

Introduction¶

A FSTR::Vector is an array of Object pointers:

struct Vector<ObjectType> {
   FSTR::Object object;
   ObjectType* entries[];
};

A key use for this is the construction of string tables.

Defining Vectors¶

Inline Strings are not supported, so the content has to be defined first:

DEFINE_FSTR(str1, "Test string #1");
DEFINE_FSTR(str2, "Test string #2");
IMPORT_FSTR(str3, PROJECT_DIR "/files/somedata.json");

Now we can define the Vector:

#include <FlashString/Vector.hpp>

DEFINE_FSTR_VECTOR(myTable, FlashString,
   &str1,
   &str2,
   nullptr,
   &str3
);

Note the use of nullptr to indicate an invalid vector entry, as distinct from an empty String.

Using Vectors¶

Now we can access the data using Vector methods:

debugf("table.length() = %u", table.length());
debugf("fstr1 = '%s'", String(table[0]).c_str());
debugf("fstr2.length() = %u", table[1].length());
debugf("fstr3.length() = %u", table[2].length());

You can share Vectors between translation units by declaring it in a header:

DECLARE_FSTR_VECTOR(table);

To search a Vector:

int i = table.indexOf("TEST STRING #1");

Note

By default, searches in Vector<String> are not case-sensitive.

The indexOf method has an extra ignoreCase parameter, which defaults to true.

Structure¶

The above example generates a structure like this:

const struct {
   ObjectBase object;
   String* entries[4];
} __fstr__myTable PROGMEM = {
   {16},
   &str1,
   &str2,
   nullptr,
   &str3,
};
const Vector<String>& myTable PROGMEM = __fstr__myTable.as<Vector<String>>();

Note: FSTR:: namespace qualifier omitted for clarity.

Macros¶

DECLARE_FSTR_VECTOR(name, ObjectType)¶

Declare a global Vector& reference.

Note

Use DEFINE_VECTOR to instantiate the global Object

Parameters

name:
ObjectType:

DEFINE_FSTR_VECTOR(name, ObjectType, ...)¶

Define a Vector Object with global reference.

Note

Size will be calculated

Parameters

name: Name of Vector& reference to define
ObjectType:
...: List of ObjectType* pointers

DEFINE_FSTR_VECTOR_LOCAL(name, ObjectType, ...)¶: Like DEFINE_FSTR_VECTOR except reference is declared static constexpr.

DEFINE_FSTR_VECTOR_SIZED(name, ObjectType, size, ...)¶

Define a Vector Object with global reference, specifying the number of elements.

Note

Use in situations where the array size cannot be automatically calculated

Parameters

name: Name of Vector& reference to define
ObjectType:
size: Number of elements
...: List of ObjectType* pointers

DEFINE_FSTR_VECTOR_SIZED_LOCAL(name, ObjectType, size, ...)¶: Like DEFINE_FSTR_VECTOR_SIZED except reference is declared static constexpr.

DEFINE_FSTR_VECTOR_DATA(name, ObjectType, ...)¶

Define a Vector data structure.

Note

Size will be calculated

Parameters

name: Name of data structure
ObjectType:
...: List of ObjectType* pointers

DEFINE_FSTR_VECTOR_DATA_SIZED(name, ObjectType, size, ...)¶

Define a Vector data structure and specify the number of elements.

Note

Use in situations where the array size cannot be automatically calculated

Parameters

name: Name of data structure
ObjectType:
size: Number of elements
...: List of ObjectType* pointers

Class Template¶

template <class ObjectType> class Vector : public FSTR::Object<Vector<ObjectType>, ObjectType *>¶

Class to access a Vector of objects stored in flash.

Template Parameters

ObjectType:

Public Types

template<> using Iterator = ObjectIterator<Vector<ObjectType>, ObjectType *>¶

Public Functions

template <typename ValueType, typename T = ObjectType> std::enable_if<std::is_same<T, String>::value, int>::type indexOf(const ValueType &value, bool ignoreCase = true) const¶

const ObjectType &valueAt(unsigned index) const¶

const ObjectType &operator[](unsigned index) const¶

ArrayPrinter<Vector> printer() const¶

size_t printTo(Print &p) const¶

Iterator begin() const

Iterator end() const

size_t length() const: Get the length of the content in elements.

int indexOf(const ValueType &value) const

size_t elementSize() const

const ObjectType **data() const

size_t read(size_t index, ObjectType **buffer, size_t count) const¶

Read content into RAM.

Parameters

index: First element to read
buffer: Where to store data
count: How many elements to read

Return Value

size_t: Number of elements actually read

size_t read(size_t offset, void *buffer, size_t count) const

Read contents of a String into RAM.

Parameters

offset: Zero-based offset from start of flash data to start reading
buffer: Where to store data
count: How many bytes to read

Return Value

size_t: Number of bytes actually read

size_t readFlash(size_t index, ObjectType **buffer, size_t count) const¶

Read content into RAM,using flashmem_read()

Parameters

index: First element to read
buffer: Where to store data
count: How many elements to read

Return Value

size_t: Number of elements actually read

size_t readFlash(size_t offset, void *buffer, size_t count) const

Read contents of a String into RAM, using flashread()

PROGMEM data is accessed via the CPU data cache, so to avoid degrading performance you can use this method to read data directly from flash memory. This is appropriate for infrequently accessed data, especially if it is large. For example, if storing content using

IMPORT_FSTR instead of SPIFFS then it is generally better to avoid contaminating the cache.

See