StringUtils

Набор инструментов для работы со строками

• Быстрые функции конвертации
• Парсинг, разбивание по разделителям
• Несколько классов-конвертеров данных в строку и обратно для использования в других библиотеках
• Кодирование и раскодирование base64, url, unicode, йцукен/qwerty-раскладки

Совместимость

Совместима со всеми Arduino платформами (используются Arduino-функции)

Содержание

• Документация
• Версии
• Установка
• Баги и обратная связь

<a id="docs"></a>

Документация

Text

Класс-обёртка для всех типов строк. Может быть создана в конструкторе из:

• "const char" - строки
• char[] - строки
• F("f-строки")
• PROGMEM - строки
• String - строки

Особенности:

• Хранит тип и длину строки
• Позволяет печататься, конвертироваться в любой целочисленный формат и сравниваться с переменными всех стандартных типов, а также сравниваться с любыми другими строками
• Вывод в подстроки разными способами, поиск и разделение
• Не может изменять исходную строку, все операции только "для чтения"
• Не создаёт копию строки и работает с оригинальной строкой, т.е. оригинальная строка должна быть в памяти на время существования Text
• Если создана из String строки, то оригинальная String строка не должна меняться в процессе работы экземпляра Text

// ====== КОНСТРУКТОР ======
Text(String& str);
Text(const String& str);
Text(const uint8_t* str, uint16_t len);
Text(const char* str, int16_t len = 0, bool pgm = 0);
Text(const __FlashStringHelper* str, int16_t len = 0);

// ======== СИСТЕМА ========
operator bool();                    // Статус строки, существует или нет
bool valid();                       // Статус строки, существует или нет
bool pgm();                         // Строка из Flash памяти
uint16_t length();                  // Длина строки
uint16_t readLen();                 // посчитать и вернуть длину строки (const)
void calcLen();                     // пересчитать и запомнить длину строки (non-const)
Type type();                        // Тип строки
const uint8_t* bytes();             // Получить указатель на строку. Всегда вернёт указатель, отличный от nullptr!
const char* str();                  // Получить указатель на строку. Всегда вернёт ненулевой указатель
const char* end();                  // указатель на конец строки. Всегда вернёт ненулевой указатель
bool terminated();                  // строка валидна и оканчивается \0

// ======== UNICODE ========
// Длина строки с учётом unicode символов
uint16_t lengthUnicode();

// получить позицию юникод символа в строке, если она содержит юникод
uint16_t posToUnicode(uint16_t pos);

// получить реальную позицию символа в строке, если она содержит юникод
uint16_t unicodeToPos(uint16_t pos);

// ======== ХЭШ ========
size_t hash();              // хэш строки size_t
uint32_t hash32();          // хэш строки 32 бит

// ======== PRINT ========
size_t printTo(Print& p);   // Напечатать в Print (c учётом длины)

// ======== СРАВНЕНИЕ И ПОИСК ========
// сравнивается со всеми типами строк через ==

// Сравнить со строкой, начиная с индекса
bool compare(Text s, uint16_t from = 0);

// Сравнить со строкой, начиная с индекса, с указанием количества символов
bool compareN(Text s, uint16_t amount, uint16_t from = 0);

// Найти позицию символа в строке, начиная с индекса
int16_t indexOf(char sym, uint16_t from = 0);

// Найти позицию строки в строке
int16_t indexOf(Text txt, uint16_t from = 0);

// Найти позицию строки в строке
int16_t indexOfUnicode(Text txt, uint16_t from = 0);

// Найти позицию символа в строке с конца
int16_t lastIndexOf(char sym);

// Найти позицию строки в строке с конца
int16_t lastIndexOf(Text txt);

// Найти позицию строки в строке с конца
int16_t lastIndexOfUnicode(Text txt);

// найти символ и получить указатель на первое вхождение
const char* find(char sym, uint16_t from = 0);

// начинается со строки
bool startsWith(const Text& txt);
bool startsWith(char c);

// заканчивается строкой
bool endsWith(const Text& txt);
bool endsWith(char c);

// ======== РАЗДЕЛЕНИЕ И ПАРСИНГ ========
// вернёт новую строку с убранными пробельными символами с начала и конца
Text trim();

// Посчитать количество подстрок, разделённых символом (количество разделителей +1)
uint16_t count(char sym);

// Посчитать количество подстрок, разделённых строками (количество разделителей +1)
uint16_t count(Text txt);

// Разделить по символу-разделителю в массив любого типа
uint16_t split(T* arr, uint16_t len, char div);
uint16_t split(T** arr, uint16_t len, char div);

// Разделить по строке-разделителю в массив любого типа
uint16_t split(T* arr, uint16_t len, Text div);
uint16_t split(T** arr, uint16_t len, Text div);

// Получить подстроку из списка по индексу и разделителю
Text getSub(uint16_t idx, char div);
Text getSub(uint16_t idx, Text div);

// Найти индекс подстроки по разделителю. Вернёт -1 если не найдено
int findSub(Text sub, char div);
int findSub(Text sub, Text div);

// выделить подстроку (начало, конец не включая). Отрицательные индексы работают с конца строки
Text substring(int16_t start, int16_t end = 0);

// выделить подстроку с содержанием юникода (начало, конец не включая). Отрицательные индексы работают с конца строки
Text substringUnicode(int16_t start, int16_t end = 0);

// Получить символ по индексу. Допускаются отрицательные
char charAt(int idx);
char operator[](int idx);

// ======== ВЫВОД. СТРОКИ ========
// получить const char* копию (Cstr конвертируется в const char*). Всегда валидна и терминирована. Если Text из PGM или не терминирован - будет создана временная копия
Cstr c_str();

// Получить как String строку
String toString(bool decodeUnicode = false);

// Вывести в String строку. Вернёт false при неудаче
bool toString(String& s, bool decodeUnicode = false);

// Добавить к String строке. Вернёт false при неудаче
bool addString(String& s, bool decodeUnicode = false);

// Вывести в char массив. Вернёт длину строки. terminate - завершить строку нулём
uint16_t toStr(char* buf, int16_t bufsize = -1, bool terminate = true);

// получить как строку, раскодировать unicode
String decodeUnicode();

// получить как строку, раскодировать urlencode
String decodeUrl();

// ======== ВЫВОД. B64 ========
// размер данных (байт), если они b64
size_t sizeB64();

// вывести в переменную из b64
bool decodeB64(void* var, size_t size);

// ======== ВЫВОД. ЧИСЛА ========
bool toBool();              // получить значение как bool
int toInt();                // получить значение как int
int16_t toInt16();          // получить значение как int16
int32_t toInt32();          // получить значение как int32
int64_t toInt64();          // получить значение как int64
uint32_t toInt32HEX();      // получить значение как uint 32 из HEX строки
float toFloat();            // получить значение как float

// также автоматически конвертируется и сравнивается с
char + unsigned
short + unsigned
int + unsigned
long + unsigned
long long + unsigned
bool
float
double
String

// для ручного управления строкой
const char* _str;           // указатель на строку
uint16_t _len;              // длина

Конвертация в целочисленные

Text может конвертироваться во все стандартные целочисленные типы вручную и автоматически (implicit и explicit):

Text t("1234");

int v = t;
(int)t;
t.toInt();

Сравнение

Text может сравниваться со всеми стандартными типами (автоматически преобразуется):

Text t("1234");

t == 1234;
t >= 1234;
t == "1234";
t == F("1234");

Конвертация в bool

Приведение Text к bool проверяет валидность строки (корректная или нет), это конструкции вида:

Text t;

(bool)t;
!t;
!!t;
if (t);

Для конвертации в bool как значение нужно использовать метод преобразования toBool(), а лучше - сравнение (учитывает валидность):

Text t;

t.toBool();
if (t == true);
if (t == false);

Если строка невалидна - сравнение с bool вернёт false независимо от значения.

Вывод в строку

Text можно вывести в новую String-строку:

t.toString();      // вернёт String
String s = t;      // запишется в s
t.toString(s);     // запишется в s
t.addString(s);    // прибавится к s

Можно вывести в строку с декодированием:

String s = t.decodeUnicode();   // декодировать UCN символы (вида \uxxx\uxxx)
String s = t.decodeUrl();       // декодировать urlencoded символы (вида %AB)

Вывод в массив

Text можно вывести в массив char (можно указать размер буфера и терминировать ли строку):

char buf[20];
t.toStr(buf);

Вывод как C-строка

Часто бывает нужно передать Text строку в функцию, которая принимает const char*. Метод str() вернёт указатель на начало строки, но случаях, когда Text создан

• Из PROGMEM строки
• Из обычной строки с указанием размера, меньшего чем размер оригинальной строки (например любой элемент JSON при парсинге библиотекой GSON)

Такая "строка" не будет являться корректной, потому что име