1 /**
2 * @file lv_iter.h
3 *
4  */
5 
6 
7 #ifndef LV_ITER_H
8 #define LV_ITER_H
9 
10 #ifdef __cplusplus
11 extern "C" {
12 #endif
13 
14 /*********************
15  *      INCLUDES
16  *********************/
17 
18 #include "lv_types.h"
19 
20 /*********************
21  *      DEFINES
22  *********************/
23 
24 /**********************
25  *      TYPEDEFS
26  **********************/
27 
28 typedef lv_result_t (*lv_iter_next_cb)(void * instance, void * context, void * elem);
29 typedef void (*lv_iter_inspect_cb)(void * elem);
30 
31 /**********************
32  * GLOBAL PROTOTYPES
33  **********************/
34 
35 /**
36  * Create an iterator based on an instance, and then the next element of the iterator can be obtained through lv_iter_next,
37  * In order to obtain the next operation in a unified and abstract way.
38  * @param instance       The instance to be iterated
39  * @param elem_size      The size of the element to be iterated in bytes
40  * @param context_size   The size of the context to be passed to the next_cb in bytes
41  * @param next_cb        The callback function to get the next element
42  * @return               The iterator object
43  */
44 lv_iter_t * lv_iter_create(void * instance, uint32_t elem_size, uint32_t context_size, lv_iter_next_cb next_cb);
45 
46 /**
47  * Get the context of the iterator. You can use it to store some temporary variables associated with current iterator..
48  * @param iter           `lv_iter_t` object create before
49  * @return the iter context
50  */
51 void * lv_iter_get_context(const lv_iter_t * iter);
52 
53 /**
54  * Destroy the iterator object, and release the context. Other resources allocated by the user are not released.
55  * The user needs to release it by itself.
56  * @param iter          `lv_iter_t` object create before
57  */
58 void lv_iter_destroy(lv_iter_t * iter);
59 
60 /**
61  * Get the next element of the iterator.
62  * @param iter          `lv_iter_t` object create before
63  * @param elem          The pointer to store the next element
64  * @return              LV_RESULT_OK: Get the next element successfully
65  *                      LV_RESULT_INVALID: The next element is invalid
66  */
67 lv_result_t lv_iter_next(lv_iter_t * iter, void * elem);
68 
69 /**
70  * Make the iterator peekable, which means that the user can peek the next element without advancing the iterator.
71  * @param iter          `lv_iter_t` object create before
72  * @param capacity      The capacity of the peek buffer
73  */
74 void lv_iter_make_peekable(lv_iter_t * iter, uint32_t capacity);
75 
76 /**
77  * Peek the next element of the iterator without advancing the iterator.
78  * @param iter          `lv_iter_t` object create before
79  * @param elem          The pointer to store the next element
80  * @return              LV_RESULT_OK: Peek the next element successfully
81  *                      LV_RESULT_INVALID: The next element is invalid
82  */
83 lv_result_t lv_iter_peek(lv_iter_t * iter, void * elem);
84 
85 /**
86  * Only advance the iterator without getting the next element.
87  * @param iter          `lv_iter_t` object create before
88  * @return              LV_RESULT_OK: Peek the next element successfully
89  *                      LV_RESULT_INVALID: The next element is invalid
90  */
91 lv_result_t lv_iter_peek_advance(lv_iter_t * iter);
92 
93 /**
94  * Reset the peek cursor to the `next` cursor.
95  * @param iter          `lv_iter_t` object create before
96  * @return              LV_RESULT_OK: Reset the peek buffer successfully
97  *                      LV_RESULT_INVALID: The peek buffer is invalid
98  */
99 lv_result_t lv_iter_peek_reset(lv_iter_t * iter);
100 
101 /**
102  * Inspect the element of the iterator. The callback function will be called for each element of the iterator.
103  * @param iter          `lv_iter_t` object create before
104  * @param inspect_cb    The callback function to inspect the element
105  */
106 void lv_iter_inspect(lv_iter_t * iter, lv_iter_inspect_cb inspect_cb);
107 
108 /*************************
109  *    GLOBAL VARIABLES
110  *************************/
111 
112 /**********************
113  *      MACROS
114  **********************/
115 
116 #ifdef __cplusplus
117 } /*extern "C"*/
118 #endif
119 
120 #endif /*LV_ITER_H*/
121