# lv_array.h (/api/misc/lv_array_h) Array. The elements are dynamically allocated by the 'lv\_mem' module. Functions [#functions] lv_array_init [#lv_array_init] Init an array. ```c title=" " lineNumbers=1 void lv_array_init(lv_array_t *array, uint32_t capacity, uint32_t element_size) ``` Parameters | Name | Type | Description | | -------------- | ---------------------------------------------------- | ------------------------------------------------- | | `array` | | pointer to an `lv_array_t` variable to initialize | | `capacity` | | the initial capacity of the array | | `element_size` | | the size of an element in bytes | lv_array_init_from_buf [#lv_array_init_from_buf] Init an array from a buffer. ```c title=" " lineNumbers=1 void lv_array_init_from_buf(lv_array_t *array, void *buf, uint32_t capacity, uint32_t element_size) ``` Parameters | Name | Type | Description | | -------------- | ---------------------------------------------------- | ------------------------------------------------- | | `array` | | pointer to an `lv_array_t` variable to initialize | | `buf` | `void *` | pointer to a buffer to use as the array's data | | `capacity` | | the initial capacity of the array | | `element_size` | | the size of an element in bytes | The buffer must be large enough to store `capacity` elements. The array will not release the buffer and reallocate it. The user must ensure that the buffer is valid during the lifetime of the array. And release the buffer when the array is no longer needed. lv_array_resize [#lv_array_resize] Resize the array to the given capacity. ```c title=" " lineNumbers=1 bool lv_array_resize(lv_array_t *array, uint32_t new_capacity) ``` Parameters | Name | Type | Description | | -------------- | ---------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | | `new_capacity` | | the new capacity of the array | if the new capacity is smaller than the current size, the array will be truncated. lv_array_deinit [#lv_array_deinit] Deinit the array, and free the allocated memory ```c title=" " lineNumbers=1 void lv_array_deinit(lv_array_t *array) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | --------------------------------------------------- | | `array` | | pointer to an `lv_array_t` variable to deinitialize | lv_array_size [#lv_array_size] Return how many elements are stored in the array. ```c title=" " lineNumbers=1 static uint32_t lv_array_size(const lv_array_t *array) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | **Returns:** — the number of elements stored in the array lv_array_capacity [#lv_array_capacity] Return the capacity of the array, i.e. how many elements can be stored. ```c title=" " lineNumbers=1 static uint32_t lv_array_capacity(const lv_array_t *array) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | **Returns:** — the capacity of the array lv_array_is_empty [#lv_array_is_empty] Return if the array is empty ```c title=" " lineNumbers=1 static bool lv_array_is_empty(const lv_array_t *array) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | **Returns:** — true: array is empty; false: array is not empty lv_array_is_full [#lv_array_is_full] Return if the array is full ```c title=" " lineNumbers=1 static bool lv_array_is_full(const lv_array_t *array) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | **Returns:** — true: array is full; false: array is not full lv_array_copy [#lv_array_copy] Copy an array to another. ```c title=" " lineNumbers=1 void lv_array_copy(lv_array_t *target, const lv_array_t *source) ``` Parameters | Name | Type | Description | | -------- | ---------------------------------------------------------- | ------------------------------------------------ | | `target` | | pointer to an `lv_array_t` variable to copy to | | `source` | | pointer to an `lv_array_t` variable to copy from | this will create a new array with the same capacity and size as the source array. lv_array_clear [#lv_array_clear] Remove all elements in array. ```c title=" " lineNumbers=1 static void lv_array_clear(lv_array_t *array) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | lv_array_shrink [#lv_array_shrink] Shrink the memory capacity of array if necessary. ```c title=" " lineNumbers=1 void lv_array_shrink(lv_array_t *array) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | lv_array_remove [#lv_array_remove] Remove the element at the specified position in the array. This function keeps the array order. Complexity is O(n) ```c title=" " lineNumbers=1 lv_result_t lv_array_remove(lv_array_t *array, uint32_t index) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | | `index` | | the index of the element to remove | **Returns:** — LV\_RESULT\_OK: success, otherwise: error lv_array_remove_unordered [#lv_array_remove_unordered] Remove the element at the specified position in the array. This function does not guarantee the array order. Complexity is O(1) ```c title=" " lineNumbers=1 lv_result_t lv_array_remove_unordered(lv_array_t *array, uint32_t index) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | | `index` | | the index of the element to remove | **Returns:** — LV\_RESULT\_OK: success, otherwise: error lv_array_erase [#lv_array_erase] Remove from the array either a single element or a range of elements (\[start, end)). ```c title=" " lineNumbers=1 lv_result_t lv_array_erase(lv_array_t *array, uint32_t start, uint32_t end) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | -------------------------------------------------------- | | `array` | | pointer to an `lv_array_t` variable | | `start` | | the index of the first element to be removed | | `end` | | the index of the first element that is not to be removed | **Returns:** — LV\_RESULT\_OK: success, otherwise: error This effectively reduces the container size by the number of elements removed. When start equals to end, the function has no effect. lv_array_concat [#lv_array_concat] Concatenate two arrays. Adds new elements to the end of the array. ```c title=" " lineNumbers=1 lv_result_t lv_array_concat(lv_array_t *array, const lv_array_t *other) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | | `other` | | pointer to the array to concatenate | **Returns:** — LV\_RESULT\_OK: success, otherwise: error The destination array is automatically expanded as necessary. lv_array_push_back [#lv_array_push_back] Push back element. Adds a new element to the end of the array. If the array capacity is not enough for the new element, the array will be resized automatically. ```c title=" " lineNumbers=1 lv_result_t lv_array_push_back(lv_array_t *array, const void *element) ``` Parameters | Name | Type | Description | | --------- | ---------------------------------------------------- | ------------------------------------------------------------- | | `array` | | pointer to an `lv_array_t` variable | | `element` | `const void *` | pointer to the element to add. NULL to push an empty element. | **Returns:** — LV\_RESULT\_OK: success, otherwise: error If the element is NULL, it will be added as an empty element. lv_array_assign [#lv_array_assign] Assigns one content to the array, replacing its current content. ```c title=" " lineNumbers=1 lv_result_t lv_array_assign(lv_array_t *array, uint32_t index, const void *value) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | | `index` | | the index of the element to replace | | `value` | `const void *` | pointer to the elements to add | **Returns:** — true: success; false: error lv_array_at [#lv_array_at] Returns a pointer to the element at position n in the array. ```c title=" " lineNumbers=1 void * lv_array_at(const lv_array_t *array, uint32_t index) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | | `index` | | the index of the element to return | **Returns:** `void *` — a pointer to the requested element, NULL if `index` is out of range lv_array_front [#lv_array_front] Returns a pointer to the first element in the array. ```c title=" " lineNumbers=1 static void * lv_array_front(const lv_array_t *array) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | **Returns:** `void *` — a pointer to the first element in the array lv_array_back [#lv_array_back] Returns a pointer to the last element in the array. ```c title=" " lineNumbers=1 static void * lv_array_back(const lv_array_t *array) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------------- | ----------------------------------- | | `array` | | pointer to an `lv_array_t` variable | Structs [#structs] \_lv_array_t [#_lv_array_t] Description of a array | Member | Type | Description | | -------------- | ---------------------------------------------- | ----------- | | `data` | | | | `size` | | | | `capacity` | | | | `element_size` | | | | `inner_alloc` | | | Macros [#macros] LV_ARRAY_DEFAULT_CAPACITY [#lv_array_default_capacity] ```c title=" " lineNumbers=1 #define LV_ARRAY_DEFAULT_CAPACITY 4 ``` LV_ARRAY_DEFAULT_SHRINK_RATIO [#lv_array_default_shrink_ratio] ```c title=" " lineNumbers=1 #define LV_ARRAY_DEFAULT_SHRINK_RATIO 2 ``` Dependencies [#dependencies]