Use an iterator API

- Also perform some minor renaming.
- Add some tests
- Add option --file
- Add benchmark for compose traversal

bench/compose-traversal.c

@@ -0,0 +1,88 @@
+/*
+ * Copyright © 2023 Pierre Le Marre
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the next
+ * paragraph) shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+#include "config.h"
+
+#include <time.h>
+
+#include "xkbcommon/xkbcommon-compose.h"
+
+#include "../test/test.h"
+#include "bench.h"
+
+#define BENCHMARK_ITERATIONS 1000
+
+int
+main(void)
+{
+    struct xkb_context *ctx;
+    char *path;
+    FILE *file;
+    struct xkb_compose_table *table;
+    struct xkb_compose_table_iterator *iter;
+    struct xkb_compose_table_entry *entry;
+    struct bench bench;
+    char *elapsed;
+
+    ctx = test_get_context(CONTEXT_NO_FLAG);
+    assert(ctx);
+
+    path = test_get_path("locale/en_US.UTF-8/Compose");
+    file = fopen(path, "rb");
+    if (file == NULL) {
+        perror(path);
+        free(path);
+        xkb_context_unref(ctx);
+        return -1;
+    }
+    free(path);
+
+    xkb_context_set_log_level(ctx, XKB_LOG_LEVEL_CRITICAL);
+    xkb_context_set_log_verbosity(ctx, 0);
+
+    table = xkb_compose_table_new_from_file(ctx, file, "",
+                                            XKB_COMPOSE_FORMAT_TEXT_V1,
+                                            XKB_COMPOSE_COMPILE_NO_FLAGS);
+    fclose(file);
+    assert(table);
+
+    bench_start(&bench);
+    for (int i = 0; i < BENCHMARK_ITERATIONS; i++) {
+        iter = xkb_compose_table_iterator_new(table);
+        while ((entry = xkb_compose_table_iterator_next(iter))) {
+            assert (entry);
+        }
+        xkb_compose_table_iterator_free(iter);
+    }
+    bench_stop(&bench);
+
+    xkb_compose_table_unref(table);
+
+    elapsed = bench_elapsed_str(&bench);
+    fprintf(stderr, "traversed %d compose tables in %ss\n",
+            BENCHMARK_ITERATIONS, elapsed);
+    free(elapsed);
+
+    xkb_context_unref(ctx);
+    return 0;
+}

include/xkbcommon/xkbcommon-compose.h

@@ -306,40 +306,52 @@ xkb_compose_table_unref(struct xkb_compose_table *table);
  * Represents a single entry in a Compose file in the iteration API.
  * It is immutable.
  *
- * @sa xkb_compose_table_for_each
- * @since 1.5.0
+ * @sa xkb_compose_table_iterator_new
+ * @since 1.6.0
  */
 struct xkb_compose_table_entry;
 
 /**
- * Get the left-hand side of a Compose table entry.
+ * Get the left-hand sequence of a Compose table entry.
  *
- * For example, given the following entry
- *    \<dead_tilde> \<space> : "~" asciitilde # TILDE
- * returns `{XKB_KEY_dead_tilde, XKB_KEY_space}`.
+ * For example, given the following entry:
+ *
+ * ```
+ * <dead_tilde> <space> : "~" asciitilde # TILDE
+ * ```
+ *
+ * it will return `{XKB_KEY_dead_tilde, XKB_KEY_space}`.
+ *
+ * @param[in]  entry The compose table entry object to process.
+ *
+ * @param[out] sequence_length Number of keysyms in the sequence.
  *
  * @returns The array of left-hand side keysyms.  The number of keysyms
- * is returned in the nsyms out-parameter.
+ * is returned in the @p sequence_length out-parameter.
  *
  * @memberof xkb_compose_table_entry
- * @since 1.5.0
+ * @since 1.6.0
  */
 const xkb_keysym_t *
-xkb_compose_table_entry_lhs(struct xkb_compose_table_entry *entry,
-                            size_t *nsyms);
+xkb_compose_table_entry_sequence(struct xkb_compose_table_entry *entry,
+                                 size_t *sequence_length);
 
 /**
  * Get the right-hand result keysym of a Compose table entry.
  *
- * For example, given the following entry
- *    \<dead_tilde> \<space> : "~" asciitilde # TILDE
+ * For example, given the following entry:
+ *
+ * ```
+ * <dead_tilde> <space> : "~" asciitilde # TILDE
+ * ```
+ *
  * it will return `XKB_KEY_asciitilde`.
  *
  * The keysym is optional; if the entry does not specify a keysym,
  * returns `XKB_KEY_NoSymbol`.
  *
  * @memberof xkb_compose_table_entry
- * @since 1.5.0
+ * @since 1.6.0
  */
 xkb_keysym_t
 xkb_compose_table_entry_keysym(struct xkb_compose_table_entry *entry);
@@ -349,44 +361,78 @@ xkb_compose_table_entry_keysym(struct xkb_compose_table_entry *entry);
  *
  * The string is UTF-8 encoded and `\0`-terminated.
  *
- * For example, given the following entry
- *    \<dead_tilde> \<space> : "~" asciitilde # TILDE
+ * For example, given the following entry:
+ *
+ * ```
+ * <dead_tilde> <space> : "~" asciitilde # TILDE
+ * ```
+ *
  * it will return `"~"`.
  *
  * The string is optional; if the entry does not specify a string,
  * returns the empty string.
  *
  * @memberof xkb_compose_table_entry
- * @since 1.5.0
+ * @since 1.6.0
  */
 const char *
 xkb_compose_table_entry_utf8(struct xkb_compose_table_entry *entry);
 
 /**
- * The iterator function type used by xkb_compose_table_for_each().
+ * @struct xkb_compose_table_iterator
+ * Iterator over a compose table’s entries.
  *
- * @sa xkb_compose_table_for_each
- * @memberof xkb_compose
- * @since 1.5.0
+ * @sa xkb_compose_table_iterator_new()
+ * @since 1.6.0
  */
-typedef void
-(*xkb_compose_table_iter_t)(struct xkb_compose_table_entry *entry,
-                            void *data);
+struct xkb_compose_table_iterator;
 
 /**
- * Run a specified function for every valid entry in the table.
+ * Create a new iterator for a compose table.
+ *
+ * Intended use:
+ *
+ * ```c
+ * struct xkb_compose_table_iterator *iter = xkb_compose_table_iterator_new(compose_table);
+ * struct xkb_compose_table_entry *entry;
+ * while (entry = xkb_compose_table_iterator_next(iter)) {
+ *     // ...
+ * }
+ * xkb_compose_table_iterator_free(iter);
+ * ```
+ *
+ * @returns A new compose table iterator, or `NULL` on failure.
+ *
+ * @memberof xkb_compose_table_iterator
+ * @sa xkb_compose_table_iterator_free()
+ * @since 1.6.0
+ */
+struct xkb_compose_table_iterator *
+xkb_compose_table_iterator_new(struct xkb_compose_table *table);
+
+/**
+ * Free a compose iterator.
+ *
+ * @memberof xkb_compose_table_iterator
+ * @since 1.6.0
+ */
+void
+xkb_compose_table_iterator_free(struct xkb_compose_table_iterator *iter);
+
+/**
+ * Get the next compose entry from a compose table iterator.
  *
  * The entries are returned in lexicographic order of the left-hand
  * side of entries. This does not correspond to the order in which
  * the entries appear in the Compose file.
  *
- * @memberof xkb_compose_table
- * @since 1.5.0
+ * Returns `NULL` in case there is no more entries.
+ *
+ * @memberof xkb_compose_table_iterator
+ * @since 1.6.0
  */
-void
-xkb_compose_table_for_each(struct xkb_compose_table *table,
-                           xkb_compose_table_iter_t iter,
-                           void *data);
+struct xkb_compose_table_entry *
+xkb_compose_table_iterator_next(struct xkb_compose_table_iterator *iter);
 
 /** Flags for compose state creation. */
 enum xkb_compose_state_flags {

meson.build

@@ -767,6 +767,11 @@ benchmark(
     executable('bench-compose', 'bench/compose.c', dependencies: test_dep),
     env: bench_env,
 )
+benchmark(
+    'compose-traversal',
+    executable('bench-compose-traversal', 'bench/compose-traversal.c', dependencies: test_dep),
+    env: bench_env,
+)
 benchmark(
     'atom',
     executable('bench-atom', 'bench/atom.c', dependencies: test_dep),