+2020-02-02 Bruno Haible <bruno@clisp.org>
+
+ list, set, oset, map, omap: Avoid imperative voice in documentation.
+ * lib/gl_list.h: Use descriptive sentences instead of imperative voice
+ in the specification of functions.
+ * lib/gl_set.h: Likewise.
+ * lib/gl_oset.h: Likewise.
+ * lib/gl_map.h: Likewise.
+ * lib/gl_omap.h: Likewise.
+ * lib/gl_*.h: Likewise.
+
2020-02-01 Bruno Haible <bruno@clisp.org>
ansi-c++-opt: Set CXXFLAGS to "-g -O2" by default.
/* -------------------------- gl_list_t Data Type -------------------------- */
-/* Create a subtree for count >= 1 elements.
+/* Creates a subtree for count >= 1 elements.
Its height is h where 2^(h-1) <= count <= 2^h - 1.
- Return NULL upon out-of-memory. */
+ Returns NULL upon out-of-memory. */
static gl_list_node_t
create_subtree_with_contents (size_t count, const void **contents)
{
return NULL;
}
-/* Ensure the tree is balanced, after an insertion or deletion operation.
+/* Ensures the tree is balanced, after an insertion or deletion operation.
The height of NODE is incremented by HEIGHT_DIFF (1 or -1).
PARENT = NODE->parent. (NODE can also be NULL. But PARENT is non-NULL.)
Rotation operations are performed starting at PARENT (not NODE itself!). */
#include "gl_anyhash_primes.h"
-/* Resize the hash table with a new estimated size. */
+/* Resizes the hash table with a new estimated size. */
static void
hash_resize (CONTAINER_T container, size_t estimate)
{
return;
}
-/* Resize the hash table if needed, after CONTAINER_COUNT (container) was
+/* Resizes the hash table if needed, after CONTAINER_COUNT (container) was
incremented. */
static void
hash_resize_after_add (CONTAINER_T container)
SIZE_MAX /* sentinel, to ensure the search terminates */
};
-/* Return a suitable prime >= ESTIMATE. */
+/* Returns a suitable prime >= ESTIMATE. */
static size_t
next_prime (size_t estimate)
{
/* -------------------------- gl_list_t Data Type -------------------------- */
-/* Create a subtree for count >= 1 elements.
+/* Creates a subtree for count >= 1 elements.
Its black-height bh is passed as argument, with
2^bh - 1 <= count <= 2^(bh+1) - 1. bh == 0 implies count == 1.
Its height is h where 2^(h-1) <= count <= 2^h - 1.
return NULL;
}
-/* Rotate left a subtree.
+/* Rotates left a subtree.
B D
/ \ / \
/ \ / \
C E A C
- Change the tree structure, update the branch sizes.
+ Changes the tree structure, updates the branch sizes.
The caller must update the colors and register D as child of its parent. */
static gl_list_node_t
rotate_left (gl_list_node_t b_node, gl_list_node_t d_node)
return d_node;
}
-/* Rotate right a subtree.
+/* Rotates right a subtree.
D B
/ \ / \
/ \ / \
A C C E
- Change the tree structure, update the branch sizes.
+ Changes the tree structure, updates the branch sizes.
The caller must update the colors and register B as child of its parent. */
static gl_list_node_t
rotate_right (gl_list_node_t b_node, gl_list_node_t d_node)
return b_node;
}
-/* Ensure the tree is balanced, after an insertion operation.
+/* Ensures the tree is balanced, after an insertion operation.
Also assigns node->color.
parent is the given node's parent, known to be non-NULL. */
static void
}
}
-/* Ensure the tree is balanced, after a deletion operation.
+/* Ensures the tree is balanced, after a deletion operation.
CHILD was a grandchild of PARENT and is now its child. Between them,
a black node was removed. CHILD is also black, or NULL.
(CHILD can also be NULL. But PARENT is non-NULL.) */
/* A stack used for iterating across the elements. */
typedef iterstack_item_t iterstack_t[MAXHEIGHT];
-/* Free a non-empty subtree recursively.
+/* Frees a non-empty subtree recursively.
This function is recursive and therefore not very fast. */
static void
free_subtree (gl_list_node_t node)
return node;
}
-/* Return the node at the given position < gl_tree_size (list). */
+/* Returns the node at the given position < gl_tree_size (list). */
static gl_list_node_t _GL_ATTRIBUTE_PURE
node_at (gl_list_node_t root, size_t position)
{
gl_list_node_impl. */
#define MULTIPLE_NODES_MAGIC (void *) -1
-/* Return the position of the given node in the tree. */
+/* Returns the position of the given node in the tree. */
static size_t
node_position (gl_list_node_t node)
{
return (position >= (uintptr_t)threshold);
}
-/* Return the first element of a non-empty ordered set of nodes. */
+/* Returns the first element of a non-empty ordered set of nodes. */
static gl_list_node_t
gl_oset_first (gl_oset_t set)
{
return (gl_list_node_t) first;
}
-/* Add a node to the hash table structure.
+/* Adds a node to the hash table structure.
If duplicates are allowed, this function performs in average time
O((log n)^2): gl_oset_nx_add may need to add an element to an ordered set
of size O(n), needing O(log n) comparison function calls. The comparison
#define add_to_bucket(list,node) \
__builtin_expect ((add_to_bucket) (list, node), 0)
-/* Remove a node from the hash table structure.
+/* Removes a node from the hash table structure.
If duplicates are allowed, this function performs in average time
O((log n)^2): gl_oset_remove may need to remove an element from an ordered
set of size O(n), needing O(log n) comparison function calls. The
}
}
-/* Build up the hash table during initialization: Store all the nodes of
+/* Builds up the hash table during initialization: Stores all the nodes of
list->root in the hash table.
- Return 0 upon success, -1 upon out-of-memory. */
+ Returns 0 upon success, -1 upon out-of-memory. */
static int
add_nodes_to_buckets (gl_list_t list)
{
this would exceed the address space of the machine. */
#define MAXHEIGHT 83
-/* Ensure the tree is balanced, after an insertion or deletion operation.
+/* Ensures the tree is balanced, after an insertion or deletion operation.
The height of NODE is incremented by HEIGHT_DIFF (1 or -1).
PARENT = NODE->parent. (NODE can also be NULL. But PARENT is non-NULL.)
Rotation operations are performed starting at PARENT (not NODE itself!). */
#if 0 /* Unless otherwise specified, these are defined inline below. */
-/* Create an empty list.
+/* Creates an empty list.
IMPLEMENTATION is one of GL_ARRAY_LIST, GL_CARRAY_LIST, GL_LINKED_LIST,
GL_AVLTREE_LIST, GL_RBTREE_LIST, GL_LINKEDHASH_LIST, GL_AVLTREEHASH_LIST,
GL_RBTREEHASH_LIST.
gl_listelement_hashcode_fn hashcode_fn,
gl_listelement_dispose_fn dispose_fn,
bool allow_duplicates);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_list_t gl_list_nx_create_empty (gl_list_implementation_t implementation,
gl_listelement_equals_fn equals_fn,
gl_listelement_hashcode_fn hashcode_fn,
gl_listelement_dispose_fn dispose_fn,
bool allow_duplicates);
-/* Create a list with given contents.
+/* Creates a list with given contents.
IMPLEMENTATION is one of GL_ARRAY_LIST, GL_CARRAY_LIST, GL_LINKED_LIST,
GL_AVLTREE_LIST, GL_RBTREE_LIST, GL_LINKEDHASH_LIST, GL_AVLTREEHASH_LIST,
GL_RBTREEHASH_LIST.
gl_listelement_dispose_fn dispose_fn,
bool allow_duplicates,
size_t count, const void **contents);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_list_t gl_list_nx_create (gl_list_implementation_t implementation,
gl_listelement_equals_fn equals_fn,
gl_listelement_hashcode_fn hashcode_fn,
bool allow_duplicates,
size_t count, const void **contents);
-/* Return the current number of elements in a list. */
+/* Returns the current number of elements in a list. */
extern size_t gl_list_size (gl_list_t list);
-/* Return the element value represented by a list node. */
+/* Returns the element value represented by a list node. */
extern const void * gl_list_node_value (gl_list_t list, gl_list_node_t node);
-/* Replace the element value represented by a list node. */
+/* Replaces the element value represented by a list node. */
/* declared in gl_xlist.h */
extern void gl_list_node_set_value (gl_list_t list, gl_list_node_t node,
const void *elt);
-/* Likewise. Return 0 upon success, -1 upon out-of-memory. */
+/* Likewise. Returns 0 upon success, -1 upon out-of-memory. */
extern int gl_list_node_nx_set_value (gl_list_t list, gl_list_node_t node,
const void *elt)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
#endif
;
-/* Return the node immediately after the given node in the list, or NULL
+/* Returns the node immediately after the given node in the list, or NULL
if the given node is the last (rightmost) one in the list. */
extern gl_list_node_t gl_list_next_node (gl_list_t list, gl_list_node_t node);
-/* Return the node immediately before the given node in the list, or NULL
+/* Returns the node immediately before the given node in the list, or NULL
if the given node is the first (leftmost) one in the list. */
extern gl_list_node_t gl_list_previous_node (gl_list_t list, gl_list_node_t node);
-/* Return the element at a given position in the list.
+/* Returns the element at a given position in the list.
POSITION must be >= 0 and < gl_list_size (list). */
extern const void * gl_list_get_at (gl_list_t list, size_t position);
-/* Replace the element at a given position in the list.
+/* Replaces the element at a given position in the list.
POSITION must be >= 0 and < gl_list_size (list).
- Return its node. */
+ Returns its node. */
/* declared in gl_xlist.h */
extern gl_list_node_t gl_list_set_at (gl_list_t list, size_t position,
const void *elt);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_list_node_t gl_list_nx_set_at (gl_list_t list, size_t position,
const void *elt)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
#endif
;
-/* Search whether an element is already in the list.
- Return its node if found, or NULL if not present in the list. */
+/* Searches whether an element is already in the list.
+ Returns its node if found, or NULL if not present in the list. */
extern gl_list_node_t gl_list_search (gl_list_t list, const void *elt);
-/* Search whether an element is already in the list,
+/* Searches whether an element is already in the list,
at a position >= START_INDEX.
- Return its node if found, or NULL if not present in the list. */
+ Returns its node if found, or NULL if not present in the list. */
extern gl_list_node_t gl_list_search_from (gl_list_t list, size_t start_index,
const void *elt);
-/* Search whether an element is already in the list,
+/* Searches whether an element is already in the list,
at a position >= START_INDEX and < END_INDEX.
- Return its node if found, or NULL if not present in the list. */
+ Returns its node if found, or NULL if not present in the list. */
extern gl_list_node_t gl_list_search_from_to (gl_list_t list,
size_t start_index,
size_t end_index,
const void *elt);
-/* Search whether an element is already in the list.
- Return its position if found, or (size_t)(-1) if not present in the list. */
+/* Searches whether an element is already in the list.
+ Returns its position if found, or (size_t)(-1) if not present in the list. */
extern size_t gl_list_indexof (gl_list_t list, const void *elt);
-/* Search whether an element is already in the list,
+/* Searches whether an element is already in the list,
at a position >= START_INDEX.
- Return its position if found, or (size_t)(-1) if not present in the list. */
+ Returns its position if found, or (size_t)(-1) if not present in the list. */
extern size_t gl_list_indexof_from (gl_list_t list, size_t start_index,
const void *elt);
-/* Search whether an element is already in the list,
+/* Searches whether an element is already in the list,
at a position >= START_INDEX and < END_INDEX.
- Return its position if found, or (size_t)(-1) if not present in the list. */
+ Returns its position if found, or (size_t)(-1) if not present in the list. */
extern size_t gl_list_indexof_from_to (gl_list_t list,
size_t start_index, size_t end_index,
const void *elt);
-/* Add an element as the first element of the list.
- Return its node. */
+/* Adds an element as the first element of the list.
+ Returns its node. */
/* declared in gl_xlist.h */
extern gl_list_node_t gl_list_add_first (gl_list_t list, const void *elt);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_list_node_t gl_list_nx_add_first (gl_list_t list, const void *elt)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
__attribute__ ((__warn_unused_result__))
#endif
;
-/* Add an element as the last element of the list.
- Return its node. */
+/* Adds an element as the last element of the list.
+ Returns its node. */
/* declared in gl_xlist.h */
extern gl_list_node_t gl_list_add_last (gl_list_t list, const void *elt);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_list_node_t gl_list_nx_add_last (gl_list_t list, const void *elt)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
__attribute__ ((__warn_unused_result__))
#endif
;
-/* Add an element before a given element node of the list.
- Return its node. */
+/* Adds an element before a given element node of the list.
+ Returns its node. */
/* declared in gl_xlist.h */
extern gl_list_node_t gl_list_add_before (gl_list_t list, gl_list_node_t node,
const void *elt);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_list_node_t gl_list_nx_add_before (gl_list_t list,
gl_list_node_t node,
const void *elt)
#endif
;
-/* Add an element after a given element node of the list.
- Return its node. */
+/* Adds an element after a given element node of the list.
+ Returns its node. */
/* declared in gl_xlist.h */
extern gl_list_node_t gl_list_add_after (gl_list_t list, gl_list_node_t node,
const void *elt);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_list_node_t gl_list_nx_add_after (gl_list_t list, gl_list_node_t node,
const void *elt)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
#endif
;
-/* Add an element at a given position in the list.
+/* Adds an element at a given position in the list.
POSITION must be >= 0 and <= gl_list_size (list). */
/* declared in gl_xlist.h */
extern gl_list_node_t gl_list_add_at (gl_list_t list, size_t position,
const void *elt);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_list_node_t gl_list_nx_add_at (gl_list_t list, size_t position,
const void *elt)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
#endif
;
-/* Remove an element from the list.
- Return true. */
+/* Removes an element from the list.
+ Returns true. */
extern bool gl_list_remove_node (gl_list_t list, gl_list_node_t node);
-/* Remove an element at a given position from the list.
+/* Removes an element at a given position from the list.
POSITION must be >= 0 and < gl_list_size (list).
- Return true. */
+ Returns true. */
extern bool gl_list_remove_at (gl_list_t list, size_t position);
-/* Search and remove an element from the list.
- Return true if it was found and removed. */
+/* Searches and removes an element from the list.
+ Returns true if it was found and removed. */
extern bool gl_list_remove (gl_list_t list, const void *elt);
-/* Free an entire list.
+/* Frees an entire list.
(But this call does not free the elements of the list. It only invokes
the DISPOSE_FN on each of the elements of the list, and only if the list
is not a sublist.) */
#if 0 /* These are defined inline below. */
-/* Create an iterator traversing a list.
+/* Creates an iterator traversing a list.
The list contents must not be modified while the iterator is in use,
except for replacing or removing the last returned element. */
extern gl_list_iterator_t gl_list_iterator (gl_list_t list);
-/* Create an iterator traversing the element with indices i,
+/* Creates an iterator traversing the element with indices i,
start_index <= i < end_index, of a list.
The list contents must not be modified while the iterator is in use,
except for replacing or removing the last returned element. */
size_t start_index,
size_t end_index);
-/* If there is a next element, store the next element in *ELTP, store its
- node in *NODEP if NODEP is non-NULL, advance the iterator and return true.
- Otherwise, return false. */
+/* If there is a next element, stores the next element in *ELTP, stores its
+ node in *NODEP if NODEP is non-NULL, advances the iterator and returns true.
+ Otherwise, returns false. */
extern bool gl_list_iterator_next (gl_list_iterator_t *iterator,
const void **eltp, gl_list_node_t *nodep);
-/* Free an iterator. */
+/* Frees an iterator. */
extern void gl_list_iterator_free (gl_list_iterator_t *iterator);
#endif /* End of inline functions. */
#if 0 /* Unless otherwise specified, these are defined inline below. */
-/* Search whether an element is already in the list.
+/* Searches whether an element is already in the list.
The list is assumed to be sorted with COMPAR.
- Return its node if found, or NULL if not present in the list.
+ Returns its node if found, or NULL if not present in the list.
If the list contains several copies of ELT, the node of the leftmost one is
returned. */
extern gl_list_node_t gl_sortedlist_search (gl_list_t list,
gl_listelement_compar_fn compar,
const void *elt);
-/* Search whether an element is already in the list.
+/* Searches whether an element is already in the list.
The list is assumed to be sorted with COMPAR.
Only list elements with indices >= START_INDEX and < END_INDEX are
considered; the implementation uses these bounds to minimize the number
of COMPAR invocations.
- Return its node if found, or NULL if not present in the list.
+ Returns its node if found, or NULL if not present in the list.
If the list contains several copies of ELT, the node of the leftmost one is
returned. */
extern gl_list_node_t gl_sortedlist_search_from_to (gl_list_t list,
size_t end_index,
const void *elt);
-/* Search whether an element is already in the list.
+/* Searches whether an element is already in the list.
The list is assumed to be sorted with COMPAR.
- Return its position if found, or (size_t)(-1) if not present in the list.
+ Returns its position if found, or (size_t)(-1) if not present in the list.
If the list contains several copies of ELT, the position of the leftmost one
is returned. */
extern size_t gl_sortedlist_indexof (gl_list_t list,
gl_listelement_compar_fn compar,
const void *elt);
-/* Search whether an element is already in the list.
+/* Searches whether an element is already in the list.
The list is assumed to be sorted with COMPAR.
Only list elements with indices >= START_INDEX and < END_INDEX are
considered; the implementation uses these bounds to minimize the number
of COMPAR invocations.
- Return its position if found, or (size_t)(-1) if not present in the list.
+ Returns its position if found, or (size_t)(-1) if not present in the list.
If the list contains several copies of ELT, the position of the leftmost one
is returned. */
extern size_t gl_sortedlist_indexof_from_to (gl_list_t list,
size_t end_index,
const void *elt);
-/* Add an element at the appropriate position in the list.
+/* Adds an element at the appropriate position in the list.
The list is assumed to be sorted with COMPAR.
- Return its node. */
+ Returns its node. */
/* declared in gl_xlist.h */
extern gl_list_node_t gl_sortedlist_add (gl_list_t list,
gl_listelement_compar_fn compar,
const void *elt);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_list_node_t gl_sortedlist_nx_add (gl_list_t list,
gl_listelement_compar_fn compar,
const void *elt)
#endif
;
-/* Search and remove an element from the list.
+/* Searches and removes an element from the list.
The list is assumed to be sorted with COMPAR.
- Return true if it was found and removed.
+ Returns true if it was found and removed.
If the list contains several copies of ELT, only the leftmost one is
removed. */
extern bool gl_sortedlist_remove (gl_list_t list,
#if 0 /* Unless otherwise specified, these are defined inline below. */
-/* Create an empty map.
+/* Creates an empty map.
IMPLEMENTATION is one of GL_ARRAY_MAP, GL_LINKEDHASH_MAP, GL_HASH_MAP.
EQUALS_FN is a key comparison function or NULL.
HASHCODE_FN is a key hash code function or NULL.
gl_mapkey_hashcode_fn hashcode_fn,
gl_mapkey_dispose_fn kdispose_fn,
gl_mapvalue_dispose_fn vdispose_fn);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_map_t gl_map_nx_create_empty (gl_map_implementation_t implementation,
gl_mapkey_equals_fn equals_fn,
gl_mapkey_hashcode_fn hashcode_fn,
gl_mapkey_dispose_fn kdispose_fn,
gl_mapvalue_dispose_fn vdispose_fn);
-/* Return the current number of pairs in a map. */
+/* Returns the current number of pairs in a map. */
extern size_t gl_map_size (gl_map_t map);
-/* Search whether a pair with the given key is already in the map.
- Return the value if found, or NULL if not present in the map. */
+/* Searches whether a pair with the given key is already in the map.
+ Returns the value if found, or NULL if not present in the map. */
extern const void * gl_map_get (gl_map_t map, const void *key);
-/* Search whether a pair with the given key is already in the map.
- Return true and set *VALUEP to the value if found.
- Return false if not present in the map. */
+/* Searches whether a pair with the given key is already in the map.
+ Returns true and sets *VALUEP to the value if found.
+ Returns false if not present in the map. */
extern bool gl_map_search (gl_map_t map, const void *key, const void **valuep);
-/* Add a pair to a map.
- Return true if a pair with the given key was not already in the map and so
+/* Adds a pair to a map.
+ Returns true if a pair with the given key was not already in the map and so
this pair was added.
- Return false if a pair with the given key was already in the map and only
+ Returns false if a pair with the given key was already in the map and only
its value was replaced. */
/* declared in gl_xmap.h */
extern bool gl_map_put (gl_map_t map, const void *key, const void *value);
-/* Likewise. Return -1 upon out-of-memory. */
+/* Likewise. Returns -1 upon out-of-memory. */
extern int gl_map_nx_put (gl_map_t map, const void *key, const void *value)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
__attribute__ ((__warn_unused_result__))
#endif
;
-/* Add a pair to a map and retrieve the previous value.
- Return true if a pair with the given key was not already in the map and so
+/* Adds a pair to a map and retrieves the previous value.
+ Returns true if a pair with the given key was not already in the map and so
this pair was added.
- Return false and set *OLDVALUEP to the previous value, if a pair with the
+ Returns false and sets *OLDVALUEP to the previous value, if a pair with the
given key was already in the map and only its value was replaced. */
/* declared in gl_xmap.h */
extern bool gl_map_getput (gl_map_t map, const void *key, const void *value,
const void **oldvaluep);
-/* Likewise. Return -1 upon out-of-memory. */
+/* Likewise. Returns -1 upon out-of-memory. */
extern int gl_map_nx_getput (gl_map_t map, const void *key, const void *value,
const void **oldvaluep)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
#endif
;
-/* Remove a pair from a map.
- Return true if the key was found and its pair removed.
- Return false otherwise. */
+/* Removes a pair from a map.
+ Returns true if the key was found and its pair removed.
+ Returns false otherwise. */
extern bool gl_map_remove (gl_map_t map, const void *key);
-/* Remove a pair from a map and retrieve the previous value.
- Return true and set *OLDVALUEP to the previous value, if the key was found
+/* Removes a pair from a map and retrieve the previous value.
+ Returns true and sets *OLDVALUEP to the previous value, if the key was found
and its pair removed.
- Return false otherwise. */
+ Returns false otherwise. */
extern bool gl_map_getremove (gl_map_t map, const void *key,
const void **oldvaluep);
-/* Free an entire map.
+/* Frees an entire map.
(But this call does not free the keys and values of the pairs in the map.
It only invokes the KDISPOSE_FN on each key and the VDISPOSE_FN on each value
of the pairs in the map.) */
#if 0 /* These are defined inline below. */
-/* Create an iterator traversing a map.
+/* Creates an iterator traversing a map.
The map's contents must not be modified while the iterator is in use,
except for modifying the value of the last returned key or removing the
last returned pair. */
extern gl_map_iterator_t gl_map_iterator (gl_map_t map);
-/* If there is a next pair, store the next pair in *KEYP and *VALUEP, advance
- the iterator, and return true. Otherwise, return false. */
+/* If there is a next pair, stores the next pair in *KEYP and *VALUEP, advances
+ the iterator, and returns true. Otherwise, returns false. */
extern bool gl_map_iterator_next (gl_map_iterator_t *iterator,
const void **keyp, const void **valuep);
-/* Free an iterator. */
+/* Frees an iterator. */
extern void gl_map_iterator_free (gl_map_iterator_t *iterator);
#endif /* End of inline functions. */
#endif
/* Type of function used to compare a key with a threshold.
- Return true if the key is greater or equal than the threshold. */
+ Returns true if the key is greater or equal than the threshold. */
typedef bool (*gl_mapkey_threshold_fn) (const void *key, const void *threshold);
struct gl_omap_impl;
#if 0 /* Unless otherwise specified, these are defined inline below. */
-/* Create an empty map.
+/* Creates an empty map.
IMPLEMENTATION is one of GL_ARRAY_OMAP, GL_AVLTREE_OMAP, GL_RBTREE_OMAP.
COMPAR_FN is a key comparison function or NULL.
KDISPOSE_FN is a key disposal function or NULL.
gl_mapkey_compar_fn compar_fn,
gl_mapkey_dispose_fn kdispose_fn,
gl_mapvalue_dispose_fn vdispose_fn);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_omap_t gl_omap_nx_create_empty (gl_omap_implementation_t implementation,
gl_mapkey_compar_fn compar_fn,
gl_mapkey_dispose_fn kdispose_fn,
gl_mapvalue_dispose_fn vdispose_fn);
-/* Return the current number of pairs in an ordered map. */
+/* Returns the current number of pairs in an ordered map. */
extern size_t gl_omap_size (gl_omap_t map);
-/* Search whether a pair with the given key is already in the ordered map.
- Return the value if found, or NULL if not present in the map. */
+/* Searches whether a pair with the given key is already in the ordered map.
+ Returns the value if found, or NULL if not present in the map. */
extern const void * gl_omap_get (gl_omap_t map, const void *key);
-/* Search whether a pair with the given key is already in the ordered map.
- Return true and set *VALUEP to the value if found.
- Return false if not present in the map. */
+/* Searches whether a pair with the given key is already in the ordered map.
+ Returns true and sets *VALUEP to the value if found.
+ Returns false if not present in the map. */
extern bool gl_omap_search (gl_omap_t map, const void *key,
const void **valuep);
-/* Search the pair with the least key in the ordered map that compares
+/* Searches the pair with the least key in the ordered map that compares
greater or equal to the given THRESHOLD. The representation of the
THRESHOLD is defined by the THRESHOLD_FN.
- Return true and store the found pair in *KEYP and *VALUEP if found.
- Otherwise return false. */
+ Returns true and stores the found pair in *KEYP and *VALUEP if found.
+ Otherwise returns false. */
extern bool gl_omap_search_atleast (gl_omap_t map,
gl_mapkey_threshold_fn threshold_fn,
const void *threshold,
const void **keyp, const void **valuep);
-/* Add a pair to an ordered map.
- Return true if a pair with the given key was not already in the map and so
+/* Adds a pair to an ordered map.
+ Returns true if a pair with the given key was not already in the map and so
this pair was added.
- Return false if a pair with the given key was already in the map and only
+ Returns false if a pair with the given key was already in the map and only
its value was replaced. */
/* declared in gl_xomap.h */
extern bool gl_omap_put (gl_omap_t map, const void *key, const void *value);
-/* Likewise. Return -1 upon out-of-memory. */
+/* Likewise. Returns -1 upon out-of-memory. */
extern int gl_omap_nx_put (gl_omap_t map, const void *key, const void *value)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
__attribute__ ((__warn_unused_result__))
#endif
;
-/* Add a pair to an ordered map and retrieve the previous value.
- Return true if a pair with the given key was not already in the map and so
+/* Adds a pair to an ordered map and retrieve the previous value.
+ Returns true if a pair with the given key was not already in the map and so
this pair was added.
- Return false and set *OLDVALUEP to the previous value, if a pair with the
+ Returns false and sets *OLDVALUEP to the previous value, if a pair with the
given key was already in the map and only its value was replaced. */
/* declared in gl_xomap.h */
extern bool gl_omap_getput (gl_omap_t map, const void *key, const void *value,
const void **oldvaluep);
-/* Likewise. Return -1 upon out-of-memory. */
+/* Likewise. Returns -1 upon out-of-memory. */
extern int gl_omap_nx_getput (gl_omap_t map, const void *key, const void *value,
const void **oldvaluep)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
#endif
;
-/* Remove a pair from an ordered map.
- Return true if the key was found and its pair removed.
- Return false otherwise. */
+/* Removes a pair from an ordered map.
+ Returns true if the key was found and its pair removed.
+ Returns false otherwise. */
extern bool gl_omap_remove (gl_omap_t map, const void *key);
-/* Remove a pair from an ordered map and retrieve the previous value.
- Return true and set *OLDVALUEP to the previous value, if the key was found
+/* Removes a pair from an ordered map and retrieve the previous value.
+ Returns true and sets *OLDVALUEP to the previous value, if the key was found
and its pair removed.
- Return false otherwise. */
+ Returns false otherwise. */
extern bool gl_omap_getremove (gl_omap_t map, const void *key,
const void **oldvaluep);
-/* Free an entire ordered map.
+/* Frees an entire ordered map.
(But this call does not free the keys and values of the pairs in the map.
It only invokes the KDISPOSE_FN on each key and the VDISPOSE_FN on each value
of the pairs in the map.) */
#if 0 /* These are defined inline below. */
-/* Create an iterator traversing an ordered map.
+/* Creates an iterator traversing an ordered map.
The map's contents must not be modified while the iterator is in use,
except for modifying the value of the last returned key or removing the
last returned pair. */
extern gl_omap_iterator_t gl_omap_iterator (gl_omap_t map);
-/* If there is a next pair, store the next pair in *KEYP and *VALUEP, advance
- the iterator, and return true. Otherwise, return false. */
+/* If there is a next pair, stores the next pair in *KEYP and *VALUEP, advances
+ the iterator, and returns true. Otherwise, returns false. */
extern bool gl_omap_iterator_next (gl_omap_iterator_t *iterator,
const void **keyp, const void **valuep);
-/* Free an iterator. */
+/* Frees an iterator. */
extern void gl_omap_iterator_free (gl_omap_iterator_t *iterator);
#endif /* End of inline functions. */
#endif
/* Type of function used to compare an element with a threshold.
- Return true if the element is greater or equal than the threshold. */
+ Returns true if the element is greater or equal than the threshold. */
typedef bool (*gl_setelement_threshold_fn) (const void *elt, const void *threshold);
struct gl_oset_impl;
#if 0 /* Unless otherwise specified, these are defined inline below. */
-/* Create an empty set.
+/* Creates an empty set.
IMPLEMENTATION is one of GL_ARRAY_OSET, GL_AVLTREE_OSET, GL_RBTREE_OSET.
COMPAR_FN is an element comparison function or NULL.
DISPOSE_FN is an element disposal function or NULL. */
extern gl_oset_t gl_oset_create_empty (gl_oset_implementation_t implementation,
gl_setelement_compar_fn compar_fn,
gl_setelement_dispose_fn dispose_fn);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_oset_t gl_oset_nx_create_empty (gl_oset_implementation_t implementation,
gl_setelement_compar_fn compar_fn,
gl_setelement_dispose_fn dispose_fn);
-/* Return the current number of elements in an ordered set. */
+/* Returns the current number of elements in an ordered set. */
extern size_t gl_oset_size (gl_oset_t set);
-/* Search whether an element is already in the ordered set.
- Return true if found, or false if not present in the set. */
+/* Searches whether an element is already in the ordered set.
+ Returns true if found, or false if not present in the set. */
extern bool gl_oset_search (gl_oset_t set, const void *elt);
-/* Search the least element in the ordered set that compares greater or equal
+/* Searches the least element in the ordered set that compares greater or equal
to the given THRESHOLD. The representation of the THRESHOLD is defined
by the THRESHOLD_FN.
- Return true and store the found element in *ELTP if found, otherwise return
+ Returns true and stores the found element in *ELTP if found, otherwise returns
false. */
extern bool gl_oset_search_atleast (gl_oset_t set,
gl_setelement_threshold_fn threshold_fn,
const void *threshold,
const void **eltp);
-/* Add an element to an ordered set.
- Return true if it was not already in the set and added, false otherwise. */
+/* Adds an element to an ordered set.
+ Returns true if it was not already in the set and added, false otherwise. */
/* declared in gl_xoset.h */
extern bool gl_oset_add (gl_oset_t set, const void *elt);
-/* Likewise. Return -1 upon out-of-memory. */
+/* Likewise. Returns -1 upon out-of-memory. */
extern int gl_oset_nx_add (gl_oset_t set, const void *elt)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
__attribute__ ((__warn_unused_result__))
#endif
;
-/* Remove an element from an ordered set.
- Return true if it was found and removed. */
+/* Removes an element from an ordered set.
+ Returns true if it was found and removed. */
extern bool gl_oset_remove (gl_oset_t set, const void *elt);
-/* Free an entire ordered set.
+/* Frees an entire ordered set.
(But this call does not free the elements of the set. It only invokes
the DISPOSE_FN on each of the elements of the set.) */
extern void gl_oset_free (gl_oset_t set);
#if 0 /* These are defined inline below. */
-/* Create an iterator traversing an ordered set.
+/* Creates an iterator traversing an ordered set.
The set's contents must not be modified while the iterator is in use,
except for removing the last returned element. */
extern gl_oset_iterator_t gl_oset_iterator (gl_oset_t set);
-/* If there is a next element, store the next element in *ELTP, advance the
- iterator and return true. Otherwise, return false. */
+/* If there is a next element, stores the next element in *ELTP, advances the
+ iterator and returns true. Otherwise, returns false. */
extern bool gl_oset_iterator_next (gl_oset_iterator_t *iterator,
const void **eltp);
-/* Free an iterator. */
+/* Frees an iterator. */
extern void gl_oset_iterator_free (gl_oset_iterator_t *iterator);
#endif /* End of inline functions. */
this would exceed the address space of the machine. */
#define MAXHEIGHT 116
-/* Rotate left a subtree.
+/* Rotates left a subtree.
B D
/ \ / \
/ \ / \
C E A C
- Change the tree structure, update the branch sizes.
+ Changes the tree structure, updates the branch sizes.
The caller must update the colors and register D as child of its parent. */
static NODE_T
rotate_left (NODE_T b_node, NODE_T d_node)
return d_node;
}
-/* Rotate right a subtree.
+/* Rotates right a subtree.
D B
/ \ / \
/ \ / \
A C C E
- Change the tree structure, update the branch sizes.
+ Changes the tree structure, updates the branch sizes.
The caller must update the colors and register B as child of its parent. */
static NODE_T
rotate_right (NODE_T b_node, NODE_T d_node)
return b_node;
}
-/* Ensure the tree is balanced, after an insertion operation.
+/* Ensures the tree is balanced, after an insertion operation.
Also assigns node->color.
parent is the given node's parent, known to be non-NULL. */
static void
}
}
-/* Ensure the tree is balanced, after a deletion operation.
+/* Ensures the tree is balanced, after a deletion operation.
CHILD was a grandchild of PARENT and is now its child. Between them,
a black node was removed. CHILD is also black, or NULL.
(CHILD can also be NULL. But PARENT is non-NULL.) */
#if 0 /* Unless otherwise specified, these are defined inline below. */
-/* Create an empty set.
+/* Creates an empty set.
IMPLEMENTATION is one of GL_ARRAY_SET, GL_LINKEDHASH_SET, GL_HASH_SET.
EQUALS_FN is an element comparison function or NULL.
HASHCODE_FN is an element hash code function or NULL.
gl_setelement_equals_fn equals_fn,
gl_setelement_hashcode_fn hashcode_fn,
gl_setelement_dispose_fn dispose_fn);
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_set_t gl_set_nx_create_empty (gl_set_implementation_t implementation,
gl_setelement_equals_fn equals_fn,
gl_setelement_hashcode_fn hashcode_fn,
gl_setelement_dispose_fn dispose_fn);
-/* Return the current number of elements in a set. */
+/* Returns the current number of elements in a set. */
extern size_t gl_set_size (gl_set_t set);
-/* Search whether an element is already in the set.
- Return true if found, or false if not present in the set. */
+/* Searches whether an element is already in the set.
+ Returns true if found, or false if not present in the set. */
extern bool gl_set_search (gl_set_t set, const void *elt);
-/* Add an element to a set.
- Return true if it was not already in the set and added, false otherwise. */
+/* Adds an element to a set.
+ Returns true if it was not already in the set and added, false otherwise. */
/* declared in gl_xset.h */
extern bool gl_set_add (gl_set_t set, const void *elt);
-/* Likewise. Return -1 upon out-of-memory. */
+/* Likewise. Returns -1 upon out-of-memory. */
extern int gl_set_nx_add (gl_set_t set, const void *elt)
#if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
__attribute__ ((__warn_unused_result__))
#endif
;
-/* Remove an element from a set.
- Return true if it was found and removed. */
+/* Removes an element from a set.
+ Returns true if it was found and removed. */
extern bool gl_set_remove (gl_set_t set, const void *elt);
-/* Free an entire set.
+/* Frees an entire set.
(But this call does not free the elements of the set. It only invokes
the DISPOSE_FN on each of the elements of the set.) */
extern void gl_set_free (gl_set_t set);
#if 0 /* These are defined inline below. */
-/* Create an iterator traversing a set.
+/* Creates an iterator traversing a set.
The set's contents must not be modified while the iterator is in use,
except for removing the last returned element. */
extern gl_set_iterator_t gl_set_iterator (gl_set_t set);
-/* If there is a next element, store the next element in *ELTP, advance the
- iterator and return true. Otherwise, return false. */
+/* If there is a next element, stores the next element in *ELTP, advances the
+ iterator and returns true. Otherwise, returns false. */
extern bool gl_set_iterator_next (gl_set_iterator_t *iterator,
const void **eltp);
-/* Free an iterator. */
+/* Frees an iterator. */
extern void gl_set_iterator_free (gl_set_iterator_t *iterator);
#endif /* End of inline functions. */
#endif
-/* Create a sublist of a given list.
+/* Creates a sublist of a given list.
This is the list of elements with indices i, start_index <= i < end_index.
The sublist is backed by the given list, which means:
- Modifications to the sublist affect the whole list.
extern gl_list_t gl_sublist_create (gl_list_t whole_list,
size_t start_index, size_t end_index);
#endif
-/* Likewise. Return NULL upon out-of-memory. */
+/* Likewise. Returns NULL upon out-of-memory. */
extern gl_list_t gl_sublist_nx_create (gl_list_t whole_list,
size_t start_index, size_t end_index);