1 /** 2 * @file lv_array.h 3 * Array. The elements are dynamically allocated by the 'lv_mem' module. 4 */ 5 6 #ifndef LV_ARRAY_H 7 #define LV_ARRAY_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 /********************* 14 * INCLUDES 15 *********************/ 16 #include "lv_types.h" 17 18 /********************* 19 * DEFINES 20 *********************/ 21 22 #ifndef LV_ARRAY_DEFAULT_CAPACITY 23 #define LV_ARRAY_DEFAULT_CAPACITY 4 24 #endif 25 26 #ifndef LV_ARRAY_DEFAULT_SHRINK_RATIO 27 #define LV_ARRAY_DEFAULT_SHRINK_RATIO 2 28 #endif 29 30 /********************** 31 * TYPEDEFS 32 **********************/ 33 34 /** Description of a array*/ 35 struct _lv_array_t { 36 uint8_t * data; 37 uint32_t size; 38 uint32_t capacity; 39 uint32_t element_size; 40 41 bool inner_alloc; /* true: data is allocated by the array; false: data is allocated by the user */ 42 }; 43 44 /********************** 45 * GLOBAL PROTOTYPES 46 **********************/ 47 48 /** 49 * Init an array. 50 * @param array pointer to an `lv_array_t` variable to initialize 51 * @param capacity the initial capacity of the array 52 * @param element_size the size of an element in bytes 53 */ 54 void lv_array_init(lv_array_t * array, uint32_t capacity, uint32_t element_size); 55 56 /** 57 * Init an array from a buffer. 58 * @note The buffer must be large enough to store `capacity` elements. The array will not release the buffer and reallocate it. 59 * 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. 60 * @param array pointer to an `lv_array_t` variable to initialize 61 * @param buf pointer to a buffer to use as the array's data 62 * @param capacity the initial capacity of the array 63 * @param element_size the size of an element in bytes 64 */ 65 void lv_array_init_from_buf(lv_array_t * array, void * buf, uint32_t capacity, uint32_t element_size); 66 67 /** 68 * Resize the array to the given capacity. 69 * @note if the new capacity is smaller than the current size, the array will be truncated. 70 * @param array pointer to an `lv_array_t` variable 71 * @param new_capacity the new capacity of the array 72 */ 73 bool lv_array_resize(lv_array_t * array, uint32_t new_capacity); 74 75 /** 76 * Deinit the array, and free the allocated memory 77 * @param array pointer to an `lv_array_t` variable to deinitialize 78 */ 79 void lv_array_deinit(lv_array_t * array); 80 81 /** 82 * Return how many elements are stored in the array. 83 * @param array pointer to an `lv_array_t` variable 84 * @return the number of elements stored in the array 85 */ 86 uint32_t lv_array_size(const lv_array_t * array); 87 88 /** 89 * Return the capacity of the array, i.e. how many elements can be stored. 90 * @param array pointer to an `lv_array_t` variable 91 * @return the capacity of the array 92 */ 93 uint32_t lv_array_capacity(const lv_array_t * array); 94 95 /** 96 * Return if the array is empty 97 * @param array pointer to an `lv_array_t` variable 98 * @return true: array is empty; false: array is not empty 99 */ 100 bool lv_array_is_empty(const lv_array_t * array); 101 102 /** 103 * Return if the array is full 104 * @param array pointer to an `lv_array_t` variable 105 * @return true: array is full; false: array is not full 106 */ 107 bool lv_array_is_full(const lv_array_t * array); 108 109 /** 110 * Copy an array to another. 111 * @note this will create a new array with the same capacity and size as the source array. 112 * @param target pointer to an `lv_array_t` variable to copy to 113 * @param source pointer to an `lv_array_t` variable to copy from 114 */ 115 void lv_array_copy(lv_array_t * target, const lv_array_t * source); 116 117 /** 118 * Remove all elements in array. 119 * @param array pointer to an `lv_array_t` variable 120 */ 121 void lv_array_clear(lv_array_t * array); 122 123 /** 124 * Shrink the memory capacity of array if necessary. 125 * @param array pointer to an `lv_array_t` variable 126 */ 127 void lv_array_shrink(lv_array_t * array); 128 129 /** 130 * Remove the element at the specified position in the array. 131 * @param array pointer to an `lv_array_t` variable 132 * @param index the index of the element to remove 133 * @return LV_RESULT_OK: success, otherwise: error 134 */ 135 lv_result_t lv_array_remove(lv_array_t * array, uint32_t index); 136 137 /** 138 * Remove from the array either a single element or a range of elements ([start, end)). 139 * @note This effectively reduces the container size by the number of elements removed. 140 * @note When start equals to end, the function has no effect. 141 * @param array pointer to an `lv_array_t` variable 142 * @param start the index of the first element to be removed 143 * @param end the index of the first element that is not to be removed 144 * @return LV_RESULT_OK: success, otherwise: error 145 */ 146 lv_result_t lv_array_erase(lv_array_t * array, uint32_t start, uint32_t end); 147 148 /** 149 * Concatenate two arrays. Adds new elements to the end of the array. 150 * @note The destination array is automatically expanded as necessary. 151 * @param array pointer to an `lv_array_t` variable 152 * @param other pointer to the array to concatenate 153 * @return LV_RESULT_OK: success, otherwise: error 154 */ 155 lv_result_t lv_array_concat(lv_array_t * array, const lv_array_t * other); 156 157 /** 158 * Push back element. Adds a new element to the end of the array. 159 * If the array capacity is not enough for the new element, the array will be resized automatically. 160 * @note If the element is NULL, it will be added as an empty element. 161 * @param array pointer to an `lv_array_t` variable 162 * @param element pointer to the element to add. NULL to push an empty element. 163 * @return LV_RESULT_OK: success, otherwise: error 164 */ 165 lv_result_t lv_array_push_back(lv_array_t * array, const void * element); 166 167 /** 168 * Assigns one content to the array, replacing its current content. 169 * @param array pointer to an `lv_array_t` variable 170 * @param index the index of the element to replace 171 * @param value pointer to the elements to add 172 * @return true: success; false: error 173 */ 174 lv_result_t lv_array_assign(lv_array_t * array, uint32_t index, const void * value); 175 176 /** 177 * Returns a pointer to the element at position n in the array. 178 * @param array pointer to an `lv_array_t` variable 179 * @param index the index of the element to return 180 * @return a pointer to the requested element, NULL if `index` is out of range 181 */ 182 void * lv_array_at(const lv_array_t * array, uint32_t index); 183 184 /** 185 * Returns a pointer to the first element in the array. 186 * @param array pointer to an `lv_array_t` variable 187 * @return a pointer to the first element in the array 188 */ 189 void * lv_array_front(const lv_array_t * array); 190 191 /** 192 * Returns a pointer to the last element in the array. 193 * @param array pointer to an `lv_array_t` variable 194 */ 195 void * lv_array_back(const lv_array_t * array); 196 197 /********************** 198 * MACROS 199 **********************/ 200 201 #ifdef __cplusplus 202 } /*extern "C"*/ 203 #endif 204 205 #endif 206
