Documentation update for shuffle

tginsberg · Sep 24, 2024 · d6e3966 · d6e3966
1 parent a01dc8a
commit d6e3966
Show file tree

Hide file tree

Showing 2 changed files with 39 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -30,19 +30,21 @@ implementation("com.ginsberg:gatherers4j:0.4.0")
 # Gatherers In This Library
 
 ### Streams
-| Function                     | Purpose                                                                                                               |
-|------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| Function                     | Purpose                                                                                                                        |
+|------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
 | `debounce(amount, duration)` | Limit stream elements to `amount` elements over `duration`, dropping any elements over the limit until a new `duration` starts |
-| `dedupeConsecutive()`        | Remove consecutive duplicates from a stream                                                                           |
-| `dedupeConsecutiveBy(fn)`    | Remove consecutive duplicates from a stream as returned by `fn`                                                       |
-| `distinctBy(fn)`             | Emit only distinct elements from the stream, as measured by `fn`                                                      |
-| `interleave(stream)`         | Creates a stream of alternating objects from the input stream and the argument stream                                 |
-| `last(n)`                    | Constrain the stream to the last `n` values                                                                           |
-| `throttle(amount, duration)` | Limit stream elements to `amount` elements over `duration`, pausing until a new `duration` period starts |
-| `withIndex()`                | Maps all elements of the stream as-is along with their 0-based index                                                  |
-| `withIndexStartingAt(n)`     | Maps all elements of the stream as-is along with an index starting at the number specified                            |
-| `zipWith(stream)`            | Creates a stream of `Pair` objects whose values come from the input stream and argument stream                        |
-| `zipWithNext()`              | Creates a stream of `List` objects via a sliding window of width 2 and stepping 1                                     |      
+| `dedupeConsecutive()`        | Remove consecutive duplicates from a stream                                                                                    |
+| `dedupeConsecutiveBy(fn)`    | Remove consecutive duplicates from a stream as returned by `fn`                                                                |
+| `distinctBy(fn)`             | Emit only distinct elements from the stream, as measured by `fn`                                                               |
+| `interleave(stream)`         | Creates a stream of alternating objects from the input stream and the argument stream                                          |
+| `last(n)`                    | Constrain the stream to the last `n` values                                                                                    |
+| `shuffle()`                  | Shuffle the stream into a random order using the platform default `RandomGenerator`                                            |
+| `shuffle(rg)`                | Shuffle the stream into a random order using the specified `RandomGenerator`                                                   |
+| `throttle(amount, duration)` | Limit stream elements to `amount` elements over `duration`, pausing until a new `duration` period starts                       |
+| `withIndex()`                | Maps all elements of the stream as-is along with their 0-based index                                                           |
+| `withIndexStartingAt(n)`     | Maps all elements of the stream as-is along with an index starting at the number specified                                     |
+| `zipWith(stream)`            | Creates a stream of `Pair` objects whose values come from the input stream and argument stream                                 |
+| `zipWithNext()`              | Creates a stream of `List` objects via a sliding window of width 2 and stepping 1                                              |      
 
 ### Mathematics/Statistics
 | Function                                   | Purpose                                                                                                                            |
@@ -160,7 +162,29 @@ Stream
 // [IndexedValue(0, "A"), IndexedValue(1, "B"), IndexedValue(2, "C")]
 ```
 
-### Throttle the number of elements consumed in a period
+#### Shuffle the stream into a random order
+
+```java
+Stream
+     .of("A", "B", "C", "D" ,"E")
+     .gather(Gatherers4j.shuffle())
+     .toList();
+
+// ex: ["B", "E", "A", "C", "D"] -- or some other randomly arranged stream
+```
+
+#### Shuffle the stream into a random order, with a specific `RandomGenerator`
+
+```java
+Stream
+     .of("A", "B", "C", "D" ,"E")
+     .gather(Gatherers4j.shuffle(RandomGenerator.of("someGenerator")))
+     .toList();
+
+// ex: ["B", "E", "A", "C", "D"] -- or some other randomly arranged stream
+```
+
+#### Throttle the number of elements consumed in a period
 
 ```java
 Stream

diff --git a/src/main/java/com/ginsberg/gatherers4j/Gatherers4j.java b/src/main/java/com/ginsberg/gatherers4j/Gatherers4j.java
@@ -20,6 +20,8 @@
 import java.time.Duration;
 import java.util.List;
 import java.util.function.Function;
+import java.util.random.RandomGenerator;
+import java.util.random.RandomGeneratorFactory;
 import java.util.stream.Gatherer;
 import java.util.stream.Stream;