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

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

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 1943 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 5943 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 231 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 2143 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 2969 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 4815 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 2894 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 2423 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 2586 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 1632 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 2234 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 89 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 2169 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:1940
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 2156 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 1570 of file hash.c.

## ◆ 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 1601 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 3041 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 4072 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 6306 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.