- * A vector is a compound of a size and a vector_page pointer, which
- * when non-null points out the top-most page of the vector indexing
- * tree. The number of levels is derived from its size with level 0
- * being the leaf level of actual content. E.g., a vector larger than
- * 256 items, has at least two levels, and generally N levels may span
- * up to 256^N content entries.
+ * \brief The implementation variants.
+ *
+ * - byte_index_levels (0) has 8-bit indexing parts and index pages
+ * with 256 pointers,
+ *
+ * - nibble_index_levels (1) has 4-bit indexing parts and index pages
+ * with 16 pointers,
+ *
+ * - bitpair_index_levels (2) has 2-bit indexing parts and index pages
+ * with 4 pointers,
+ *
+ * - single_index_level (3) has a single page that is sized as the
+ * vector.
+ *
+ * The first three variants are managed by adding/removing full pages
+ * of the indexing tree upon resize and access. The single_index_level
+ * variant is managed by using realloc upon resize. In all cases
+ * shrinking a vector might mean to reclaim items about to be "lost",
+ * if any, via a provided item reclaim callback function. The callback
+ * function may then also veto the shrinking.
+ *
+ * \related vector
+ */
+enum vector_variant {
+ byte_index_levels = 0,
+ nibble_index_levels = 1,
+ bitpair_index_levels = 2,
+ single_index_level = 3
+};
+
+/**
+ * A vector struct is the "foot part" of a representation that
+ * constitutes the implementation variant for a vector abstraction. It
+ * holds the variant indicator, the intended slot size and a root
+ * pointer for the indexing structure, which consist of indexing pages
+ * according to the variant.