Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Macros | Typedefs | Functions
hash.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

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"
Include dependency graph for hash.h:
This graph shows which files directly or indirectly include this file:

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...
 

Detailed Description

Public APIs related to rb_cHash.

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
Warning
Symbols prefixed with either 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.
Note
To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __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.

Macro Definition Documentation

◆ st_foreach_safe

#define st_foreach_safe   rb_st_foreach_safe

Just another name of rb_st_foreach_safe.

Definition at line 51 of file hash.h.

Typedef Documentation

◆ rb_hash_update_func

typedef VALUE rb_hash_update_func(VALUE newkey, VALUE oldkey, VALUE value)

Type of callback functions to pass to rb_hash_update_by().

Parameters
[in]newkeyA key of the table.
[in]oldkeyValue associated with key in hash1.
[in]valueValue associated with key in hash2.
Returns
Either one of the passed values to take.

Definition at line 269 of file hash.h.

Function Documentation

◆ rb_check_hash_type()

VALUE rb_check_hash_type ( VALUE  obj)

Try converting an object to its hash representation using its to_hash method, if any.

If there is no such thing, returns RUBY_Qnil.

Parameters
[in]objArbitrary ruby object to convert.
Exceptions
rb_eTypeErrorobj.to_hash returned something non-Hash.
Return values
RUBY_QnilNo conversion from obj to hash defined.
otherwiseConverted hash representation of obj.
See also
rb_io_check_io
rb_check_array_type
rb_check_string_type

Definition at line 1864 of file hash.c.

Referenced by rb_econv_prepare_options(), and rb_Hash().

◆ rb_env_clear()

VALUE rb_env_clear ( void  )

Destructively removes every environment variables of the running process.

Returns
The ENV object.
Postcondition
The process has no environment variables.

Definition at line 5825 of file hash.c.

◆ rb_hash()

VALUE rb_hash ( VALUE  obj)

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.

Parameters
[in]objArbitrary Ruby object.
Exceptions
rb_eTypeErrorobj.hash returned something non-Integer.
Returns
A small integer.
Note
#hash can return very big integers, but they get truncated.

Definition at line 267 of file hash.c.

◆ rb_hash_aref()

VALUE rb_hash_aref ( VALUE  hash,
VALUE  key 
)

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).

Parameters
[in]hashHash table to look into.
[in]keyHash key to look for.
Returns
Either the value associated with the key, or the default one if absent.

Definition at line 2073 of file hash.c.

Referenced by rb_econv_open_opts(), rb_econv_prepare_options(), and rb_io_extract_modeenc().

◆ rb_hash_aset()

VALUE rb_hash_aset ( VALUE  hash,
VALUE  key,
VALUE  val 
)

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.

Parameters
[out]hashTarget hash table to modify.
[in]keyArbitrary Ruby object.
[in]valA value to be associated with key.
Exceptions
rb_eFrozenErrorhash is frozen.
Returns
The passed val
Postcondition
val is associated with key in hash.

Definition at line 2893 of file hash.c.

Referenced by rb_econv_prepare_options().

◆ rb_hash_bulk_insert()

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.

It is semantically identical to repeatedly calling rb_hash_aset(), but can be faster than that.

Parameters
[in]argcLength of argv, must be even.
[in]argvA list of key, value, key, value, ...
[out]hashTarget hash table to modify.
Postcondition
hash has contents from argv.
Note
argv is allowed to be NULL as long as argc is zero.

Definition at line 4766 of file hash.c.

◆ rb_hash_clear()

VALUE rb_hash_clear ( VALUE  hash)

Swipes everything out of the passed hash table.

Parameters
[out]hashTarget to clear.
Exceptions
rb_eFrozenErrorhashis frozen.
Returns
The passed hash
Postcondition
hash has no contents.

Definition at line 2820 of file hash.c.

◆ rb_hash_delete()

VALUE rb_hash_delete ( VALUE  hash,
VALUE  key 
)

Deletes the passed key from the passed hash table, if any.

Parameters
[out]hashTarget hash to modify.
[in]keyKey to delete.
Return values
RUBY_Qnilhash has no such key as key.
otherwiseWhat was associated with key.
Postcondition
hash has no such key as key.

Definition at line 2353 of file hash.c.

◆ rb_hash_delete_if()

VALUE rb_hash_delete_if ( VALUE  hash)

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.

Parameters
[out]hashTarget hash to modify.
Exceptions
rb_eFrozenErrorhash is frozen.
Return values
hashThe hash is modified.
otherwiseAn instance of rb_cEnumerator that does it.

Definition at line 2516 of file hash.c.

◆ rb_hash_dup()

VALUE rb_hash_dup ( VALUE  hash)

Duplicates a hash.

Parameters
[in]hashAn instance of rb_cHash.
Returns
An allocated new instance of rb_cHash, whose contents are a verbatim copy of from hash.

Definition at line 1563 of file hash.c.

◆ rb_hash_fetch()

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.

Parameters
[in]hashHash table to look into.
[in]keyHash key to look for.
Exceptions
rb_eKeyErrorNo block given.
Returns
Either the value associated with the key, or what the block evaluates to if absent.

Definition at line 2164 of file hash.c.

◆ rb_hash_foreach()

void rb_hash_foreach ( VALUE  hash,
int(*)(VALUE key, VALUE val, VALUE arg)  func,
VALUE  arg 
)

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.

Parameters
[in]hashAn instance of rb_cHash to iterate over.
[in]funcCallback function to yield.
[in]argPassed as-is to func.
Exceptions
rb_eRuntimeErrorhash was tampered during iterating.

Referenced by rb_extract_keywords(), rb_hash_clear(), rb_hash_delete_if(), rb_hash_update_by(), and rb_tracepoint_disable().

◆ rb_hash_freeze()

VALUE rb_hash_freeze ( VALUE  obj)

Just another name of rb_obj_freeze.

Definition at line 108 of file hash.c.

Referenced by rb_econv_prepare_options().

◆ rb_hash_lookup()

VALUE rb_hash_lookup ( VALUE  hash,
VALUE  key 
)

Identical to rb_hash_aref(), except it always returns RUBY_Qnil for misshits.

Parameters
[in]hashHash table to look into.
[in]keyHash key to look for.
Returns
Either the value associated with the key, or RUBY_Qnil if absent.
Note
A hash can store RUBY_Qnil as an ordinary value. You cannot distinguish whether the key is missing, or just its associated value happens to be RUBY_Qnil, as far as you use this API.

Definition at line 2099 of file hash.c.

Referenced by rb_ext_resolve_symbol().

◆ rb_hash_lookup2()

VALUE rb_hash_lookup2 ( VALUE  hash,
VALUE  key,
VALUE  def 
)

Identical to rb_hash_lookup(), except you can specify what to return on misshits.

This is much like 2-arguments version of Hash#fetch.

VALUE hash;
VALUE key;
VALUE tmp = rb_obj_alloc(rb_cObject);
VALUE val = rb_hash_lookup2(hash, key, tmp);
if (val == tmp) {
printf("misshit");
}
else {
printf("hit");
}
VALUE rb_obj_alloc(VALUE klass)
Allocates an instance of the given class.
Definition: object.c:2093
VALUE rb_hash_lookup2(VALUE hash, VALUE key, VALUE def)
Identical to rb_hash_lookup(), except you can specify what to return on misshits.
Definition: hash.c:2086
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40
Parameters
[in]hashHash table to look into.
[in]keyHash key to look for.
[in]defDefault value.
Return values
defhash does not have key.
otherwiseThe 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().

◆ rb_hash_new()

VALUE rb_hash_new ( void  )

Creates a new, empty hash object.

Returns
An allocated new instance of rb_cHash.

Definition at line 1475 of file hash.c.

Referenced by rb_econv_prepare_options(), and rb_Hash().

◆ rb_hash_new_capa()

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.

Parameters
[in]capaDesigned capacity of the hash.
Returns
An empty Hash, whose capacity is capa.

Definition at line 1503 of file hash.c.

◆ rb_hash_size()

VALUE rb_hash_size ( VALUE  hash)

Identical to RHASH_SIZE(), except it returns the size in Ruby's integer instead of C's.

Parameters
[in]hashA hash object.
Returns
The size of the hash.

Definition at line 2954 of file hash.c.

◆ rb_hash_update_by()

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.

Parameters
[out]hash1Target hash to be modified.
[in]hash2A hash to merge into hash1.
[in]funcConflict reconciler.
Exceptions
rb_eFrozenErrorhash1 is frozen.
rb_eRuntimeErrorhash2 is updated instead.
Returns
The passed hash1.
Postcondition
Contents of hash2 is merged into hash1.
Note
You can pass zero to func. This means values from hash2 are always taken.

Definition at line 4021 of file hash.c.

◆ rb_path_check()

int rb_path_check ( const char *  path)

This function is mysterious.

What it does is not immediately obvious. Also what it does seems platform dependent.

Parameters
[in]pathA local path.
Return values
0The "check" succeeded.
otherwiseThe "check" failed.

Definition at line 6427 of file file.c.

◆ rb_st_foreach_safe()

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.

Parameters
[in]stTable to iterate over.
[in]funcCallback function to apply.
[in]argPassed as-is to func.
Exceptions
rb_eRuntimeErrorst was tampered during iterating.