From 493cc6490230857aa3008d5442d8e41faba4a4a1 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 31 May 2025 23:33:12 +0000 Subject: [PATCH] hash.c: add descriptive comments to C-facing MRB_API hash functions This commit adds C-style descriptive comments to MRB_API functions in `src/hash.c` that are intended for use as part of mruby's C API. The comments are targeted at C developers using these functions directly. Comments were added or updated for the following functions: - mrb_hash_new: Added comment. - mrb_hash_new_capa: Updated existing comment to be more C API user-centric. - mrb_hash_dup: Added comment. - mrb_hash_get: Added comment. - mrb_hash_fetch: Added comment. - mrb_hash_set: Added comment. - mrb_hash_delete_key: Added comment. - mrb_hash_size: Added comment. - mrb_hash_merge: Added comment. - mrb_hash_foreach: Comment updated in a previous phase of work. This work aligns with the guideline to comment C-facing MRB_API functions, while avoiding adding new C-API comments to those MRB_API functions that solely implement Ruby methods and already have extensive Ruby method documentation (call-seq) in the source. The @brief markup was avoided as per the original issue request. --- src/hash.c | 152 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 148 insertions(+), 4 deletions(-) diff --git a/src/hash.c b/src/hash.c index e03acbb19..3faf852d3 100644 --- a/src/hash.c +++ b/src/hash.c @@ -1118,7 +1118,33 @@ mrb_hash_memsize(mrb_value self) ib_byte_size_for(ib_bit(h)))); } -/* Iterates over the key/value pairs. */ +/** + * Iterates over each key-value pair in the given hash. + * + * This function calls the provided callback function `func` for each entry + * in the hash `h`. The iteration order is the insertion order. + * + * The callback function `func` has the signature: + * `int callback(mrb_state *mrb, mrb_value key, mrb_value value, void *data)` + * - `mrb`: The mruby state. + * - `key`: The key of the current hash entry. + * - `value`: The value of the current hash entry. + * - `data`: The user-supplied data pointer passed to `mrb_hash_foreach`. + * + * If the callback function returns a non-zero value, the iteration stops. + * + * Important: Modifying the hash `h` within the callback function can lead + * to undefined behavior if not handled carefully (e.g., using `H_CHECK_MODIFIED` + * as done internally for Ruby methods, though direct C API users must be cautious). + * The `H_CHECK_MODIFIED` macro within this function is for internal safety + * when this function is used to implement Ruby methods that might call + * arbitrary Ruby code during iteration. + * + * @param mrb The mruby state. + * @param h A pointer to the RHash structure to iterate over. + * @param func The callback function to be called for each key-value pair. + * @param data A void pointer that will be passed to the callback function. + */ MRB_API void mrb_hash_foreach(mrb_state *mrb, struct RHash *h, mrb_hash_foreach_func *func, void *data) { @@ -1140,6 +1166,15 @@ mrb_hash_first_key(mrb_state *mrb, mrb_value h) return mrb_nil_value(); } +/** + * Creates a new, empty hash. + * + * This function allocates and initializes a new hash object. + * The returned hash is empty and ready to have elements added to it. + * + * @param mrb The mruby state. + * @return An mrb_value representing the new empty hash. + */ MRB_API mrb_value mrb_hash_new(mrb_state *mrb) { @@ -1147,9 +1182,21 @@ mrb_hash_new(mrb_state *mrb) return mrb_obj_value(h); } -/* - * Set the capacity of EA and IB to minimum capacity (and appropriate load - * factor) that does not cause expansion when inserting `capa` elements. +/** + * Creates a new, empty hash with a specified initial capacity. + * + * This function allocates and initializes a new hash object, pre-allocating + * internal structures to hold at least `capa` elements. This can be an + * optimization if the number of elements to be stored is known in advance, + * as it can prevent reallocations. + * + * If `capa` is 0, it behaves like `mrb_hash_new()`. + * An error will be raised if `capa` is negative or excessively large. + * + * @param mrb The mruby state. + * @param capa The initial capacity (number of elements) the hash should be + * able to hold without needing to resize. + * @return An mrb_value representing the new empty hash with preallocated capacity. */ MRB_API mrb_value mrb_hash_new_capa(mrb_state *mrb, mrb_int capa) @@ -1225,6 +1272,18 @@ mrb_hash_init_copy(mrb_state *mrb, mrb_value self) return self; } +/** + * Creates a new hash that is a duplicate of the given hash. + * + * This function creates a shallow copy of the original hash `self`. + * The keys and values themselves are not duplicated, but the internal + * structure of the hash (entry array, hash table, default values/procs) + * is copied. + * + * @param mrb The mruby state. + * @param self The hash object (mrb_value) to duplicate. + * @return An mrb_value representing the new duplicated hash. + */ MRB_API mrb_value mrb_hash_dup(mrb_state *mrb, mrb_value self) { @@ -1235,6 +1294,24 @@ mrb_hash_dup(mrb_state *mrb, mrb_value self) return copy; } +/** + * Retrieves the value associated with a given key from the hash. + * + * If the key is found in the hash, its corresponding value is returned. + * If the key is not found, this function considers the hash's default settings: + * - If a default proc is set for the hash, it is called with the hash and key, + * and its result is returned. + * - If a default value is set, that value is returned. + * - Otherwise (no key found and no default settings), nil is returned. + * This function may also invoke a user-defined `default` method on the hash + * if it has been overridden and no basic default proc/value handles the lookup. + * + * @param mrb The mruby state. + * @param hash The hash object (mrb_value) to search. + * @param key The key (mrb_value) to look up. + * @return The associated mrb_value, or the result of the default proc, + * or the default value, or nil if not found and no defaults apply. + */ MRB_API mrb_value mrb_hash_get(mrb_state *mrb, mrb_value hash, mrb_value key) { @@ -1253,6 +1330,21 @@ mrb_hash_get(mrb_state *mrb, mrb_value hash, mrb_value key) return mrb_funcall_argv(mrb, hash, mid, 1, &key); } +/** + * Retrieves the value associated with a given key from the hash, + * returning a C-provided default value if the key is not found. + * + * If the `key` is found in the `hash`, its corresponding value is returned. + * If the `key` is not found, the `def` mrb_value provided to this function + * is returned. This function does *not* use the hash's own default proc + * or default value. + * + * @param mrb The mruby state. + * @param hash The hash object (mrb_value) to search. + * @param key The key (mrb_value) to look up. + * @param def The default mrb_value to return if the key is not found. + * @return The associated mrb_value if the key is found, otherwise `def`. + */ MRB_API mrb_value mrb_hash_fetch(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value def) { @@ -1265,6 +1357,22 @@ mrb_hash_fetch(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value def) return def; } +/** + * Sets or updates a key-value pair in the hash. + * + * Associates `val` with `key` in the `hash`. If `key` already exists, + * its value is updated. If `key` does not exist, a new entry is created. + * The hash is modified in place. + * + * If the `key` is a `MRB_TT_STRING` and not frozen, it will be duplicated + * and the duplicate will be frozen before use. + * Write barriers are triggered for garbage collection purposes for the key and value. + * + * @param mrb The mruby state. + * @param hash The hash object (mrb_value) to modify. + * @param key The key (mrb_value) for the entry. + * @param val The value (mrb_value) to associate with the key. + */ MRB_API void mrb_hash_set(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value val) { @@ -1509,6 +1617,17 @@ mrb_hash_set_default_proc(mrb_state *mrb, mrb_value hash) return ifnone; } +/** + * Deletes a key-value pair from the hash. + * + * Removes the entry associated with `key` from the `hash`. + * The hash is modified in place. + * + * @param mrb The mruby state. + * @param hash The hash object (mrb_value) to modify. + * @param key The key (mrb_value) of the entry to delete. + * @return The value associated with the deleted key if found, otherwise nil. + */ MRB_API mrb_value mrb_hash_delete_key(mrb_state *mrb, mrb_value hash, mrb_value key) { @@ -1619,6 +1738,13 @@ mrb_hash_aset(mrb_state *mrb, mrb_value self) return val; } +/** + * Returns the number of key-value pairs in the hash. + * + * @param mrb The mruby state (unused in the current implementation, but part of MRB_API convention). + * @param hash The hash object (mrb_value) to get the size of. + * @return An mrb_int representing the number of entries in the hash. + */ MRB_API mrb_int mrb_hash_size(mrb_state *mrb, mrb_value hash) { @@ -1780,6 +1906,24 @@ mrb_hash_has_value(mrb_state *mrb, mrb_value hash) return mrb_false_value(); } +/** + * Merges the contents of `hash2` into `hash1`. + * + * Iterates over `hash2` and for each key-value pair, sets it in `hash1`. + * If a key from `hash2` already exists in `hash1`, its value in `hash1` + * will be overwritten. `hash1` is modified in place. + * + * - `hash1` must not be frozen. + * - `hash2` must be a hash. + * - If `hash1` and `hash2` are the same object, or if `hash2` is empty, + * the function returns without doing anything. + * - Write barriers are triggered for keys and values from `hash2` as they + * are inserted into `hash1`. + * + * @param mrb The mruby state. + * @param hash1 The hash object (mrb_value) to be modified. + * @param hash2 The hash object (mrb_value) whose contents will be merged into `hash1`. + */ MRB_API void mrb_hash_merge(mrb_state *mrb, mrb_value hash1, mrb_value hash2) {