diff options
Diffstat (limited to 'array.rb')
| -rw-r--r-- | array.rb | 274 |
1 files changed, 202 insertions, 72 deletions
@@ -1,62 +1,97 @@ class Array # call-seq: - # array.shuffle!(random: Random) -> array + # shuffle!(random: Random) -> self # - # Shuffles the elements of +self+ in place. - # a = [1, 2, 3] #=> [1, 2, 3] - # a.shuffle! #=> [2, 3, 1] - # a #=> [2, 3, 1] + # Shuffles all elements in +self+ into a random order, + # as selected by the object given by the keyword argument +random+. + # Returns +self+: # - # The optional +random+ argument will be used as the random number generator: - # a.shuffle!(random: Random.new(1)) #=> [1, 3, 2] + # a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + # a.shuffle! # => [5, 3, 8, 7, 6, 1, 9, 4, 2, 0] + # a.shuffle! # => [9, 4, 0, 6, 2, 8, 1, 5, 3, 7] + # + # Duplicate elements are included: + # + # a = [0, 1, 0, 1, 0, 1, 0, 1, 0, 1] + # a.shuffle! # => [1, 0, 0, 1, 1, 0, 1, 0, 0, 1] + # a.shuffle! # => [0, 1, 0, 1, 1, 0, 1, 0, 1, 0] + # + # The object given with the keyword argument +random+ is used as the random number generator. + # + # Related: see {Methods for Assigning}[rdoc-ref:Array@Methods+for+Assigning]. def shuffle!(random: Random) Primitive.rb_ary_shuffle_bang(random) end # call-seq: - # array.shuffle(random: Random) -> new_ary + # shuffle(random: Random) -> new_array + # + # Returns a new array containing all elements from +self+ in a random order, + # as selected by the object given by the keyword argument +random+: # - # Returns a new array with elements of +self+ shuffled. - # a = [1, 2, 3] #=> [1, 2, 3] - # a.shuffle #=> [2, 3, 1] - # a #=> [1, 2, 3] + # a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + # a.shuffle # => [0, 8, 1, 9, 6, 3, 4, 7, 2, 5] + # a.shuffle # => [8, 9, 0, 5, 1, 2, 6, 4, 7, 3] # - # The optional +random+ argument will be used as the random number generator: - # a.shuffle(random: Random.new(1)) #=> [1, 3, 2] + # Duplicate elements are included: + # + # a = [0, 1, 0, 1, 0, 1, 0, 1, 0, 1] + # a.shuffle # => [1, 0, 1, 1, 0, 0, 1, 0, 0, 1] + # a.shuffle # => [1, 1, 0, 0, 0, 1, 1, 0, 0, 1] + # + # The object given with the keyword argument +random+ is used as the random number generator. + # + # Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching]. def shuffle(random: Random) Primitive.rb_ary_shuffle(random) end # call-seq: - # array.sample(random: Random) -> object - # array.sample(n, random: Random) -> new_ary + # sample(random: Random) -> object + # sample(count, random: Random) -> new_ary # - # Returns random elements from +self+. + # Returns random elements from +self+, + # as selected by the object given by the keyword argument +random+. # - # When no arguments are given, returns a random element from +self+: - # a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] - # a.sample # => 3 - # a.sample # => 8 - # If +self+ is empty, returns +nil+. + # With no argument +count+ given, returns one random element from +self+: + # + # a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + # a.sample # => 3 + # a.sample # => 8 + # + # Returns +nil+ if +self+ is empty: + # + # [].sample # => nil + # + # With a non-negative numeric argument +count+ given, + # returns a new array containing +count+ random elements from +self+: + # + # a.sample(3) # => [8, 9, 2] + # a.sample(6) # => [9, 6, 0, 3, 1, 4] + # + # The order of the result array is unrelated to the order of +self+. + # + # Returns a new empty array if +self+ is empty: + # + # [].sample(4) # => [] + # + # May return duplicates in +self+: + # + # a = [1, 1, 1, 2, 2, 3] + # a.sample(a.size) # => [1, 1, 3, 2, 1, 2] # - # 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] # Returns no more than <tt>a.size</tt> elements # (because no new duplicates are introduced): - # a.sample(a.size * 2) # => [6, 4, 1, 8, 5, 9, 10, 2, 3, 7] - # But +self+ may contain duplicates: - # a = [1, 1, 1, 2, 2, 3] - # a.sample(a.size * 2) # => [1, 1, 3, 2, 1, 2] - # 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] + # a.sample(50) # => [6, 4, 1, 8, 5, 9, 0, 2, 3, 7] + # + # The object given with the keyword argument +random+ is 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] + # + # Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching]. def sample(n = (ary = false), random: Random) if Primitive.mandatory_only? # Primitive.cexpr! %{ rb_ary_sample(self, rb_cRandom, Qfalse, Qfalse) } @@ -68,12 +103,12 @@ class Array end # call-seq: - # array.first -> object or nil - # array.first(n) -> new_array + # first -> object or nil + # first(count) -> new_array # - # Returns elements from +self+; does not modify +self+. + # Returns elements from +self+, or +nil+; does not modify +self+. # - # When no argument is given, returns the first element: + # With no argument given, returns the first element (if available): # # a = [:foo, 'bar', 2] # a.first # => :foo @@ -81,23 +116,16 @@ class Array # # 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"] + # [].first # => nil # - # If <tt>n >= array.size</tt>, returns all elements: + # With a non-negative integer argument +count+ given, + # returns the first +count+ elements (as available) in a new array: # - # a = [:foo, 'bar', 2] + # a.first(0) # => [] + # a.first(2) # => [:foo, "bar"] # 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. + # Related: see {Methods for Querying}[rdoc-ref:Array@Methods+for+Querying]. def first n = unspecified = true if Primitive.mandatory_only? Primitive.attr! :leaf @@ -112,36 +140,29 @@ class Array end # call-seq: - # array.last -> object or nil - # array.last(n) -> new_array + # last -> last_object or nil + # last(count) -> new_array # - # Returns elements from +self+; +self+ is not modified. + # Returns elements from +self+, or +nil+; +self+ is not modified. # - # When no argument is given, returns the last element: + # With no argument given, returns the last element, or +nil+ if +self+ is empty: # # a = [:foo, 'bar', 2] # a.last # => 2 # a # => [:foo, "bar", 2] + # [].last # => nil # - # 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: + # With non-negative integer argument +count+ given, + # returns a new array containing the trailing +count+ elements of +self+, as available: # # a = [:foo, 'bar', 2] + # a.last(2) # => ["bar", 2] # a.last(50) # => [:foo, "bar", 2] + # a.last(0) # => [] + # [].last(3) # => [] # - # If <tt>n == 0</tt>, returns an new empty \Array: - # - # a = [:foo, 'bar', 2] - # a.last(0) # [] - # - # Related: #first. + # Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching]. def last n = unspecified = true if Primitive.mandatory_only? Primitive.attr! :leaf @@ -154,4 +175,113 @@ class Array end end end + + # call-seq: + # fetch_values(*indexes) -> new_array + # fetch_values(*indexes) { |index| ... } -> new_array + # + # With no block given, returns a new array containing the elements of +self+ + # at the offsets specified by +indexes+. Each of the +indexes+ must be an + # {integer-convertible object}[rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects]: + # + # a = [:foo, :bar, :baz] + # a.fetch_values(2, 0) # => [:baz, :foo] + # a.fetch_values(2.1, 0) # => [:baz, :foo] + # a.fetch_values # => [] + # + # For a negative index, counts backwards from the end of the array: + # + # a.fetch_values(-2, -1) # [:bar, :baz] + # + # When no block is given, raises an exception if any index is out of range. + # + # With a block given, for each index: + # + # - If the index is in range, uses an element of +self+ (as above). + # - Otherwise, calls the block with the index and uses the block's return value. + # + # Example: + # + # a = [:foo, :bar, :baz] + # a.fetch_values(1, 0, 42, 777) { |index| index.to_s } + # # => [:bar, :foo, "42", "777"] + # + # Related: see {Methods for Fetching}[rdoc-ref:Array@Methods+for+Fetching]. + def fetch_values(*indexes, &block) + indexes.map! { |i| fetch(i, &block) } + indexes + end + + with_jit do + if Primitive.rb_builtin_basic_definition_p(:each) + undef :each + + def each # :nodoc: + Primitive.attr! :inline_block, :c_trace + + 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 + end + + if Primitive.rb_builtin_basic_definition_p(:map) + undef :map + + def map # :nodoc: + Primitive.attr! :inline_block, :c_trace + + unless defined?(yield) + return Primitive.cexpr! 'SIZED_ENUMERATOR(self, 0, 0, ary_enum_length)' + end + + _i = 0 + value = nil + result = Primitive.ary_sized_alloc + while Primitive.cexpr!(%q{ ary_fetch_next(self, LOCAL_PTR(_i), LOCAL_PTR(value)) }) + value = yield(value) + Primitive.cexpr!(%q{ rb_ary_push(result, value) }) + end + result + end + + if Primitive.rb_builtin_basic_definition_p(:collect) + undef :collect + alias collect map + end + end + + if Primitive.rb_builtin_basic_definition_p(:select) + undef :select + + def select # :nodoc: + Primitive.attr! :inline_block, :c_trace + + unless defined?(yield) + return Primitive.cexpr! 'SIZED_ENUMERATOR(self, 0, 0, ary_enum_length)' + end + + _i = 0 + value = nil + result = Primitive.ary_sized_alloc + while Primitive.cexpr!(%q{ ary_fetch_next(self, LOCAL_PTR(_i), LOCAL_PTR(value)) }) + if yield value + Primitive.cexpr!(%q{ rb_ary_push(result, value) }) + end + end + result + end + + if Primitive.rb_builtin_basic_definition_p(:filter) + undef :filter + alias filter select + end + end + end end |