Ruby
3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
|
Public APIs related to rb_cHash. More...
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
#include "ruby/st.h"
Go to the source code of this file.
Macros | |
#define | st_foreach_safe rb_st_foreach_safe |
Just another name of rb_st_foreach_safe. More... | |
Typedefs | |
typedef VALUE | rb_hash_update_func(VALUE newkey, VALUE oldkey, VALUE value) |
Type of callback functions to pass to rb_hash_update_by(). More... | |
Functions | |
void | rb_st_foreach_safe (struct st_table *st, st_foreach_callback_func *func, st_data_t arg) |
Identical to rb_st_foreach(), except it raises exceptions when the callback function tampers the table during iterating over it. More... | |
VALUE | rb_check_hash_type (VALUE obj) |
Try converting an object to its hash representation using its to_hash method, if any. More... | |
void | rb_hash_foreach (VALUE hash, int(*func)(VALUE key, VALUE val, VALUE arg), VALUE arg) |
Iterates over a hash. More... | |
VALUE | rb_hash (VALUE obj) |
Calculates a message authentication code of the passed object. More... | |
VALUE | rb_hash_new (void) |
Creates a new, empty hash object. More... | |
VALUE | rb_hash_new_capa (long capa) |
Identical to rb_hash_new(), except it additionally specifies how many keys it is expected to contain. More... | |
VALUE | rb_hash_dup (VALUE hash) |
Duplicates a hash. More... | |
VALUE | rb_hash_freeze (VALUE obj) |
Just another name of rb_obj_freeze. More... | |
VALUE | rb_hash_aref (VALUE hash, VALUE key) |
Queries the given key in the given hash table. More... | |
VALUE | rb_hash_lookup (VALUE hash, VALUE key) |
Identical to rb_hash_aref(), except it always returns RUBY_Qnil for misshits. More... | |
VALUE | rb_hash_lookup2 (VALUE hash, VALUE key, VALUE def) |
Identical to rb_hash_lookup(), except you can specify what to return on misshits. More... | |
VALUE | rb_hash_fetch (VALUE hash, VALUE key) |
Identical to rb_hash_lookup(), except it yields the (implicitly) passed block instead of returning RUBY_Qnil. More... | |
VALUE | rb_hash_aset (VALUE hash, VALUE key, VALUE val) |
Inserts or replaces ("upsert"s) the objects into the given hash table. More... | |
VALUE | rb_hash_clear (VALUE hash) |
Swipes everything out of the passed hash table. More... | |
VALUE | rb_hash_delete_if (VALUE hash) |
Deletes each entry for which the block returns a truthy value. More... | |
VALUE | rb_hash_delete (VALUE hash, VALUE key) |
Deletes the passed key from the passed hash table, if any. More... | |
void | rb_hash_bulk_insert (long argc, const VALUE *argv, VALUE hash) |
Inserts a list of key-value pairs into a hash table at once. More... | |
VALUE | rb_hash_update_by (VALUE hash1, VALUE hash2, rb_hash_update_func *func) |
Destructively merges two hash tables into one. More... | |
int | rb_path_check (const char *path) |
This function is mysterious. More... | |
VALUE | rb_env_clear (void) |
Destructively removes every environment variables of the running process. More... | |
VALUE | rb_hash_size (VALUE hash) |
Identical to RHASH_SIZE(), except it returns the size in Ruby's integer instead of C's. More... | |
Public APIs related to rb_cHash.
RBIMPL
or rbimpl
are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will. __VA_ARGS__
is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98. Definition in file hash.h.
#define st_foreach_safe rb_st_foreach_safe |
Just another name of rb_st_foreach_safe.
Type of callback functions to pass to rb_hash_update_by().
[in] | newkey | A key of the table. |
[in] | oldkey | Value associated with key in hash1. |
[in] | value | Value associated with key in hash2. |
Try converting an object to its hash representation using its to_hash
method, if any.
If there is no such thing, returns RUBY_Qnil.
[in] | obj | Arbitrary ruby object to convert. |
rb_eTypeError | obj.to_hash returned something non-Hash. |
RUBY_Qnil | No conversion from obj to hash defined. |
otherwise | Converted hash representation of obj . |
Definition at line 1864 of file hash.c.
Referenced by rb_econv_prepare_options(), and rb_Hash().
VALUE rb_env_clear | ( | void | ) |
Calculates a message authentication code of the passed object.
The return value is a very small integer used as an index of a key of a table. In order to calculate the value this function calls #hash
method of the passed object. Ruby provides you a default implementation. But if you implement your class in C, that default implementation cannot know the underlying data structure. You must implement your own #hash
method then, which must return an integer of uniform distribution in a sufficiently instant manner.
[in] | obj | Arbitrary Ruby object. |
rb_eTypeError | obj.hash returned something non-Integer. |
#hash
can return very big integers, but they get truncated. Queries the given key in the given hash table.
If there is the key in the hash, returns the value associated with the key. Otherwise it returns the "default" value (defined per hash table).
[in] | hash | Hash table to look into. |
[in] | key | Hash key to look for. |
Definition at line 2073 of file hash.c.
Referenced by rb_econv_open_opts(), rb_econv_prepare_options(), and rb_io_extract_modeenc().
Inserts or replaces ("upsert"s) the objects into the given hash table.
This basically associates the given value with the given key. On duplicate key this function updates its associated value with the given one. Otherwise it inserts the association at the end of the table.
[out] | hash | Target hash table to modify. |
[in] | key | Arbitrary Ruby object. |
[in] | val | A value to be associated with key . |
rb_eFrozenError | hash is frozen. |
val
val
is associated with key
in hash
. Definition at line 2893 of file hash.c.
Referenced by rb_econv_prepare_options().
Inserts a list of key-value pairs into a hash table at once.
It is semantically identical to repeatedly calling rb_hash_aset(), but can be faster than that.
[in] | argc | Length of argv , must be even. |
[in] | argv | A list of key, value, key, value, ... |
[out] | hash | Target hash table to modify. |
hash
has contents from argv
. argv
is allowed to be NULL as long as argc
is zero. Deletes each entry for which the block returns a truthy value.
If there is no block given, it returns an enumerator that does the thing.
[out] | hash | Target hash to modify. |
rb_eFrozenError | hash is frozen. |
hash | The hash is modified. |
otherwise | An instance of rb_cEnumerator that does it. |
Identical to rb_hash_lookup(), except it yields the (implicitly) passed block instead of returning RUBY_Qnil.
[in] | hash | Hash table to look into. |
[in] | key | Hash key to look for. |
rb_eKeyError | No block given. |
Iterates over a hash.
This basically does the same thing as rb_st_foreach(). But because the passed hash is a Ruby object, its keys and values are both Ruby objects.
[in] | hash | An instance of rb_cHash to iterate over. |
[in] | func | Callback function to yield. |
[in] | arg | Passed as-is to func . |
rb_eRuntimeError | hash was tampered during iterating. |
Referenced by rb_extract_keywords(), rb_hash_clear(), rb_hash_delete_if(), rb_hash_update_by(), and rb_tracepoint_disable().
Just another name of rb_obj_freeze.
Definition at line 108 of file hash.c.
Referenced by rb_econv_prepare_options().
Identical to rb_hash_aref(), except it always returns RUBY_Qnil for misshits.
[in] | hash | Hash table to look into. |
[in] | key | Hash key to look for. |
Definition at line 2099 of file hash.c.
Referenced by rb_ext_resolve_symbol().
Identical to rb_hash_lookup(), except you can specify what to return on misshits.
This is much like 2-arguments version of Hash#fetch
.
[in] | hash | Hash table to look into. |
[in] | key | Hash key to look for. |
[in] | def | Default value. |
def | hash does not have key . |
otherwise | The value associated with key . |
Definition at line 2086 of file hash.c.
Referenced by rb_hash_lookup(), rb_io_extract_encoding_option(), and rb_str_format().
VALUE rb_hash_new | ( | void | ) |
Creates a new, empty hash object.
Definition at line 1475 of file hash.c.
Referenced by rb_econv_prepare_options(), and rb_Hash().
VALUE rb_hash_new_capa | ( | long | capa | ) |
Identical to rb_hash_new(), except it additionally specifies how many keys it is expected to contain.
This way you can create a hash that is large enough for your need. For large hashes it means it won't need to be reallocated and rehashed as much, improving performance.
[in] | capa | Designed capacity of the hash. |
capa
. Identical to RHASH_SIZE(), except it returns the size in Ruby's integer instead of C's.
[in] | hash | A hash object. |
VALUE rb_hash_update_by | ( | VALUE | hash1, |
VALUE | hash2, | ||
rb_hash_update_func * | func | ||
) |
Destructively merges two hash tables into one.
It resolves key conflicts by calling the passed function and take its return value.
[out] | hash1 | Target hash to be modified. |
[in] | hash2 | A hash to merge into hash1 . |
[in] | func | Conflict reconciler. |
rb_eFrozenError | hash1 is frozen. |
rb_eRuntimeError | hash2 is updated instead. |
hash1
. hash2
is merged into hash1
. func
. This means values from hash2
are always taken. int rb_path_check | ( | const char * | path | ) |
void rb_st_foreach_safe | ( | struct st_table * | st, |
st_foreach_callback_func * | func, | ||
st_data_t | arg | ||
) |
Identical to rb_st_foreach(), except it raises exceptions when the callback function tampers the table during iterating over it.
[in] | st | Table to iterate over. |
[in] | func | Callback function to apply. |
[in] | arg | Passed as-is to func . |
rb_eRuntimeError | st was tampered during iterating. |