C API/Array

The functions described here create and manipulate arrays.

Creating an array
and  creates a new array with zero elements. also reserves space for  elements, but the reported size is still zero.

creates a new array with  elements. is followed by  instances of , each designating an element of the new array.

creates a new array with  elements. The C array  has   elements, each designating an element of the new array.

The return value is the new array.

returns a shallow copy of the array.

creates a two element array, whose elements are  and.

The return value is the new array.

creates an array by calling  once for each   from 0 to. If a Range is encountered,  is called for each   in the Range. The objects returned by  populate the array in the order in which they are called.

The return value is the new array.

Type checking and conversion
checks that  is in fact an array, or convertible to an array via a   method. If so, it returns the resulting array; otherwise, it returns.

checks that  is in fact an array, or convertible to an array via a   method. If so, it returns the resulting array; otherwise, it returns a new array whose single element is.

.

Setting array elements
stores the value  into the array   at index. Negative indexes count from the end of the array.

prefixes the object  to the start of the array.

The return value is, mainly because this function implements the   method.

appends the object  to the end of the array.

The return value is, mainly because this function implements the   method.

replaces the elements of  with those of , so that   is a shallow copy of.

Retrieving array elements
retrieves the element from  at index. Negative indexes count from the end of the array.

removes the first element from  and returns it. then has one less element than before, and the remaining elements appear at an index one less than before.

removes the last element from  and returns it. then has one less element than before.

returns a new array containing  elements, copied from   starting at index. Negative indexes are not supported; if  is negative or out of bounds, or   is negative,   returns. If  exceeds the end of the array, the returned array will have fewer than   elements.

implements the  method.

returns an Enumerator over the array ; or, if a block is given, it calls the block once for each element of the array, passing the elements of the array in order, one per call, and returns.

Removing elements from an array
removes elements from  that are equal to. The return value is  if any matches are found, or   if not.

If a block is given and there are no matches,  calls the block and returns the return value of the block.

removes the element at position  in the array , shifts all following elements downward one position, and returns the deleted element, or returns   if   is out of bounds. Negative indexes count from the end of the array.

deletes all elements of the array, and returns.

Operations on arrays
returns a String, consisting of the string representations of each element of, joined by the String.

reverses the order of the elements of  in place.

returns a copy of, comparing them according to their own   method, or according to a block if one is provided. is similar, except that it sorts  in place and returns.

returns a new array consisting of array  concatenated with array.

appends the contents of the array  to those of. It differs from  in that it modifies   in place.

scans through the array, from beginning to end, and assumes that the elements of   are themselves arrays; it returns the first such array whose first element matches.

is similar, but matches the second element of each array. It is intended for use with two-element arrays, such as are created by.

The return value is  if no element matches.

returns  if the item   is present in the array , else. Use RTEST to convert the return value to a C Boolean.

compares  to   by comparing the corresponding elements, beginning with 0. It returns a Fixnum corresponding to -1, 0, or +1 to indicate the result of the comparison, with a longer array being considered greater than a shorter one if no other mismatch is found. If  is not an array, the return value is  ...

Freezing
freezes the object. This is presently equivalent to.

Uncategorized
sets each of  elements of   to. It is not clear that this function is meant to be called by extensions.

creates a new array and reserves space for  elements. It differs from  in that it does not use   as a base class, but uses   instead. This is likely not meant to be called by extensions.

frees memory attached to. This is likely not meant to be called by extensions.