summaryloggraphiclog1graphiclog2commitcommitdifftreerefseditfork
rawpatchinlineside by side (parent: b92ce6f)
rawpatchinlineside by side (parent: b92ce6f)
| author | Burdette Lamar <[email protected]> | |
| Thu, 7 Nov 2024 03:19:42 +0000 (6 21:19 -0600) | ||
| committer | GitHub <[email protected]> | |
| Thu, 7 Nov 2024 03:19:42 +0000 (6 22:19 -0500) |
| array.c | patchblobblamehistory |
--- a/array.c
+++ b/array.c
/*
* call-seq:
- * array.values_at(*indexes) -> new_array
+ * values_at(*specifiers) -> new_array
*
- * Returns a new +Array+ whose elements are the elements
- * of +self+ at the given Integer or Range +indexes+.
+ * Returns elements from +self+ in a new array; does not modify +self+.
*
- * For each positive +index+, returns the element at offset +index+:
+ * The objects included in the returned array are the elements of +self+
+ * selected by the given +specifiers+,
+ * each of which must be a numeric index or a Range.
*
- * a = [:foo, 'bar', 2]
- * a.values_at(0, 2) # => [:foo, 2]
- * a.values_at(0..1) # => [:foo, "bar"]
+ * In brief:
*
- * The given +indexes+ may be in any order, and may repeat:
+ * a = ['a', 'b', 'c', 'd']
*
- * a = [:foo, 'bar', 2]
- * a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2]
- * a.values_at(1, 0..2) # => ["bar", :foo, "bar", 2]
+ * # Index specifiers.
+ * a.values_at(2, 0, 2, 0) # => ["c", "a", "c", "a"] # May repeat.
+ * a.values_at(-4, -3, -2, -1) # => ["a", "b", "c", "d"] # Counts backwards if negative.
+ * a.values_at(-50, 50) # => [nil, nil] # Outside of self.
*
- * Assigns +nil+ for an +index+ that is too large:
+ * # Range specifiers.
+ * a.values_at(1..3) # => ["b", "c", "d"] # From range.begin to range.end.
+ * a.values_at(1...3) # => ["b", "c"] # End excluded.
+ * a.values_at(3..1) # => [] # No such elements.
*
- * a = [:foo, 'bar', 2]
- * a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]
+ * a.values_at(-3..3) # => ["b", "c", "d"] # Negative range.begin counts backwards.
+ * a.values_at(-50..3) # Raises RangeError.
*
- * Returns a new empty +Array+ if no arguments given.
+ * a.values_at(1..-2) # => ["b", "c"] # Negative range.end counts backwards.
+ * a.values_at(1..-50) # => [] # No such elements.
*
- * For each negative +index+, counts backward from the end of the array:
+ * # Mixture of specifiers.
+ * a.values_at(2..3, 3, 0..1, 0) # => ["c", "d", "d", "a", "b", "a"]
*
- * a = [:foo, 'bar', 2]
- * a.values_at(-1, -3) # => [2, :foo]
+ * With no +specifiers+ given, returns a new empty array:
*
- * Assigns +nil+ for an +index+ that is too small:
+ * a = ['a', 'b', 'c', 'd']
+ * a.values_at # => []
*
- * a = [:foo, 'bar', 2]
- * a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]
+ * For each numeric specifier +index+, includes an element:
*
- * The given +indexes+ may have a mixture of signs:
+ * - For each non-negative numeric specifier +index+ that is in-range (less than <tt>self.size</tt>),
+ * includes the element at offset +index+:
*
- * a = [:foo, 'bar', 2]
- * a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]
+ * a.values_at(0, 2) # => ["a", "c"]
+ * a.values_at(0.1, 2.9) # => ["a", "c"]
+ *
+ * - For each negative numeric +index+ that is in-range (greater than or equal to <tt>- self.size</tt>),
+ * counts backwards from the end of +self+:
+ *
+ * a.values_at(-1, -4) # => ["d", "a"]
+ *
+ * The given indexes may be in any order, and may repeat:
+ *
+ * a.values_at(2, 0, 1, 0, 2) # => ["c", "a", "b", "a", "c"]
+ *
+ * For each +index+ that is out-of-range, includes +nil+:
+ *
+ * a.values_at(4, -5) # => [nil, nil]
+ *
+ * For each Range specifier +range+, includes elements
+ * according to <tt>range.begin</tt> and <tt>range.end</tt>:
+ *
+ * - If both <tt>range.begin</tt> and <tt>range.end</tt>
+ * are non-negative and in-range (less than <tt>self.size</tt>),
+ * includes elements from index <tt>range.begin</tt>
+ * through <tt>range.end - 1</tt> (if <tt>range.exclude_end?</tt>),
+ * or through <tt>range.end</tt> (otherwise):
*
+ * a.values_at(1..2) # => ["b", "c"]
+ * a.values_at(1...2) # => ["b"]
+ *
+ * - If <tt>range.begin</tt> is negative and in-range (greater than or equal to <tt>- self.size</tt>),
+ * counts backwards from the end of +self+:
+ *
+ * a.values_at(-2..3) # => ["c", "d"]
+ *
+ * - If <tt>range.begin</tt> is negative and out-of-range, raises an exception:
+ *
+ * a.values_at(-5..3) # Raises RangeError.
+ *
+ * - If <tt>range.end</tt> is positive and out-of-range,
+ * extends the returned array with +nil+ elements:
+ *
+ * a.values_at(1..5) # => ["b", "c", "d", nil, nil]
+ *
+ * - If <tt>range.end</tt> is negative and in-range,
+ * counts backwards from the end of +self+:
+ *
+ * a.values_at(1..-2) # => ["b", "c"]
+ *
+ * - If <tt>range.end</tt> is negative and out-of-range,
+ * returns an empty array:
+ *
+ * a.values_at(1..-5) # => []
+ *
+ * The given ranges may be in any order and may repeat:
+ *
+ * a.values_at(2..3, 0..1, 2..3) # => ["c", "d", "a", "b", "c", "d"]
+ *
+ * The given specifiers may be any mixture of indexes and ranges:
+ *
+ * a.values_at(3, 1..2, 0, 2..3) # => ["d", "b", "c", "a", "c", "d"]
+ *
+ * Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching].
*/
static VALUE