diff options
| author | Burdette Lamar <[email protected]> | 2024-10-11 10:25:58 -0500 |
|---|---|---|
| committer | GitHub <[email protected]> | 2024-10-11 11:25:58 -0400 |
| commit | 628da153bb184285aee864b4548f974e547d839d (patch) | |
| tree | 8b9a7a3b6bc397fe0e428c5122fab78dcb084a44 /array.rb | |
| parent | 5e799cc182fdab41b696b0dea036751d621ca4f5 (diff) | |
[DOC] Tweaks for Array#sample (#11876)
Notes
Notes:
Merged-By: peterzhu2118 <[email protected]>
Diffstat (limited to 'array.rb')
| -rw-r--r-- | array.rb | 51 |
1 files changed, 34 insertions, 17 deletions
@@ -73,35 +73,52 @@ class Array 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 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] + # 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 - # If +self+ is empty, returns +nil+. # - # When argument +n+ is given, returns a new +Array+ containing +n+ random - # elements from +self+: + # Returns +nil+ if +self+ is empty: + # + # [].sample # => nil + # + # + # With 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, 10, 3, 1, 4] + # 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] + # # 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.sample(50) # => [6, 4, 1, 8, 5, 9, 0, 2, 3, 7] + # + # The object given with 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) } |