diff --git a/WIKI_EN.md b/WIKI_EN.md index f54cc87..3a1f14c 100644 --- a/WIKI_EN.md +++ b/WIKI_EN.md @@ -126,6 +126,25 @@ Deinitializes the vector and frees all allocated memory. Sets the vector pointer --- +### zh_vector_get_capacity() + +Gets the current allocated capacity of the vector (maximum number of elements without reallocation). + +**Parameters:** + +- `vector` - Pointer to pointer to vector structure (`zh_vector_t **`). Must not be NULL. +- `capacity` - Pointer to variable to store the capacity. Must not be NULL. + +**Returns:** + +- `ESP_OK` - Success +- `ESP_ERR_INVALID_ARG` - Invalid argument (NULL vector pointer or capacity pointer) +- `ESP_ERR_INVALID_STATE` - Failed to acquire mutex (rare system error) + +**Note:** Capacity may be larger than the current size (e.g., after deletions), and is reduced lazily when size < capacity/2 (or when size becomes 0). + +--- + ### zh_vector_get_size() Gets the current number of elements in the vector. diff --git a/WIKI_RU.md b/WIKI_RU.md index f7772af..f8e1be4 100644 --- a/WIKI_RU.md +++ b/WIKI_RU.md @@ -126,6 +126,25 @@ if (ret != ESP_OK) { --- +### zh_vector_get_capacity() + +Получает текущую выделенную емкость вектора (максимальное количество элементов без перераспределения). + +**Параметры:** + +- `vector` - Указатель на указатель на структуру вектора (`zh_vector_t **`). Не должен быть NULL. +- `capacity` - Указатель на переменную для сохранения емкости. Не должен быть NULL. + +**Возвращает:** + +- `ESP_OK` - Успех +- `ESP_ERR_INVALID_ARG` - Неверный аргумент (NULL указатель на указатель на вектор или capacity) +- `ESP_ERR_INVALID_STATE` - Не удалось захватить mutex (редкий системный сбой) + +**Примечание:** Емкость может быть больше текущего размера (например, после удалений), и уменьшается лениво при size < capacity/2 (или когда size становится 0). + +--- + ### zh_vector_get_size() Получает текущее количество элементов в векторе. diff --git a/idf_component.yml b/idf_component.yml index 7c577bc..7f537c8 100644 --- a/idf_component.yml +++ b/idf_component.yml @@ -1,6 +1,6 @@ description: ESP32 ESP-IDF component for vector (dynamic array) url: https://github.com/aZholtikov/zh_vector -version: "2.0.0" +version: "2.1.0" license: "Apache-2.0" maintainers: - "Alexey Zholtikov " diff --git a/include/zh_vector.h b/include/zh_vector.h index 36c03dc..a2a03f1 100644 --- a/include/zh_vector.h +++ b/include/zh_vector.h @@ -79,6 +79,23 @@ extern "C" */ esp_err_t zh_vector_get_size(zh_vector_t **vector, uint16_t *size); + /** + * @brief Gets the current allocated capacity (maximum number of elements without reallocation). + * + * @note Thread-safe: internally locks/unlocks the mutex. + * @note Capacity may be larger than the current size (e.g., after deletions), and is reduced + * lazily via _resize() only when size < capacity/2 (or when size becomes 0). + * @note When the vector is empty (size == 0), capacity is guaranteed to be 0. + * + * @param[in] vector Double pointer to vector structure (`zh_vector_t **`). Must not be `NULL`. + * @param[out] capacity Pointer to store the allocated capacity. Must not be `NULL`. + * + * @return ESP_OK on success. + * @return ESP_ERR_INVALID_ARG if `vector == NULL`, `capacity == NULL`, or `*vector == NULL` (not initialized). + * @return ESP_ERR_INVALID_STATE if the internal mutex cannot be acquired (rare, indicates a system error). + */ + esp_err_t zh_vector_get_capacity(zh_vector_t **vector, uint16_t *capacity); + /** * @brief Adds a copy of the item to the beginning of the vector. * diff --git a/version.txt b/version.txt index 359a5b9..50aea0e 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -2.0.0 \ No newline at end of file +2.1.0 \ No newline at end of file diff --git a/zh_vector.c b/zh_vector.c index 04f27ff..4c9eb09 100644 --- a/zh_vector.c +++ b/zh_vector.c @@ -111,6 +111,17 @@ esp_err_t zh_vector_get_size(zh_vector_t **vector, uint16_t *size) return ESP_OK; } +esp_err_t zh_vector_get_capacity(zh_vector_t **vector, uint16_t *capacity) +{ + ZH_LOGI("Getting vector capacity begin."); + ZH_ERROR_CHECK(vector != NULL && *vector != NULL && capacity != NULL, ESP_ERR_INVALID_ARG, NULL, "Getting vector capacity failed. Invalid argument."); + ZH_ERROR_CHECK(xSemaphoreTake((*vector)->mutex, portMAX_DELAY) == pdTRUE, ESP_ERR_INVALID_STATE, NULL, "Getting vector capacity failed. Failed to acquire mutex."); + *capacity = (*vector)->capacity; + xSemaphoreGive((*vector)->mutex); + ZH_LOGI("Getting vector capacity success."); + return ESP_OK; +} + esp_err_t zh_vector_push_front(zh_vector_t **vector, const void *item) // -V2008 { ZH_LOGI("Adding item to beginning of vector begin.");