Mercurial > hg > ucx / file diff

--- a/docs/src/modules.md	Thu May 03 10:09:49 2018 +0200
+++ b/docs/src/modules.md	Thu May 03 10:44:33 2018 +0200
@@ -51,6 +51,47 @@
 All common binary tree operations are implemented. Furthermore, this module
 provides search functions via lower and upper bounds.
 
+### Filtering items with a time window
+
+Suppose you have a list of items which contain a `time_t` value and your task
+is to find all items within a time window `[t_start, t_end]`.
+With AVL Trees this is easy:
+```C
+/* ---------------------
+ * Somewhere in a header
+ */
+typedef struct {
+    time_t ts;
+    // other important data
+} MyObject;
+
+/* -----------
+ * Source code
+ */
+
+UcxAVLTree* tree = ucx_avl_new(ucx_longintcmp);
+// ... populate tree with objects, use '& MyObject.ts' as key ...
+
+
+// Now find every item, with 30 <= ts <= 70
+time_t ts_start = 30;
+time_t ts_end = 70;
+
+printf("Values in range:\n");
+for (
+        UcxAVLNode* node = ucx_avl_find_node(
+            tree, (intptr_t) &ts_start,
+            ucx_longintdist, UCX_AVL_FIND_LOWER_BOUNDED);
+        node && (*(time_t*)node->key) <= ts_end;
+        node = ucx_avl_succ(node)
+    ) {
+    printf(" ts: %ld\n", ((MyObject*)node->value)->ts);
+}
+
+ucx_avl_free_content(tree, free);
+ucx_avl_free(tree);
+```
+
 ## Buffer
 
 *Header file:* [buffer.h](api/buffer_8h.html)