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

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

Data Structures | Macros | Enumerations | Functions
rarray.h File Reference

Defines struct RArray. More...

`#include "ruby/internal/arithmetic/long.h"`
`#include "ruby/internal/attr/artificial.h"`
`#include "ruby/internal/attr/constexpr.h"`
`#include "ruby/internal/attr/maybe_unused.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/cast.h"`
`#include "ruby/internal/core/rbasic.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/fl_type.h"`
`#include "ruby/internal/rgengc.h"`
`#include "ruby/internal/stdbool.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/internal/value_type.h"`
`#include "ruby/assert.h"`

Go to the source code of this file.

## Data Structures
struct | RArray
| Ruby's array. More...

## Macros
#define | USE_TRANSIENT_HEAP 1
#define | RARRAY(obj)
| Convenient casting macro.
#define | RARRAY_LEN rb_array_len
| Just another name of rb_array_len.
#define | RARRAY_CONST_PTR rb_array_const_ptr
| Just another name of rb_array_const_ptr.
#define | RARRAY_CONST_PTR_TRANSIENT rb_array_const_ptr_transient
| Just another name of rb_array_const_ptr_transient.
#define | RBIMPL_RARRAY_STMT(flag, ary, var, expr)
| This is an implementation detail of RARRAY_PTR_USE.
#define | RARRAY_PTR_USE_END(a)
| This is an implementation detail of RARRAY_PTR_USE.
#define | RARRAY_PTR_USE(ary, ptr_name, expr)
| Declares a section of code where raw pointers are used.
#define | RARRAY_PTR_USE_TRANSIENT(ary, ptr_name, expr)
| Identical to RARRAY_PTR_USE, except the pointer can be a transient one.
#define | RARRAY_AREF(a, i)

## Enumerations
enum | ruby_rarray_consts { RARRAY_EMBED_LEN_SHIFT = RUBY_FL_USHIFT + 3 , RARRAY_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(VALUE) }
| This is an enum because GDB wants it (rather than a macro). More...

## Functions
static long | RARRAY_EMBED_LEN (VALUE ary)
| Queries the length of the array.
static long | rb_array_len (VALUE a)
| Queries the length of the array.
static int | RARRAY_LENINT (VALUE ary)
| Identical to rb_array_len(), except it differs for the return type.
static bool | RARRAY_TRANSIENT_P (VALUE ary)
| Queries if the array is a transient array.
static VALUE * | RARRAY_PTR (VALUE ary)
| Wild use of a C pointer.
static void | RARRAY_ASET (VALUE ary, long i, VALUE v)
| Assigns an object in an array.

## Detailed Description

Defines struct RArray.

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

## Macro Definition Documentation

## ◆ RARRAY

#define RARRAY | ( |  | obj | ) |

Value:
RBIMPL_CAST((struct RArray *)(obj))
RArray
Ruby's array.
Definition rarray.h:176

Convenient casting macro.

Parameters

  obj | An object, which is in fact an RArray.

Returns
  The passed object casted to RArray.

Definition at line 56 of file rarray.h.

Referenced by rb_array_len().

## ◆ RARRAY_AREF

#define RARRAY_AREF | ( |  | a,
|  |  | i )

Value:
RARRAY_CONST_PTR_TRANSIENT(a)[i]
RARRAY_CONST_PTR_TRANSIENT
#define RARRAY_CONST_PTR_TRANSIENT
Just another name of rb_array_const_ptr_transient.
Definition rarray.h:70

Deprecated

:FIXME: we want to convert RARRAY_AREF into an inline function (to add rooms for more sanity checks). However there were situations where the address of this macro is taken i.e. &RARRAY_AREF(...). They cannot be possible if this is not a macro. Such usages are abuse, and we eliminated them internally. However we are afraid of similar things to remain in the wild. This macro remains as it is due to that. If we could warn such usages we can set a transition path, but currently no way is found to do so.

Definition at line 583 of file rarray.h.

Referenced by rb_ary_assoc(), rb_ary_delete(), rb_ary_delete_at(), rb_ary_each(), rb_ary_includes(), rb_ary_join(), rb_ary_pop(), rb_ary_rassoc(), rb_ary_shift(), rb_env_clear(), rb_find_file(), rb_find_file_ext(), and rb_mod_init_copy().

## ◆ RARRAY_CONST_PTR

#define RARRAY_CONST_PTR rb_array_const_ptr

Just another name of rb_array_const_ptr.

Definition at line 69 of file rarray.h.

Referenced by RARRAY_PTR(), rb_apply(), rb_eval_cmd_kw(), rb_proc_call_kw(), rb_struct_alloc(), rb_struct_initialize(), rb_yield_splat(), and rb_yield_splat_kw().

## ◆ RARRAY_CONST_PTR_TRANSIENT

#define RARRAY_CONST_PTR_TRANSIENT rb_array_const_ptr_transient

Just another name of rb_array_const_ptr_transient.

Definition at line 70 of file rarray.h.

Referenced by rb_apply(), rb_ary_dup(), rb_ary_plus(), and rb_ary_replace().

## ◆ RARRAY_LEN

#define RARRAY_LEN rb_array_len

Just another name of rb_array_len.

Definition at line 68 of file rarray.h.

Referenced by RARRAY_LENINT(), rb_ary_assoc(), rb_ary_cat(), rb_ary_cmp(), rb_ary_delete(), rb_ary_delete_at(), rb_ary_dup(), rb_ary_each(), rb_ary_free(), rb_ary_includes(), rb_ary_join(), rb_ary_plus(), rb_ary_pop(), rb_ary_push(), rb_ary_rassoc(), rb_ary_replace(), rb_ary_resize(), rb_ary_resurrect(), rb_ary_reverse(), rb_ary_rotate(), rb_ary_shift(), rb_ary_sort_bang(), rb_ary_store(), rb_debug_inspector_open(), rb_env_clear(), rb_find_file(), rb_find_file_ext(), rb_gc_register_mark_object(), rb_get_values_at(), rb_Hash(), rb_mod_init_copy(), rb_proc_call_kw(), and rb_struct_members().

## ◆ RARRAY_PTR_USE

#define RARRAY_PTR_USE | ( |  | ary,
|  |  | ptr_name,
|  |  | expr )

Value:
RBIMPL_RARRAY_STMT(0, ary, ptr_name, expr)
RBIMPL_RARRAY_STMT
#define RBIMPL_RARRAY_STMT(flag, ary, var, expr)
This is an implementation detail of RARRAY_PTR_USE.
Definition rarray.h:477

Declares a section of code where raw pointers are used.

In case you need to touch the raw C array instead of polite CAPIs, then that operation shall be wrapped using this macro.

const auto ary = rb_eval_string("[...]");
const auto len = RARRAY_LENINT(ary);
const auto symwrite = rb_intern("write");
RARRAY_PTR_USE(ary, ptr, {
rb_funcallv(rb_stdout, symwrite, len, ptr);
});
rb_stdout
VALUE rb_stdout
STDOUT constant.
Definition io.c:194
rb_eval_string
VALUE rb_eval_string(const char *str)
Evaluates the given string.
Definition vm_eval.c:1848
rb_intern
ID rb_intern(const char *name)
Finds or creates a symbol of the given name.
Definition symbol.c:796
RARRAY_LENINT
static int RARRAY_LENINT(VALUE ary)
Identical to rb_array_len(), except it differs for the return type.
Definition rarray.h:343
RARRAY_PTR_USE
#define RARRAY_PTR_USE(ary, ptr_name, expr)
Declares a section of code where raw pointers are used.
Definition rarray.h:518

Parameters

  ary | An object of RArray.
  ptr_name | A variable name which points the C array in `expr`.
  expr | The expression that touches `ptr_name`.

Definition at line 518 of file rarray.h.

Referenced by rb_ary_sort_bang().

## ◆ RARRAY_PTR_USE_END

#define RARRAY_PTR_USE_END | ( |  | a | ) |

Value:
rb_array_ptr_use_end(a, 0)

This is an implementation detail of RARRAY_PTR_USE.

People do not use it directly.

Definition at line 491 of file rarray.h.

## ◆ RARRAY_PTR_USE_TRANSIENT

#define RARRAY_PTR_USE_TRANSIENT | ( |  | ary,
|  |  | ptr_name,
|  |  | expr )

Value:
RBIMPL_RARRAY_STMT(1, ary, ptr_name, expr)

Identical to RARRAY_PTR_USE, except the pointer can be a transient one.

Parameters

  ary | An object of RArray.
  ptr_name | A variable name which points the C array in `expr`.
  expr | The expression that touches `ptr_name`.

Definition at line 528 of file rarray.h.

Referenced by RARRAY_ASET(), rb_ary_delete_at(), rb_ary_push(), rb_ary_reverse(), and rb_ary_rotate().

## ◆ RBIMPL_RARRAY_STMT

#define RBIMPL_RARRAY_STMT | ( |  | flag,
|  |  | ary,
|  |  | var,
|  |  | expr )

Value:
do { \
RBIMPL_ASSERT_TYPE((ary), RUBY_T_ARRAY); \
const VALUE rbimpl_ary = (ary); \
VALUE *var = rb_array_ptr_use_start(rbimpl_ary, (flag)); \
expr; \
rb_array_ptr_use_end(rbimpl_ary, (flag)); \
} while (0)
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40
RUBY_T_ARRAY
@ RUBY_T_ARRAY
Definition value_type.h:121

This is an implementation detail of RARRAY_PTR_USE.

People do not use it directly.

Definition at line 477 of file rarray.h.

## ◆ USE_TRANSIENT_HEAP

#define USE_TRANSIENT_HEAP 1

Warning
  Do not touch this macro.
  It is an implementation detail.
  The value of this macro must match for ruby itself and all extension libraries, otherwise serious memory corruption shall occur.

Definition at line 47 of file rarray.h.

## Enumeration Type Documentation

## ◆ ruby_rarray_consts

enum ruby_rarray_consts

This is an enum because GDB wants it (rather than a macro).

People need not bother.

Enumerator
RARRAY_EMBED_LEN_SHIFT | Where RARRAY_EMBED_LEN_MASK resides.
RARRAY_EMBED_LEN_MAX | Max possible number elements that can be embedded.

Definition at line 163 of file rarray.h.

## Function Documentation

## ◆ RARRAY_ASET()

static void RARRAY_ASET | ( | VALUE | ary,
|  | long | i,
|  | VALUE | v )
| inlinestatic

Assigns an object in an array.

Parameters

  [out] | ary | Destination array object.
  [in] | i | Index of `ary`.
  [in] | v | Arbitrary ruby object.

Precondition
  `ary` must be an instance of RArray.
  `ary`'s length must be longer than or equal to `i`.
  `i` must be greater than or equal to zero.

Postcondition
  `ary`'s `i`th element is set to `v`.

Definition at line 566 of file rarray.h.

## ◆ RARRAY_EMBED_LEN()

static long RARRAY_EMBED_LEN | ( | VALUE | ary | ) |
| inlinestatic

Queries the length of the array.

Parameters

  [in] | ary | Array in question.

Returns
  Its number of elements.

Precondition
  `ary` must be an instance of RArray, and must has its RARRAY_EMBED_FLAG flag set.

Definition at line 297 of file rarray.h.

Referenced by rb_array_len().

## ◆ RARRAY_LENINT()

static int RARRAY_LENINT | ( | VALUE | ary | ) |
| inlinestatic

Identical to rb_array_len(), except it differs for the return type.

Parameters

  [in] | ary | Array in question.

Exceptions

  rb_eRangeError | Too long.

Returns
  Its number of elements.

Precondition
  `ary` must be an instance of RArray.

Definition at line 343 of file rarray.h.

Referenced by rb_apply(), rb_eval_cmd_kw(), rb_struct_alloc(), rb_struct_initialize(), rb_yield_splat(), and rb_yield_splat_kw().

## ◆ RARRAY_PTR()

static VALUE * RARRAY_PTR | ( | VALUE | ary | ) |
| inlinestatic

Wild use of a C pointer.

This function accesses the backend storage directly. This is slower than RARRAY_PTR_USE_TRANSIENT. It exercises extra manoeuvres to protect our generational GC. Use of this function is considered archaic. Use a modern way instead.

Parameters

  [in] | ary | An object of RArray.

Returns
  The backend C array.

Definition at line 546 of file rarray.h.

Referenced by rb_struct_new().

## ◆ RARRAY_TRANSIENT_P()

static bool RARRAY_TRANSIENT_P | ( | VALUE | ary | ) |
| inlinestatic

Queries if the array is a transient array.

Parameters

  [in] | ary | Array in question.

Return values

  true | Yes it is.
  false | No it isn't.

Precondition
  `ary` must be an instance of RArray.

Definition at line 364 of file rarray.h.

Referenced by rb_ary_free(), and rb_ary_resize().

## ◆ rb_array_len()

static long rb_array_len | ( | VALUE | a | ) |
| inlinestatic

Queries the length of the array.

Parameters

  [in] | a | Array in question.

Returns
  Its number of elements.

Precondition
  `a` must be an instance of RArray.

Definition at line 317 of file rarray.h.