зеркало из https://github.com/github/ruby.git
[ci skip] Enhanced RDoc for Array (#3252)
Methods:
map/collect
map!/collect!
values_at
select/filter
select!/filter!
This commit is contained in:
Burdette Lamar
GitHub
Родитель
3d8705dcfd
Коммит
5e860ed4c1
217
array.c
217
array.c
|
|
@ -1253,7 +1253,7 @@ ary_take_first_or_last(int argc, const VALUE *argv, VALUE ary, enum ary_take_pos
|
|||
* Appends +object+ as one element, even if it is another \Array:
|
||||
*
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a1 = a << [3, 4] # =>
|
||||
* a1 = a << [3, 4]
|
||||
* a1 # => [:foo, "bar", 2, [3, 4]]
|
||||
*/
|
||||
|
||||
|
|
@ -1285,7 +1285,9 @@ rb_ary_cat(VALUE ary, const VALUE *argv, long len)
|
|||
* array.push(*objects) -> self
|
||||
* array.append(*objects) -> self
|
||||
*
|
||||
* Appends trailing elements. #append is an alias for \#push.
|
||||
* Appends trailing elements.
|
||||
*
|
||||
* Array#append is an alias for \Array#push.
|
||||
|
||||
* See also:
|
||||
* - #pop: Removes and returns trailing elements.
|
||||
|
|
@ -1622,7 +1624,9 @@ ary_ensure_room_for_unshift(VALUE ary, int argc)
|
|||
* array.unshift(*objects) -> self
|
||||
* array.prepend(*objects) -> self
|
||||
*
|
||||
* Prepends leading elements. #prepend is an alias for \#unshift.
|
||||
* Prepends leading elements.
|
||||
*
|
||||
* Array#prepend is an alias for \Array#unshift.
|
||||
*
|
||||
* See also:
|
||||
* - #push: Appends trailing elements.
|
||||
|
|
@ -2080,7 +2084,7 @@ rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
|
|||
* array.find_index {|element| ... } -> integer or nil
|
||||
* array.find_index -> new_enumerator
|
||||
*
|
||||
* Array#index is an alias for Array#find_index.
|
||||
* Array#find_index is an alias for Array#index.
|
||||
* See also Array#rindex.
|
||||
*
|
||||
* ---
|
||||
|
|
@ -3850,18 +3854,28 @@ sort_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, dummy))
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* ary.sort_by! {|obj| block} -> ary
|
||||
* ary.sort_by! -> Enumerator
|
||||
* array.sort_by! {|element| ... } -> self
|
||||
* array.sort_by! -> new_enumerator
|
||||
*
|
||||
* Sorts +self+ in place using a set of keys generated by mapping the
|
||||
* values in +self+ through the given block.
|
||||
* Sorts the elements of +self+ in place,
|
||||
* using an ordering determined by the block; returns self.
|
||||
*
|
||||
* The result is not guaranteed to be stable. When two keys are equal,
|
||||
* the order of the corresponding elements is unpredictable.
|
||||
* Calls the block with each successive element;
|
||||
* sorts elements based on the values returned from the block.
|
||||
*
|
||||
* If no block is given, an Enumerator is returned instead.
|
||||
* For duplicates returned by the block, the ordering is indeterminate, and may be unstable.
|
||||
*
|
||||
* See also Enumerable#sort_by.
|
||||
* This example sorts strings based on their sizes:
|
||||
* a = ['aaaa', 'bbb', 'cc', 'd']
|
||||
* a.sort_by! {|element| element.size }
|
||||
* a # => ["d", "cc", "bbb", "aaaa"]
|
||||
*
|
||||
* ---
|
||||
*
|
||||
* Returns a new \Enumerator if no block given:
|
||||
*
|
||||
* a = ['aaaa', 'bbb', 'cc', 'd']
|
||||
* a.sort_by! # => #<Enumerator: ["aaaa", "bbb", "cc", "d"]:sort_by!>
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -3879,23 +3893,25 @@ rb_ary_sort_by_bang(VALUE ary)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* ary.collect {|item| block} -> new_ary
|
||||
* ary.map {|item| block} -> new_ary
|
||||
* ary.collect -> Enumerator
|
||||
* ary.map -> Enumerator
|
||||
* array.map {|element| ... } -> new_array
|
||||
* array.map -> new_enumerator
|
||||
* array.collect {|element| ... } -> new_array
|
||||
* array.collect -> new_enumerator
|
||||
*
|
||||
* Invokes the given block once for each element of +self+.
|
||||
* Array#map is an alias for Array#collect.
|
||||
*
|
||||
* Creates a new array containing the values returned by the block.
|
||||
* Calls the block, if given, with each element of +self+;
|
||||
* returns a new \Array whose elements are the return values from the block:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a1 = a.collect {|element| element.class }
|
||||
* a1 # => [Symbol, String, Integer]
|
||||
*
|
||||
* See also Enumerable#collect.
|
||||
* ---
|
||||
*
|
||||
* If no block is given, an Enumerator is returned instead.
|
||||
*
|
||||
* a = [ "a", "b", "c", "d" ]
|
||||
* a.collect {|x| x + "!"} #=> ["a!", "b!", "c!", "d!"]
|
||||
* a.map.with_index {|x, i| x * i} #=> ["", "b", "cc", "ddd"]
|
||||
* a #=> ["a", "b", "c", "d"]
|
||||
* Returns a new \Enumerator if no block given:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a1 = a.collect
|
||||
* a1 # => #<Enumerator: [:foo, "bar", 2]:collect>
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -3915,23 +3931,26 @@ rb_ary_collect(VALUE ary)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* ary.collect! {|item| block } -> ary
|
||||
* ary.map! {|item| block } -> ary
|
||||
* ary.collect! -> Enumerator
|
||||
* ary.map! -> Enumerator
|
||||
* array.map! {|element| ... } -> self
|
||||
* array.map! -> new_enumerator
|
||||
* array.collect! {|element| ... } -> self
|
||||
* array.collect! -> new_enumerator
|
||||
*
|
||||
* Invokes the given block once for each element of +self+, replacing the
|
||||
* element with the value returned by the block.
|
||||
* Array#map! is an alias for Array#collect!.
|
||||
*
|
||||
* See also Enumerable#collect.
|
||||
* Calls the block, if given, with each element;
|
||||
* replaces the element with the block's return value:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a1 = a.collect! { |element| element.class }
|
||||
* a1 # => [Symbol, String, Integer]
|
||||
* a1.equal?(a) # => true # Returned self
|
||||
*
|
||||
* If no block is given, an Enumerator is returned instead.
|
||||
* ---
|
||||
*
|
||||
* a = [ "a", "b", "c", "d" ]
|
||||
* a.map! {|x| x + "!" }
|
||||
* a #=> [ "a!", "b!", "c!", "d!" ]
|
||||
* a.collect!.with_index {|x, i| x[0...i] }
|
||||
* a #=> ["", "b", "c!", "d!"]
|
||||
* Returns a new \Enumerator if no block given:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a1 = a.collect!
|
||||
* a1 # => #<Enumerator: [:foo, "bar", 2]:collect!>
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -4003,20 +4022,51 @@ append_values_at_single(VALUE result, VALUE ary, long olen, VALUE idx)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* ary.values_at(selector, ...) -> new_ary
|
||||
* array.values_at(*indexes) -> new_array
|
||||
*
|
||||
* Returns an array containing the elements in +self+ corresponding to the
|
||||
* given +selector+(s).
|
||||
* Returns a new \Array whose elements are the elements
|
||||
* of +self+ at the given +indexes+.
|
||||
*
|
||||
* The selectors may be either integer indices or ranges.
|
||||
* Each +index+ given in +indexes+ must be an
|
||||
* {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects].
|
||||
*
|
||||
* See also Array#select.
|
||||
* ---
|
||||
*
|
||||
* a = %w{ a b c d e f }
|
||||
* a.values_at(1, 3, 5) # => ["b", "d", "f"]
|
||||
* a.values_at(1, 3, 5, 7) # => ["b", "d", "f", nil]
|
||||
* a.values_at(-1, -2, -2, -7) # => ["f", "e", "e", nil]
|
||||
* a.values_at(4..6, 3...6) # => ["e", "f", nil, "d", "e", "f"]
|
||||
* For each positive +index+, returns the element at offset +index+:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a.values_at(0, 2) # => [:foo, 2]
|
||||
*
|
||||
* The given +indexes+ may be in any order, and may repeat:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a.values_at(2, 0, 1, 0, 2) # => [2, :foo, "bar", :foo, 2]
|
||||
*
|
||||
* Assigns +nil+ for an +index+ that is too large:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a.values_at(0, 3, 1, 3) # => [:foo, nil, "bar", nil]
|
||||
*
|
||||
* Returns a new empty \Array if no arguments given:
|
||||
* [].values_at # => []
|
||||
*
|
||||
* ---
|
||||
*
|
||||
* For each negative +index+, counts backward from the end of the array:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a.values_at(-1, -3) # => [2, :foo]
|
||||
*
|
||||
* Assigns +nil+ for an +index+ that is too small:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a.values_at(0, -5, 1, -6, 2) # => [:foo, nil, "bar", nil, 2]
|
||||
*
|
||||
* The given +indexes+ may have a mixture of signs:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* a.values_at(0, -2, 1, -1) # => [:foo, "bar", "bar", 2]
|
||||
*
|
||||
* ---
|
||||
*
|
||||
* Raises an exception if any +index+ is not an Integer-convertible object:
|
||||
* a = [:foo, 'bar', 2]
|
||||
* # Raises TypeError (no implicit conversion of Symbol into Integer):
|
||||
* a.values_at(0, :foo)
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -4034,24 +4084,25 @@ rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* ary.select {|item| block} -> new_ary
|
||||
* ary.select -> Enumerator
|
||||
* ary.filter {|item| block} -> new_ary
|
||||
* ary.filter -> Enumerator
|
||||
*
|
||||
* Returns a new array containing all elements of +ary+
|
||||
* for which the given +block+ returns a true value.
|
||||
*
|
||||
* If no block is given, an Enumerator is returned instead.
|
||||
*
|
||||
* [1,2,3,4,5].select {|num| num.even? } #=> [2, 4]
|
||||
*
|
||||
* a = %w[ a b c d e f ]
|
||||
* a.select {|v| v =~ /[aeiou]/ } #=> ["a", "e"]
|
||||
*
|
||||
* See also Enumerable#select.
|
||||
* array.select {|element| ... } -> new_array
|
||||
* array.select -> new_enumerator
|
||||
* array.filter {|element| ... } -> new_array
|
||||
* array.filter -> new_enumerator
|
||||
*
|
||||
* Array#filter is an alias for Array#select.
|
||||
*
|
||||
* Calls the block, if given, with each element of +self+;
|
||||
* returns a new \Array containing those elements of +self+
|
||||
* for which the block returns a truthy value:
|
||||
* a = [:foo, 'bar', 2, :bam]
|
||||
* a1 = a.select {|element| element.to_s.start_with?('b') }
|
||||
* a1 # => ["bar", :bam]
|
||||
*
|
||||
* ---
|
||||
*
|
||||
* Returns a new \Enumerator if no block given:
|
||||
* a = [:foo, 'bar', 2, :bam]
|
||||
* a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select>
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -4116,23 +4167,31 @@ select_bang_ensure(VALUE a)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* ary.select! {|item| block } -> ary or nil
|
||||
* ary.select! -> Enumerator
|
||||
* ary.filter! {|item| block } -> ary or nil
|
||||
* ary.filter! -> Enumerator
|
||||
*
|
||||
* Invokes the given block passing in successive elements from +self+,
|
||||
* deleting elements for which the block returns a +false+ value.
|
||||
*
|
||||
* The array may not be changed instantly every time the block is called.
|
||||
*
|
||||
* If changes were made, it will return +self+, otherwise it returns +nil+.
|
||||
*
|
||||
* If no block is given, an Enumerator is returned instead.
|
||||
*
|
||||
* See also Array#keep_if.
|
||||
* array.select! {|element| ... } -> self or nil
|
||||
* array.select! -> new_enumerator
|
||||
* array.filter! {|element| ... } -> self or nil
|
||||
* array.filter! -> new_enumerator
|
||||
*
|
||||
* Array#filter! is an alias for Array#select!.
|
||||
*
|
||||
* Calls the block, if given with each element of +self+;
|
||||
* removes from +self+ those elements for which the block returns +false+ or +nil+.
|
||||
*
|
||||
* Returns +self+ if any elements were removed:
|
||||
* a = [:foo, 'bar', 2, :bam]
|
||||
* a1 = a.select! {|element| element.to_s.start_with?('b') }
|
||||
* a1 # => ["bar", :bam]
|
||||
* a1.equal?(a) # => true # Returned self
|
||||
*
|
||||
* Returns +nil+ if no elements were removed:
|
||||
* a = [:foo, 'bar', 2, :bam]
|
||||
* a.select! { |element| element.kind_of?(Object) } # => nil
|
||||
*
|
||||
* ---
|
||||
*
|
||||
* Returns a new \Enumerator if no block given:
|
||||
* a = [:foo, 'bar', 2, :bam]
|
||||
* a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!>
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче