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"

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.
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 1876 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 6150 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 263 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 2091 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 2952 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 5115 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 hashis frozen.

Returns: The passed hash

Postcondition: hash has no contents.

Definition at line 2874 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 2377 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 2549 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 1572 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 2185 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 104 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 2117 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");
}

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 2104 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 1484 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 1512 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 3024 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 4300 of file hash.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().

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ st_foreach_safe

Typedef Documentation

◆ rb_hash_update_func

Function Documentation

◆ rb_check_hash_type()

◆ rb_env_clear()

◆ rb_hash()

◆ rb_hash_aref()

◆ rb_hash_aset()

◆ rb_hash_bulk_insert()

◆ rb_hash_clear()

◆ rb_hash_delete()

◆ rb_hash_delete_if()

◆ rb_hash_dup()

◆ rb_hash_fetch()

◆ rb_hash_foreach()

◆ rb_hash_freeze()

◆ rb_hash_lookup()

◆ rb_hash_lookup2()

◆ rb_hash_new()

◆ rb_hash_new_capa()

◆ rb_hash_size()

◆ rb_hash_update_by()

◆ rb_st_foreach_safe()