Array#sample

.sample and .shuffle are two essential methods for working with random data in Ruby arrays. Use .sample when you need to grab random elements, and .shuffle when you need to randomize the order of an entire array.

.sample — Random Element Selection

The .sample method returns one or more random elements from an array without modifying the original.

Signature

arr.sample(n=nil, random: nil) -> obj or array

Parameters

Parameter	Type	Default	Description
n	Integer	nil	Number of elements to return
random	Object	nil	Custom random number generator

Return Value

• Without n: Returns a single random element, or nil if the array is empty
• With n: Returns an array of n unique random elements, or an empty array if the array is empty

Examples

numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

# Single random element
numbers.sample       # => 7
numbers.sample       # => 3

# Multiple random elements (no duplicates)
numbers.sample(3)    # => [2, 8, 5]
numbers.sample(3)    # => [10, 1, 6]

# Empty array behavior
[].sample            # => nil
[].sample(3)        # => []

# Using a custom random generator
require 'securerandom'
numbers.sample(random: SecureRandom)  # => 4

The random: parameter accepts any object that responds to rand(max). This is useful when you need reproducible results or want to use a specific random distribution.

rng = Random.new(42)
[1, 2, 3, 4, 5].sample(random: rng)  # => 3 (deterministic)

Edge Cases

• Empty array without arguments returns nil
• Empty array with n returns an empty array []
• Requesting more elements than available returns all unique elements
• Raises ArgumentError if n is negative

[].sample            # => nil
[].sample(3)        # => []
[1, 2].sample(5)    # => [1, 2]
[1, 2].sample(-1)  # => ArgumentError: negative sample number

.shuffle — Randomize Array Order

The .shuffle method returns a new array with elements in random order, leaving the original unchanged.

Signature

arr.shuffle(random: nil) -> array

Parameters

Parameter	Type	Default	Description
random	Object	nil	Custom random number generator

Return Value

Returns a new array with all elements in random order.

Examples

numbers = [1, 2, 3, 4, 5]

# Shuffle the array
numbers.shuffle     # => [3, 1, 5, 2, 4]
numbers.shuffle     # => [5, 4, 2, 1, 3]

# Original array unchanged
numbers             # => [1, 2, 3, 4, 5]

# Using a custom random generator for reproducibility
rng = Random.new(123)
numbers.shuffle(random: rng)  # => [4, 1, 5, 2, 3]

In-Place Shuffle with .shuffle!

If you want to shuffle the array in place (modifying the original), use .shuffle!:

numbers = [1, 2, 3, 4, 5]
numbers.shuffle!    # => [2, 5, 1, 4, 3]
numbers             # => [2, 5, 1, 4, 3]  # modified

Ruby Version Differences

• .shuffle was introduced in Ruby 1.9. Ruby 1.8.7 and earlier required a manual implementation
• .sample was added in Ruby 1.8.7
• Both methods support the random: parameter starting from Ruby 1.9

Choosing Between Them

Use .sample when you need to pick random elements from an array:

• Grabbing a random item from a list
• Selecting winners for a lottery
• Sampling data for testing

Use .shuffle when you need to randomize the order of all elements:

• Shuffling a deck of cards
• Randomizing quiz questions
• Creating a random playlist

See Also

• array::first — Access the first element(s) of an array
• array::pop — Remove and return the last element
• array::rotate — Rotate array elements by a given offset