diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2020-08-10 11:33:31 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-08-10 11:33:31 -0500 |
commit | c303e21d5222aa10cd1649198893d5bf0da3b63a (patch) | |
tree | 4f4c870011c2dff7b33219b109f9be1b99890357 /array.c | |
parent | 0ca6b973e89889f1ce0dbbc05da780cb75776bfe (diff) | |
download | ruby-c303e21d5222aa10cd1649198893d5bf0da3b63a.tar.gz |
Enhanced RDoc for Array (#3400)
Methods:
drop
drop_while
any?
all?
none?
one?
Diffstat (limited to 'array.c')
-rw-r--r-- | array.c | 208 |
1 files changed, 180 insertions, 28 deletions
@@ -8272,18 +8272,32 @@ rb_ary_take_while(VALUE ary) /* * call-seq: - * ary.drop(n) -> new_ary + * array.drop(n) -> new_array * - * Drops first +n+ elements from +ary+ and returns the rest of the elements in - * an array. + * Returns a new \Array containing all but the first +n+ element of +self+; + * does not modify +self+. + * + * Argument +n+ must be an + * {Integer-convertible object}[doc/implicit_conversion_rdoc.html#label-Integer-Convertible+Objects] + * and non-negative. * - * If a negative number is given, raises an ArgumentError. + * Examples: + * a = [0, 1, 2, 3, 4, 5] + * a.drop(0) # => [0, 1, 2, 3, 4, 5] + * a.drop(1) # => [1, 2, 3, 4, 5] + * a.drop(2) # => [2, 3, 4, 5] + * a.drop(50) # => [] + * a # => [0, 1, 2, 3, 4, 5] * - * See also Array#take + * --- * - * a = [1, 2, 3, 4, 5, 0] - * a.drop(3) #=> [4, 5, 0] + * Raises an exception if +n+ is negative: + * # Raises ArgumentError (attempt to drop negative size): + * [0, 1].drop(-1) * + * Raises an exception if +n+ is not an Integer-convertible object: + * # Raises TypeError (no implicit conversion of Symbol into Integer): + * [0, 1].drop(:foo) */ static VALUE @@ -8302,20 +8316,22 @@ rb_ary_drop(VALUE ary, VALUE n) /* * call-seq: - * ary.drop_while {|obj| block} -> new_ary - * ary.drop_while -> Enumerator - * - * Drops elements up to, but not including, the first element for which the - * block returns +nil+ or +false+ and returns an array containing the - * remaining elements. - * - * If no block is given, an Enumerator is returned instead. - * - * See also Array#take_while + * array.drop_while {|element| ... } -> new_array + * array.drop_while -> new_enumerator + + * Returns a new \Array containing zero or more trailing elements of +self+; + * does not modify +self+. * - * a = [1, 2, 3, 4, 5, 0] - * a.drop_while {|i| i < 3 } #=> [3, 4, 5, 0] + * With a block given, calls the block with each successive element of +self+; + * stops if the block returns +false+ or +nil+; + * returns a new Array _omitting_ those elements for which the block returned a truthy value: + * a = [0, 1, 2, 3, 4, 5] + * a.drop_while {|element| element < 3 } # => [3, 4, 5] + * a.drop_while {|element| true } # => [] + * a.drop_while {|element| false } # => [0, 1, 2, 3, 4, 5] * + * With no block given, returns a new \Enumerator: + * [0, 1].drop_while # => # => #<Enumerator: [0, 1]:drop_while> */ static VALUE @@ -8332,10 +8348,47 @@ rb_ary_drop_while(VALUE ary) /* * call-seq: - * ary.any? [{|obj| block} ] -> true or false - * ary.any?(pattern) -> true or false + * array.any? -> true or false + * array.any? {|element| ... } -> true or false + * array.any?(obj) -> true or false + * + * Returns +true+ if any element of +self+ meets a given criterion. + * + * The argument, if given, must have instance method <tt>===</tt>. + * + * With no block given and no argument, returns +true+ if +self+ has any truthy element, + * +false+ otherwise: + * [nil, 0, false].any? # => true + * [nil, false].any? # => false + * [].any? # => false + * + * With a block given and no argument, calls the block with each element in +self+; + * returns +true+ if the block returns any truthy value, +false+ otherwise: + * [0, 1, 2].any? {|element| element > 1 } # => true + * [0, 1, 2].any? {|element| element > 2 } # => false + * + * Does not call the block if +self+ is empty: + * [].any? {|element| fail 'Cannot happen' } # => false + * + * If argument +obj+ is given, returns +true+ if +obj+.<tt>===</tt> any element, + * +false+ otherwise: + * ['food', 'drink'].any?(/foo/) # => true + * ['food', 'drink'].any?(/bar/) # => false + * [].any?(/foo/) # => false + * [0, 1, 2].any?(1) # => true + * [0, 1, 2].any?(3) # => false + * + * Issues a warning ('given block not used') + * if both an argument and a block given: + * [0, 1, 2].any?(/foo/) {|element|} # => false * * See also Enumerable#any? + * + * --- + * + * Raises an exception if the argument does not have instance method <tt>===</tt>: + * # Raises NoMethodError (undefined method `===' for #<BasicObject:>): + * [0, 1, 2].any?(BasicObject.new) */ static VALUE @@ -8368,8 +8421,45 @@ rb_ary_any_p(int argc, VALUE *argv, VALUE ary) /* * call-seq: - * ary.all? [{|obj| block} ] -> true or false - * ary.all?(pattern) -> true or false + * array.all? -> true or false + * array.all? {|element| ... } -> true or false + * array.all?(obj) -> true or false + * + * Returns +true+ if all elements of +self+ meet a given criterion. + * + * The argument, if given, must have instance method <tt>===</tt>. + * + * With no block given and no argument, returns +true+ if +self+ contains only truthy elements, + * +false+ otherwise: + * [0, 1, :foo].all? # => true + * [0, nil, 2].all? # => false + * [].all? # => true + * + * With a block given and no argument, calls the block with each element in +self+; + * returns +true+ if the block returns only truthy values, +false+ otherwise: + * [0, 1, 2].all? { |element| element < 3 } # => true + * [0, 1, 2].all? { |element| element < 2 } # => false + * + * Does not call the block if +self+ is empty: + * [].all? { |element| fail 'Cannot happen' } # => true + * + * If argument +obj+ is given, returns +true+ if <tt>obj.===</tt> every element, +false+ otherwise: + * ['food', 'fool', 'foot'].all?(/foo/) # => true + * ['food', 'drink'].all?(/bar/) # => false + * [].all?(/foo/) # => true + * [0, 0, 0].all?(0) # => true + * [0, 1, 2].all?(1) # => false + * + * Issues a warning ('warning: given block not used') if both an argument and a block given: + * [0, 1, 2].all?(/foo/) { |element|} # => false + * + * See also Enumerable#all? + * + * --- + * + * Raises an exception if the argument does not have instance method <tt>===<tt/>: + * # Raises NoMethodError (undefined method `===' for #<BasicObject:>): + * [0, 1, 2].all?(BasicObject.new) * * See also Enumerable#all? */ @@ -8404,8 +8494,37 @@ rb_ary_all_p(int argc, VALUE *argv, VALUE ary) /* * call-seq: - * ary.none? [{|obj| block} ] -> true or false - * ary.none?(pattern) -> true or false + * array.none? -> true or false + * array.none? {|element| ... } -> true or false + * array.none?(obj) -> true or false + * + * Returns +true+ if no element of +self+ meet a given criterion. + * + * The argument, if given, must have instance method <tt>===</tt>. + * + * With no block given and no argument, returns +true+ if +self+ has no truthy elements, + * +false+ otherwise: + * [nil, false].none? # => true + * [nil, 0, false].none? # => false + * [].none? # => true + * + * With a block given and no argument, calls the block with each element in +self+; + * returns +true+ if the block returns no truthy value, +false+ otherwise: + * [0, 1, 2].none? {|element| element > 3 } # => true + * [0, 1, 2].none? {|element| element > 1 } # => false + * + * Does not call the block if +self+ is empty: + * [].none? {|element| fail 'Cannot happen' } # => true + * + * If argument +obj+ is given, returns +true+ if <tt>obj.===</tt> no element, +false+ otherwise: + * ['food', 'drink'].none?(/bar/) # => true + * ['food', 'drink'].none?(/foo/) # => false + * [].none?(/foo/) # => true + * [0, 1, 2].none?(3) # => true + * [0, 1, 2].none?(1) # => false + * + * Issues a warning ('given block not used') if both an argument and a block given: + * [0, 1, 2].none?(/foo/) { |element| } # => true * * See also Enumerable#none? */ @@ -8440,10 +8559,43 @@ rb_ary_none_p(int argc, VALUE *argv, VALUE ary) /* * call-seq: - * ary.one? [{|obj| block} ] -> true or false - * ary.one?(pattern) -> true or false + * array.one? -> true or false + * array.one? {|element| ... } -> true or false + * array.one?(obj) -> true or false + * + * Returns +true+ if exactly one element of +self+ meets a given criterion. + * + * The argument, if given, must have instance method <tt>===</tt>. * - * See also Enumerable#one? + * With no block given and no argument, returns +true+ if +self+ has exactly one truthy element, + * +false+ otherwise: + * [nil, 0].one? # => true + * [0, 0].one? # => false + * [nil, nil].one? # => false + * [].one? # => false + * + * With a block given and no argument, calls the block with each element in +self+; + * returns +true+ if the block a truthy value for exactly one element, +false+ otherwise: + * [0, 1, 2].one? {|element| element > 0 } # => false + * [0, 1, 2].one? {|element| element > 1 } # => true + * [0, 1, 2].one? {|element| element > 2 } # => false + * + * Does not call the block if +self+ is empty: + * [].one? {|element| fail 'Cannot happen' } # => false + * + * If argument +obj+ is given, returns +true+ if <tt>obj.===</tt> exactly one element, + * +false+ otherwise: + * [0, 1, 2].one?(0) # => true + * [0, 0, 1].one?(0) # => false + * [1, 1, 2].one?(0) # => false + * ['food', 'drink'].one?(/bar/) # => false + * ['food', 'drink'].one?(/foo/) # => true + * [].one?(/foo/) # => false + * + * Issues a warning ('given block not used') if both an argument and a block given: + * [0, 1, 2].one?(/foo/) { |element| } # => false + * + * See also Enumerable#none? */ static VALUE |