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

Ruby 3.4.6p54 (2025-09-16 revision dbd83256b1cec76c69756ecb8758b9e1079833de)

Macros | Functions
array.h File Reference

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.
#define | rb_ary_new3 rb_ary_new_from_args
| Old name of rb_ary_new_from_args.
#define | rb_ary_new4 rb_ary_new_from_values
| Old name of rb_ary_new_from_values.

## Functions
void | rb_mem_clear (VALUE *buf, long len)
| Fills the memory region with a series of RUBY_Qnil.
VALUE | rb_assoc_new (VALUE car, VALUE cdr)
| Identical to rb_ary_new_from_values(), except it expects exactly two parameters.
VALUE | rb_check_array_type (VALUE obj)
| Try converting an object to its array representation using its to_ary method, if any.
VALUE | rb_ary_new (void)
| Allocates a new, empty array.
VALUE | rb_ary_new_capa (long capa)
| Identical to rb_ary_new(), except it additionally specifies how many rooms of objects it should allocate.
VALUE | rb_ary_new_from_args (long n,...)
| Constructs an array from the passed objects.
VALUE | rb_ary_new_from_values (long n, const VALUE *elts)
| Identical to rb_ary_new_from_args(), except how objects are passed.
VALUE | rb_ary_hidden_new (long capa)
| Allocates a hidden (no class) empty array.
void | rb_ary_free (VALUE ary)
| Destroys the given array for no reason.
void | rb_ary_modify (VALUE ary)
| Declares that the array is about to be modified.
VALUE | rb_ary_freeze (VALUE obj)
| Freeze an array, preventing further modifications.
VALUE | rb_ary_shared_with_p (VALUE lhs, VALUE rhs)
| Queries if the passed two arrays share the same backend storage.
VALUE | rb_ary_aref (int argc, const VALUE *argv, VALUE ary)
| Queries element(s) of an array.
VALUE | rb_ary_subseq (VALUE ary, long beg, long len)
| Obtains a part of the passed array.
void | rb_ary_store (VALUE ary, long key, VALUE val)
| Destructively stores the passed value to the passed array's passed index.
VALUE | rb_ary_dup (VALUE ary)
| Duplicates an array.
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().
VALUE | rb_ary_to_ary (VALUE obj)
| Force converts an object to an array.
VALUE | rb_ary_to_s (VALUE ary)
| Converts an array into a human-readable string.
VALUE | rb_ary_cat (VALUE ary, const VALUE *train, long len)
| Destructively appends multiple elements at the end of the array.
VALUE | rb_ary_push (VALUE ary, VALUE elem)
| Special case of rb_ary_cat() that it adds only one element.
VALUE | rb_ary_pop (VALUE ary)
| Destructively deletes an element from the end of the passed array and returns what was deleted.
VALUE | rb_ary_shift (VALUE ary)
| Destructively deletes an element from the beginning of the passed array and returns what was deleted.
VALUE | rb_ary_unshift (VALUE ary, VALUE elem)
| Destructively prepends the passed item at the beginning of the passed array.
VALUE | rb_ary_entry (VALUE ary, long off)
| Queries an element of an array.
VALUE | rb_ary_each (VALUE ary)
| Iteratively yields each element of the passed array to the implicitly passed block if any.
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.
VALUE | rb_ary_reverse (VALUE ary)
| Destructively reverses the passed array in-place.
VALUE | rb_ary_rotate (VALUE ary, long rot)
| Destructively rotates the passed array in-place to towards its end.
VALUE | rb_ary_sort (VALUE ary)
| Creates a copy of the passed array, whose elements are sorted according to their <=> result.
VALUE | rb_ary_sort_bang (VALUE ary)
| Destructively sorts the passed array in-place, according to each elements' <=> result.
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.
VALUE | rb_ary_delete_at (VALUE ary, long pos)
| Destructively removes an element which resides at the specific index of the passed array.
VALUE | rb_ary_clear (VALUE ary)
| Destructively removes everything form an array.
VALUE | rb_ary_plus (VALUE lhs, VALUE rhs)
| Creates a new array, concatenating the former to the latter.
VALUE | rb_ary_concat (VALUE lhs, VALUE rhs)
| Destructively appends the contents of latter into the end of former.
VALUE | rb_ary_assoc (VALUE alist, VALUE key)
| Looks up the passed key, assuming the passed array is an alist.
VALUE | rb_ary_rassoc (VALUE alist, VALUE key)
| Identical to rb_ary_assoc(), except it scans the passed array from the opposite direction.
VALUE | rb_ary_includes (VALUE ary, VALUE elem)
| Queries if the passed array has the passed entry.
VALUE | rb_ary_cmp (VALUE lhs, VALUE rhs)
| Recursively compares each elements of the two arrays one-by-one using <=>.
VALUE | rb_ary_replace (VALUE copy, VALUE orig)
| Replaces the contents of the former object with the contents of the latter.
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.
VALUE | rb_ary_resize (VALUE ary, long len)
| Expands or shrinks the passed array to the passed length.

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

## Macro Definition Documentation

## ◆ rb_ary_tmp_new

#define rb_ary_tmp_new rb_ary_hidden_new

Definition at line 117 of 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 1889 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 5152 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 1391 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 4729 of file array.c.

## ◆ 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 5455 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 5068 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 4048 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 4102 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 2771 of file array.c.

## ◆ 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 2635 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 1731 of file array.c.

## ◆ 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 869 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 642 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 853 of file array.c.

## ◆ 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 5367 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 2885 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 570 of file array.c.

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

## ◆ 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 735 of file array.c.

## ◆ 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 746 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 780 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 5005 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 1425 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 1378 of file array.c.

## ◆ 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 5184 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 4674 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 2290 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 2784 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 3113 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 3202 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 663 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 1490 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 3481 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 3388 of file array.c.

## ◆ 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 1201 of file array.c.

## ◆ 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 1759 of file array.c.

## ◆ 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 2191 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 3007 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 1713 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 995 of file array.c.

## ◆ 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 1008 of file array.c.

## ◆ rb_get_values_at()

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.

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.

Definition at line 3685 of file array.c.

## ◆ 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 288 of file array.c.