Ruby: include/ruby/internal/core/rhash.h File Reference

Ruby 3.3.5p100 (2024-09-03 revision ef084cc8f4958c1b6e4ead99136631bef6d8ddba)

Macros | Functions
rhash.h File Reference

Routines to manipulate struct RHash. More...

`#include "ruby/internal/config.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/backward.h"`

Go to the source code of this file.

## Macros
#define | RHASH_TBL(h)
| Retrieves the internal table.
#define | RHASH_IFNONE(h)
#define | RHASH_SIZE(h)
| Queries the size of the hash.
#define | RHASH_EMPTY_P(h)
| Checks if the hash is empty.
#define | RHASH_SET_IFNONE(h, ifnone)
| Destructively updates the default value of the hash.

## Functions
size_t | rb_hash_size_num (VALUE hash)
| This is the implementation detail of RHASH_SIZE.
struct st_table * | rb_hash_tbl (VALUE hash, const char *file, int line)
| This is the implementation detail of RHASH_TBL.
VALUE | rb_hash_set_ifnone (VALUE hash, VALUE ifnone)
| This is the implementation detail of RHASH_SET_IFNONE.

## Detailed Description

Routines to manipulate struct RHash.

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.
  The struct RHash itself is opaque.

Definition in file rhash.h.

## Macro Definition Documentation

## ◆ RHASH_EMPTY_P

#define RHASH_EMPTY_P | ( |  | h | ) |

Value:
(RHASH_SIZE(h) == 0)
RHASH_SIZE
#define RHASH_SIZE(h)
Queries the size of the hash.
Definition rhash.h:69

Checks if the hash is empty.

Parameters

  [in] | h | An instance of RHash.

Precondition
  `h` must be of RUBY_T_HASH.

Return values

  true | It is.
  false | It isn't.

Definition at line 79 of file rhash.h.

Referenced by rb_extract_keywords().

## ◆ RHASH_IFNONE

#define RHASH_IFNONE | ( |  | h | ) |

Value:
rb_hash_ifnone(h)

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 59 of file rhash.h.

## ◆ RHASH_SET_IFNONE

#define RHASH_SET_IFNONE | ( |  | h,
|  |  | ifnone )

Value:
rb_hash_set_ifnone((VALUE)h, ifnone)
rb_hash_set_ifnone
VALUE rb_hash_set_ifnone(VALUE hash, VALUE ifnone)
This is the implementation detail of RHASH_SET_IFNONE.
Definition hash.c:119
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

Destructively updates the default value of the hash.

Parameters

  [out] | h | An instance of RHash.
  [in] | ifnone | Arbitrary default value.

Precondition
  `h` must be of RUBY_T_HASH.

Definition at line 92 of file rhash.h.

## ◆ RHASH_SIZE

#define RHASH_SIZE | ( |  | h | ) |

Value:
rb_hash_size_num(h)
rb_hash_size_num
size_t rb_hash_size_num(VALUE hash)
This is the implementation detail of RHASH_SIZE.
Definition hash.c:2974

Queries the size of the hash.

Size here means the number of keys that the hash stores.

Parameters

  [in] | h | An instance of RHash.

Precondition
  `h` must be of RUBY_T_HASH.

Returns
  The size of the hash.

Definition at line 69 of file rhash.h.

Referenced by rb_get_kwargs(), rb_hash_size(), and rb_hash_size_num().

## ◆ RHASH_TBL

#define RHASH_TBL | ( |  | h | ) |

Value:
rb_hash_tbl(h, __FILE__, __LINE__)
rb_hash_tbl
struct st_table * rb_hash_tbl(VALUE hash, const char *file, int line)
This is the implementation detail of RHASH_TBL.
Definition hash.c:1580

Retrieves the internal table.

Parameters

  [in] | h | An instance of RHash.

Precondition
  `h` must be of RUBY_T_HASH.

Returns
  A struct st_table which has the contents of this hash.

Note
  Nowadays as Ruby evolved over ages, RHash has multiple backend storage engines. `h`'s backend is not guaranteed to be a st_table. This function creates one when necessary.

Definition at line 46 of file rhash.h.

## Function Documentation

## ◆ rb_hash_set_ifnone()

VALUE rb_hash_set_ifnone | ( | VALUE | hash,
|  | VALUE | ifnone )

This is the implementation detail of RHASH_SET_IFNONE.

People don't call this directly.

Parameters

  [out] | hash | An instance of RHash.
  [in] | ifnone | Arbitrary default value.

Precondition
  `hash` must be of RUBY_T_HASH.

Definition at line 119 of file hash.c.

## ◆ rb_hash_size_num()

size_t rb_hash_size_num | ( | VALUE | hash | ) |

This is the implementation detail of RHASH_SIZE.

People don't call this directly.

Parameters

  [in] | hash | An instance of RHash.

Precondition
  `hash` must be of RUBY_T_HASH.

Returns
  The size of the hash.

Definition at line 2974 of file hash.c.

## ◆ rb_hash_tbl()

struct st_table * rb_hash_tbl | ( | VALUE | hash,
|  | const char * | file,
|  | int | line )

This is the implementation detail of RHASH_TBL.

People don't call this directly.

Parameters

  [in] | hash | An instance of RHash.
  [in] | file | The `__FILE__`.
  [in] | line | The `__LINE__`.

Precondition
  `hash` must be of RUBY_T_HASH.

Returns
  Table that has the contents of the hash.

Definition at line 1580 of file hash.c.