[or-cvs] Add documentation to a few functions in container.c; reform...
Nick Mathewson
nickm at seul.org
Tue Sep 13 15:30:24 UTC 2005
Update of /home/or/cvsroot/tor/src/common
In directory moria:/tmp/cvs-serv13794/src/common
Modified Files:
container.c
Log Message:
Add documentation to a few functions in container.c; reformat function definitions
Index: container.c
===================================================================
RCS file: /home/or/cvsroot/tor/src/common/container.c,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -d -r1.37 -r1.38
--- container.c 12 Sep 2005 08:29:53 -0000 1.37
+++ container.c 13 Sep 2005 15:30:22 -0000 1.38
@@ -42,7 +42,8 @@
/** Allocate and return an empty smartlist.
*/
-smartlist_t *smartlist_create() {
+smartlist_t *
+smartlist_create() {
smartlist_t *sl = tor_malloc(sizeof(smartlist_t));
sl->num_used = 0;
sl->capacity = SMARTLIST_DEFAULT_CAPACITY;
@@ -53,7 +54,8 @@
/** Deallocate a smartlist. Does not release storage associated with the
* list's elements.
*/
-void smartlist_free(smartlist_t *sl) {
+void
+smartlist_free(smartlist_t *sl) {
free(sl->list);
free(sl);
}
@@ -75,7 +77,8 @@
/** Remove all elements from the list.
*/
-void smartlist_clear(smartlist_t *sl) {
+void
+smartlist_clear(smartlist_t *sl) {
sl->num_used = 0;
}
@@ -83,14 +86,16 @@
* current size). Remove the last smartlist_len(sl)-len elements from the
* list.
*/
-void smartlist_truncate(smartlist_t *sl, int len)
+void
+smartlist_truncate(smartlist_t *sl, int len)
{
tor_assert(len <= sl->num_used);
sl->num_used = len;
}
/** Append element to the end of the list. */
-void smartlist_add(smartlist_t *sl, void *element) {
+void
+smartlist_add(smartlist_t *sl, void *element) {
if (sl->num_used >= sl->capacity) {
int higher = sl->capacity * 2;
tor_assert(higher > sl->capacity); /* detect overflow */
@@ -101,7 +106,8 @@
}
/** Append each element from S2 to the end of S1. */
-void smartlist_add_all(smartlist_t *sl, const smartlist_t *s2)
+void
+smartlist_add_all(smartlist_t *sl, const smartlist_t *s2)
{
SMARTLIST_FOREACH(s2, void *, element, smartlist_add(sl, element));
}
@@ -110,7 +116,9 @@
* the order of any elements before E, but elements after E can be
* rearranged.
*/
-void smartlist_remove(smartlist_t *sl, void *element) {
+void
+smartlist_remove(smartlist_t *sl, void *element)
+{
int i;
if (element == NULL)
return;
@@ -140,7 +148,9 @@
/** Return true iff some element E of sl has E==element.
*/
-int smartlist_isin(const smartlist_t *sl, void *element) {
+int
+smartlist_isin(const smartlist_t *sl, void *element)
+{
int i;
for (i=0; i < sl->num_used; i++)
if (sl->list[i] == element)
@@ -148,7 +158,12 @@
return 0;
}
-int smartlist_string_isin(const smartlist_t *sl, const char *element) {
+/** Return true iff <b>sl</b> has some element E such that
+ * !strcmp(E,<b>element</b>)
+ */
+int
+smartlist_string_isin(const smartlist_t *sl, const char *element)
+{
int i;
if (!sl) return 0;
for (i=0; i < sl->num_used; i++)
@@ -157,7 +172,12 @@
return 0;
}
-int smartlist_string_num_isin(const smartlist_t *sl, int num) {
+/** Return true iff <b>sl</b> has some element E such that E is equal
+ * to the decimal encoding of <b>num</b>.
+ */
+int
+smartlist_string_num_isin(const smartlist_t *sl, int num)
+{
char buf[16];
tor_snprintf(buf,sizeof(buf),"%d", num);
return smartlist_string_isin(sl, buf);
@@ -165,7 +185,9 @@
/** Return true iff some element E of sl2 has smartlist_isin(sl1,E).
*/
-int smartlist_overlap(const smartlist_t *sl1, const smartlist_t *sl2) {
+int
+smartlist_overlap(const smartlist_t *sl1, const smartlist_t *sl2)
+{
int i;
for (i=0; i < sl2->num_used; i++)
if (smartlist_isin(sl1, sl2->list[i]))
@@ -176,7 +198,9 @@
/** Remove every element E of sl1 such that !smartlist_isin(sl2,E).
* Does not preserve the order of sl1.
*/
-void smartlist_intersect(smartlist_t *sl1, const smartlist_t *sl2) {
+void
+smartlist_intersect(smartlist_t *sl1, const smartlist_t *sl2)
+{
int i;
for (i=0; i < sl1->num_used; i++)
if (!smartlist_isin(sl2, sl1->list[i])) {
@@ -188,7 +212,9 @@
/** Remove every element E of sl1 such that smartlist_isin(sl2,E).
* Does not preserve the order of sl1.
*/
-void smartlist_subtract(smartlist_t *sl1, const smartlist_t *sl2) {
+void
+smartlist_subtract(smartlist_t *sl1, const smartlist_t *sl2)
+{
int i;
for (i=0; i < sl2->num_used; i++)
smartlist_remove(sl1, sl2->list[i]);
@@ -197,7 +223,8 @@
#ifndef FAST_SMARTLIST
/** Return the <b>idx</b>th element of sl.
*/
-void *smartlist_get(const smartlist_t *sl, int idx)
+void *
+smartlist_get(const smartlist_t *sl, int idx)
{
tor_assert(sl);
tor_assert(idx>=0);
@@ -206,7 +233,8 @@
}
/** Change the value of the <b>idx</b>th element of sl to <b>val</b>.
*/
-void smartlist_set(smartlist_t *sl, int idx, void *val)
+void
+smartlist_set(smartlist_t *sl, int idx, void *val)
{
tor_assert(sl);
tor_assert(idx>=0);
@@ -215,7 +243,8 @@
}
/** Return the number of items in sl.
*/
-int smartlist_len(const smartlist_t *sl)
+int
+smartlist_len(const smartlist_t *sl)
{
return sl->num_used;
}
@@ -225,7 +254,8 @@
* element, swap the last element of sl into the <b>idx</b>th space.
* Return the old value of the <b>idx</b>th element.
*/
-void smartlist_del(smartlist_t *sl, int idx)
+void
+smartlist_del(smartlist_t *sl, int idx)
{
tor_assert(sl);
tor_assert(idx>=0);
@@ -236,7 +266,8 @@
* moving all subsequent elements back one space. Return the old value
* of the <b>idx</b>th element.
*/
-void smartlist_del_keeporder(smartlist_t *sl, int idx)
+void
+smartlist_del_keeporder(smartlist_t *sl, int idx)
{
tor_assert(sl);
tor_assert(idx>=0);
@@ -249,7 +280,8 @@
* <b>sl</b>, moving all items previously at <b>idx</b> or later
* forward one space.
*/
-void smartlist_insert(smartlist_t *sl, int idx, void *val)
+void
+smartlist_insert(smartlist_t *sl, int idx, void *val)
{
tor_assert(sl);
tor_assert(idx>=0);
@@ -280,8 +312,9 @@
* length 0. If max>0, divide the string into no more than <b>max</b>
* pieces. If <b>sep</b> is NULL, split on any sequence of horizontal space.
*/
-int smartlist_split_string(smartlist_t *sl, const char *str, const char *sep,
- int flags, int max)
+int
+smartlist_split_string(smartlist_t *sl, const char *str, const char *sep,
+ int flags, int max)
{
const char *cp, *end, *next;
int n = 0;
@@ -339,8 +372,9 @@
* the returned string. Requires that every element of <b>sl</b> is
* NUL-terminated string.
*/
-char *smartlist_join_strings(smartlist_t *sl, const char *join,
- int terminate, size_t *len_out)
+char *
+smartlist_join_strings(smartlist_t *sl, const char *join,
+ int terminate, size_t *len_out)
{
return smartlist_join_strings2(sl,join,strlen(join),terminate,len_out);
}
@@ -350,8 +384,9 @@
* at <b>join</b>. (Useful for generating a sequence of NUL-terminated
* strings.)
*/
-char *smartlist_join_strings2(smartlist_t *sl, const char *join,
- size_t join_len, int terminate, size_t *len_out)
+char *
+smartlist_join_strings2(smartlist_t *sl, const char *join,
+ size_t join_len, int terminate, size_t *len_out)
{
int i;
size_t n = 0;
@@ -419,19 +454,22 @@
return r ? *r : NULL;
}
+/** Helper: compare two const char **s. */
static int
_compare_string_ptrs(const void **_a, const void **_b)
{
return strcmp((const char*)*_a, (const char*)*_b);
}
+/** Sort a smartlist <b>sl</b> containing strings into lexically ascending
+ * order. */
void
smartlist_sort_strings(smartlist_t *sl)
{
smartlist_sort(sl, _compare_string_ptrs);
}
-/* Splay-tree implementation of string-to-void* map
+/** Splay-tree implementation of string-to-void* map
*/
typedef struct strmap_entry_t {
SPLAY_ENTRY(strmap_entry_t) node;
@@ -443,8 +481,10 @@
SPLAY_HEAD(strmap_tree, strmap_entry_t) head;
};
-static int compare_strmap_entries(strmap_entry_t *a,
- strmap_entry_t *b)
+/** Helper: compare strmap_entry_t objects by key value. */
+static int
+compare_strmap_entries(strmap_entry_t *a,
+ strmap_entry_t *b)
{
return strcmp(a->key, b->key);
}
@@ -454,7 +494,8 @@
/** Create a new empty map from strings to void*'s.
*/
-strmap_t* strmap_new(void)
+strmap_t *
+strmap_new(void)
{
strmap_t *result;
result = tor_malloc(sizeof(strmap_t));
@@ -467,7 +508,8 @@
*
* This function makes a copy of <b>key</b> if necessary, but not of <b>val</b>.
*/
-void* strmap_set(strmap_t *map, const char *key, void *val)
+void *
+strmap_set(strmap_t *map, const char *key, void *val)
{
strmap_entry_t *resolve;
strmap_entry_t search;
@@ -493,7 +535,7 @@
/** Return the current value associated with <b>key</b>, or NULL if no
* value is set.
*/
-void* strmap_get(strmap_t *map, const char *key)
+void *strmap_get(strmap_t *map, const char *key)
{
strmap_entry_t *resolve;
strmap_entry_t search;
@@ -514,7 +556,8 @@
*
* Note: you must free any storage associated with the returned value.
*/
-void* strmap_remove(strmap_t *map, const char *key)
+void *
+strmap_remove(strmap_t *map, const char *key)
{
strmap_entry_t *resolve;
strmap_entry_t search;
@@ -535,7 +578,8 @@
}
/** Same as strmap_set, but first converts <b>key</b> to lowercase. */
-void* strmap_set_lc(strmap_t *map, const char *key, void *val)
+void *
+strmap_set_lc(strmap_t *map, const char *key, void *val)
{
/* We could be a little faster by using strcasecmp instead, and a separate
* type, but I don't think it matters. */
@@ -547,7 +591,8 @@
return v;
}
/** Same as strmap_get, but first converts <b>key</b> to lowercase. */
-void* strmap_get_lc(strmap_t *map, const char *key)
+void *
+strmap_get_lc(strmap_t *map, const char *key)
{
void *v;
char *lc_key = tor_strdup(key);
@@ -557,7 +602,8 @@
return v;
}
/** Same as strmap_remove, but first converts <b>key</b> to lowercase */
-void* strmap_remove_lc(strmap_t *map, const char *key)
+void *
+strmap_remove_lc(strmap_t *map, const char *key)
{
void *v;
char *lc_key = tor_strdup(key);
@@ -594,9 +640,10 @@
* strmap_foreach(map, upcase_and_remove_empty_vals, NULL);
* \endcode
*/
-void strmap_foreach(strmap_t *map,
- void* (*fn)(const char *key, void *val, void *data),
- void *data)
+void
+strmap_foreach(strmap_t *map,
+ void* (*fn)(const char *key, void *val, void *data),
+ void *data)
{
strmap_entry_t *ptr, *next;
tor_assert(map);
@@ -639,14 +686,16 @@
* \endcode
*
*/
-strmap_iter_t *strmap_iter_init(strmap_t *map)
+strmap_iter_t *
+strmap_iter_init(strmap_t *map)
{
tor_assert(map);
return SPLAY_MIN(strmap_tree, &map->head);
}
/** Advance the iterator <b>iter</b> for map a single step to the next entry.
*/
-strmap_iter_t *strmap_iter_next(strmap_t *map, strmap_iter_t *iter)
+strmap_iter_t *
+strmap_iter_next(strmap_t *map, strmap_iter_t *iter)
{
tor_assert(map);
tor_assert(iter);
@@ -655,7 +704,8 @@
/** Advance the iterator <b>iter</b> a single step to the next entry, removing
* the current entry.
*/
-strmap_iter_t *strmap_iter_next_rmv(strmap_t *map, strmap_iter_t *iter)
+strmap_iter_t *
+strmap_iter_next_rmv(strmap_t *map, strmap_iter_t *iter)
{
strmap_iter_t *next;
tor_assert(map);
@@ -668,7 +718,8 @@
}
/** Set *keyp and *valp to the current entry pointed to by iter.
*/
-void strmap_iter_get(strmap_iter_t *iter, const char **keyp, void **valp)
+void
+strmap_iter_get(strmap_iter_t *iter, const char **keyp, void **valp)
{
tor_assert(iter);
tor_assert(keyp);
@@ -678,7 +729,8 @@
}
/** Return true iff iter has advanced past the last entry of map.
*/
-int strmap_iter_done(strmap_iter_t *iter)
+int
+strmap_iter_done(strmap_iter_t *iter)
{
return iter == NULL;
}
@@ -701,7 +753,10 @@
tor_free(map);
}
-int strmap_isempty(strmap_t *map)
+/* Return true iff <b>map</b> has no entries.
+ */
+int
+strmap_isempty(strmap_t *map)
{
return SPLAY_EMPTY(&map->head);
}
More information about the tor-commits
mailing list