zh_vector/WIKI_EN.md

zh_vector - Vector (Dynamic Array) Component for ESP-IDF

Table of Contents

• Overview
• Features
• Installation
• API Reference
• Usage Examples
• Technical Specifications
• Error Codes
• Contributing
• License

---

Overview

zh_vector is a lightweight, efficient vector (dynamic array) component for ESP-IDF (Espressif IoT Development Framework). It provides a flexible container that can store elements of any data type with automatic memory management. The vector automatically resizes as items are added or removed, making it ideal for dynamic data management in embedded systems.

The component is designed specifically for ESP32 microcontrollers and uses ESP-IDF's heap management functions for optimal memory allocation with different memory caps (internal/external RAM).

---

Features

1. Type Agnostic: Supports any data type (integers, floats, structs, custom types, etc.)
2. Automatic Memory Management: Automatic memory allocation and deallocation
3. Dynamic Resizing: Vector capacity grows and shrinks as needed
4. Maximum Capacity: Up to 65,535 elements (16-bit index limit)
5. ESP-IDF Optimized: Uses heap_caps functions for memory allocation with memory caps
6. Error Handling: Comprehensive error checking with detailed logging
7. Thread-Safe: Not thread-safe by default (can be made thread-safe with external mutex)
8. Minimal Overhead: Low memory and CPU overhead

---

Installation

1. Navigate to your project's components directory:

cd ../your_project/components

2. Clone the repository:

git clone https://github.com/aZholtikov/zh_vector

3. In your application, include the header:

#include "zh_vector.h"

4. The component will be automatically built with your project.

---

API Reference

zh_vector_t Structure

typedef struct
{
    void **items;        // Array of pointers of vector items
    uint16_t capacity;   // Maximum capacity of the vector
    uint16_t size;       // Number of items in the vector
    uint16_t unit;       // Vector item size (in bytes)
    bool is_initialized; // Vector initialization status flag
} zh_vector_t;

---

zh_vector_init()

Initializes the vector.

Parameters:

• vector - Pointer to the vector structure
• unit - Size of each element in bytes

Returns:

• ESP_OK - Success
• ESP_ERR_INVALID_ARG - Invalid argument (NULL vector or zero unit size)
• ESP_ERR_INVALID_STATE - Vector already initialized

Example:

zh_vector_t vector = {0};
zh_vector_init(&vector, sizeof(int)); // For integers

---

zh_vector_free()

Deinitializes the vector and frees all allocated memory.

Parameters:

• vector - Pointer to the vector structure

Returns:

• ESP_OK - Success
• ESP_ERR_INVALID_ARG - Invalid argument (NULL vector)
• ESP_ERR_INVALID_STATE - Vector not initialized

Note: All dynamically allocated element memory is also freed.

---

zh_vector_get_size()

Gets the current number of elements in the vector.

Parameters:

• vector - Pointer to the vector structure

Returns:

• >= 0 - Number of elements (success)
• ESP_FAIL - Error (NULL vector or not initialized)

---

zh_vector_push_front()

Adds an element to the beginning of the vector.

Parameters:

• vector - Pointer to the vector structure
• item - Pointer to the element to add

Returns:

• ESP_OK - Success
• ESP_ERR_INVALID_ARG - Invalid argument (NULL vector or item)
• ESP_ERR_INVALID_STATE - Vector not initialized
• ESP_ERR_NO_MEM - Memory allocation failed

Note: The function allocates memory for a copy of the item and copies the data. All existing elements are shifted right by one position.

---

zh_vector_push_back()

Adds an element to the end of the vector.

Parameters:

• vector - Pointer to the vector structure
• item - Pointer to the element to add

Returns:

• ESP_OK - Success
• ESP_ERR_INVALID_ARG - Invalid argument (NULL vector or item)
• ESP_ERR_INVALID_STATE - Vector not initialized
• ESP_ERR_NO_MEM - Memory allocation failed

Note: The function allocates memory for a copy of the item and copies the data.

---

zh_vector_change_item()

Changes an element at a specific index.

Parameters:

• vector - Pointer to the vector structure
• index - Index of the element to change (0-based)
• item - Pointer to the new element data

Returns:

• ESP_OK - Success
• ESP_ERR_INVALID_ARG - Invalid argument (NULL vector, item, or invalid index)
• ESP_ERR_INVALID_STATE - Vector not initialized
• ESP_FAIL - Index out of bounds

---

zh_vector_get_item()

Gets an element at a specific index.

Parameters:

• vector - Pointer to the vector structure
• index - Index of the element to get (0-based)

Returns:

• Pointer to the element (success)
• NULL - Error (NULL vector, not initialized, or invalid index)

Note: Returns a pointer to the internal data. Do not free this pointer.

---

zh_vector_delete_item()

Deletes an element at a specific index and shifts all subsequent elements.

Parameters:

• vector - Pointer to the vector structure
• index - Index of the element to delete (0-based)

Returns:

• ESP_OK - Success
• ESP_ERR_INVALID_ARG - Invalid argument (NULL vector)
• ESP_ERR_INVALID_STATE - Vector not initialized
• ESP_FAIL - Index out of bounds

Note: All elements after the deleted index are shifted left by one position.

---

Usage Examples

Basic Example: Integer Vector

#include "zh_vector.h"

zh_vector_t int_vector = {0};

void app_main(void)
{
    esp_log_level_set("zh_vector", ESP_LOG_ERROR);
    // Initialize vector for integers
    zh_vector_init(&int_vector, sizeof(int));
    // Add elements
    int val1 = 10;
    int val2 = 20;
    int val3 = 30;
    zh_vector_push_front(&int_vector, &val1);
    zh_vector_push_back(&int_vector, &val2);
    zh_vector_push_back(&int_vector, &val3);
    printf("Vector size: %d\n", zh_vector_get_size(&int_vector));
    // Access elements
    for (int i = 0; i < zh_vector_get_size(&int_vector); i++) {
        int *item = (int *)zh_vector_get_item(&int_vector, i);
        printf("Element %d: %d\n", i, *item);
    }
    // Change element
    int new_val = 100;
    zh_vector_change_item(&int_vector, 1, &new_val);
    // Delete element
    zh_vector_delete_item(&int_vector, 0);
    // Cleanup
    zh_vector_free(&int_vector);
}

Struct Example

#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)
{
    esp_log_level_set("zh_vector", ESP_LOG_ERROR);
    // Initialize vector for structs
    zh_vector_init(&struct_vector, sizeof(my_struct_t));
    // Add struct elements
    my_struct_t item1 = {1, "Item 1", 1.5f};
    my_struct_t item2 = {2, "Item 2", 2.5f};
    zh_vector_push_front(&struct_vector, &item1);
    zh_vector_push_back(&struct_vector, &item2);
    // Access and modify
    my_struct_t *ptr = (my_struct_t *)zh_vector_get_item(&struct_vector, 0);
    ptr->value = 10.5f;
    // Cleanup
    zh_vector_free(&struct_vector);
}

String Example (Char Arrays)

#include "zh_vector.h"
#include "string.h"

zh_vector_t string_vector = {0};

void app_main(void)
{
    esp_log_level_set("zh_vector", ESP_LOG_ERROR);
    // Initialize vector for strings (100 char max)
    char buffer[100] = {0};
    zh_vector_init(&string_vector, sizeof(buffer));
    // Add strings
    strcpy(buffer, "Hello");
    zh_vector_push_front(&string_vector, &buffer);
    strcpy(buffer, "World");
    zh_vector_push_back(&string_vector, &buffer);
    // Print all strings
    for (int i = 0; i < zh_vector_get_size(&string_vector); i++) {
        char *str = (char *)zh_vector_get_item(&string_vector, i);
        printf("String %d: %s\n", i, str);
    }
    // Cleanup
    zh_vector_free(&string_vector);
}

---

Technical Specifications

Parameter	Value
Maximum Capacity	65,535 elements
Index Type	uint16_t (16-bit)
Memory Management	heap_caps_calloc, heap_caps_realloc, heap_caps_free
Memory Caps	MALLOC_CAP_8BIT
Thread Safety	Not thread-safe
ESP-IDF Version	>= 5.0
Platform	ESP32 series
Language	C (C99)

---

Error Codes

Error Code	Description
ESP_OK	Operation successful
ESP_ERR_INVALID_ARG	Invalid argument (NULL pointer or zero size)
ESP_ERR_INVALID_STATE	Vector not initialized or already initialized
ESP_ERR_NO_MEM	Memory allocation failed (out of memory)
ESP_FAIL	General failure (e.g., index out of bounds)

---

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please ensure your code follows the existing style and includes appropriate documentation.

---

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

Apache License, Version 2.0

Copyright (c) 2026 Alexey Zholtikov

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

---

Additional Notes

• Memory Overhead: Each element requires additional memory for the pointer in the internal pointer array
• Performance: O(1) for get/set by index, O(n) for insert/delete in the middle
• Best Practices:
  • Always initialize the vector before use
  • Free the vector when done to avoid memory leaks
  • Consider the maximum size limit (65,535 elements)
  • For string handling, consider using fixed-size buffers

---

Generated for zh_vector v1.2.0