# shuffle()

> Shuffle the input stream into a random order.

---

Site [llms.txt](/gatherers4j/llms.txt)

---

### Implementation Notes

This implementation reads the entire stream before emitting any results, making it inappropriate for infinite streams. There
are two versions of this Gatherer, one that uses the platform default `RandomGenerator` and one that allows the caller to 
specify a `RandomGenerator`. Most `RandomGenerator` implementations are not thread-safe, so a single instance of this Gatherer
should not be used from multiple threads at the same time.

**Signatures**

1. `shuffle()`
2. `shuffle(RandomGenerator randomGenerator)`

* `randomGenerator` - _(Optional)_ A [`RandomGenerator`](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/random/RandomGenerator.html) to use as the source of randomness.


### Examples

#### Randomly shuffle the input stream specifying the source of randomness

```java
Stream
    .of("A", "B", "C", "D", "E", "F", "G")
    .gather(Gatherers4j.shuffle(new Random(42)))
    .toList();
    
// [ "B", "D", "F", "A", "E", "G", "C" ]
```

#### Randomly shuffle the input stream with the default source of random

```java
Stream
    .of("A", "B", "C", "D", "E", "F", "G")
    .gather(Gatherers4j.shuffle())
    .toList();
    
// [ "F", "D", "A", "G", "B", "C", "E" ]  <-- Random!
```