search

GyverLibs / GyverDB

Простая база данных для Arduino
MIT License
7 stars 1 forks source link

readme

latest PIO Foo Foo Foo

Foo

GyverDB

Простая база данных для Arduino:

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

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

Зависимости

Содержание

Использование

Настройки компиляции перед подключением библиотеки

#define DB_NO_UPDATES  // убрать стек обновлений
#define DB_NO_FLOAT    // убрать поддержку float
#define DB_NO_INT64    // убрать поддержку int64
#define DB_NO_CONVERT  // не конвертировать данные (принудительно менять тип записи, keepTypes не работает)

GyverDB

// конструктор
// можно зарезервировать ячейки
GyverDB(uint16_t reserve = 0);

// не изменять тип записи (конвертировать данные если тип отличается) (умолч. true)
void keepTypes(bool keep);

// использовать стек обновлений (умолч. false)
void useUpdates(bool use);

// было изменение данных. После срабатывания сбросится в false
bool changed();

// вывести всё содержимое БД
void dump(Print& p);

// полный вес БД
size_t size();

// экспортный размер БД (для writeTo)
size_t writeSize();

// экспортировать БД в Stream (напр. файл)
bool writeTo(Stream& stream);

// экспортировать БД в буфер размера writeSize()
bool writeTo(uint8_t* buffer);

// импортировать БД из Stream (напр. файл)
bool readFrom(Stream& stream, size_t len);

// импортировать БД из буфера
bool readFrom(const uint8_t* buffer, size_t len);

// создать запись. Если существует - перезаписать пустой с новым типом
bool create(size_t hash, gdb::Type type, uint16_t reserve = 0);

// полностью освободить память
void reset();

// стереть все записи (не освобождает зарезервированное место)
void clear();

// удалить из БД записи, ключей которых нет в переданном списке
void cleanup(size_t* hashes, size_t len);

// вывести все ключи в массив длиной length()
void getKeys(size_t* hashes);

// получить запись
gdb::Entry get(size_t hash);
gdb::Entry get(const Text& key);

// получить запись по порядку
gdb::Entry getN(int idx);

// удалить запись
void remove(size_t hash);
void remove(const Text& key);

// БД содержит запись с именем
bool has(size_t hash);
bool has(const Text& key);

// записать данные (создать ячейку, если не существует). DATA - любой тип данных
bool set(size_t hash, DATA data);
bool set(const Text& key hash, DATA data);

// инициализировать данные (создать ячейку и записать, если ячейка не существует). DATA - любой тип данных
bool init(size_t hash, DATA data);
bool init(const Text& key hash, DATA data);

// обновить данные (если ячейка существует). DATA - любой тип данных
bool update(size_t hash, DATA data);
bool update(const Text& key hash, DATA data);

GyverDBFile

Данный класс наследует GyverDB, но умеет самостоятельно записываться в файл на флешку ESP при любом изменении и по истечении таймаута

GyverDBFile(fs::FS* nfs = nullptr, const char* path = nullptr, uint32_t tout = 10000);

// установить файловую систему и имя файла
void setFS(fs::FS* nfs, const char* path);

// установить таймаут записи, мс (умолч. 10000)
void setTimeout(uint32_t tout = 10000);

// прочитать данные
bool begin();

// обновить данные в файле сейчас
bool update();

// тикер, вызывать в loop. Сам обновит данные при изменении и выходе таймаута, вернёт true
bool tick();

Для использования нужно запустить FS и вызывать тикер в loop. При любом изменении в БД она сама запишется в файл после выхода таймаута:

#include <LittleFS.h>
#include <GyverDBFile.h>
GyverDBFile db(&LittleFS, "/db.bin");

void setup() {
    LittleFS.begin();
    db.begin(); // прочитать данные из файла

    // для работы в таком режиме очень пригодится метод init():
    // создаёт запись соответствующего типа и записывает "начальные" данные,
    // если такой записи ещё нет в БД
    db.init("key", 123);    // int
    db.init("uint", 123ul); // uint32
    db.init("str", "init"); // строка
}
void loop() {
    db.tick();
}

Типы записей

None
Int
Uint
Int64
Uint64
Float
String
Bin

Entry

// тип записи
gdb::Type type();

// вывести данные в буфер размера size(). Не добавляет 0-терминатор, если это строка
void writeBytes(void* buf);

// вывести в переменную
bool writeTo(T& dest);

Value toText();
String toString();
bool toBool();
int32_t toInt();
int64_t toInt64();
double toFloat();

Использование

Ключи

БД хранит ключи в виде хэш-кодов, для доступа к БД нужно использовать непосредственно хэш или обычную строку, библиотека сама посчитает хэш:

db["key1"] = 1234;      // строка
db[SH("key2")] = 1234;  // хэш
db["key3"_h] = 1234;    // хэш

Здесь SH() - хэш-функция из библиотеки StringUtils, выполняемая на этапе компиляции. Переданная в неё строка не существует в программе - на этапе компиляции она превращается в число. Также можно использовать литерал _h - он делает же самое.

Так как хэш - это число, то с базой можно работать и просто обычными числами. Можно считать, что база данных - это массив на 2^29 ячейки:

db[0] = 123;
db[2] = 456;
db[100] = "hello";

И поэтому вместо хэшей также можно использовать обычный enum:

enum keys : size_t {
    key1,
    key2,
    mykey,
    lolkek,
};

db[keys::key1] = 123;
db[keys::key2] = 456;
db[keys::lolkek] = "hello";

Это очень удобно, потому что IDE подскажет список имеющихся ключей при вводе keys::.

При активной разработке может оказаться удобнее использовать хэш-ключи, так как удаление ключа из обычного enum приведёт к смещению нумерации и под старыми ключами окажутся новые данные. В этом случае enum тоже можно использовать для подсказок IDE, но чуть в другом виде:

enum keys : size_t {
    key1 = SH("key1"),
    key2 = SH("key2"),
    mykey = SH("mykey"),
};

Теперь enum хранит хэши и не боится удаления или добавления ключей не в конец. Для более короткой записи в библиотеке есть удобный макрос:

DB_KEYS(keys,
    key1,
    key2,
    mykey  // последнюю запятую ставить нельзя
);

Он развернётся в такой же хэш-enum как в примере выше.

Запись и чтение

GyverDB db;

// эта ячейка у нас объявлена как int, текст корректно сконвертируется в число
db["key1"] = "123456";

// чтение. Библиотека сама конвертирует в нужный тип
int i = db["key1"];
float f = db[SH("key2")];

// любые данные "печатаются", даже бинарные
Serial.println(db["key3"_h]);

// можно указать конкретный тип при выводе
db["key3"_h].toInt32();

// можно сравнивать с целочисленными
int i = 123;
db["key1"] == i;
db["key1"] >= i;

// сравнение напрямую со строками работает только у записей с типом String
db["key1"] == "str";

// но можно и вот так, для любых типов записей
// toText() конвертирует все типы записей БД во временную строку
db["key1"].toText() == "12345";

// GyverDB может записать данные любого типа, даже составные (массивы, структуры)
uint8_t arr[5] = {1, 2, 3, 4, 5};
db["arr"] = arr;

// вывод обратно. Тип должен иметь такой же размер!
uint8_t arr2[5];
db["arr"].writeTo(arr2);

// посмотрим что записалось
db.dump(Serial);

При разработке проекта может оказаться так, что некоторые ключи "устарели" или были переименованы в процессе разработки, и записи по ним уже не нужны. В библиотеке есть возможность провести очистку БД: удалить все лишние записи и оставить только заданный список ключей. Это делается так:

  // список ключей, которые надо оставить. В формате size_t в любом виде
  size_t hashes[] = {SH("key1"), "key2"_h, kesy::key3};

  // очищаем
  db.cleanup(hashes, 3);

  // в БД останутся только записи, соответствующие указанным выше ключам

Примечания

Версии

Установка

Баги и обратная связь

При нахождении багов создавайте Issue, а лучше сразу пишите на почту alex@alexgyver.ru
Библиотека открыта для доработки и ваших Pull Request'ов!

При сообщении о багах или некорректной работе библиотеки нужно обязательно указывать: