prepare the beginning of postlicyd.conf(5)

[apps/pfixtools.git] / common / trie.h

diff --git a/common/trie.h b/common/trie.h
index ddf984a..eed6732 100644 (file)
--- a/common/trie.h
+++ b/common/trie.h
@@ -16,17 +16,20 @@
 /*     products derived from this software without specific prior written     */
 /*     permission.                                                            */
 /*                                                                            */
-/*  THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND   */
-/*  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE     */
-/*  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR        */
-/*  PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS    */
-/*  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR    */
-/*  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF      */
-/*  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS  */
-/*  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN   */
-/*  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)   */
-/*  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF    */
-/*  THE POSSIBILITY OF SUCH DAMAGE.                                           */
+/*  THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS   */
+/*  OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED         */
+/*  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE    */
+/*  DISCLAIMED.  IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY         */
+/*  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL        */
+/*  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS   */
+/*  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)     */
+/*  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,       */
+/*  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN  */
+/*  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE           */
+/*  POSSIBILITY OF SUCH DAMAGE.                                               */
+/*                                                                            */
+/*   Copyright (c) 2006-2008 the Authors                                      */
+/*   see AUTHORS and source files for details                                 */
 /******************************************************************************/
 
 /*
@@ -37,6 +40,7 @@
 #define PFIXTOOLS_TRIE_H
 
 #include "common.h"
+#include "array.h"
 
 typedef struct trie_t trie_t;
 PARRAY(trie_t)
@@ -44,21 +48,56 @@ PARRAY(trie_t)
 trie_t *trie_new(void);
 void trie_delete(trie_t **trie);
 
+/** Add a string in the trie.
+ * \ref trie_compile.
+ */
 __attribute__((nonnull(1,2)))
-void trie_insert(trie_t *trie, const char* key);
+void trie_insert(trie_t *trie, const char *key);
 
+/** Compile the trie.
+ * A trie must be compiled before lookup is possible. Compiling the trie
+ * consists in building the tree.
+ *
+ * \param memlock if true, the trie is locked into the RAM (mlock).
+ *
+ * Usage of a trie:
+ *   trie_insert(trie, ...);
+ *   trie_insert(trie, ...);
+ *   ...
+ *   trie_insert(trie, ...);
+ *
+ *   trie_compile(trie, lock);
+ *
+ *   trie_lookup(trie, ...);
+ *   trie_lookup(trie, ...);
+ */
 __attribute__((nonnull(1)))
 void trie_compile(trie_t *trie, bool memlock);
 
+/** Lock the trie into memory.
+ * \ref trie_unlock
+ */
 __attribute__((nonnull(1)))
 void trie_lock(trie_t *trie);
 
+/** Unlock the trie.
+ * \ref trie_lock
+ */
 __attribute__((nonnull(1)))
 void trie_unlock(trie_t *trie);
 
+/** Check if the trie contains \p key.
+ */
 __attribute__((nonnull(1,2)))
-bool trie_lookup(const trie_t *trie, const char* key);
+bool trie_lookup(const trie_t *trie, const char *key);
 
+/** Check if the trie contains a prefix of \p key.
+ */
+__attribute__((nonnull(1,2)))
+bool trie_prefix(const trie_t *trie, const char *key);
+
+/** Show the content of the trie and computes statistics.
+ */
 __attribute__((nonnull(1)))
 void trie_inspect(const trie_t *trie, bool show_content);