container.h 7.32 KB
Newer Older
Nick Mathewson's avatar
Nick Mathewson committed
1
/* Copyright 2003-2004 Roger Dingledine
2
 * Copyright 2004-2007 Roger Dingledine, Nick Mathewson */
3
4
5
6
7
/* See LICENSE for licensing information */
/* $Id$ */

#ifndef __CONTAINER_H
#define __CONTAINER_H
8
9
#define CONTAINER_H_ID \
  "$Id$"
10

Nick Mathewson's avatar
Nick Mathewson committed
11
12
#include "compat.h"
#include "util.h"
13

14
15
16
17
18
19
/** A resizeable list of pointers, with associated helpful functionality.
 *
 * The members of this struct are exposed only so that macros and inlines can
 * use them; all access to smartlist internals should go throuch the functions
 * and macros defined here.
 **/
20
typedef struct smartlist_t {
21
22
23
24
25
26
27
  /** <b>list</b> has enough capacity to store exactly <b>capacity</b> elements
   * before it needs to be resized.  Only the first <b>num_used</b> (\<=
   * capacity) elements point to valid data.
   */
  void **list;
  int num_used;
  int capacity;
28
} smartlist_t;
29
30
31
32
33
34
35

smartlist_t *smartlist_create(void);
void smartlist_free(smartlist_t *sl);
void smartlist_set_capacity(smartlist_t *sl, int n);
void smartlist_clear(smartlist_t *sl);
void smartlist_add(smartlist_t *sl, void *element);
void smartlist_add_all(smartlist_t *sl, const smartlist_t *s2);
36
void smartlist_remove(smartlist_t *sl, const void *element);
37
38
void *smartlist_pop_last(smartlist_t *sl);
void smartlist_reverse(smartlist_t *sl);
39
void smartlist_string_remove(smartlist_t *sl, const char *element);
40
int smartlist_isin(const smartlist_t *sl, const void *element) ATTR_PURE;
41
42
int smartlist_string_isin(const smartlist_t *sl, const char *element)
  ATTR_PURE;
43
44
int smartlist_string_isin_case(const smartlist_t *sl, const char *element)
  ATTR_PURE;
45
int smartlist_string_num_isin(const smartlist_t *sl, int num) ATTR_PURE;
46
47
int smartlist_overlap(const smartlist_t *sl1, const smartlist_t *sl2)
  ATTR_PURE;
48
49
void smartlist_intersect(smartlist_t *sl1, const smartlist_t *sl2);
void smartlist_subtract(smartlist_t *sl1, const smartlist_t *sl2);
50

51
/* smartlist_choose() is defined in crypto.[ch] */
52
#ifdef DEBUG_SMARTLIST
53
54
/** Return the number of items in sl.
 */
55
extern INLINE int smartlist_len(const smartlist_t *sl) ATTR_PURE {
56
57
58
59
60
  tor_assert(sl);
  return (sl)->num_used;
}
/** Return the <b>idx</b>th element of sl.
 */
61
extern INLINE void *smartlist_get(const smartlist_t *sl, int idx) ATTR_PURE {
62
63
64
65
66
67
68
69
70
71
72
  tor_assert(sl);
  tor_assert(idx>=0);
  tor_assert(sl->num_used < idx);
  return sl->list[idx];
}
extern INLINE void smartlist_set(smartlist_t *sl, int idx, void *val) {
  tor_assert(sl);
  tor_assert(idx>=0);
  tor_assert(sl->num_used < idx);
  sl->list[idx] = val;
}
73
74
75
76
77
78
#else
#define smartlist_len(sl) ((sl)->num_used)
#define smartlist_get(sl, idx) ((sl)->list[idx])
#define smartlist_set(sl, idx, val) ((sl)->list[idx] = (val))
#endif

79
80
void smartlist_del(smartlist_t *sl, int idx);
void smartlist_del_keeporder(smartlist_t *sl, int idx);
81
void smartlist_insert(smartlist_t *sl, int idx, void *val);
82
83
void smartlist_sort(smartlist_t *sl,
                    int (*compare)(const void **a, const void **b));
84
85
86
void smartlist_uniq(smartlist_t *sl,
                    int (*compare)(const void **a, const void **b),
                    void (*free_fn)(void *elt));
87
void smartlist_sort_strings(smartlist_t *sl);
88
void smartlist_sort_digests(smartlist_t *sl);
89
90
void smartlist_uniq_strings(smartlist_t *sl);
void smartlist_uniq_digests(smartlist_t *sl);
91
void *smartlist_bsearch(smartlist_t *sl, const void *key,
92
93
                        int (*compare)(const void *key, const void **member))
 ATTR_PURE;
94

95
96
97
98
99
100
101
102
void smartlist_pqueue_add(smartlist_t *sl,
                          int (*compare)(const void *a, const void *b),
                          void *item);
void *smartlist_pqueue_pop(smartlist_t *sl,
                           int (*compare)(const void *a, const void *b));
void smartlist_pqueue_assert_ok(smartlist_t *sl,
                                int (*compare)(const void *a, const void *b));

103
104
105
106
#define SPLIT_SKIP_SPACE   0x01
#define SPLIT_IGNORE_BLANK 0x02
int smartlist_split_string(smartlist_t *sl, const char *str, const char *sep,
                           int flags, int max);
107
char *smartlist_join_strings(smartlist_t *sl, const char *join, int terminate,
108
                             size_t *len_out) ATTR_MALLOC;
109
char *smartlist_join_strings2(smartlist_t *sl, const char *join,
110
111
                              size_t join_len, int terminate, size_t *len_out)
  ATTR_MALLOC;
112

113
114
115
/** Iterate over the items in a smartlist <b>sl</b>, in order.  For each item,
 * assign it to a new local variable of type <b>type</b> named <b>var</b>, and
 * execute the statement <b>cmd</b>.  Inside the loop, the loop index can
116
117
118
119
120
121
 * be accessed as <b>var</b>_sl_idx and the length of the list can be accessed
 * as <b>var</b>_sl_len.
 *
 * NOTE: Do not change the length of the list while the loop is in progress,
 * unless you adjust the _sl_len variable correspondingly.  See second example
 * below.
122
123
124
125
126
127
128
129
130
 *
 * Example use:
 * <pre>
 *   smartlist_t *list = smartlist_split("A:B:C", ":", 0, 0);
 *   SMARTLIST_FOREACH(list, char *, cp,
 *   {
 *     printf("%d: %s\n", cp_sl_idx, cp);
 *     tor_free(cp);
 *   });
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 *   smartlist_free(list);
 * </pre>
 *
 * Example use (advanced):
 * <pre>
 *   SMARTLIST_FOREACH(list, char *, cp,
 *   {
 *     if (!strcmp(cp, "junk")) {
 *       smartlist_del(list, cp_sl_idx);
 *       tor_free(cp);
 *       --cp_sl_len; // decrement length of list so we don't run off the end
 *       --cp_sl_idx; // decrement idx so we consider the item that moved here
 *     }
 *   });
145
146
 * </pre>
 */
147
148
#define SMARTLIST_FOREACH(sl, type, var, cmd)                   \
  do {                                                          \
149
    int var ## _sl_idx, var ## _sl_len=(sl)->num_used;          \
150
    type var;                                                   \
151
    for (var ## _sl_idx = 0; var ## _sl_idx < var ## _sl_len;   \
152
         ++var ## _sl_idx) {                                    \
153
      var = (sl)->list[var ## _sl_idx];                         \
154
155
156
      cmd;                                                      \
    } } while (0)

157
158
#define DECLARE_MAP_FNS(maptype, keytype, prefix)                       \
  typedef struct maptype maptype;                                       \
159
  typedef struct prefix##entry_t *prefix##iter_t;                       \
160
161
162
163
164
165
  maptype* prefix##new(void);                                           \
  void* prefix##set(maptype *map, keytype key, void *val);              \
  void* prefix##get(maptype *map, keytype key);                         \
  void* prefix##remove(maptype *map, keytype key);                      \
  void prefix##free(maptype *map, void (*free_val)(void*));             \
  int prefix##isempty(maptype *map);                                    \
166
  int prefix##size(maptype *map);                                       \
167
168
169
170
  prefix##iter_t *prefix##iter_init(maptype *map);                      \
  prefix##iter_t *prefix##iter_next(maptype *map, prefix##iter_t *iter); \
  prefix##iter_t *prefix##iter_next_rmv(maptype *map, prefix##iter_t *iter); \
  void prefix##iter_get(prefix##iter_t *iter, keytype *keyp, void **valp); \
171
172
  int prefix##iter_done(prefix##iter_t *iter);                          \
  void prefix##assert_ok(maptype *map);
173

174
/* Map from const char * to void *. Implemented with a hash table. */
175
176
177
DECLARE_MAP_FNS(strmap_t, const char *, strmap_);
DECLARE_MAP_FNS(digestmap_t, const char *, digestmap_);

178
179
180
181
182
void* strmap_set_lc(strmap_t *map, const char *key, void *val);
void* strmap_get_lc(strmap_t *map, const char *key);
void* strmap_remove_lc(strmap_t *map, const char *key);

#endif
183