Add RandomStringGenerator.Builder.usingRandom(IntUnaryOperator)

Author: garydgregory

src/changes/changes.xml

@@ -50,6 +50,7 @@ The <action> type attribute can be add,update,fix,remove.
     <!-- ADD -->
     <action type="add" dev="ggregory" due-to="Gary Gregory">Interface StringLookup now extends UnaryOperator&lt;String&gt;.</action>
     <action type="add" dev="ggregory" due-to="Gary Gregory">Interface TextRandomProvider extends IntUnaryOperator.</action>
+    <action type="add" dev="ggregory" due-to="Gary Gregory">Add RandomStringGenerator.Builder.usingRandom(IntUnaryOperator).</action>
     <!-- UPDATE -->
     <action type="update" dev="ggregory" due-to="Dependabot, Gary Gregory">Bump org.apache.commons:commons-parent from 81 to 84 #668.</action>
     <action type="update" dev="ggregory" due-to="Gary Gregory">Bump commons-io:commons-io from 2.18.0 to 2.19.0.</action>

src/main/java/org/apache/commons/text/RandomStringGenerator.java

@@ -22,6 +22,7 @@
 import java.util.List;
 import java.util.Set;
 import java.util.concurrent.ThreadLocalRandom;
+import java.util.function.IntUnaryOperator;
 
 import org.apache.commons.lang3.ArrayUtils;
 import org.apache.commons.lang3.StringUtils;
@@ -118,7 +119,7 @@ public static class Builder implements org.apache.commons.text.Builder<RandomStr
         /**
          * The source of randomness.
          */
-        private TextRandomProvider random;
+        private IntUnaryOperator random;
 
         /**
          * The source of provided characters.
@@ -216,7 +217,42 @@ public Builder selectFrom(final char... chars) {
          * be used to provide the random number generation.
          *
          * <p>
-         * When using Java 8 or later, {@link TextRandomProvider} is a
+         * {@link TextRandomProvider} is a
+         * functional interface and need not be explicitly implemented:
+         * </p>
+         * <pre>
+         * {@code
+         *     UniformRandomProvider rng = RandomSource.create(...);
+         *     RandomStringGenerator gen = RandomStringGenerator.builder()
+         *         .usingRandom(rng::nextInt)
+         *         // additional builder calls as needed
+         *         .build();
+         * }
+         * </pre>
+         *
+         * <p>
+         * Passing {@code null} to this method will revert to the default source of
+         * randomness.
+         * </p>
+         *
+         * @param random
+         *            the source of randomness, may be {@code null}
+         * @return {@code this}, to allow method chaining
+         * @since 1.14.0
+         */
+        public Builder usingRandom(final IntUnaryOperator random) {
+            this.random = random;
+            return this;
+        }
+
+        /**
+         * Overrides the default source of randomness.  It is highly
+         * recommended that a random number generator library like
+         * <a href="https://commons.apache.org/proper/commons-rng/">Apache Commons RNG</a>
+         * be used to provide the random number generation.
+         *
+         * <p>
+         * {@link TextRandomProvider} is a
          * functional interface and need not be explicitly implemented:
          * </p>
          * <pre>
@@ -334,7 +370,7 @@ public static Builder builder() {
     /**
      * The source of randomness for this generator.
      */
-    private final TextRandomProvider random;
+    private final IntUnaryOperator random;
 
     /**
      * The source of provided characters.
@@ -355,7 +391,7 @@ public static Builder builder() {
      * @param characterList list of predefined set of characters.
      */
     private RandomStringGenerator(final int minimumCodePoint, final int maximumCodePoint,
-                                  final Set<CharacterPredicate> inclusivePredicates, final TextRandomProvider random,
+                                  final Set<CharacterPredicate> inclusivePredicates, final IntUnaryOperator random,
                                   final List<Character> characterList) {
         this.minimumCodePoint = minimumCodePoint;
         this.maximumCodePoint = maximumCodePoint;

src/test/java/org/apache/commons/text/RandomStringGeneratorTest.java

@@ -22,6 +22,8 @@
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.junit.jupiter.api.Assertions.fail;
 
+import java.util.function.IntUnaryOperator;
+
 import org.apache.commons.text.RandomStringGenerator.Builder;
 import org.junit.jupiter.api.Test;
 
@@ -278,10 +280,19 @@ public void testSetLength() {
     }
 
     @Test
-    public void testUsingRandom() {
+    public void testUsingRandomTextRandomProvider() {
         final char testChar = 'a';
         final TextRandomProvider testRandom = n -> testChar;
+        final String str = RandomStringGenerator.builder().usingRandom(testRandom).build().generate(10);
+        for (final char c : str.toCharArray()) {
+            assertEquals(testChar, c);
+        }
+    }
 
+    @Test
+    public void testUsingRandomIntUnaryOperator() {
+        final char testChar = 'a';
+        final IntUnaryOperator testRandom = n -> testChar;
         final String str = RandomStringGenerator.builder().usingRandom(testRandom).build().generate(10);
         for (final char c : str.toCharArray()) {
             assertEquals(testChar, c);