Strings

Collaboration diagram for Strings:

Macros
#define	FS_PTR(str)
	Define an inline String and return a pointer to it. More...
#define	FS(str)   (*FS_PTR(str))
	Define an inline FSTR::String and return it as a copy. More...
#define	DECLARE_FSTR(name)   DECLARE_FSTR_OBJECT(name, FSTR::String)
	Declare a global FSTR::String& reference. More...
#define	DEFINE_FSTR(name, str)
	Define a FSTR::String object with global reference. More...
#define	DEFINE_FSTR_LOCAL(name, str)
	Like DEFINE_FSTR except reference is declared static constexpr. More...
#define	DEFINE_FSTR_DATA(name, str)
	Define a FSTR::String data structure. More...
#define	LOAD_FSTR(name, fstr)
	Load a FSTR::String object into a named local (stack) buffer. More...
#define	FSTR_ARRAY(name, str)
	Define a flash FSTR::String and load it into a named char[] buffer on the stack. More...
#define	IMPORT_FSTR(name, file)   IMPORT_FSTR_OBJECT(name, FSTR::String, file)
	Define a FSTR::String containing data from an external file. More...
#define	IMPORT_FSTR_LOCAL(name, file)   IMPORT_FSTR_OBJECT_LOCAL(name, FSTR::String, file)
	Like IMPORT_FSTR except reference is declared static constexpr. More...
#define	FSTR_TABLE(name)   const FSTR::String* const name[] PROGMEM
	declare a table of FlashStrings More...

Detailed Description

Macro Definition Documentation

DECLARE_FSTR

#define DECLARE_FSTR

(

name

)

DECLARE_FSTR_OBJECT(name, FSTR::String)

Declare a global FSTR::String& reference.

Parameters

name

Note

Define the FSTR::String object using DEFINE_STR()

DEFINE_FSTR

#define DEFINE_FSTR	(		name,
			str
	)

Value:

    static DEFINE_FSTR_DATA(FSTR_DATA_NAME(name), str);                                                                \
    DEFINE_FSTR_REF_NAMED(name, FSTR::String);

Define a FSTR::String object with global reference.

Parameters

name	Name of FSTR::String& reference to define
str	Content of the FSTR::String

Example:

DEFINE_FSTR(test, "This is a test\0Another test\0hello")

The data includes the nul terminator but the length does not.

DEFINE_FSTR_DATA

#define DEFINE_FSTR_DATA	(		name,
			str
	)

Value:

    constexpr const struct {                                                                                           \
        FSTR::ObjectBase object;                                                                                       \
        char data[ALIGNUP4(sizeof(str))];                                                                              \
    } name PROGMEM = {{sizeof(str) - 1}, str};                                                                         \
    FSTR_CHECK_STRUCT(name);

Define a FSTR::String data structure.

Parameters

name	Name of data structure
str	Quoted string content

DEFINE_FSTR_LOCAL

#define DEFINE_FSTR_LOCAL	(		name,
			str
	)

Value:

    static DEFINE_FSTR_DATA(FSTR_DATA_NAME(name), str);                                                                \
    static constexpr DEFINE_FSTR_REF_NAMED(name, FSTR::String);

Like DEFINE_FSTR except reference is declared static constexpr.

FS

#define FS

(

str

)

(*FS_PTR(str))

Define an inline FSTR::String and return it as a copy.

Example:

    Serial.println(FS("This is a Flash String"));

FS_PTR

#define FS_PTR

(

str

)

Value:

    (__extension__({                                                                                                   \
        static DEFINE_FSTR_DATA(__fstr__, str);                                                                        \
        static_cast<const FSTR::String*>(&__fstr__.object);                                                            \
    }))

Define an inline String and return a pointer to it.

Note

The rather obscure asm statement is required to prevent the compiler from discarding the symbol at link time, which leads to an 'undefined reference' error

FSTR_ARRAY

#define FSTR_ARRAY	(		name,
			str
	)

Value:

    static DEFINE_FSTR_DATA(FSTR_DATA_NAME(name), str);                                                                \
    LOAD_FSTR(name, FSTR_DATA_NAME(name).object.template as<FSTR::String>())

Define a flash FSTR::String and load it into a named char[] buffer on the stack.

Parameters

name	Name of char[] buffer
str	Content of FSTR::String

Note

Equivalent to char name[] = "text" except the buffer is word aligned. Faster than using a temporary Wiring String and avoids using the heap.

FSTR_TABLE

#define FSTR_TABLE

(

name

)

const FSTR::String* const name[] PROGMEM

declare a table of FlashStrings

Parameters

name	name of the table

Deprecated:

Use a Vector or Map

Declares a simple table. Example:

DEFINE_FSTR(fstr1, "Test string #1");
DEFINE_FSTR(fstr2, "Test string #2");

FSTR_TABLE(table) = {
    &fstr1,
    &fstr2,
};

Table entries may be accessed directly as they are word-aligned. Examples:

debugf("fstr1 = '%s'", FSTR::String(*table[0]).c_str());
debugf("fstr2.length() = %u", table[1]->length());

IMPORT_FSTR

#define IMPORT_FSTR	(		name,
			file
	)		IMPORT_FSTR_OBJECT(name, FSTR::String, file)

Define a FSTR::String containing data from an external file.

Parameters

name	Name for the FSTR::String object
file	Absolute path to the file containing the content

See also

See also IMPORT_FSTR_DATA

IMPORT_FSTR_LOCAL

#define IMPORT_FSTR_LOCAL	(		name,
			file
	)		IMPORT_FSTR_OBJECT_LOCAL(name, FSTR::String, file)

Like IMPORT_FSTR except reference is declared static constexpr.

LOAD_FSTR

#define LOAD_FSTR	(		name,
			fstr
	)

Value:

    char name[(fstr).size()] FSTR_ALIGNED;                                                                             \
    memcpy_aligned(name, (fstr).data(), (fstr).length());                                                              \
    name[(fstr).length()] = '\0';

Load a FSTR::String object into a named local (stack) buffer.

Example:

DEFINE_FSTR(globalTest, "This is a testing string")
...
LOAD_FSTR(local, globalTest)
printf("%s, %u characters, buffer is %u bytes\n", local, globalTest.length(), sizeof(local));