summaryrefslogtreecommitdiff
path: root/array.rb
diff options
context:
space:
mode:
Diffstat (limited to 'array.rb')
-rw-r--r--array.rb157
1 files changed, 154 insertions, 3 deletions
diff --git a/array.rb b/array.rb
index a43a3b27b1..8e809b35c9 100644
--- a/array.rb
+++ b/array.rb
@@ -1,5 +1,60 @@
class Array
# call-seq:
+ # array.each {|element| ... } -> self
+ # array.each -> Enumerator
+ #
+ # Iterates over array elements.
+ #
+ # When a block given, passes each successive array element to the block;
+ # returns +self+:
+ #
+ # a = [:foo, 'bar', 2]
+ # a.each {|element| puts "#{element.class} #{element}" }
+ #
+ # Output:
+ #
+ # Symbol foo
+ # String bar
+ # Integer 2
+ #
+ # Allows the array to be modified during iteration:
+ #
+ # a = [:foo, 'bar', 2]
+ # a.each {|element| puts element; a.clear if element.to_s.start_with?('b') }
+ #
+ # Output:
+ #
+ # foo
+ # bar
+ #
+ # When no block given, returns a new Enumerator:
+ # a = [:foo, 'bar', 2]
+ #
+ # e = a.each
+ # e # => #<Enumerator: [:foo, "bar", 2]:each>
+ # a1 = e.each {|element| puts "#{element.class} #{element}" }
+ #
+ # Output:
+ #
+ # Symbol foo
+ # String bar
+ # Integer 2
+ #
+ # Related: #each_index, #reverse_each.
+ def each
+ Primitive.attr! :inline_block
+ unless defined?(yield)
+ return Primitive.cexpr! 'SIZED_ENUMERATOR(self, 0, 0, ary_enum_length)'
+ end
+ _i = 0
+ value = nil
+ while Primitive.cexpr!(%q{ ary_fetch_next(self, LOCAL_PTR(_i), LOCAL_PTR(value)) })
+ yield value
+ end
+ self
+ end
+
+ # call-seq:
# array.shuffle!(random: Random) -> array
#
# Shuffles the elements of +self+ in place.
@@ -39,7 +94,7 @@ class Array
# a.sample # => 8
# If +self+ is empty, returns +nil+.
#
- # When argument +n+ is given, returns a new \Array containing +n+ random
+ # When argument +n+ is given, returns a new +Array+ containing +n+ random
# elements from +self+:
# a.sample(3) # => [8, 9, 2]
# a.sample(6) # => [9, 6, 10, 3, 1, 4]
@@ -49,13 +104,109 @@ class Array
# But +self+ may contain duplicates:
# a = [1, 1, 1, 2, 2, 3]
# a.sample(a.size * 2) # => [1, 1, 3, 2, 1, 2]
- # Returns a new empty \Array if +self+ is empty.
+ # The argument +n+ must be a non-negative numeric value.
+ # The order of the result array is unrelated to the order of +self+.
+ # Returns a new empty +Array+ if +self+ is empty.
#
# The optional +random+ argument will be used as the random number generator:
# a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
# a.sample(random: Random.new(1)) #=> 6
# a.sample(4, random: Random.new(1)) #=> [6, 10, 9, 2]
def sample(n = (ary = false), random: Random)
- Primitive.rb_ary_sample(random, n, ary)
+ if Primitive.mandatory_only?
+ # Primitive.cexpr! %{ rb_ary_sample(self, rb_cRandom, Qfalse, Qfalse) }
+ Primitive.ary_sample0
+ else
+ # Primitive.cexpr! %{ rb_ary_sample(self, random, n, ary) }
+ Primitive.ary_sample(random, n, ary)
+ end
+ end
+
+ # call-seq:
+ # array.first -> object or nil
+ # array.first(n) -> new_array
+ #
+ # Returns elements from +self+; does not modify +self+.
+ #
+ # When no argument is given, returns the first element:
+ #
+ # a = [:foo, 'bar', 2]
+ # a.first # => :foo
+ # a # => [:foo, "bar", 2]
+ #
+ # If +self+ is empty, returns +nil+.
+ #
+ # When non-negative Integer argument +n+ is given,
+ # returns the first +n+ elements in a new +Array+:
+ #
+ # a = [:foo, 'bar', 2]
+ # a.first(2) # => [:foo, "bar"]
+ #
+ # If <tt>n >= array.size</tt>, returns all elements:
+ #
+ # a = [:foo, 'bar', 2]
+ # a.first(50) # => [:foo, "bar", 2]
+ #
+ # If <tt>n == 0</tt> returns an new empty +Array+:
+ #
+ # a = [:foo, 'bar', 2]
+ # a.first(0) # []
+ #
+ # Related: #last.
+ def first n = unspecified = true
+ if Primitive.mandatory_only?
+ Primitive.attr! :leaf
+ Primitive.cexpr! %q{ ary_first(self) }
+ else
+ if unspecified
+ Primitive.cexpr! %q{ ary_first(self) }
+ else
+ Primitive.cexpr! %q{ ary_take_first_or_last_n(self, NUM2LONG(n), ARY_TAKE_FIRST) }
+ end
+ end
+ end
+
+ # call-seq:
+ # array.last -> object or nil
+ # array.last(n) -> new_array
+ #
+ # Returns elements from +self+; +self+ is not modified.
+ #
+ # When no argument is given, returns the last element:
+ #
+ # a = [:foo, 'bar', 2]
+ # a.last # => 2
+ # a # => [:foo, "bar", 2]
+ #
+ # If +self+ is empty, returns +nil+.
+ #
+ # When non-negative Integer argument +n+ is given,
+ # returns the last +n+ elements in a new +Array+:
+ #
+ # a = [:foo, 'bar', 2]
+ # a.last(2) # => ["bar", 2]
+ #
+ # If <tt>n >= array.size</tt>, returns all elements:
+ #
+ # a = [:foo, 'bar', 2]
+ # a.last(50) # => [:foo, "bar", 2]
+ #
+ # If <tt>n == 0</tt>, returns an new empty +Array+:
+ #
+ # a = [:foo, 'bar', 2]
+ # a.last(0) # []
+ #
+ # Related: #first.
+ def last n = unspecified = true
+ if Primitive.mandatory_only?
+ Primitive.attr! :leaf
+ Primitive.cexpr! %q{ ary_last(self) }
+ else
+ if unspecified
+ Primitive.cexpr! %q{ ary_last(self) }
+ else
+ Primitive.cexpr! %q{ ary_take_first_or_last_n(self, NUM2LONG(n), ARY_TAKE_LAST) }
+ end
+ end
end
end