Ruby: include/ruby/internal/intern/hash.h File Reference

Ruby 3.4.5p51 (2025-07-16 revision 20cda200d3ce092571d0b5d342dadca69636cb0f)

Macros | Typedefs | Functions
hash.h File Reference

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.

## Typedefs
typedef VALUE | rb_hash_update_func(VALUE newkey, VALUE oldkey, VALUE value)
| Type of callback functions to pass to rb_hash_update_by().

## 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.
VALUE | rb_check_hash_type (VALUE obj)
| Try converting an object to its hash representation using its to_hash method, if any.
void | rb_hash_foreach (VALUE hash, int(*func)(VALUE key, VALUE val, VALUE arg), VALUE arg)
| Iterates over a hash.
VALUE | rb_hash (VALUE obj)
| Calculates a message authentication code of the passed object.
VALUE | rb_hash_new (void)
| Creates a new, empty hash object.
VALUE | rb_hash_new_capa (long capa)
| Identical to rb_hash_new(), except it additionally specifies how many keys it is expected to contain.
VALUE | rb_hash_dup (VALUE hash)
| Duplicates a hash.
VALUE | rb_hash_freeze (VALUE obj)
| Just another name of rb_obj_freeze.
VALUE | rb_hash_aref (VALUE hash, VALUE key)
| Queries the given key in the given hash table.
VALUE | rb_hash_lookup (VALUE hash, VALUE key)
| Identical to rb_hash_aref(), except it always returns RUBY_Qnil for misshits.
VALUE | rb_hash_lookup2 (VALUE hash, VALUE key, VALUE def)
| Identical to rb_hash_lookup(), except you can specify what to return on misshits.
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.
VALUE | rb_hash_aset (VALUE hash, VALUE key, VALUE val)
| Inserts or replaces ("upsert"s) the objects into the given hash table.
VALUE | rb_hash_clear (VALUE hash)
| Swipes everything out of the passed hash table.
VALUE | rb_hash_delete_if (VALUE hash)
| Deletes each entry for which the block returns a truthy value.
VALUE | rb_hash_delete (VALUE hash, VALUE key)
| Deletes the passed key from the passed hash table, if any.
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.
VALUE | rb_hash_update_by (VALUE hash1, VALUE hash2, rb_hash_update_func *func)
| Destructively merges two hash tables into one.
int | rb_path_check (const char *path)
| This function is mysterious.
VALUE | rb_env_clear (void)
| Destructively removes every environment variables of the running process.
VALUE | rb_hash_size (VALUE hash)
| Identical to RHASH_SIZE(), except it returns the size in Ruby's integer instead of C's.

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

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

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.

Referenced by rb_const_list(), and ruby::backward::cxxanyargs::st_foreach_safe().

## 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] | newkey | A key of the table.
  [in] | oldkey | Value associated with key in hash1.
  [in] | value | Value 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] | obj | Arbitrary ruby object to convert.

Exceptions

  rb_eTypeError | `obj.to_hash` returned something non-Hash.

Return values

  RUBY_Qnil | No conversion from obj to hash defined.
  otherwise | Converted hash representation of obj.

See also
  rb_io_check_io
  rb_check_array_type
  rb_check_string_type

Definition at line 1866 of file hash.c.

## ◆ 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 5878 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] | obj | Arbitrary Ruby object.

Exceptions

  rb_eTypeError | `obj.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] | hash | Hash table to look into.
  [in] | key | Hash key to look for.

Returns
  Either the value associated with the key, or the default one if absent.

Definition at line 2075 of file hash.c.

## ◆ 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] | hash | Target hash table to modify.
  [in] | key | Arbitrary Ruby object.
  [in] | val | A value to be associated with key.

Exceptions

  rb_eFrozenError | `hash` is frozen.

Returns
  The passed val

Postcondition
  val is associated with key in hash.

Definition at line 2895 of file hash.c.

## ◆ 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] | argc | Length of argv, must be even.
  [in] | argv | A list of key, value, key, value, ...
  [out] | hash | Target 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 4819 of file hash.c.

## ◆ rb_hash_clear()

VALUE rb_hash_clear | ( | VALUE | hash | ) |

Swipes everything out of the passed hash table.

Parameters

  [out] | hash | Target to clear.

Exceptions

  rb_eFrozenError | `hash`is frozen.

Returns
  The passed hash

Postcondition
  hash has no contents.

Definition at line 2822 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] | hash | Target hash to modify.
  [in] | key | Key to delete.

Return values

  RUBY_Qnil | hash has no such key as key.
  otherwise | What was associated with key.

Postcondition
  hash has no such key as key.

Definition at line 2355 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] | hash | Target hash to modify.

Exceptions

  rb_eFrozenError | `hash` is frozen.

Return values

  hash | The hash is modified.
  otherwise | An instance of rb_cEnumerator that does it.

Definition at line 2518 of file hash.c.

## ◆ rb_hash_dup()

VALUE rb_hash_dup | ( | VALUE | hash | ) |

Duplicates a hash.

Parameters

  [in] | hash | An instance of rb_cHash.

Returns
  An allocated new instance of rb_cHash, whose contents are a verbatim copy of from hash.

Definition at line 1565 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] | hash | Hash table to look into.
  [in] | key | Hash key to look for.

Exceptions

  rb_eKeyError | No block given.

Returns
  Either the value associated with the key, or what the block evaluates to if absent.

Definition at line 2166 of file hash.c.

## ◆ rb_hash_foreach()

void rb_hash_foreach | ( | VALUE | hash,
|  | int(* | func )(VALUE key, VALUE val, VALUE arg),
|  | 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] | hash | An instance of rb_cHash to iterate over.
  [in] | func | Callback function to yield.
  [in] | arg | Passed as-is to func.

Exceptions

  rb_eRuntimeError | `hash` was tampered during iterating.

## ◆ rb_hash_freeze()

VALUE rb_hash_freeze | ( | VALUE | obj | ) |

Just another name of rb_obj_freeze.

Definition at line 108 of file hash.c.

## ◆ 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] | hash | Hash table to look into.
  [in] | key | Hash 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 2101 of file hash.c.

## ◆ 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");
}
rb_obj_alloc
VALUE rb_obj_alloc(VALUE klass)
Allocates an instance of the given class.
Definition object.c:2097
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.
Definition hash.c:2088
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

Parameters

  [in] | hash | Hash table to look into.
  [in] | key | Hash key to look for.
  [in] | def | Default value.

Return values

  def | hash does not have key.
  otherwise | The value associated with key.

Definition at line 2088 of file hash.c.

## ◆ 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 1477 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] | capa | Designed capacity of the hash.

Returns
  An empty Hash, whose capacity is capa.

Definition at line 1505 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] | hash | A hash object.

Returns
  The size of the hash.

Definition at line 2956 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] | hash1 | Target hash to be modified.
  [in] | hash2 | A hash to merge into hash1.
  [in] | func | Conflict reconciler.

Exceptions

  rb_eFrozenError | `hash1` is frozen.
  rb_eRuntimeError | `hash2` 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 4074 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] | path | A local path.

Return values

  0 | The "check" succeeded.
  otherwise | The "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] | st | Table to iterate over.
  [in] | func | Callback function to apply.
  [in] | arg | Passed as-is to func.

Exceptions

  rb_eRuntimeError | `st` was tampered during iterating.

Referenced by rb_st_foreach_safe().