1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
/*
* tclist.h -- a list for transcode / interface
* (C) 2008-2010 - Francesco Romani <fromani -at- gmail -dot- com>
*
* This file is part of transcode, a video stream processing tool.
*
* transcode is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* transcode is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef TCLIST_H
#define TCLIST_H
typedef struct tclistitem_ TCListItem;
struct tclistitem_ {
void *data;
TCListItem *next;
TCListItem *prev;
};
typedef struct tclist_ TCList;
struct tclist_ {
TCListItem *head;
TCListItem *tail;
TCListItem *cache;
int use_cache;
int nelems;
};
/*
* LIST INDEXING NOTE:
* -----------------------------------------------------------------------
* WRITEME
*/
/*
* TCListVisitor:
* typedef for visitor function.
* A visitor function is called on elements of a given list (usually
* on each element) giving to it pointers to current element and custom
* user data. It is safe to modify the element data inside the visitor
* function, even free()ing it. But DO NOT modify the list *item*
* inside this function. Use the special crafted upper-level list
* functions for that.
*
* Parameters:
* item: pointer to the list item currently visited.
* userdata: pointer to custom, opaque caller-given data.
* Return Value:
* 0: success. Iteration continues to the next element, if any.
* !0: failure. Iteration stops here.
*/
typedef int (*TCListVisitor)(TCListItem *item, void *userdata);
/*
* tc_list_init:
* intializes a list data structure.
* A list can use a deleted element cache. The deleted list elements
* (NOT the data pointed by them!) are not really released until the
* tc_list_fini() is called, but they are just saved (in the `cache'
* field.
* Use the cache feature if ALL the following conditions are met:
* - you will do a lot of insertion/removals.
* - you will stabilize the list size around a given size.
* Otherwise using the cache will not hurt, but it will neither help.
*
* Parameters:
* L: pointer to list to be initialized.
* elemcache: treated as boolean, enables or disable the internal cache.
* Return Value:
* TC_OK on success,
* TC_ERROR on error.
*/
int tc_list_init(TCList *L, int elemcache);
/*
* tc_list_fini:
* finalizes a list data structure. Frees all resources aquired,
* including any cached list element (if any), but *NOT* the data
* pointed by list elements.
*
* Parameters:
* L: pointer to list to be finalized
* Return Value:
* TC_OK on success,
* TC_ERROR on error.
*/
int tc_list_fini(TCList *L);
/*
* tc_list_size:
* gives the number of elements present in the list.
*
* Parameters:
* L: list to be used.
* Return Value:
* -1 on error,
* the number of elements otherwise
*/
int tc_list_size(TCList *L);
/*
* tc_list_foreach:
* applies a visitor function to all elements in the given lists,
* halting at first visit failed.
*
* Parameters:
* L: pointer to list to be visited.
* vis: visitor function to be applied.
* userdata: pointer to opaque data to be passed unchanged to visitor
* function at each call.
* Return Value:
* 0: if all elements are visited correctly.
* !0: the value returned by the first failed call to visitor function.
*/
int tc_list_foreach(TCList *L, TCListVisitor vis, void *userdata);
/*
* tc_list_{append,prepend}:
* append or prepend an element to the list.
* The element is added on the {last,first} position of the list.
*
* Parameters:
* L: pointer to list to be used
* data: pointer to data to be appended or prepend.
* *PLEASE NOTE* that JUST THE POINTER is copied on the newly-added
* element. NO deep copy is performed.
* The caller has to allocate memory by itself if it want to
* add a copy of the data.
* Return Value:
* TC_OK on success,
* TC_ERROR on error.
*/
int tc_list_append(TCList *L, void *data);
int tc_list_prepend(TCList *L, void *data);
/*
* tc_list_insert:
* the newly-inserted elements BECOMES the position `pos' on the list.
* Position after the last -> the last.
* Position before the first -> the first.
*/
int tc_list_insert(TCList *L, int pos, void *data);
/*
* tc_list_get:
* gives access to the data pointed by the element in the given position.
*
* Parameters:
* L: list to be accessed.
* pos: position of the element on which the data will be returned.
* Return Value:
* NULL on error (requested element doesn't exist)
* a pointer to the data belonging to the requested list item.
*/
void *tc_list_get(TCList *L, int pos);
/*
* tc_list_pop:
* removes the element in the given position.
*
* Parameters:
* L: list to be accessed.
* pos: position of the element on which the data will be returned.
* Return Value:
* NULL on error (requested element doesn't exist)
* a pointer to the data assigned to the requested list item.
*/
void *tc_list_pop(TCList *L, int pos);
/*************************************************************************/
TCList *tc_list_new(int usecache);
void tc_list_del(TCList *L, int deepclean);
int tc_list_insert_dup(TCList *L, int pos, void *data, size_t size);
#define tc_list_append_dup(L, DATA, SIZE) tc_list_insert_dup(L, -1, DATA, SIZE)
#define tc_list_prepend_dup(L, DATA, SIZE) tc_list_insert_dup(L, 0, DATA, SIZE)
#endif /* TCLIST_H */
|
