source: trunk/libtransmission/list.h @ 9891

Last change on this file since 9891 was 9891, checked in by charles, 12 years ago

(trunk libT) more documentation and doxygen markup

  • Property svn:keywords set to Date Rev Author Id
File size: 4.5 KB
Line 
1/*
2 * This file Copyright (C) 2007-2010 Mnemosyne LLC
3 *
4 * This file is licensed by the GPL version 2.  Works owned by the
5 * Transmission project are granted a special exemption to clause 2(b)
6 * so that the bulk of its code can remain under the MIT license.
7 * This exemption does not extend to derived works not owned by
8 * the Transmission project.
9 *
10 * $Id: list.h 9891 2010-01-06 00:18:33Z charles $
11 */
12
13#ifndef __TRANSMISSION__
14#error only libtransmission should #include this header.
15#endif
16
17#ifndef TR_LIST_H
18#define TR_LIST_H
19
20/**
21 * @addtogroup utils Utilities
22 * @{
23 */
24
25#include "transmission.h" /* inline */
26
27/** @brief simple list structure similar to glib's GList */
28typedef struct tr_list
29{
30    void *  data;
31    struct tr_list  * next;
32    struct tr_list  * prev;
33}
34tr_list;
35
36typedef int ( *TrListCompareFunc )( const void * a, const void * b );
37typedef void ( *TrListForeachFunc )( void * );
38
39/**
40 * @brief return the number of items in the list
41 * @return the number of items in the list
42 */
43int      tr_list_size( const tr_list * list );
44
45/**
46 * @brief free the specified list and set its pointer to NULL
47 * @param list pointer to the list to be freed
48 * @param func optional function to invoke on each item in the list
49 */
50void     tr_list_free( tr_list ** list, TrListForeachFunc data_free_func );
51
52/**
53 * @brief append an item to the specified list
54 * @param list pointer to the list
55 * @param item the item to append
56 */
57void tr_list_append( tr_list ** list, void * data );
58
59/**
60 * @brief prepend an item to the specified list
61 * @param list pointer to the list
62 * @param item the item to prepend
63 */
64void tr_list_prepend( tr_list ** list, void * data );
65
66/**
67 * @brief remove the next item in the list
68 * @return the next item in the list, or NULL if the list is empty
69 * @param list pointer to the list
70 */
71void* tr_list_pop_front( tr_list ** list );
72
73/**
74 * @brief remove the list's node that contains the specified data pointer
75 * @param list pointer to the list
76 * @param data data to remove
77 * @return the removed data pointer, or NULL if no match was found
78 */
79void* tr_list_remove_data( tr_list ** list, const void * data );
80
81/**
82 * @brief remove the list's node that compares equal to "b" when compared with "compare_func"
83 * @param list pointer to the list
84 * @param b the comparison key
85 * @param compare_func the comparison function.  The arguments passed to it will be the list's pointers and the comparison key "b"
86 * @return the removed data pointer, or NULL if no match was found
87 */
88void*    tr_list_remove( tr_list **        list,
89                         const void *      b,
90                         TrListCompareFunc compare_func );
91
92/**
93 * @brief find the list node whose data that compares equal to "b" when compared with "compare_func"
94 * @param list pointer to the list
95 * @param b the comparison key
96 * @param compare_func the comparison function.  The arguments passed to it will be the list's pointers and the comparison key "b"
97 * @return the matching list node, or NULL if not match was found
98 */
99tr_list* tr_list_find( tr_list *         list,
100                       const void *      b,
101                       TrListCompareFunc compare_func );
102
103
104/** @brief Double-linked list with easy memory management and fast insert/remove operations */
105struct __tr_list
106{
107    struct __tr_list * next, * prev;
108};
109
110/**
111 * @brief Given a __tr_list node that's embedded in a struct, returns a pointer to the struct.
112 * @param ptr     pointer to the embedded __tr_list
113 * @param type    struct type that has contains the __tr_list
114 * @param field   the name of the struct's _tr_list field
115 */
116#define __tr_list_entry(ptr,type,field) ((type*) (((char*)ptr) - offsetof(type,field)))
117
118typedef int  ( *__tr_list_cmp_t ) ( const void * a, const void * b );
119typedef void ( *__tr_list_free_t )( void * );
120
121
122/** @brief Init @head as an empty list. */
123static inline void
124__tr_list_init( struct __tr_list * head )
125{
126    head->next = head->prev = head;
127}
128
129
130/** @brief Insert @list between @prev and @next. */
131void
132__tr_list_insert( struct __tr_list * list,
133                  struct __tr_list * prev,
134                  struct __tr_list * next);
135
136/** @brief Append @list to the end of @head. */
137static inline void
138__tr_list_append( struct __tr_list * head, struct __tr_list * list)
139{
140    __tr_list_insert( list, head->prev, head );
141}
142
143/** @brief Remove @head from the list it is in. */
144void __tr_list_remove( struct __tr_list * head );
145
146/** @brief Destroy the list and free all nodes */
147void __tr_list_destroy( struct __tr_list * head, __tr_list_free_t func );
148
149/* @} */
150#endif /* TR_LIST_H */
151
Note: See TracBrowser for help on using the repository browser.