Ruby
3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
|
Public APIs related to rb_cArray. More...
#include "ruby/internal/attr/noalias.h"
#include "ruby/internal/attr/noexcept.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_ary_tmp_new rb_ary_hidden_new |
#define | rb_ary_new2 rb_ary_new_capa |
Old name of rb_ary_new_capa. More... | |
#define | rb_ary_new3 rb_ary_new_from_args |
Old name of rb_ary_new_from_args. More... | |
#define | rb_ary_new4 rb_ary_new_from_values |
Old name of rb_ary_new_from_values. More... | |
Functions | |
void | rb_mem_clear (VALUE *buf, long len) |
Fills the memory region with a series of RUBY_Qnil. More... | |
VALUE | rb_assoc_new (VALUE car, VALUE cdr) |
Identical to rb_ary_new_from_values(), except it expects exactly two parameters. More... | |
VALUE | rb_check_array_type (VALUE obj) |
Try converting an object to its array representation using its to_ary method, if any. More... | |
VALUE | rb_ary_new (void) |
Allocates a new, empty array. More... | |
VALUE | rb_ary_new_capa (long capa) |
Identical to rb_ary_new(), except it additionally specifies how many rooms of objects it should allocate. More... | |
VALUE | rb_ary_new_from_args (long n,...) |
Constructs an array from the passed objects. More... | |
VALUE | rb_ary_new_from_values (long n, const VALUE *elts) |
Identical to rb_ary_new_from_args(), except how objects are passed. More... | |
VALUE | rb_ary_hidden_new (long capa) |
Allocates a hidden (no class) empty array. More... | |
void | rb_ary_free (VALUE ary) |
Destroys the given array for no reason. More... | |
void | rb_ary_modify (VALUE ary) |
Declares that the array is about to be modified. More... | |
VALUE | rb_ary_freeze (VALUE obj) |
Freeze an array, preventing further modifications. More... | |
VALUE | rb_ary_shared_with_p (VALUE lhs, VALUE rhs) |
Queries if the passed two arrays share the same backend storage. More... | |
VALUE | rb_ary_aref (int argc, const VALUE *argv, VALUE ary) |
Queries element(s) of an array. More... | |
VALUE | rb_ary_subseq (VALUE ary, long beg, long len) |
Obtains a part of the passed array. More... | |
void | rb_ary_store (VALUE ary, long key, VALUE val) |
Destructively stores the passed value to the passed array's passed index. More... | |
VALUE | rb_ary_dup (VALUE ary) |
Duplicates an array. More... | |
VALUE | rb_ary_resurrect (VALUE ary) |
I guess there is no use case of this function in extension libraries, but this is a routine identical to rb_ary_dup(). More... | |
VALUE | rb_ary_to_ary (VALUE obj) |
Force converts an object to an array. More... | |
VALUE | rb_ary_to_s (VALUE ary) |
Converts an array into a human-readable string. More... | |
VALUE | rb_ary_cat (VALUE ary, const VALUE *train, long len) |
Destructively appends multiple elements at the end of the array. More... | |
VALUE | rb_ary_push (VALUE ary, VALUE elem) |
Special case of rb_ary_cat() that it adds only one element. More... | |
VALUE | rb_ary_pop (VALUE ary) |
Destructively deletes an element from the end of the passed array and returns what was deleted. More... | |
VALUE | rb_ary_shift (VALUE ary) |
Destructively deletes an element from the beginning of the passed array and returns what was deleted. More... | |
VALUE | rb_ary_unshift (VALUE ary, VALUE elem) |
Destructively prepends the passed item at the beginning of the passed array. More... | |
VALUE | rb_ary_entry (VALUE ary, long off) |
Queries an element of an array. More... | |
VALUE | rb_ary_each (VALUE ary) |
Iteratively yields each element of the passed array to the implicitly passed block if any. More... | |
VALUE | rb_ary_join (VALUE ary, VALUE sep) |
Recursively stringises the elements of the passed array, flattens that result, then joins the sequence using the passed separator. More... | |
VALUE | rb_ary_reverse (VALUE ary) |
Destructively reverses the passed array in-place. More... | |
VALUE | rb_ary_rotate (VALUE ary, long rot) |
Destructively rotates the passed array in-place to towards its end. More... | |
VALUE | rb_ary_sort (VALUE ary) |
Creates a copy of the passed array, whose elements are sorted according to their <=> result. More... | |
VALUE | rb_ary_sort_bang (VALUE ary) |
Destructively sorts the passed array in-place, according to each elements' <=> result. More... | |
VALUE | rb_ary_delete (VALUE ary, VALUE elem) |
Destructively removes elements from the passed array, so that there would be no elements inside that satisfy == relationship with the passed object. More... | |
VALUE | rb_ary_delete_at (VALUE ary, long pos) |
Destructively removes an element which resides at the specific index of the passed array. More... | |
VALUE | rb_ary_clear (VALUE ary) |
Destructively removes everything form an array. More... | |
VALUE | rb_ary_plus (VALUE lhs, VALUE rhs) |
Creates a new array, concatenating the former to the latter. More... | |
VALUE | rb_ary_concat (VALUE lhs, VALUE rhs) |
Destructively appends the contents of latter into the end of former. More... | |
VALUE | rb_ary_assoc (VALUE alist, VALUE key) |
Looks up the passed key, assuming the passed array is an alist. More... | |
VALUE | rb_ary_rassoc (VALUE alist, VALUE key) |
Identical to rb_ary_assoc(), except it scans the passed array from the opposite direction. More... | |
VALUE | rb_ary_includes (VALUE ary, VALUE elem) |
Queries if the passed array has the passed entry. More... | |
VALUE | rb_ary_cmp (VALUE lhs, VALUE rhs) |
Recursively compares each elements of the two arrays one-by-one using <=> . More... | |
VALUE | rb_ary_replace (VALUE copy, VALUE orig) |
Replaces the contents of the former object with the contents of the latter. More... | |
VALUE | rb_get_values_at (VALUE obj, long olen, int argc, const VALUE *argv, VALUE(*func)(VALUE obj, long oidx)) |
This was a generalisation of Array#values_at , Struct#values_at , and MatchData#values_at . More... | |
VALUE | rb_ary_resize (VALUE ary, long len) |
Expands or shrinks the passed array to the passed length. More... | |
Public APIs related to rb_cArray.
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. __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 array.h.
Queries element(s) of an array.
This is complicated! Refer Array#slice
document for the complete description of how it behaves.
[in] | argc | Number of objects of argv . |
[in] | argv | Up to 2 objects. |
[in] | ary | Target array. |
rb_eTypeError | argv (or its part) includes non-Integer. |
rb_eRangeError | rb_cArithSeq is passed, and is OOB. |
Looks up the passed key, assuming the passed array is an alist.
An "alist" here is a list of "association"s, much like that of Emacs. Emacs has assoc
function that behaves exactly the same as this one.
This function scans the passed array looking for an element, which itself is an array, whose first element is the passed key. If no such element is found, returns RUBY_Qnil.
Although this function expects the passed array be an array of arrays, it can happily accept non-array elements; it just ignores such things.
[in] | alist | An array of arrays. |
[in] | key | Needle. |
RUBY_Qnil | Nothing was found. |
otherwise | An element in alist whose first element is in == relationship with key . |
Destructively appends multiple elements at the end of the array.
[out] | ary | Where to push train . |
[in] | train | Arbitrary ruby objects to push to ary . |
[in] | len | Number of objects of train . |
rb_eIndexError | len too large. |
rb_eFrozenError | ary is frozen. |
ary
. ary
has contents from train
appended at its end. Destructively removes everything form an array.
[out] | ary | Target array to modify. |
rb_eFrozenError | ary is frozen. |
ary
. ary
is an empty array. Definition at line 4729 of file array.c.
Referenced by ruby_set_argv().
Destructively appends the contents of latter into the end of former.
[out] | lhs | Destination array. |
[in] | rhs | Source array. |
rb_eFrozenError | lhs is frozen. |
rb_eIndexError | Result array too big. |
rb_eTypeError | rhs doesn't respond to #to_ary . |
lhs
. lhs
has contents of rhs
appended to its end. Destructively removes elements from the passed array, so that there would be no elements inside that satisfy ==
relationship with the passed object.
Returns the last deleted element if any. But in case there was nothing to delete it gets complicated. It checks for the implicitly passed block. If there is a block the return value would be what the block evaluates to. Otherwise it resorts to RUBY_Qnil.
[out] | ary | Target array to modify. |
[in] | elem | Template object to match against each element. |
rb_eFrozenError | ary is frozen. |
==
relationship with elem
are purged from ary
. Elements shift their positions so that ary
gets compact. Destructively removes an element which resides at the specific index of the passed array.
Unlike rb_ary_stre() the index can be negative, which means the index counts backwards from the array's tail.
[out] | ary | Target array to modify. |
[in] | pos | Position (can be negative). |
rb_eFrozenError | ary is frozen. |
ary
's pos
-th element is deleted if any. pos
is out of bound, or pos
did exist but stored RUBY_Qnil as an ordinal value. Duplicates an array.
[in] | ary | Target to duplicate. |
ary
. Definition at line 2771 of file array.c.
Referenced by rb_ary_sort().
Iteratively yields each element of the passed array to the implicitly passed block if any.
In case there is no block given, an enumerator that does the thing is generated instead.
[in] | ary | Array to iterate over. |
ary | Passed block was evaluated. |
otherwise | An instance of rb_cEnumerator for Array#each . |
Queries an element of an array.
When passed offset is negative it counts backwards.
[in] | ary | An array to look into. |
[in] | off | Offset (can be negative). |
off
is out of bounds of ary
. Otherwise what is stored at off
-th position of ary
. ary
's off
-th element can happen to be RUBY_Qnil. Definition at line 1731 of file array.c.
Referenced by rb_debug_inspector_frame_binding_get(), rb_debug_inspector_frame_class_get(), rb_debug_inspector_frame_depth(), rb_debug_inspector_frame_iseq_get(), rb_debug_inspector_frame_self_get(), and rb_ext_resolve_symbol().
void rb_ary_free | ( | VALUE | ary | ) |
Destroys the given array for no reason.
[out] | ary | The array to be executed. |
Array#clear
could be what you want. Freeze an array, preventing further modifications.
The underlying buffer may be shrunk before freezing to conserve memory.
[out] | obj | Object assumed to be an array to freeze. |
VALUE rb_ary_hidden_new | ( | long | capa | ) |
Allocates a hidden (no class) empty array.
[in] | capa | Designed capacity of the array. |
Definition at line 853 of file array.c.
Referenced by rb_get_kwargs(), and rb_struct_new().
Queries if the passed array has the passed entry.
[in] | ary | Target array to scan. |
[in] | elem | Target array to find. |
RUBY_Qfalse | No element in ary is in == relationship with elem . |
RUBY_Qtrue | There is at least one element in ary which is in == relationship with elem . |
Recursively stringises the elements of the passed array, flattens that result, then joins the sequence using the passed separator.
[in] | ary | Target array to convert. |
[in] | sep | Separator. Either a string, or RUBY_Qnil if you want no separator. |
rb_eArgError | Infinite recursion in ary . |
rb_eTypeError | sep is not a string. |
rb_eEncCompatError | Strings do not agree with their encodings. |
ary
, using sep
as separator. void rb_ary_modify | ( | VALUE | ary | ) |
Declares that the array is about to be modified.
This for instance let the array have a dedicated backend storage.
[out] | ary | Array about to be modified. |
rb_eFrozenError | ary is frozen. |
Definition at line 570 of file array.c.
Referenced by rb_ary_delete_at(), rb_ary_resize(), rb_ary_reverse(), rb_ary_rotate(), rb_ary_sort_bang(), and rb_ary_store().
VALUE rb_ary_new | ( | void | ) |
Allocates a new, empty array.
Definition at line 741 of file array.c.
Referenced by rb_f_global_variables(), rb_f_untrace_var(), rb_memory_view_extract_item_members(), rb_mod_ancestors(), rb_mod_included_modules(), and rb_obj_instance_variables().
VALUE rb_ary_new_capa | ( | long | capa | ) |
Identical to rb_ary_new(), except it additionally specifies how many rooms of objects it should allocate.
This way you can create an array whose capacity is bigger than the length of it. If you can say that an array grows to a specific amount, this could be effective than resizing an array over and over again and again.
[in] | capa | Designed capacity of the generating array. |
capa
. Definition at line 735 of file array.c.
Referenced by rb_ary_new().
VALUE rb_ary_new_from_args | ( | long | n, |
... | |||
) |
Identical to rb_ary_new_from_args(), except how objects are passed.
[in] | n | Number of objects of elts . |
[in] | elts | Arbitrary ruby objects, filled into the returning array. |
n
, whose contents are the passed objects. Creates a new array, concatenating the former to the latter.
[in] | lhs | Source array #1. |
[in] | rhs | Source array #2. |
rb_eIndexError | Result array too big. |
rhs
concatenated to lhs
. +
s in Ruby. This is one of such things. There has been a long discussion around +
s in programming languages. Destructively deletes an element from the end of the passed array and returns what was deleted.
[out] | ary | Target array to modify. |
rb_eFrozenError | ary is frozen. |
ary
, or RUBY_Qnil if there is nothing to remove. ary
's last element, if any, is removed. ary
was an 1-element array whose content was RUBY_Qnil, or was empty. Special case of rb_ary_cat() that it adds only one element.
[out] | ary | Where to push elem . |
[in] | elem | Arbitrary ruby object to push. |
rb_eFrozenError | ary is frozen. |
ary
. ary
has elem
appended at its end. Definition at line 1378 of file array.c.
Referenced by rb_f_global_variables(), rb_f_untrace_var(), rb_get_kwargs(), rb_memory_view_extract_item_members(), ruby_init_loadpath(), and ruby_set_argv().
Identical to rb_ary_assoc(), except it scans the passed array from the opposite direction.
[in] | alist | An array of arrays. |
[in] | key | Needle. |
RUBY_Qnil | Nothing was found. |
otherwise | An element in alist whose first element is in == relationship with key . |
Replaces the contents of the former object with the contents of the latter.
[out] | copy | Destination object. |
[in] | orig | Source object. |
rb_eTypeError | orig has no implicit conversion to Array. |
rb_eFrozenError | copy is frozen. |
copy
. copy
's former components are abandoned. It now has the identical length and contents to orig
. Expands or shrinks the passed array to the passed length.
[out] | ary | An array to modify. |
[in] | len | Desired length of ary . |
rb_eFrozenError | ary is frozen. |
rb_eIndexError | len too long. |
ary
. ary
's length is len
. len
and previous length of ary
this operation can also create a series of "hole" positions inside of the backend storage. They are filled with RUBY_Qnil. I guess there is no use case of this function in extension libraries, but this is a routine identical to rb_ary_dup().
This makes the most sense when the passed array is formerly hidden by rb_obj_hide().
[in] | ary | An array, possibly hidden. |
Destructively rotates the passed array in-place to towards its end.
The amount can be negative. Would rotate to the opposite direction then.
Array#rotate!
, not Array#rotate
. [out] | ary | Target array to modify. |
[in] | rot | Amount of rotation. |
rb_eFrozenError | ary is frozen. |
RUBY_Qnil | Not rotated. |
ary | Rotated. |
ary
is rotated. Queries if the passed two arrays share the same backend storage.
A use-case for knowing such property is to take a snapshot of an array (using e.g. rb_ary_replace()), then check later if that snapshot still shares the storage with the original. Taking a snapshot is ultra-cheap. If nothing happens the impact shall be minimal. But if someone modifies the original, that entity shall pay the cost of copy-on-write. You can detect that using this API.
[in] | lhs | Comparison LHS. |
[in] | rhs | Comparison RHS. |
RUBY_Qtrue | They share the same backend storage. |
RUBY_Qfalse | They are distinct. |
Destructively deletes an element from the beginning of the passed array and returns what was deleted.
It can also be seen as a routine identical to rb_ary_pop(), except which side of the array to scrub.
[out] | ary | Target array to modify. |
rb_eFrozenError | ary is frozen. |
ary
, or RUBY_Qnil if there is nothing to remove. ary
's first element, if any, is removed. As the name implies everything else remaining in ary
gets moved towards ary
's beginning. ary
was an 1-element array whose content was RUBY_Qnil, or was empty. Creates a copy of the passed array, whose elements are sorted according to their <=>
result.
[in] | ary | Array to sort. |
rb_eArgError | Comparison not defined among elements. |
rb_eRuntimeError | Infinite recursion in <=> . |
ary
, sorted. qsort
as backend algorithm, which means the result is unstable (in terms of sort stability). Destructively sorts the passed array in-place, according to each elements' <=>
result.
[in] | ary | Target array to modify. |
rb_eArgError | Comparison not defined among elements. |
rb_eRuntimeError | Infinite recursion in <=> . |
ary
. ary
is sorted. qsort
as backend algorithm, which means the result is unstable (in terms of sort stability). Definition at line 3388 of file array.c.
Referenced by rb_ary_sort().
Destructively stores the passed value to the passed array's passed index.
It also resizes the array's backend storage so that the requested index is not out of bounds.
[out] | ary | Target array to modify. |
[in] | key | Where to store val . |
[in] | val | What to store at key . |
rb_eFrozenError | ary is frozen. |
rb_eIndexError | key is negative. |
ary
's key
th position is occupied with val
. key
and previous length of ary
this operation can also create a series of "hole" positions inside of the backend storage. They are filled with RUBY_Qnil. Definition at line 1201 of file array.c.
Referenced by rb_ary_delete().
Obtains a part of the passed array.
[in] | ary | Target array. |
[in] | beg | Subpart index. |
[in] | len | Requested length of returning array. |
RUBY_Qnil | Requested range out of bounds of ary . |
otherwise | An allocated new array whose contents are ary 's beg to len . |
len
when for instance [0, 1, 2, 3]
's 4th to 1,000,000,000th is requested. Definition at line 1759 of file array.c.
Referenced by rb_apply().
Force converts an object to an array.
It first tries its #to_ary
method. Takes the result if any. Otherwise creates an array of size 1 whose sole element is the passed object.
[in] | obj | Arbitrary ruby object. |
obj
. Converts an array into a human-readable string.
Historically its behaviour changed over time. Currently it is identical to calling inspect
method. This behaviour is from that of python (!!) circa 2006.
[in] | ary | Array to inspect. |
ary
. [ruby-dev:29520]
Destructively prepends the passed item at the beginning of the passed array.
It can also be seen as a routine identical to rb_ary_push(), except which side of the array to modify.
[out] | ary | Target array to modify. |
[in] | elem | Arbitrary ruby object to unshift. |
rb_eFrozenError | ary is frozen. |
ary
. ary
has elem
prepended at this beginning. Identical to rb_ary_new_from_values(), except it expects exactly two parameters.
[in] | car | Arbitrary ruby object. |
[in] | cdr | Arbitrary ruby object. |
Definition at line 995 of file array.c.
Referenced by rb_big_divmod().
Try converting an object to its array representation using its to_ary
method, if any.
If there is no such thing, returns RUBY_Qnil.
[in] | obj | Arbitrary ruby object to convert. |
rb_eTypeError | obj.to_ary returned something non-Array. |
RUBY_Qnil | No conversion from obj to array defined. |
otherwise | Converted array representation of obj . |
Definition at line 1008 of file array.c.
Referenced by rb_Array(), rb_ary_assoc(), rb_ary_cmp(), rb_ary_rassoc(), rb_ary_to_ary(), rb_yield_splat(), and rb_yield_splat_kw().
VALUE rb_get_values_at | ( | VALUE | obj, |
long | olen, | ||
int | argc, | ||
const VALUE * | argv, | ||
VALUE(*)(VALUE obj, long oidx) | func | ||
) |
This was a generalisation of Array#values_at
, Struct#values_at
, and MatchData#values_at
.
It begun its life as a refactoring effort. However as Ruby evolves over time, as of writing none of aforementioned methods share their implementations at all. This function is not deprecated; still works as it has been. But it is now kind of like a rudimentum.
This function takes an object, which is a receiver, and a series of "indices", which are either integers, or ranges of integers. Calls the passed callback for each of those indices, along with the receiver. This callback is expected to do something like rb_ary_aref(), rb_struct_aref(), etc. In case of a range index rb_range_beg_len() expands the range. Finally return values of the callback are gathered as an array, then returned.
[in] | obj | Arbitrary ruby object. |
[in] | olen | "Length" of obj . |
[in] | argc | Number of objects of argv . |
[in] | argv | List of "indices", described above. |
[in] | func | Callback function. |
func
outputs.