(348a53415339076afc4a02fcd09f3ae36e9c4c61)

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"

Include dependency graph for array.h:

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

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

Detailed Description

Public APIs related to rb_cArray.

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

Function Documentation

◆ rb_ary_aref()

VALUE rb_ary_aref	(	int	argc,
		const VALUE *	argv,
		VALUE	ary
	)

Queries element(s) of an array.

This is complicated! Refer Array#slice document for the complete description of how it behaves.

Parameters

[in]	argc	Number of objects of `argv`.
[in]	argv	Up to 2 objects.
[in]	ary	Target array.

Exceptions

rb_eTypeError	`argv` (or its part) includes non-Integer.
rb_eRangeError	rb_cArithSeq is passed, and is OOB.

Returns: An element (if requested), or an array of elements (if requested), or RUBY_Qnil (if index OOB).

Definition at line 1895 of file array.c.

◆ rb_ary_assoc()

VALUE rb_ary_assoc	(	VALUE	alist,
		VALUE	key
	)

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 is an example of aliist.
auto_mode_alist = [
  [ /\.[ch]\z/, :"c-mode" ],
  [ /\.[ch]pp\z/, :"c++-mode" ],
  [ /\.awk\z/, :"awk-mode" ],
  [ /\.cs\z/, :"csharp-mode" ],
  [ /\.go\z/, :"go-mode" ],
  [ /\.java\z/, :"java-mode" ],
  [ /\.pas\z/, :"pascal-mode" ],
  [ /\.rs\z/, :"rust-mode" ],
  [ /\.txt\z/, :"text-mode" ],
]

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.

Parameters

[in]	alist	An array of arrays.
[in]	key	Needle.

Return values

RUBY_Qnil	Nothing was found.
otherwise	An element in `alist` whose first element is in `==` relationship with `key`.

Definition at line 5065 of file array.c.

◆ rb_ary_cat()

VALUE rb_ary_cat	(	VALUE	ary,
		const VALUE *	train,
		long	len
	)

Destructively appends multiple elements at the end of the array.

Parameters

[out]	ary	Where to push `train`.
[in]	train	Arbitrary ruby objects to push to `ary`.
[in]	len	Number of objects of `train`.

Exceptions

rb_eIndexError	`len` too large.
rb_eFrozenError	`ary` is frozen.

Returns: The passed ary.

Postcondition: ary has contents from train appended at its end.

Definition at line 1397 of file array.c.

◆ rb_ary_clear()

VALUE rb_ary_clear ( VALUE ary )

Destructively removes everything form an array.

Parameters

[out] ary Target array to modify.

Exceptions

rb_eFrozenError ary is frozen.

Returns: The passed ary.

Postcondition: ary is an empty array.

Definition at line 4642 of file array.c.

Referenced by ruby_set_argv().

◆ rb_ary_cmp()

VALUE rb_ary_cmp	(	VALUE	lhs,
		VALUE	rhs
	)

Recursively compares each elements of the two arrays one-by-one using <=>.

Parameters

[in]	lhs	Comparison LHS.
[in]	rhs	Comparison RHS.

Return values

RUBY_Qnil	`lhs` and `rhs` are not comparable.
-1	`lhs` is less than `rhs`.
0	They are equal.
1	`rhs` is less then `lhs`.

Definition at line 5368 of file array.c.

◆ rb_ary_concat()

VALUE rb_ary_concat	(	VALUE	lhs,
		VALUE	rhs
	)

Destructively appends the contents of latter into the end of former.

Parameters

[out]	lhs	Destination array.
[in]	rhs	Source array.

Exceptions

rb_eFrozenError	`lhs` is frozen.
rb_eIndexError	Result array too big.
rb_eTypeError	`rhs` doesn't respond to `#to_ary`.

Returns: The passed lhs.

Postcondition: lhs has contents of rhs appended to its end.

Definition at line 4981 of file array.c.

◆ rb_ary_delete()

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.

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.

Parameters

[out]	ary	Target array to modify.
[in]	elem	Template object to match against each element.

Exceptions

rb_eFrozenError ary is frozen.

Returns: What was deleted, or what was the block returned, or RUBY_Qnil (see above).

Postcondition: All elements that have == relationship with elem are purged from ary. Elements shift their positions so that ary gets compact.

Definition at line 3991 of file array.c.

◆ rb_ary_delete_at()

VALUE rb_ary_delete_at	(	VALUE	ary,
		long	pos
	)

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.

Parameters

[out]	ary	Target array to modify.
[in]	pos	Position (can be negative).

Exceptions

rb_eFrozenError ary is frozen.

Returns: What was deleted, or RUBY_Qnil in case of OOB.

Postcondition: ary's pos-th element is deleted if any.

Note: There is no way to distinguish whether pos is out of bound, or pos did exist but stored RUBY_Qnil as an ordinal value.

Definition at line 4045 of file array.c.

◆ rb_ary_dup()

VALUE rb_ary_dup ( VALUE ary )

Duplicates an array.

Parameters

[in] ary Target to duplicate.

Returns: An allocated new array whose contents are identical to ary.

Definition at line 2777 of file array.c.

Referenced by rb_ary_sort().

◆ rb_ary_each()

VALUE rb_ary_each ( VALUE ary )

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.

Parameters

[in] ary Array to iterate over.

Return values

ary	Passed block was evaluated.
otherwise	An instance of rb_cEnumerator for `Array#each`.

Definition at line 2641 of file array.c.

◆ rb_ary_entry()

VALUE rb_ary_entry	(	VALUE	ary,
		long	off
	)

Queries an element of an array.

When passed offset is negative it counts backwards.

Parameters

[in]	ary	An array to look into.
[in]	off	Offset (can be negative).

Returns: RUBY_Qnil when off is out of bounds of ary. Otherwise what is stored at off-th position of ary.

Note: ary's off-th element can happen to be RUBY_Qnil.

Definition at line 1737 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().

◆ rb_ary_free()

void rb_ary_free ( VALUE ary )

Destroys the given array for no reason.

Warning: DO NOT USE IT.; Leave this task to our GC.; It was a wrong indea at the first place to let you know about it.

Parameters

[out] ary The array to be executed.

Postcondition: The given array no longer exists.

Note: Maybe Array#clear could be what you want.

Definition at line 875 of file array.c.

◆ rb_ary_freeze()

VALUE rb_ary_freeze ( VALUE obj )

Freeze an array, preventing further modifications.

The underlying buffer may be shrunk before freezing to conserve memory.

Parameters

[out] obj Object assumed to be an array to freeze.

See also: RB_OBJ_FREEZE()

Definition at line 648 of file array.c.

◆ rb_ary_hidden_new()

VALUE rb_ary_hidden_new ( long capa )

Allocates a hidden (no class) empty array.

Parameters

[in] capa Designed capacity of the array.

Returns: A hidden, empty array.

See also: rb_obj_hide()

Definition at line 859 of file array.c.

Referenced by rb_get_kwargs(), and rb_struct_new().

◆ rb_ary_includes()

VALUE rb_ary_includes	(	VALUE	ary,
		VALUE	elem
	)

Queries if the passed array has the passed entry.

Parameters

[in]	ary	Target array to scan.
[in]	elem	Target array to find.

Return values

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`.

Definition at line 5280 of file array.c.

◆ rb_ary_join()

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.

Parameters

[in]	ary	Target array to convert.
[in]	sep	Separator. Either a string, or RUBY_Qnil if you want no separator.

Exceptions

rb_eArgError	Infinite recursion in `ary`.
rb_eTypeError	`sep` is not a string.
rb_eEncCompatError	Strings do not agree with their encodings.

Returns: An instance of rb_cString which concatenates stringised contents of ary, using sep as separator.

Definition at line 2891 of file array.c.

◆ rb_ary_modify()

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.

Parameters

[out] ary Array about to be modified.

Exceptions

rb_eFrozenError ary is frozen.

Postcondition: Upon successful return the passed array is eligible to be modified.

Definition at line 576 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().

◆ rb_ary_new()

VALUE rb_ary_new ( void )

Allocates a new, empty array.

Returns: An allocated new array, whose length is 0.

Definition at line 747 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().

◆ rb_ary_new_capa()

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.

Parameters

[in] capa Designed capacity of the generating array.

Returns: An empty array, whose capacity is capa.

Definition at line 741 of file array.c.

Referenced by rb_ary_new().

◆ rb_ary_new_from_args()

VALUE rb_ary_new_from_args	(	long	n,
			...
	)

Constructs an array from the passed objects.

Parameters

[in]	n	Number of passed objects.
[in]	...	Arbitrary ruby objects, filled into the returning array.

Returns: An array of size n, whose contents are the passed objects.

Definition at line 752 of file array.c.

◆ rb_ary_new_from_values()

VALUE rb_ary_new_from_values	(	long	n,
		const VALUE *	elts
	)

Identical to rb_ary_new_from_args(), except how objects are passed.

Parameters

[in]	n	Number of objects of `elts`.
[in]	elts	Arbitrary ruby objects, filled into the returning array.

Returns: An array of size n, whose contents are the passed objects.

Definition at line 786 of file array.c.

◆ rb_ary_plus()

VALUE rb_ary_plus	(	VALUE	lhs,
		VALUE	rhs
	)

Creates a new array, concatenating the former to the latter.

Parameters

[in]	lhs	Source array #1.
[in]	rhs	Source array #2.

Exceptions

rb_eIndexError Result array too big.

Returns: A new array containing rhs concatenated to lhs.

Note: This operation doesn't commute. Don't get confused by the "plus" terminology. For historical reasons there are some noncommutative +s in Ruby. This is one of such things. There has been a long discussion around +s in programming languages.

Definition at line 4918 of file array.c.

◆ rb_ary_pop()

VALUE rb_ary_pop ( VALUE ary )

Destructively deletes an element from the end of the passed array and returns what was deleted.

Parameters

[out] ary Target array to modify.

Exceptions

rb_eFrozenError ary is frozen.

Returns: What was at the end of ary, or RUBY_Qnil if there is nothing to remove.

Postcondition: ary's last element, if any, is removed.

Note: There is no way to distinguish whether ary was an 1-element array whose content was RUBY_Qnil, or was empty.

Definition at line 1431 of file array.c.

◆ rb_ary_push()

VALUE rb_ary_push	(	VALUE	ary,
		VALUE	elem
	)

Special case of rb_ary_cat() that it adds only one element.

Parameters

[out]	ary	Where to push `elem`.
[in]	elem	Arbitrary ruby object to push.

Exceptions

rb_eFrozenError ary is frozen.

Returns: The passed ary.

Postcondition: ary has elem appended at its end.

Definition at line 1384 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().

◆ rb_ary_rassoc()

VALUE rb_ary_rassoc	(	VALUE	alist,
		VALUE	key
	)

Identical to rb_ary_assoc(), except it scans the passed array from the opposite direction.

Parameters

[in]	alist	An array of arrays.
[in]	key	Needle.

Return values

RUBY_Qnil	Nothing was found.
otherwise	An element in `alist` whose first element is in `==` relationship with `key`.

Definition at line 5097 of file array.c.

◆ rb_ary_replace()

VALUE rb_ary_replace	(	VALUE	copy,
		VALUE	orig
	)

Replaces the contents of the former object with the contents of the latter.

Parameters

[out]	copy	Destination object.
[in]	orig	Source object.

Exceptions

rb_eTypeError	`orig` has no implicit conversion to Array.
rb_eFrozenError	`copy` is frozen.

Returns: The passed copy.

Postcondition: copy's former components are abandoned. It now has the identical length and contents to orig.

Definition at line 4587 of file array.c.

◆ rb_ary_resize()

VALUE rb_ary_resize	(	VALUE	ary,
		long	len
	)

Expands or shrinks the passed array to the passed length.

Parameters

[out]	ary	An array to modify.
[in]	len	Desired length of `ary`.

Exceptions

rb_eFrozenError	`ary` is frozen.
rb_eIndexError	`len` too long.

Returns: The passed ary.

Postcondition: ary's length is len.; Depending on 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.

Definition at line 2296 of file array.c.

◆ rb_ary_resurrect()

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().

This makes the most sense when the passed array is formerly hidden by rb_obj_hide().

Parameters

[in] ary An array, possibly hidden.

Returns: A duplicated new instance of rb_cArray.

Definition at line 2790 of file array.c.

◆ rb_ary_reverse()

VALUE rb_ary_reverse ( VALUE ary )

Destructively reverses the passed array in-place.

Warning: This is Array#reverse!, not Array#reverse.

Parameters

[out] ary Target array to modify.

Exceptions

rb_eFrozenError ary is frozen.

Returns: Passed ary.

Postcondition: ary is reversed.

Definition at line 3119 of file array.c.

◆ rb_ary_rotate()

VALUE rb_ary_rotate	(	VALUE	ary,
		long	rot
	)

Destructively rotates the passed array in-place to towards its end.

The amount can be negative. Would rotate to the opposite direction then.

Warning: This is Array#rotate!, not Array#rotate.

Parameters

[out]	ary	Target array to modify.
[in]	rot	Amount of rotation.

Exceptions

rb_eFrozenError ary is frozen.

Return values

RUBY_Qnil	Not rotated.
ary	Rotated.

Postcondition: ary is rotated.

Definition at line 3208 of file array.c.

◆ rb_ary_shared_with_p()

VALUE rb_ary_shared_with_p	(	VALUE	lhs,
		VALUE	rhs
	)

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.

Parameters

[in]	lhs	Comparison LHS.
[in]	rhs	Comparison RHS.

Return values

RUBY_Qtrue	They share the same backend storage.
RUBY_Qfalse	They are distinct.

Precondition: Both arguments must be of RUBY_T_ARRAY.

Definition at line 669 of file array.c.

◆ rb_ary_shift()

VALUE rb_ary_shift ( VALUE ary )

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.

Parameters

[out] ary Target array to modify.

Exceptions

rb_eFrozenError ary is frozen.

Returns: What was at the beginning of ary, or RUBY_Qnil if there is nothing to remove.

Postcondition: ary's first element, if any, is removed. As the name implies everything else remaining in ary gets moved towards ary's beginning.

Note: There is no way to distinguish whether ary was an 1-element array whose content was RUBY_Qnil, or was empty.

Definition at line 1496 of file array.c.

◆ rb_ary_sort()

VALUE rb_ary_sort ( VALUE ary )

Creates a copy of the passed array, whose elements are sorted according to their <=> result.

Parameters

[in] ary Array to sort.

Exceptions

rb_eArgError	Comparison not defined among elements.
rb_eRuntimeError	Infinite recursion in `<=>`.

Returns: A copy of ary, sorted.

Note: As of writing this function uses qsort as backend algorithm, which means the result is unstable (in terms of sort stability).

Definition at line 3487 of file array.c.

◆ rb_ary_sort_bang()

VALUE rb_ary_sort_bang ( VALUE ary )

Destructively sorts the passed array in-place, according to each elements' <=> result.

Parameters

[in] ary Target array to modify.

Exceptions

rb_eArgError	Comparison not defined among elements.
rb_eRuntimeError	Infinite recursion in `<=>`.

Returns: Passed ary.

Postcondition: ary is sorted.

Note: As of writing this function uses qsort as backend algorithm, which means the result is unstable (in terms of sort stability).

Definition at line 3394 of file array.c.

Referenced by rb_ary_sort().

◆ rb_ary_store()

void rb_ary_store	(	VALUE	ary,
		long	key,
		VALUE	val
	)

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.

Parameters

[out]	ary	Target array to modify.
[in]	key	Where to store `val`.
[in]	val	What to store at `key`.

Exceptions

rb_eFrozenError	`ary` is frozen.
rb_eIndexError	`key` is negative.

Postcondition: ary's keyth position is occupied with val.; Depending on 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 1207 of file array.c.

Referenced by rb_ary_delete().

◆ rb_ary_subseq()

VALUE rb_ary_subseq	(	VALUE	ary,
		long	beg,
		long	len
	)

Obtains a part of the passed array.

Parameters

[in]	ary	Target array.
[in]	beg	Subpart index.
[in]	len	Requested length of returning array.

Return values

RUBY_Qnil	Requested range out of bounds of `ary`.
otherwise	An allocated new array whose contents are `ary`'s `beg` to `len`.

Note: Return array can be shorter than len when for instance [0, 1, 2, 3]'s 4th to 1,000,000,000th is requested.

Definition at line 1765 of file array.c.

Referenced by rb_apply().

◆ rb_ary_to_ary()

VALUE rb_ary_to_ary ( VALUE obj )

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.

Parameters

[in] obj Arbitrary ruby object.

Returns: An array representation of obj.

Note: Unlike rb_str_to_str() which is a variant of rb_check_string_type(), rb_ary_to_ary() is not a variant of rb_check_array_type().

Definition at line 2197 of file array.c.

◆ rb_ary_to_s()

VALUE rb_ary_to_s ( VALUE ary )

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.

Parameters

[in] ary Array to inspect.

Returns: Recursively inspected representation of ary.

See also: [ruby-dev:29520]

Definition at line 3013 of file array.c.

◆ rb_ary_unshift()

VALUE rb_ary_unshift	(	VALUE	ary,
		VALUE	elem
	)

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.

Parameters

[out]	ary	Target array to modify.
[in]	elem	Arbitrary ruby object to unshift.

Exceptions

rb_eFrozenError ary is frozen.

Returns: The passed ary.

Postcondition: ary has elem prepended at this beginning.

Definition at line 1719 of file array.c.

◆ rb_assoc_new()

VALUE rb_assoc_new	(	VALUE	car,
		VALUE	cdr
	)

Identical to rb_ary_new_from_values(), except it expects exactly two parameters.

Parameters

[in]	car	Arbitrary ruby object.
[in]	cdr	Arbitrary ruby object.

Returns: An allocated new array, of length 2, whose contents are the passed objects.

Definition at line 1001 of file array.c.

Referenced by rb_big_divmod().

◆ rb_check_array_type()

VALUE rb_check_array_type ( VALUE obj )

Try converting an object to its array representation using its to_ary method, if any.

If there is no such thing, returns RUBY_Qnil.

Parameters

[in] obj Arbitrary ruby object to convert.

Exceptions

rb_eTypeError obj.to_ary returned something non-Array.

Return values

RUBY_Qnil	No conversion from `obj` to array defined.
otherwise	Converted array representation of `obj`.

See also: rb_io_check_io; rb_check_string_type; rb_check_hash_type

Definition at line 1014 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().

◆ rb_get_values_at()

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.

Parameters

[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.

Returns: A new instance of rb_cArray gathering funcoutputs.

◆ rb_mem_clear()

void rb_mem_clear	(	VALUE *	buf,
		long	len
	)

Fills the memory region with a series of RUBY_Qnil.

Parameters

[out]	buf	Buffer to squash.
[in]	len	Number of objects of `buf`.

Postcondition: buf is filled with RUBY_Qnil.

Definition at line 294 of file array.c.

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

Macros

Functions

Detailed Description

Function Documentation

◆ rb_ary_aref()

◆ rb_ary_assoc()

◆ rb_ary_cat()

◆ rb_ary_clear()

◆ rb_ary_cmp()

◆ rb_ary_concat()

◆ rb_ary_delete()

◆ rb_ary_delete_at()

◆ rb_ary_dup()

◆ rb_ary_each()

◆ rb_ary_entry()

◆ rb_ary_free()

◆ rb_ary_freeze()

◆ rb_ary_hidden_new()

◆ rb_ary_includes()

◆ rb_ary_join()

◆ rb_ary_modify()

◆ rb_ary_new()

◆ rb_ary_new_capa()

◆ rb_ary_new_from_args()

◆ rb_ary_new_from_values()

◆ 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_shared_with_p()

◆ rb_ary_shift()

◆ rb_ary_sort()

◆ rb_ary_sort_bang()

◆ rb_ary_store()

◆ rb_ary_subseq()

◆ rb_ary_to_ary()

◆ rb_ary_to_s()

◆ rb_ary_unshift()

◆ rb_assoc_new()

◆ rb_check_array_type()

◆ rb_get_values_at()

◆ rb_mem_clear()