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

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

Macros | Functions
object.h File Reference

Public APIs related to rb_cObject. More...

`#include "ruby/internal/attr/const.h"`
`#include "ruby/internal/attr/deprecated.h"`
`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Macros
#define | RB_OBJ_INIT_COPY(obj, orig)
| This macro is (used but) mysterious.
#define | OBJ_INIT_COPY(obj, orig)
| Old name of RB_OBJ_INIT_COPY.

## Functions
VALUE | rb_class_new_instance_pass_kw (int argc, const VALUE *argv, VALUE klass)
| Identical to rb_class_new_instance(), except it passes the passed keywords if any to the `#initialize` method.
VALUE | rb_class_new_instance (int argc, const VALUE *argv, VALUE klass)
| Allocates, then initialises an instance of the given class.
VALUE | rb_class_new_instance_kw (int argc, const VALUE *argv, VALUE klass, int kw_splat)
| Identical to rb_class_new_instance(), except you can specify how to handle the last element of the given array.
int | rb_eql (VALUE lhs, VALUE rhs)
| Checks for equality of the passed objects, in terms of `Object#eql?`.
VALUE | rb_any_to_s (VALUE obj)
| Generates a textual representation of the given object.
VALUE | rb_inspect (VALUE obj)
| Generates a human-readable textual representation of the given object.
VALUE | rb_obj_is_instance_of (VALUE obj, VALUE klass)
| Queries if the given object is a direct instance of the given class.
VALUE | rb_obj_is_kind_of (VALUE obj, VALUE klass)
| Queries if the given object is an instance (of possibly descendants) of the given class.
VALUE | rb_obj_alloc (VALUE klass)
| Allocates an instance of the given class.
VALUE | rb_obj_clone (VALUE obj)
| Produces a shallow copy of the given object.
VALUE | rb_obj_dup (VALUE obj)
| Duplicates the given object.
VALUE | rb_obj_init_copy (VALUE src, VALUE dst)
| Default implementation of `#initialize_copy`, `#initialize_dup` and `#initialize_clone`.
VALUE | rb_obj_freeze (VALUE obj)
| Just calls rb_obj_freeze_inline() inside.
VALUE | rb_obj_frozen_p (VALUE obj)
| Just calls RB_OBJ_FROZEN() inside.
VALUE | rb_obj_id (VALUE obj)
| Finds or creates an integer primary key of the given object.
VALUE | rb_memory_id (VALUE obj)
| Identical to rb_obj_id(), except it hesitates from allocating a new instance of rb_cInteger.
VALUE | rb_class_real (VALUE klass)
| Finds a "real" class.
VALUE | rb_class_inherited_p (VALUE scion, VALUE ascendant)
| Determines if the given two modules are relatives.
VALUE | rb_class_superclass (VALUE klass)
| Queries the parent of the given class.
VALUE | rb_convert_type (VALUE val, int type, const char *name, const char *mid)
| Converts an object into another type.
VALUE | rb_check_convert_type (VALUE val, int type, const char *name, const char *mid)
| Identical to rb_convert_type(), except it returns RUBY_Qnil instead of raising exceptions, in case of conversion failure.
VALUE | rb_check_to_integer (VALUE val, const char *mid)
| Identical to rb_check_convert_type(), except the return value type is fixed to rb_cInteger.
VALUE | rb_check_to_float (VALUE val)
| This is complicated.
VALUE | rb_to_int (VALUE val)
| Identical to rb_check_to_int(), except it raises in case of conversion mismatch.
VALUE | rb_check_to_int (VALUE val)
| Identical to rb_check_to_integer(), except it uses `#to_int` for conversion.
VALUE | rb_Integer (VALUE val)
| This is the logic behind `Kernel#Integer`.
VALUE | rb_to_float (VALUE val)
| Identical to rb_check_to_float(), except it raises on error.
VALUE | rb_Float (VALUE val)
| This is the logic behind `Kernel#Float`.
VALUE | rb_String (VALUE val)
| This is the logic behind `Kernel#String`.
VALUE | rb_Array (VALUE val)
| This is the logic behind `Kernel#Array`.
VALUE | rb_Hash (VALUE val)
| This is the logic behind `Kernel#Hash`.
double | rb_cstr_to_dbl (const char *str, int mode)
| Converts a textual representation of a real number into a numeric, which is the nearest value that the return type can represent, of the value that the argument represents.
double | rb_str_to_dbl (VALUE str, int mode)
| Identical to rb_cstr_to_dbl(), except it accepts a Ruby's string instead of C's.

## Detailed Description

Public APIs related to rb_cObject.

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

## Macro Definition Documentation

## ◆ RB_OBJ_INIT_COPY

#define RB_OBJ_INIT_COPY | ( |  | obj,
|  |  | orig )

Value:
((obj) != (orig) && (rb_obj_init_copy((obj), (orig)), 1))
rb_obj_init_copy
VALUE rb_obj_init_copy(VALUE src, VALUE dst)
Default implementation of #initialize_copy, #initialize_dup and #initialize_clone.
Definition object.c:537

This macro is (used but) mysterious.

Why on earth do we need this?

- `obj != orig` check is done anyways inside of rb_obj_init_copy().
- rb_obj_init_copy() returns something. No need are there to add `, 1`.

Definition at line 38 of file object.h.

## Function Documentation

## ◆ rb_memory_id()

VALUE rb_memory_id | ( | VALUE | obj | ) |

Identical to rb_obj_id(), except it hesitates from allocating a new instance of rb_cInteger.

rb_obj_id() could allocate RUBY_T_BIGNUM objects. That allocation might perhaps impact negatively. On such situations, this function instead returns one-shot temporary small integers that need no allocations at all. The values are guaranteed unique at the moment, but no future promise is made; could be reused. Use of this API should be very instant. It is a failure to store the returned integer to somewhere else.

In short it is difficult to use.

Parameters

  [in] | obj | Arbitrary ruby object.

Returns
  An instance of rb_cInteger unique at the moment.

Definition at line 4795 of file gc.c.

## ◆ rb_obj_id()

VALUE rb_obj_id | ( | VALUE | obj | ) |

Finds or creates an integer primary key of the given object.

In the old days this function was a purely arithmetic operation that maps the underlying memory address where the object resides into a Ruby's integer. Some time around 2.x this changed. It no longer relates its return values to C level pointers. This function assigns some random number to the given object if absent. The same number will be returned on all subsequent requests. No two active objects share a number.

Parameters

  [in] | obj | Arbitrary ruby object.

Returns
  An instance of rb_cInteger which is an "identifier" of `obj`.

Definition at line 4828 of file gc.c.