Documentation and Code Cleanup

src/core/data_structures/int64_hash_set.h

@@ -43,7 +43,14 @@
 #define INT64_HASH_SET_EMPTY_KEY INT64_MIN
 
 /**
- * @brief A hash set optimized for storing 64-bit integer keys.
+ * @brief Highly optimized linear probing hash set for storing 64-bit integer
+ * keys.
+ *
+ * @note `INT64_MIN` (`INT64_HASH_SET_EMPTY_KEY`) is reserved as a sentinel
+ * value for the hash table to represent an empty slot for optimization
+ * purposes. Because of this, `Int64HashSet` cannot be used to store
+ * `INT64_MIN`. The user must make sure that `INT64_MIN` is never inserted as a
+ * key.
  */
 typedef struct Int64HashSet {
     int64_t *keys;    /**< Array of keys in the hash set. */

src/core/types/CMakeLists.txt

@@ -22,12 +22,7 @@ set(HEADERS
     ${CMAKE_CURRENT_SOURCE_DIR}/tier_to_ptr_chained_hash_map.h)
 
 set(SOURCES
-    ${CMAKE_CURRENT_SOURCE_DIR}/move_array.c
-    ${CMAKE_CURRENT_SOURCE_DIR}/position_array.c
-    ${CMAKE_CURRENT_SOURCE_DIR}/tier_array.c
-    ${CMAKE_CURRENT_SOURCE_DIR}/tier_hash_map.c
     ${CMAKE_CURRENT_SOURCE_DIR}/tier_position_array.c
-    ${CMAKE_CURRENT_SOURCE_DIR}/tier_position_hash_set.c
-    ${CMAKE_CURRENT_SOURCE_DIR}/tier_stack.c)
+    ${CMAKE_CURRENT_SOURCE_DIR}/tier_position_hash_set.c)
 
 target_sources(gamesman_core PRIVATE ${HEADERS} ${SOURCES})

src/core/types/move_array.h

@@ -4,8 +4,6 @@
  * @author GamesCrafters Research Group, UC Berkeley
  *         Supervised by Dan Garcia <[email protected]>
  * @brief Dynamic Move array.
- * @version 2.0.0
- * @date 2024-12-10
  *
  * @copyright This file is part of GAMESMAN, The Finite, Two-person
  * Perfect-Information Game Generator released under the GPL:
@@ -32,48 +30,80 @@
 #include "core/data_structures/int64_array.h"
 #include "core/types/base.h"
 
-/** @brief Dynamic Move array. */
+/**
+ * @brief Dynamic `Move` array.
+ */
 typedef Int64Array MoveArray;
 
-/** @brief Initializes the move ARRAY to an empty array. */
-void MoveArrayInit(MoveArray *array);
+/**
+ * @brief Initializes `array`.
+ *
+ * @param[out] array Array to initialize.
+ */
+static inline void MoveArrayInit(MoveArray *array) { Int64ArrayInit(array); }
 
-/** @brief Destroyes the move ARRAY. */
-void MoveArrayDestroy(MoveArray *array);
+/**
+ * @brief Deallocates `array`.
+ *
+ * @param[in,out] array Array to deallocate.
+ */
+static inline void MoveArrayDestroy(MoveArray *array) {
+    Int64ArrayDestroy(array);
+}
 
 /**
- * @brief Appends MOVE to the end of ARRAY.
+ * @brief Appends a new `move` to the back of the `array`.
+ *
+ * @param[in,out] array Destination array.
+ * @param[in] move New move.
  *
- * @param array Destination array.
- * @param move Move to append.
- * @return true on success,
- * @return false otherwise.
+ * @retval true on success.
+ * @retval false otherwise.
  */
-bool MoveArrayAppend(MoveArray *array, Move move);
+static inline bool MoveArrayAppend(MoveArray *array, Move move) {
+    return Int64ArrayPushBack(array, move);
+}
 
 /**
- * @brief Removes the last Move in ARRAY.
+ * @brief Pops the move at the back of the `array`.
  *
- * @param array Target array.
- * @return true on success,
- * @return false if ARRAY is empty.
+ * @param[in,out] array Array to pop the move from.
+ *
+ * @retval true on success.
+ * @retval false if the array is empty.
  */
-bool MoveArrayPopBack(MoveArray *array);
+static inline bool MoveArrayPopBack(MoveArray *array) {
+    if (array->size <= 0) return false;
+    --array->size;
+    return true;
+}
 
 /**
- * @brief Sorts the move ARRAY in ascending order using the given COMP-arison
- * function.
+ * @brief Sorts the given `array` according to the given comparison function.
  *
- * @param array Array to be sorted.
- * @param comp Comparison function which returns ​a negative integer value if
+ * @param[in,out] array The array to be sorted.
+ * @param[in] comp Comparison function which returns a negative integer value if
  * the first argument is less than the second, a positive integer value if the
- * first argument is greater than the second and zero if the arguments are
+ * first argument is greater than the second, and zero if the arguments are
  * equivalent.
  */
-void MoveArraySortExplicit(MoveArray *array,
-                           int (*comp)(const void *, const void *));
+static inline void MoveArraySortExplicit(MoveArray *array,
+                                         int (*comp)(const void *,
+                                                     const void *)) {
+    Int64ArraySortExplicit(array, comp);
+}
 
-/** @brief Returns true if ARRAY contains MOVE, or false otherwise. */
-bool MoveArrayContains(const MoveArray *array, Move move);
+/**
+ * @brief Returns whether the given `array` contains the given `move`.
+ *
+ * @param[in] array Array to check.
+ * @param[in] move Move to look for.
+ *
+ * @retval true if the array contains the move.
+ * @retval false otherwise.
+ */
+static inline bool MoveArrayContains(const MoveArray *array, Move move) {
+    return Int64ArrayContains(array, move);
+}
 
 #endif  // GAMESMANONE_CORE_TYPES_MOVE_ARRAY_H_

src/core/types/position_array.h

@@ -4,8 +4,6 @@
  * @author GamesCrafters Research Group, UC Berkeley
  *         Supervised by Dan Garcia <[email protected]>
  * @brief Dynamic Position array.
- * @version 1.1.0
- * @date 2025-04-26
  *
  * @copyright This file is part of GAMESMAN, The Finite, Two-person
  * Perfect-Information Game Generator released under the GPL:
@@ -33,29 +31,72 @@
 #include "core/gamesman_memory.h"
 #include "core/types/base.h"
 
-/** @brief Dynamic Position array. */
+/**
+ * @brief Dynamic `Position` array.
+ */
 typedef Int64Array PositionArray;
 
-/** @brief Initializes the position ARRAY to an empty array. */
-void PositionArrayInit(PositionArray *array);
+/**
+ * @brief Initializes `array`.
+ *
+ * @param[out] array Array to initialize.
+ */
+static inline void PositionArrayInit(PositionArray *array) {
+    Int64ArrayInit(array);
+}
 
-void PositionArrayInitAllocator(PositionArray *array,
-                                GamesmanAllocator *allocator);
+/**
+ * @brief Initializes `array` using `allocator` as the underlying memory
+ * allocator.
+ *
+ * @details If `allocator` is `NULL`, the function call is equivalent to
+ * `PositionArrayInit(array)`. Note that this function does not transfer the
+ * ownership of `allocator` to the new array object. The caller is responsible
+ * for releasing its own copy of the allocator.
+ *
+ * @param[out] array Array to initialize.
+ * @param[in,out] allocator Memory allocator to use.
+ */
+static inline void PositionArrayInitAllocator(PositionArray *array,
+                                              GamesmanAllocator *allocator) {
+    Int64ArrayInitAllocator(array, allocator);
+}
 
-/** @brief Destroyes the position ARRAY. */
-void PositionArrayDestroy(PositionArray *array);
+/**
+ * @brief Deallocates `array`.
+ *
+ * @param[in,out] array Array to deallocate.
+ */
+static inline void PositionArrayDestroy(PositionArray *array) {
+    Int64ArrayDestroy(array);
+}
 
 /**
- * @brief Appends POSITION to the end of ARRAY.
+ * @brief Appends a new `position` to the back of the `array`.
+ *
+ * @param[in,out] array Destination array.
+ * @param[in] position New position.
  *
- * @param array Destination array.
- * @param position Position to append.
- * @return true on success,
- * @return false otherwise.
+ * @retval true on success.
+ * @retval false otherwise.
  */
-bool PositionArrayAppend(PositionArray *array, Position position);
+static inline bool PositionArrayAppend(PositionArray *array,
+                                       Position position) {
+    return Int64ArrayPushBack(array, position);
+}
 
-/** @brief Returns true if ARRAY contains POSITION, or false otherwise. */
-bool PositionArrayContains(PositionArray *array, Position position);
+/**
+ * @brief Returns whether the given `array` contains the given `position`.
+ *
+ * @param[in] array Array to check.
+ * @param[in] position Position to look for.
+ *
+ * @retval true if the array contains the position.
+ * @retval false otherwise.
+ */
+static inline bool PositionArrayContains(PositionArray *array,
+                                         Position position) {
+    return Int64ArrayContains(array, position);
+}
 
 #endif  // GAMESMANONE_CORE_TYPES_POSITION_ARRAY_H_

src/core/types/simd.h

@@ -29,6 +29,10 @@
 
 #include <stdint.h>
 
+#ifdef GAMESMAN_HAS_BMI1
+#include <immintrin.h>
+#endif  // GAMESMAN_HAS_BMI1
+
 /**
  * @brief 128-bit SIMD vector of 16 signed 8-bit integers.
  */
@@ -44,12 +48,6 @@ typedef uint8_t U8x16 __attribute__((vector_size(16)));
  */
 typedef uint64_t U64x2 __attribute__((vector_size(16)));
 
-#include <stdint.h>
-
-#ifdef GAMESMAN_HAS_BMI1
-#include <immintrin.h>
-#endif  // GAMESMAN_HAS_BMI1
-
 /**
  * @brief Extract bits from unsigned 64-bit integer `val` at the corresponding
  * bit locations specified by mask to contiguous low bits; the remaining