ThingWorx C SDK
cfulist.h
1 /*
2  * cfulist.h - This file is part of the libcfu library
3  *
4  * Copyright (c) 2005 Don Owens. All rights reserved.
5  *
6  * This code is released under the BSD license:
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * * Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * * Redistributions in binary form must reproduce the above
16  * copyright notice, this list of conditions and the following
17  * disclaimer in the documentation and/or other materials provided
18  * with the distribution.
19  *
20  * * Neither the name of the author nor the names of its
21  * contributors may be used to endorse or promote products derived
22  * from this software without specific prior written permission.
23  *
24  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
27  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
28  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
29  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
30  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
31  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
33  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
35  * OF THE POSSIBILITY OF SUCH DAMAGE.
36  */
37 
38 #ifndef CFU_LIST_
39 #define CFU_LIST_
40 
41 #include <cfu.h>
42 #include <stddef.h>
43 
44 CFU_BEGIN_DECLS
45 
46 /* The list itself. */
47 typedef struct cfulist cfulist_t;
48 
49 /* Function called for each element in the list when passed to
50  * cfulist_foreach(). A non-zero return value means to stop
51  * iteration.
52  */
53 typedef int (*cfulist_foreach_fn_t)(void *data, size_t data_size, void *arg);
54 
55 /* Function called for each element in the list when passed to
56  * cfulist_map(). The return value is used to build a new
57  * list.
58  */
59 typedef void * (*cfulist_map_fn_t)(void *data, size_t data_size, void *arg,
60  size_t *new_data_size);
61 
62 /* Function called to free the data in an element. */
63 typedef void (*cfulist_free_fn_t)(void *data);
64 
65 /* Returns a new list. */
66 cfulist_t * cfulist_new(void);
67 
68 /* Same as cfulist_new(), but set a function to be called on each
69  * element when the list is destroyed.
70  */
71 cfulist_t * cfulist_new_with_free_fn(cfulist_free_fn_t free_fn);
72 
73 /* Returns the number of entries in the list. */
74 size_t cfulist_num_entries(cfulist_t *list);
75 
76 /* Manipulating list entries */
77 
78 /* Push a value onto the end of the list. */
79 int cfulist_push_data(cfulist_t *list, void *data, size_t data_size);
80 
81 /* Pop a value from the end of the list. */
82 int cfulist_pop_data(cfulist_t *list, void **data, size_t *data_size);
83 
84 /* Add a value at the beginning of the list. */
85 int cfulist_unshift_data(cfulist_t *list, void *data, size_t data_size);
86 
87 /* Shift a value off the beginning of the list. */
88 int cfulist_shift_data(cfulist_t *list, void **data, size_t *data_size);
89 
90 /* Add a value at the end of the queue (equivalent to push) */
91 int cfulist_enqueue_data(cfulist_t *list, void *data, size_t data_size);
92 
93 /* Remove the value at the beginning of the list (equivalent to shift). */
94 int cfulist_dequeue_data(cfulist_t *list, void **data, size_t *data_size);
95 
96 /* Return the last entry from the list (without removing it from
97  * the list).
98  */
99 int cfulist_first_data(cfulist_t *list, void **data, size_t *data_size);
100 
101 /* Return the last entry from the list (without removing it from
102  * the list).
103  */
104 int cfulist_last_data(cfulist_t *list, void **data, size_t *data_size);
105 
106 /* Return the nth entry from the list (without removing it from
107  * the list). n starts at zero.
108 */
109 int cfulist_nth_data(cfulist_t *list, void **data, size_t *data_size, size_t n);
110 
111 void cfulist_reset_each(cfulist_t *list);
112 int cfulist_each_data(cfulist_t *list, void **data, size_t *data_size);
113 int cfulist_next_data(cfulist_t *list, void **data, size_t *data_size);
114 
115 /* Calls fe_fn() for each element in the list. Also passes arg on
116  * each call. If fe_fn() returns a non-zero value, the iteration
117  * over the elements stops.
118  */
119 size_t cfulist_foreach(cfulist_t *list, cfulist_foreach_fn_t fe_fn, void *arg);
120 
121 /* Creates a new list from the list passed in. Calls map_fn() on
122  * each element in the list. The return value is placed in the
123  * corresponding position in the new list.
124  */
125 cfulist_t *cfulist_map(cfulist_t *list, cfulist_map_fn_t map_fn, void *arg);
126 
127 /* Free all resources used by the list. */
128 void cfulist_destroy(cfulist_t *list);
129 void cfulist_destroy_with_free_fn(cfulist_t *list, cfulist_free_fn_t free_fn);
130 
131 /* When you don't care about the size of the data */
132 
133 int cfulist_push(cfulist_t *list, void *data);
134 void * cfulist_pop(cfulist_t *list);
135 int cfulist_unshift(cfulist_t *list, void *data);
136 void * cfulist_shift(cfulist_t *list);
137 int cfulist_enqueue(cfulist_t *list, void *data);
138 void *cfulist_dequeue(cfulist_t *list);
139 
140 /* Strings -- assume data is a null-terminated string -- size is
141  * calculated by strlen(data) + 1
142  */
143 
144 int cfulist_push_string(cfulist_t *list, char *data);
145 char * cfulist_pop_string(cfulist_t *list);
146 int cfulist_unshift_string(cfulist_t *list, char *data);
147 char * cfulist_shift_string(cfulist_t *list);
148 int cfulist_enqueue_string(cfulist_t *list, char *data);
149 char *cfulist_dequeue_string(cfulist_t *list);
150 
151 char *cfulist_join(cfulist_t *list, const char *delimiter);
152 
153 CFU_END_DECLS
154 
155 #endif
Definition: cfulist.c:62