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

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

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)
| Just another name of rb_obj_freeze.
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 1977 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 5228 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 1496 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 4791 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 5503 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 5145 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 4177 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 4231 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 2894 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 2734 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 1836 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 998 of file array.c.

## ◆ rb_ary_freeze()

VALUE rb_ary_freeze | ( | VALUE | obj | ) |

Just another name of rb_obj_freeze.

Definition at line 770 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 981 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 5422 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 3008 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 701 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 865 of file array.c.

## ◆ 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 859 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 870 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 904 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 5085 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 1534 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 1483 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 5258 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 4735 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 2420 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 2907 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 3238 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 3325 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 783 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 1600 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 3673 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 3572 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 `key`th 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 1313 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 1864 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 2326 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 3128 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 1818 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 1116 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 1129 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 `func`outputs.

Definition at line 3874 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 331 of file array.c.