feat: added getting vector capacity

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.

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()
 
 Получает текущее количество элементов в векторе.

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 <alexey.zholtikov@yandex.ru>"

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.
      *

version.txt

@@ -1 +1 @@
-2.0.0
+2.1.0

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.");