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_LOCAL(str1, "Test string #1");
DEFINE_FSTR_LOCAL(str2, "Test string #2");
IMPORT_FSTR_LOCAL(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>, const ObjectType*>

Class to access a Vector of objects stored in flash.

Template Parameters:: ObjectType –