(0e258742221c81dddb807e48a5691ce44b46dadd)

Defines struct RArray. More...

#include "ruby/internal/arithmetic/len_t.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/gc.h"
#include "ruby/internal/stdbool.h"
#include "ruby/internal/value.h"
#include "ruby/internal/value_type.h"
#include "ruby/assert.h"

Include dependency graph for rarray.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

Macros
#define	RARRAY(obj) RBIMPL_CAST((struct 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	RBIMPL_RARRAY_STMT(ary, var, expr)
	This is an implementation detail of RARRAY_PTR_USE.

#define	RARRAY_PTR_USE(ary, ptr_name, expr) RBIMPL_RARRAY_STMT(ary, ptr_name, expr)
	Declares a section of code where raw pointers are used.

#define	RARRAY_AREF(a, i) (*RBIMPL_AREF_PTR(a, i))
	References an object in an array.

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

Functions
static rb_len_t	RARRAY_EMBED_LEN (VALUE ary)
	Queries the length of the array.

static rb_len_t	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 VALUE *	RARRAY_PTR (VALUE ary)
	Wild use of a C pointer.

static void	RARRAY_ASET (VALUE ary, rb_len_t 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 ) RBIMPL_CAST((struct RArray *)(obj))

Convenient casting macro.

Parameters

obj	An object, which is in fact an RArray.

Returns: The passed object casted to RArray.

Definition at line 44 of file rarray.h.

◆ RARRAY_AREF

#define RARRAY_AREF	(	a,
		i
	)	(*RBIMPL_AREF_PTR(a, i))

References an object in an array.

Parameters

[in]	ary	An object of RArray.
[in]	idx	Index to access ary

Returns: The object at idx in ary

Definition at line 421 of file rarray.h.

◆ RARRAY_CONST_PTR

#define RARRAY_CONST_PTR rb_array_const_ptr

Just another name of rb_array_const_ptr.

Definition at line 51 of file rarray.h.

◆ RARRAY_LEN

#define RARRAY_LEN rb_array_len

Just another name of rb_array_len.

Definition at line 50 of file rarray.h.

◆ RARRAY_PTR_USE

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

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);
});

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 347 of file rarray.h.

◆ RBIMPL_RARRAY_STMT

#define RBIMPL_RARRAY_STMT	(	ary,
		var,
		expr
	)

Value:

    do {        \
    RBIMPL_ASSERT_TYPE((ary), RUBY_T_ARRAY);                 \
    const VALUE rbimpl_ary = (ary);                          \
    VALUE *var = rb_ary_ptr_use_start(rbimpl_ary); \
    expr;                                                   \
    rb_ary_ptr_use_end(rbimpl_ary);                \
} while (0)

This is an implementation detail of RARRAY_PTR_USE.

People do not use it directly.

Definition at line 314 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.

Definition at line 121 of file rarray.h.

Function Documentation

◆ RARRAY_ASET()

static void RARRAY_ASET	(	VALUE	ary,
		rb_len_t	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 ith element is set to v.

Definition at line 385 of file rarray.h.

◆ RARRAY_EMBED_LEN()

static rb_len_t 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 234 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 280 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. 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 365 of file rarray.h.

Referenced by rb_proc_call_kw(), and rb_struct_new().

◆ rb_array_len()

static rb_len_t 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 254 of file rarray.h.

(0e258742221c81dddb807e48a5691ce44b46dadd)

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ RARRAY

◆ RARRAY_AREF

◆ RARRAY_CONST_PTR

◆ RARRAY_LEN

◆ RARRAY_PTR_USE

◆ RBIMPL_RARRAY_STMT

Enumeration Type Documentation

◆ ruby_rarray_consts

Function Documentation

◆ RARRAY_ASET()

◆ RARRAY_EMBED_LEN()

◆ RARRAY_LENINT()

◆ RARRAY_PTR()

◆ rb_array_len()