400 lines
16 KiB
Markdown
400 lines
16 KiB
Markdown
# zh_vector - Компонент вектора (динамического массива) для ESP-IDF
|
|
|
|
## Содержание
|
|
|
|
- [Обзор](#обзор)
|
|
- [Возможности](#возможности)
|
|
- [Установка](#установка)
|
|
- [Справочник API](#справочник-api)
|
|
- [Примеры использования](#примеры-использования)
|
|
- [Технические характеристики](#технические-характеристики)
|
|
- [Коды ошибок](#коды-ошибок)
|
|
- [Вклад в проект](#вклад-в-проект)
|
|
- [Лицензия](#лицензия)
|
|
|
|
---
|
|
|
|
## Обзор
|
|
|
|
`zh_vector` — это легковесный и эффективный компонент вектора (динамического массива) для ESP-IDF (Espressif IoT Development Framework). Он предоставляет гибкий контейнер, который может хранить элементы любого типа данных с автоматическим управлением памятью. Вектор автоматически изменяет размер при добавлении или удалении элементов, что делает его идеальным для динамического управления данными во встраиваемых системах.
|
|
|
|
Компонент разработан специально для микроконтроллеров ESP32 и использует функции управления кучей ESP-IDF для оптимального выделения памяти с различными параметрами памяти (внутренняя/внешняя RAM).
|
|
|
|
---
|
|
|
|
## Возможности
|
|
|
|
1. **Независимость от типа данных**: Поддерживает любой тип данных (целые числа, числа с плавающей точкой, структуры, пользовательские типы и т.д.)
|
|
2. **Автоматическое управление памятью**: Автоматическое выделение и освобождение памяти
|
|
3. **Динамическое изменение размера**: Емкость вектора увеличивается и уменьшается по мере необходимости
|
|
4. **Максимальная емкость**: До 65 535 элементов (ограничение 16-битного индекса)
|
|
5. **Оптимизировано под ESP-IDF**: Использует функции heap_caps для выделения памяти с параметрами памяти
|
|
6. **Обработка ошибок**: Комплексная проверка ошибок с детальным логированием
|
|
7. **Потокобезопасность**: Не является потокобезопасным по умолчанию (можно сделать потокобезопасным с внешним мьютексом)
|
|
8. **Минимальные накладные расходы**: Низкие накладные расходы на память и процессор
|
|
|
|
---
|
|
|
|
## Установка
|
|
|
|
1. Перейдите в каталог компонентов вашего проекта:
|
|
|
|
```bash
|
|
cd ../ваш_проект/components
|
|
```
|
|
|
|
2. Клонируйте репозиторий:
|
|
|
|
```bash
|
|
git clone https://github.com/aZholtikov/zh_vector
|
|
```
|
|
|
|
3. В вашем приложении подключите заголовочный файл:
|
|
|
|
```c
|
|
#include "zh_vector.h"
|
|
```
|
|
|
|
4. Компонент будет автоматически собран вместе с вашим проектом.
|
|
|
|
---
|
|
|
|
## Справочник API
|
|
|
|
### Структура zh_vector_t
|
|
|
|
```c
|
|
typedef struct
|
|
{
|
|
void **items; // Массив указателей на элементы вектора
|
|
uint16_t capacity; // Максимальная емкость вектора
|
|
uint16_t size; // Количество элементов в векторе
|
|
uint16_t unit; // Размер элемента вектора (в байтах)
|
|
bool is_initialized; // Флаг состояния инициализации вектора
|
|
} zh_vector_t;
|
|
```
|
|
|
|
---
|
|
|
|
### zh_vector_init()
|
|
|
|
Инициализирует вектор.
|
|
|
|
**Параметры:**
|
|
|
|
- `vector` - Указатель на структуру вектора
|
|
- `unit` - Размер каждого элемента в байтах
|
|
|
|
**Возвращает:**
|
|
|
|
- `ESP_OK` - Успех
|
|
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL вектор или нулевой размер unit)
|
|
- `ESP_ERR_INVALID_STATE` - Вектор уже инициализирован
|
|
|
|
**Пример:**
|
|
|
|
```c
|
|
zh_vector_t vector = {0};
|
|
zh_vector_init(&vector, sizeof(int)); // Для целых чисел
|
|
```
|
|
|
|
---
|
|
|
|
### zh_vector_free()
|
|
|
|
Деинициализирует вектор и освобождает всю выделенную память.
|
|
|
|
**Параметры:**
|
|
|
|
- `vector` - Указатель на структуру вектора
|
|
|
|
**Возвращает:**
|
|
|
|
- `ESP_OK` - Успех
|
|
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL вектор)
|
|
- `ESP_ERR_INVALID_STATE` - Вектор не инициализирован
|
|
|
|
**Примечание:** Вся динамически выделенная память элементов также освобождается.
|
|
|
|
---
|
|
|
|
### zh_vector_get_size()
|
|
|
|
Получает текущее количество элементов в векторе.
|
|
|
|
**Параметры:**
|
|
|
|
- `vector` - Указатель на структуру вектора
|
|
|
|
**Возвращает:**
|
|
|
|
- `>= 0` - Количество элементов (успех)
|
|
- `ESP_FAIL` - Ошибка (NULL вектор или не инициализирован)
|
|
|
|
---
|
|
|
|
### zh_vector_push_back()
|
|
|
|
Добавляет элемент в конец вектора.
|
|
|
|
**Параметры:**
|
|
|
|
- `vector` - Указатель на структуру вектора
|
|
- `item` - Указатель на элемент для добавления
|
|
|
|
**Возвращает:**
|
|
|
|
- `ESP_OK` - Успех
|
|
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL вектор или item)
|
|
- `ESP_ERR_INVALID_STATE` - Вектор не инициализирован
|
|
- `ESP_ERR_NO_MEM` - Ошибка выделения памяти
|
|
|
|
**Примечание:** Функция выделяет память для копии элемента и копирует данные.
|
|
|
|
---
|
|
|
|
### zh_vector_change_item()
|
|
|
|
Изменяет элемент по определенному индексу.
|
|
|
|
**Параметры:**
|
|
|
|
- `vector` - Указатель на структуру вектора
|
|
- `index` - Индекс элемента для изменения (начиная с 0)
|
|
- `item` - Указатель на новые данные элемента
|
|
|
|
**Возвращает:**
|
|
|
|
- `ESP_OK` - Успех
|
|
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL вектор, item или неверный индекс)
|
|
- `ESP_ERR_INVALID_STATE` - Вектор не инициализирован
|
|
- `ESP_FAIL` - Индекс вне границ
|
|
|
|
---
|
|
|
|
### zh_vector_get_item()
|
|
|
|
Получает элемент по определенному индексу.
|
|
|
|
**Параметры:**
|
|
|
|
- `vector` - Указатель на структуру вектора
|
|
- `index` - Индекс элемента для получения (начиная с 0)
|
|
|
|
**Возвращает:**
|
|
|
|
- Указатель на элемент (успех)
|
|
- `NULL` - Ошибка (NULL вектор, не инициализирован или неверный индекс)
|
|
|
|
**Примечание:** Возвращает указатель на внутренние данные. Не освобождайте этот указатель.
|
|
|
|
---
|
|
|
|
### zh_vector_delete_item()
|
|
|
|
Удаляет элемент по определенному индексу и сдвигает все последующие элементы.
|
|
|
|
**Параметры:**
|
|
|
|
- `vector` - Указатель на структуру вектора
|
|
- `index` - Индекс элемента для удаления (начиная с 0)
|
|
|
|
**Возвращает:**
|
|
|
|
- `ESP_OK` - Успех
|
|
- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL вектор)
|
|
- `ESP_ERR_INVALID_STATE` - Вектор не инициализирован
|
|
- `ESP_FAIL` - Индекс вне границ
|
|
|
|
**Примечание:** Все элементы после удаляемого индекса сдвигаются влево на одну позицию.
|
|
|
|
---
|
|
|
|
## Примеры использования
|
|
|
|
### Базовый пример: Вектор целых чисел
|
|
|
|
```c
|
|
#include "zh_vector.h"
|
|
|
|
zh_vector_t int_vector = {0};
|
|
|
|
void app_main(void)
|
|
{
|
|
// Инициализация вектора для целых чисел
|
|
zh_vector_init(&int_vector, sizeof(int));
|
|
|
|
// Добавление элементов
|
|
int val1 = 10;
|
|
int val2 = 20;
|
|
int val3 = 30;
|
|
|
|
zh_vector_push_back(&int_vector, &val1);
|
|
zh_vector_push_back(&int_vector, &val2);
|
|
zh_vector_push_back(&int_vector, &val3);
|
|
|
|
printf("Размер вектора: %d\n", zh_vector_get_size(&int_vector));
|
|
|
|
// Доступ к элементам
|
|
for (int i = 0; i < zh_vector_get_size(&int_vector); i++) {
|
|
int *item = (int *)zh_vector_get_item(&int_vector, i);
|
|
printf("Элемент %d: %d\n", i, *item);
|
|
}
|
|
|
|
// Изменение элемента
|
|
int new_val = 100;
|
|
zh_vector_change_item(&int_vector, 1, &new_val);
|
|
|
|
// Удаление элемента
|
|
zh_vector_delete_item(&int_vector, 0);
|
|
|
|
// Очистка
|
|
zh_vector_free(&int_vector);
|
|
}
|
|
```
|
|
|
|
### Пример со структурой
|
|
|
|
```c
|
|
#include "zh_vector.h"
|
|
|
|
typedef struct {
|
|
int id;
|
|
char name[32];
|
|
float value;
|
|
} my_struct_t;
|
|
|
|
zh_vector_t struct_vector = {0};
|
|
|
|
void app_main(void)
|
|
{
|
|
// Инициализация вектора для структур
|
|
zh_vector_init(&struct_vector, sizeof(my_struct_t));
|
|
|
|
// Добавление элементов-структур
|
|
my_struct_t item1 = {1, "Item 1", 1.5f};
|
|
my_struct_t item2 = {2, "Item 2", 2.5f};
|
|
|
|
zh_vector_push_back(&struct_vector, &item1);
|
|
zh_vector_push_back(&struct_vector, &item2);
|
|
|
|
// Доступ и модификация
|
|
my_struct_t *ptr = (my_struct_t *)zh_vector_get_item(&struct_vector, 0);
|
|
ptr->value = 10.5f;
|
|
|
|
// Очистка
|
|
zh_vector_free(&struct_vector);
|
|
}
|
|
```
|
|
|
|
### Пример со строками (массивы символов)
|
|
|
|
```c
|
|
#include "zh_vector.h"
|
|
#include "string.h"
|
|
|
|
zh_vector_t string_vector = {0};
|
|
|
|
void app_main(void)
|
|
{
|
|
// Инициализация вектора для строк (макс. 100 символов)
|
|
char buffer[100] = {0};
|
|
zh_vector_init(&string_vector, sizeof(buffer));
|
|
|
|
// Добавление строк
|
|
strcpy(buffer, "Привет");
|
|
zh_vector_push_back(&string_vector, &buffer);
|
|
|
|
strcpy(buffer, "Мир");
|
|
zh_vector_push_back(&string_vector, &buffer);
|
|
|
|
// Печать всех строк
|
|
for (int i = 0; i < zh_vector_get_size(&string_vector); i++) {
|
|
char *str = (char *)zh_vector_get_item(&string_vector, i);
|
|
printf("Строка %d: %s\n", i, str);
|
|
}
|
|
|
|
// Очистка
|
|
zh_vector_free(&string_vector);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Технические характеристики
|
|
|
|
| Параметр | Значение |
|
|
|----------|----------|
|
|
| **Максимальная емкость** | 65 535 элементов |
|
|
| **Тип индекса** | uint16_t (16-бит) |
|
|
| **Управление памятью** | heap_caps_calloc, heap_caps_realloc, heap_caps_free |
|
|
| **Параметры памяти** | MALLOC_CAP_8BIT |
|
|
| **Потокобезопасность** | Не является потокобезопасным |
|
|
| **Версия ESP-IDF** | Тестировалось с v6.0.0 |
|
|
| **Платформа** | Серия ESP32 |
|
|
| **Язык** | C (C99) |
|
|
|
|
---
|
|
|
|
## Коды ошибок
|
|
|
|
| Код ошибки | Описание |
|
|
|------------|----------|
|
|
| `ESP_OK` | Операция выполнена успешно |
|
|
| `ESP_ERR_INVALID_ARG` | Неверный аргумент (NULL указатель или нулевой размер) |
|
|
| `ESP_ERR_INVALID_STATE` | Вектор не инициализирован или уже инициализирован |
|
|
| `ESP_ERR_NO_MEM` | Ошибка выделения памяти (не хватает памяти) |
|
|
| `ESP_FAIL` | Общий сбой (например, индекс вне границ) |
|
|
|
|
---
|
|
|
|
## Вклад в проект
|
|
|
|
Вклад приветствуется! Чтобы внести свой вклад:
|
|
|
|
1. Сделайте форк репозитория
|
|
2. Создайте ветку функции (`git checkout -b feature/AmazingFeature`)
|
|
3. Закоммитьте ваши изменения (`git commit -m 'Add some AmazingFeature'`)
|
|
4. Отправьте в ветку (`git push origin feature/AmazingFeature`)
|
|
5. Откройте Pull Request
|
|
|
|
Пожалуйста, убедитесь, что ваш код следует существующему стилю и включает соответствующую документацию.
|
|
|
|
---
|
|
|
|
## Лицензия
|
|
|
|
Этот проект лицензирован по лицензии Apache, версия 2.0 - см. файл [LICENSE](LICENSE) для подробной информации.
|
|
|
|
### Apache License, Version 2.0
|
|
|
|
Авторское право (c) 2026 Алексей Жолтиков
|
|
|
|
Лицензировано по лицензии Apache License, Version 2.0 (далее — "Лицензия");
|
|
вы не можете использовать этот файл, кроме случаев, предусмотренных Лицензией.
|
|
Копию Лицензии можно получить по адресу:
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Если иное не требуется действующим законодательством или не согласовано в письменном виде,
|
|
программное обеспечение, распространяемое по Лицензии, распространяется на условиях "КАК ЕСТЬ",
|
|
БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, явных или подразумеваемых, включая, но не ограничиваясь, гарантии
|
|
ТОВАРНОГО СОСТОЯНИЯ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ.
|
|
Смотрите Лицензию для получения конкретных прав и ограничений.
|
|
|
|
---
|
|
|
|
## Дополнительные заметки
|
|
|
|
- **Накладные расходы памяти**: Каждый элемент требует дополнительной памяти для указателя во внутреннем массиве указателей
|
|
- **Производительность**: O(1) для получения/установки по индексу, O(n) для вставки/удаления в середине
|
|
- **Лучшие практики**:
|
|
- Всегда инициализируйте вектор перед использованием
|
|
- Освобождайте вектор по завершении, чтобы избежать утечек памяти
|
|
- Учитывайте ограничение максимального размера (65 535 элементов)
|
|
- Для обработки строк рассмотрите использование буферов фиксированного размера
|
|
|
|
---
|
|
|
|
*Сгенерировано для zh_vector v1.1.1*
|