Refactor of BASIC scalar variable storage

1) Move from a linked list to hashmaps for each type
2) Tidy up tidwall hashmap, proper doxygen comments, and add support for passing udata to the allocator functions so that it can be used with BASIC's per-context buddy allocator
3) Vastly improve the readability of variable.c

Author: braindigitalis

include/basic.h

@@ -28,6 +28,9 @@
 
 #define basic_debug if (debug) dprintf
 
+#define SEED0 0x12345678abcdefULL
+#define SEED1 0xfedcba9876543210ULL
+
 #include "basic/defines.h"
 #include "basic/structs.h"
 #include "basic/context.h"

include/basic/context.h

@@ -128,17 +128,17 @@ typedef struct basic_ctx {
 	 *
 	 * Each index in this array corresponds to a specific depth in the call stack.
 	 */
-	struct ub_var_int* local_int_variables[MAX_CALL_STACK_DEPTH];
+	struct hashmap* local_int_variables[MAX_CALL_STACK_DEPTH]; // ub_var_int*
 
 	/**
 	 * @brief Local string variable stack for function/procedure scopes.
 	 */
-	struct ub_var_string* local_string_variables[MAX_CALL_STACK_DEPTH];
+	struct hashmap* local_string_variables[MAX_CALL_STACK_DEPTH]; // ub_var_string*
 
 	/**
 	 * @brief Local double (real) variable stack for function/procedure scopes.
 	 */
-	struct ub_var_double* local_double_variables[MAX_CALL_STACK_DEPTH];
+	struct hashmap* local_double_variables[MAX_CALL_STACK_DEPTH]; // ub_var_double*
 
 	/**
 	 * @brief Call stack for return line numbers during function, procedure, or `GOSUB` calls.
@@ -215,17 +215,17 @@ typedef struct basic_ctx {
 	 *
 	 * Stores all globally scoped integer variables in the program.
 	 */
-	struct ub_var_int* int_variables;
+	struct hashmap* int_variables; // ub_var_int*
 
 	/**
 	 * @brief Global string variable list.
 	 */
-	struct ub_var_string* str_variables;
+	struct hashmap* str_variables; // ub_var_string*
 
 	/**
 	 * @brief Global double variable list.
 	 */
-	struct ub_var_double* double_variables;
+	struct hashmap* double_variables; // ub_var_double*
 
 	/**
 	 * @brief Global integer array variable list.

include/basic/structs.h

@@ -60,7 +60,6 @@ typedef struct ub_var_string {
 	size_t name_length; ///< Length of the variable name
 	char* value; ///< The value of the string variable
 	bool global; ///< True if the variable is global, false if local
-	struct ub_var_string* next; ///< Pointer to the next string variable (for chaining)
 } ub_var_string;
 
 /**

include/basic/variable.h

@@ -47,9 +47,9 @@ const char* basic_get_string_variable(const char* var, struct basic_ctx* ctx);
  * @param value The value to set for the string variable.
  * @param ctx The current BASIC context.
  * @param local Boolean indicating whether the variable is local.
- * @param global Boolean indicating whether the variable is global.
+ * @param propagate_global Boolean indicating whether the variable is propagated globally to child programs.
  */
-void basic_set_string_variable(const char* var, const char* value, struct basic_ctx* ctx, bool local, bool global);
+void basic_set_string_variable(const char* var, const char* value, struct basic_ctx* ctx, bool local, bool propagate_global);
 
 /**
  * @brief Set the value of a double (real) variable.
@@ -60,9 +60,9 @@ void basic_set_string_variable(const char* var, const char* value, struct basic_
  * @param value The value to set for the double variable.
  * @param ctx The current BASIC context.
  * @param local Boolean indicating whether the variable is local.
- * @param global Boolean indicating whether the variable is global.
+ * @param propagate_global Boolean indicating whether the variable is propagated globally to child programs.
  */
-void basic_set_double_variable(const char* var, const double value, struct basic_ctx* ctx, bool local, bool global);
+void basic_set_double_variable(const char* var, const double value, struct basic_ctx* ctx, bool local, bool propagate_global);
 
 /**
  * @brief Set the value of an integer variable.
@@ -73,9 +73,9 @@ void basic_set_double_variable(const char* var, const double value, struct basic
  * @param value The value to set for the integer variable.
  * @param ctx The current BASIC context.
  * @param local Boolean indicating whether the variable is local.
- * @param global Boolean indicating whether the variable is global.
+ * @param propagate_global Boolean indicating whether the variable is propagated globally to child programs.
  */
-void basic_set_int_variable(const char* var, int64_t value, struct basic_ctx* ctx, bool local, bool global);
+void basic_set_int_variable(const char* var, int64_t value, struct basic_ctx* ctx, bool local, bool propagate_global);
 
 /**
  * @brief Get the numeric value of a variable.

include/hashmap.h

@@ -1,14 +1,16 @@
 /**
  * @file hashmap.h
+ * @brief Open-addressed hashmap (Robin Hood), with allocator udata support.
+ *
+ * Updated by Craig Edwards, September 2025, to allow `udata` to be passed to
+ * the allocator functions. This enables contextual/arena allocators (e.g., per
+ * BASIC interpreter context) without altering external call sites.
+ *
+ * Based on tidwall hashmap, copyright 2020 Joshua J Baker. All rights
+ * reserved. Use of this source code is governed by an MIT-style licence that
+ * can be found in the LICENSE file. https://github.com/tidwall/hashmap.c
  */
-// Copyright 2020 Joshua J Baker. All rights reserved.
-// Use of this source code is governed by an MIT-style
-// license that can be found in the LICENSE file.
-
-// https://github.com/tidwall/hashmap.c
-
-#ifndef HASHMAP_H
-#define HASHMAP_H
+#pragma once
 
 #include "kernel.h"
 #include <stdbool.h>
@@ -17,45 +19,215 @@
 
 struct hashmap;
 
-struct hashmap *hashmap_new(size_t elsize, size_t cap, 
-                            uint64_t seed0, uint64_t seed1,
-                            uint64_t (*hash)(const void *item, 
-                                             uint64_t seed0, uint64_t seed1),
-                            int (*compare)(const void *a, const void *b, 
-                                           void *udata),
-                            void (*elfree)(const void *item),
-                            void *udata);
-struct hashmap *hashmap_new_with_allocator(
-                            void *(*malloc)(size_t), 
-                            void *(*realloc)(void *, size_t), 
-                            void (*free)(const void*),
-                            size_t elsize, size_t cap, 
-                            uint64_t seed0, uint64_t seed1,
-                            uint64_t (*hash)(const void *item, 
-                                             uint64_t seed0, uint64_t seed1),
-                            int (*compare)(const void *a, const void *b, 
-                                           void *udata),
-                            void (*elfree)(const void *item),
-                            void *udata);
+/* --------------------------------------------------------------------------
+ * Callback typedefs
+ * -------------------------------------------------------------------------- */
+
+/**
+ * @brief Allocate a new block.
+ * @param size  Bytes requested.
+ * @param udata User data pointer supplied at map construction.
+ * @return Pointer to allocated block, or NULL on failure.
+ */
+typedef void *(*hashmap_allocator)(size_t size, void *udata);
+
+/**
+ * @brief Resize an existing block.
+ * @param ptr   Existing allocation (or NULL to behave like malloc).
+ * @param size  New size in bytes.
+ * @param udata User data pointer supplied at map construction.
+ * @return Pointer to (possibly moved) block, or NULL on failure.
+ */
+typedef void *(*hashmap_reallocator)(void *ptr, size_t size, void *udata);
+
+/**
+ * @brief Release an allocated block.
+ * @param ptr   Block to free (may be NULL).
+ * @param udata User data pointer supplied at map construction.
+ */
+typedef void  (*hashmap_releaser)(const void *ptr, void *udata);
+
+/**
+ * @brief Hash an item.
+ * @param item  Pointer to key/item.
+ * @param seed0 First 64-bit seed.
+ * @param seed1 Second 64-bit seed.
+ * @return 64-bit hash value.
+ */
+typedef uint64_t (*hashmap_hash_fn)(const void *item, uint64_t seed0, uint64_t seed1);
+
+/**
+ * @brief Compare two items.
+ * @param a     First item.
+ * @param b     Second item.
+ * @param udata User data pointer supplied at map construction.
+ * @return <0 if a<b, 0 if equal, >0 if a>b.
+ */
+typedef int (*hashmap_compare_fn)(const void *a, const void *b, void *udata);
+
+/**
+ * @brief Optional element destructor for items stored by value.
+ * @param item  Element to dispose.
+ *
+ * Note: This is only for element-internal resources. The map storage itself is
+ * freed by the map’s allocator callbacks.
+ */
+typedef void (*hashmap_elfree_fn)(const void *item, void *udata);
+
+/**
+ * @brief Iterator callback for scanning all items.
+ * @param item  Current element.
+ * @param udata User data pointer supplied at call site.
+ * @return true to continue, false to stop.
+ */
+typedef bool (*hashmap_iter_fn)(const void *item, void *udata);
+
+
+/* --------------------------------------------------------------------------
+ * Creation / destruction
+ * -------------------------------------------------------------------------- */
+
+/**
+ * @brief Create a new hashmap with standard kernel allocators.
+ *
+ * @param elsize Size in bytes of each element stored by the map.
+ * @param cap    Initial capacity hint (0 defaults to 16).
+ * @param seed0  First 64-bit hash seed.
+ * @param seed1  Second 64-bit hash seed.
+ * @param hash   Hash function for items.
+ * @param compare Comparison function for items.
+ * @param elfree Optional element destructor (may be NULL).
+ * @param udata  User data passed to `compare` (and may be used internally).
+ * @return Handle to a new hashmap, or NULL on OOM.
+ */
+struct hashmap *hashmap_new(size_t elsize, size_t cap, uint64_t seed0, uint64_t seed1, hashmap_hash_fn hash, hashmap_compare_fn compare, hashmap_elfree_fn elfree, void *udata);
+
+/**
+ * @brief Create a new hashmap with custom allocators.
+ *
+ * @param _malloc  Allocator callback (required).
+ * @param _realloc Reallocator callback (required).
+ * @param _free    Releaser callback (required).
+ * @param elsize   Size in bytes of each element stored by the map.
+ * @param cap      Initial capacity hint (0 defaults to 16).
+ * @param seed0    First 64-bit hash seed.
+ * @param seed1    Second 64-bit hash seed.
+ * @param hash     Hash function for items.
+ * @param compare  Comparison function for items.
+ * @param elfree   Optional element destructor (may be NULL).
+ * @param udata    User data passed to allocator callbacks and `compare`.
+ * @return Handle to a new hashmap, or NULL on OOM.
+ */
+struct hashmap *hashmap_new_with_allocator(hashmap_allocator _malloc, hashmap_reallocator _realloc, hashmap_releaser _free, size_t elsize, size_t cap, uint64_t seed0, uint64_t seed1, hashmap_hash_fn hash, hashmap_compare_fn compare, hashmap_elfree_fn elfree, void *udata);
+
+/**
+ * @brief Free a hashmap and its storage.
+ *
+ * Calls `elfree` for each element if provided, then releases internal buffers
+ * via the map’s allocator callbacks.
+ *
+ * @param map Hashmap handle (may be NULL).
+ */
 void hashmap_free(struct hashmap *map);
+
+/**
+ * @brief Clear all items from the map.
+ *
+ * Each element is passed to `elfree` (if provided). If `update_cap` is true,
+ * internal capacity is trimmed to the current number of buckets to avoid new
+ * allocations on the clear.
+ *
+ * @param map        Hashmap handle.
+ * @param update_cap When true, shrink capacity to current bucket count.
+ */
 void hashmap_clear(struct hashmap *map, bool update_cap);
+
+/**
+ * @brief Get the number of stored items.
+ * @param map Hashmap handle.
+ * @return Item count.
+ */
 size_t hashmap_count(struct hashmap *map);
+
+/**
+ * @brief Test whether the previous `hashmap_set` failed due to OOM.
+ * @param map Hashmap handle.
+ * @return true if the last set operation ran out of memory.
+ */
 bool hashmap_oom(struct hashmap *map);
+
+/**
+ * @brief Look up an item by key.
+ * @param map  Hashmap handle.
+ * @param item Key to search for.
+ * @return Pointer to stored item, or NULL if not found.
+ */
 void *hashmap_get(struct hashmap *map, const void *item);
+
+/**
+ * @brief Insert or replace an item.
+ * @param map  Hashmap handle.
+ * @param item Item to insert (by value).
+ * @return Pointer to the replaced item if it existed, otherwise NULL.
+ *
+ * On allocation failure returns NULL and sets the sticky OOM flag
+ * (see `hashmap_oom`).
+ */
 void *hashmap_set(struct hashmap *map, const void *item);
+
+/**
+ * @brief Remove an item by key.
+ * @param map  Hashmap handle.
+ * @param item Key to delete.
+ * @return Pointer to the removed item, or NULL if not found.
+ */
 void *hashmap_delete(struct hashmap *map, void *item);
+
+/**
+ * @brief Probe a raw bucket position.
+ * @param map      Hashmap handle.
+ * @param position Bucket index (will be reduced modulo bucket count).
+ * @return Pointer to stored item at that bucket, or NULL.
+ */
 void *hashmap_probe(struct hashmap *map, uint64_t position);
-bool hashmap_scan(struct hashmap *map,
-                  bool (*iter)(const void *item, void *udata), void *udata);
-bool hashmap_iter(struct hashmap *map, size_t *i, void **item);
 
-uint64_t hashmap_sip(const void *data, size_t len, 
-                     uint64_t seed0, uint64_t seed1);
-uint64_t hashmap_murmur(const void *data, size_t len, 
-                        uint64_t seed0, uint64_t seed1);
+/**
+ * @brief Iterate over every item in the map.
+ * @param map   Hashmap handle.
+ * @param iter  Callback invoked for each item; return false to stop early.
+ * @param udata User data passed to `iter`.
+ * @return false if iteration was stopped early, true otherwise.
+ */
+bool hashmap_scan(struct hashmap *map, hashmap_iter_fn iter, void *udata);
 
+/**
+ * @brief Cursor-based iterator over items.
+ * @param map  Hashmap handle.
+ * @param i    Cursor (initialise to 0; updated on each call).
+ * @param item Out: pointer to the current stored item.
+ * @return true if an item was produced; false if iteration is complete.
+ *
+ * Note: If `hashmap_delete` is called during iteration, the bucket layout may
+ * change. Reset the cursor to 0 to restart iteration safely.
+ */
+bool hashmap_iter(struct hashmap *map, size_t *i, void **item);
 
-// DEPRECATED: use `hashmap_new_with_allocator`
-void hashmap_set_allocator(void *(*malloc)(size_t), void (*free)(const void*));
+/**
+ * @brief SipHash-2-4.
+ * @param data  Input buffer.
+ * @param len   Length in bytes.
+ * @param seed0 First 64-bit seed.
+ * @param seed1 Second 64-bit seed.
+ * @return 64-bit hash value.
+ */
+uint64_t hashmap_sip(const void *data, size_t len, uint64_t seed0, uint64_t seed1);
 
-#endif
+/**
+ * @brief Murmur3_86_128 (folded to 64 bits).
+ * @param data  Input buffer.
+ * @param len   Length in bytes.
+ * @param seed0 First 64-bit seed.
+ * @param seed1 Second 64-bit seed.
+ * @return 64-bit hash value.
+ */
+uint64_t hashmap_murmur(const void *data, size_t len, uint64_t seed0, uint64_t seed1);