You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2025/05/20 14:51:53 UTC
(commons-text) 03/04: Interface TextRandomProvider extends IntUnaryOperator
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-text.git
commit 98aae9ada74f51b52dbcf41c7ad46452721a6ffe
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Tue May 20 10:49:31 2025 -0400
Interface TextRandomProvider extends IntUnaryOperator
---
src/changes/changes.xml | 1 +
.../apache/commons/text/RandomStringGenerator.java | 4 +--
.../apache/commons/text/TextRandomProvider.java | 34 +++++++++++++++++-----
3 files changed, 29 insertions(+), 10 deletions(-)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index b5824ded..69c3ce3f 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -49,6 +49,7 @@ The <action> type attribute can be add,update,fix,remove.
<!-- FIX -->
<!-- ADD -->
<action type="add" dev="ggregory" due-to="Gary Gregory">Interface StringLookup now extends UnaryOperator<String>.</action>
+ <action type="add" dev="ggregory" due-to="Gary Gregory">Interface TextRandomProvider extends 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>
diff --git a/src/main/java/org/apache/commons/text/RandomStringGenerator.java b/src/main/java/org/apache/commons/text/RandomStringGenerator.java
index df3f3938..4a999649 100644
--- a/src/main/java/org/apache/commons/text/RandomStringGenerator.java
+++ b/src/main/java/org/apache/commons/text/RandomStringGenerator.java
@@ -459,7 +459,7 @@ public final class RandomStringGenerator {
*/
private int generateRandomNumber(final int minInclusive, final int maxInclusive) {
if (random != null) {
- return random.nextInt(maxInclusive - minInclusive + 1) + minInclusive;
+ return random.applyAsInt(maxInclusive - minInclusive + 1) + minInclusive;
}
return ThreadLocalRandom.current().nextInt(minInclusive, maxInclusive + 1);
}
@@ -474,7 +474,7 @@ public final class RandomStringGenerator {
private int generateRandomNumber(final List<Character> characterList) {
final int listSize = characterList.size();
if (random != null) {
- return String.valueOf(characterList.get(random.nextInt(listSize))).codePointAt(0);
+ return String.valueOf(characterList.get(random.applyAsInt(listSize))).codePointAt(0);
}
return String.valueOf(characterList.get(ThreadLocalRandom.current().nextInt(0, listSize))).codePointAt(0);
}
diff --git a/src/main/java/org/apache/commons/text/TextRandomProvider.java b/src/main/java/org/apache/commons/text/TextRandomProvider.java
index 0190d9cb..23ba9173 100644
--- a/src/main/java/org/apache/commons/text/TextRandomProvider.java
+++ b/src/main/java/org/apache/commons/text/TextRandomProvider.java
@@ -16,6 +16,8 @@
*/
package org.apache.commons.text;
+import java.util.function.IntUnaryOperator;
+
/**
* TextRandomProvider implementations are used by {@link RandomStringGenerator}
* as a source of randomness. It is highly recommended that the
@@ -23,27 +25,43 @@ package org.apache.commons.text;
* library be used to provide the random number generation.
*
* <p>
- * When using Java 8 or later, TextRandomProvider is a functional interface and
- * need not be explicitly implemented. For example:
+ * {@code TextRandomProvider} is a functional interface and need not be explicitly implemented.
+ * </p>
+ * <p>
+ * For example:
* </p>
* <pre>
* {@code
* UniformRandomProvider rng = RandomSource.create(...);
* RandomStringGenerator gen = RandomStringGenerator.builder()
- * .usingRandom(rng::nextInt)
+ * .usingRandom(rng::applyAsInt)
* // additional builder calls as needed
* .build();
* }
* </pre>
* @since 1.1
*/
-public interface TextRandomProvider {
+public interface TextRandomProvider extends IntUnaryOperator {
+
+ /**
+ * Generates an int value between 0 (inclusive) and the specified value (exclusive).
+ *
+ * @param max Bound on the random number to be returned. Must be positive.
+ * @return a random int value between 0 (inclusive) and max (exclusive).
+ * @since 1.14.0
+ */
+ @Override
+ default int applyAsInt(final int max) {
+ return nextInt(max);
+ }
/**
- * Generates an int value between 0 (inclusive) and the specified value
- * (exclusive).
- * @param max Bound on the random number to be returned. Must be positive.
- * @return a random int value between 0 (inclusive) and n (exclusive).
+ * Generates an int value between 0 (inclusive) and the specified value (exclusive).
+ *
+ * @param max Bound on the random number to be returned. Must be positive.
+ * @return a random int value between 0 (inclusive) and max (exclusive).
+ * @deprecated Use {@link #applyAsInt(int)}.
*/
+ @Deprecated
int nextInt(int max);
}
Re: (commons-text) 03/04: Interface TextRandomProvider extends IntUnaryOperator
Posted by Gary Gregory <ga...@gmail.com>.
On Tue, May 20, 2025 at 11:48 AM Alex Herbert <al...@gmail.com>
wrote:
> This change breaks the code example on how to use the class, see below:
>
> On Tue, 20 May 2025 at 15:51, <gg...@apache.org> wrote:
>
> > This is an automated email from the ASF dual-hosted git repository.
> >
> > ggregory pushed a commit to branch master
> > in repository https://gitbox.apache.org/repos/asf/commons-text.git
> >
> > commit 98aae9ada74f51b52dbcf41c7ad46452721a6ffe
> > Author: Gary Gregory <ga...@gmail.com>
> > AuthorDate: Tue May 20 10:49:31 2025 -0400
> >
> > Interface TextRandomProvider extends IntUnaryOperator
> > ---
> > src/changes/changes.xml | 1 +
> > .../apache/commons/text/RandomStringGenerator.java | 4 +--
> > .../apache/commons/text/TextRandomProvider.java | 34
> > +++++++++++++++++-----
> > 3 files changed, 29 insertions(+), 10 deletions(-)
> >
> > diff --git a/src/changes/changes.xml b/src/changes/changes.xml
> > index b5824ded..69c3ce3f 100644
> > --- a/src/changes/changes.xml
> > +++ b/src/changes/changes.xml
> > @@ -49,6 +49,7 @@ The <action> type attribute can be
> add,update,fix,remove.
> > <!-- FIX -->
> > <!-- ADD -->
> > <action type="add" dev="ggregory" due-to="Gary Gregory">Interface
> > StringLookup now extends UnaryOperator<String>.</action>
> > + <action type="add" dev="ggregory" due-to="Gary Gregory">Interface
> > TextRandomProvider extends 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>
> > diff --git
> > a/src/main/java/org/apache/commons/text/RandomStringGenerator.java
> > b/src/main/java/org/apache/commons/text/RandomStringGenerator.java
> > index df3f3938..4a999649 100644
> > --- a/src/main/java/org/apache/commons/text/RandomStringGenerator.java
> > +++ b/src/main/java/org/apache/commons/text/RandomStringGenerator.java
> > @@ -459,7 +459,7 @@ public final class RandomStringGenerator {
> > */
> > private int generateRandomNumber(final int minInclusive, final int
> > maxInclusive) {
> > if (random != null) {
> > - return random.nextInt(maxInclusive - minInclusive + 1) +
> > minInclusive;
> > + return random.applyAsInt(maxInclusive - minInclusive + 1) +
> > minInclusive;
> > }
> > return ThreadLocalRandom.current().nextInt(minInclusive,
> > maxInclusive + 1);
> > }
> > @@ -474,7 +474,7 @@ public final class RandomStringGenerator {
> > private int generateRandomNumber(final List<Character>
> characterList)
> > {
> > final int listSize = characterList.size();
> > if (random != null) {
> > - return
> >
> String.valueOf(characterList.get(random.nextInt(listSize))).codePointAt(0);
> > + return
> >
> String.valueOf(characterList.get(random.applyAsInt(listSize))).codePointAt(0);
> > }
> > return
> > String.valueOf(characterList.get(ThreadLocalRandom.current().nextInt(0,
> > listSize))).codePointAt(0);
> > }
> > diff --git
> a/src/main/java/org/apache/commons/text/TextRandomProvider.java
> > b/src/main/java/org/apache/commons/text/TextRandomProvider.java
> > index 0190d9cb..23ba9173 100644
> > --- a/src/main/java/org/apache/commons/text/TextRandomProvider.java
> > +++ b/src/main/java/org/apache/commons/text/TextRandomProvider.java
> > @@ -16,6 +16,8 @@
> > */
> > package org.apache.commons.text;
> >
> > +import java.util.function.IntUnaryOperator;
> > +
> > /**
> > * TextRandomProvider implementations are used by {@link
> > RandomStringGenerator}
> > * as a source of randomness. It is highly recommended that the
> > @@ -23,27 +25,43 @@ package org.apache.commons.text;
> > * library be used to provide the random number generation.
> > *
> > * <p>
> > - * When using Java 8 or later, TextRandomProvider is a functional
> > interface and
> > - * need not be explicitly implemented. For example:
> > + * {@code TextRandomProvider} is a functional interface and need not be
> > explicitly implemented.
> > + * </p>
> > + * <p>
> > + * For example:
> > * </p>
> > * <pre>
> > * {@code
> > * UniformRandomProvider rng = RandomSource.create(...);
> > * RandomStringGenerator gen = RandomStringGenerator.builder()
> > - * .usingRandom(rng::nextInt)
> > + * .usingRandom(rng::applyAsInt)
> >
>
> This is not a valid example. The UniformRandomProvider interface does not
> have a 'applyAsInt' method, so the code would not compile.
>
I fixed the Javadoc in git master. TY!
Gary
>
>
>
> > * // additional builder calls as needed
> > * .build();
> > * }
> > * </pre>
> > * @since 1.1
> > */
> > -public interface TextRandomProvider {
> > +public interface TextRandomProvider extends IntUnaryOperator {
> > +
> > + /**
> > + * Generates an int value between 0 (inclusive) and the specified
> > value (exclusive).
> > + *
> > + * @param max Bound on the random number to be returned. Must be
> > positive.
> > + * @return a random int value between 0 (inclusive) and max
> > (exclusive).
> > + * @since 1.14.0
> > + */
> > + @Override
> > + default int applyAsInt(final int max) {
> > + return nextInt(max);
> > + }
> >
> > /**
> > - * Generates an int value between 0 (inclusive) and the specified
> > value
> > - * (exclusive).
> > - * @param max Bound on the random number to be returned. Must be
> > positive.
> > - * @return a random int value between 0 (inclusive) and n
> (exclusive).
> > + * Generates an int value between 0 (inclusive) and the specified
> > value (exclusive).
> > + *
> > + * @param max Bound on the random number to be returned. Must be
> > positive.
> > + * @return a random int value between 0 (inclusive) and max
> > (exclusive).
> > + * @deprecated Use {@link #applyAsInt(int)}.
> > */
> > + @Deprecated
> > int nextInt(int max);
> > }
> >
> >
>
Re: (commons-text) 03/04: Interface TextRandomProvider extends IntUnaryOperator
Posted by Alex Herbert <al...@gmail.com>.
This change breaks the code example on how to use the class, see below:
On Tue, 20 May 2025 at 15:51, <gg...@apache.org> wrote:
> This is an automated email from the ASF dual-hosted git repository.
>
> ggregory pushed a commit to branch master
> in repository https://gitbox.apache.org/repos/asf/commons-text.git
>
> commit 98aae9ada74f51b52dbcf41c7ad46452721a6ffe
> Author: Gary Gregory <ga...@gmail.com>
> AuthorDate: Tue May 20 10:49:31 2025 -0400
>
> Interface TextRandomProvider extends IntUnaryOperator
> ---
> src/changes/changes.xml | 1 +
> .../apache/commons/text/RandomStringGenerator.java | 4 +--
> .../apache/commons/text/TextRandomProvider.java | 34
> +++++++++++++++++-----
> 3 files changed, 29 insertions(+), 10 deletions(-)
>
> diff --git a/src/changes/changes.xml b/src/changes/changes.xml
> index b5824ded..69c3ce3f 100644
> --- a/src/changes/changes.xml
> +++ b/src/changes/changes.xml
> @@ -49,6 +49,7 @@ The <action> type attribute can be add,update,fix,remove.
> <!-- FIX -->
> <!-- ADD -->
> <action type="add" dev="ggregory" due-to="Gary Gregory">Interface
> StringLookup now extends UnaryOperator<String>.</action>
> + <action type="add" dev="ggregory" due-to="Gary Gregory">Interface
> TextRandomProvider extends 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>
> diff --git
> a/src/main/java/org/apache/commons/text/RandomStringGenerator.java
> b/src/main/java/org/apache/commons/text/RandomStringGenerator.java
> index df3f3938..4a999649 100644
> --- a/src/main/java/org/apache/commons/text/RandomStringGenerator.java
> +++ b/src/main/java/org/apache/commons/text/RandomStringGenerator.java
> @@ -459,7 +459,7 @@ public final class RandomStringGenerator {
> */
> private int generateRandomNumber(final int minInclusive, final int
> maxInclusive) {
> if (random != null) {
> - return random.nextInt(maxInclusive - minInclusive + 1) +
> minInclusive;
> + return random.applyAsInt(maxInclusive - minInclusive + 1) +
> minInclusive;
> }
> return ThreadLocalRandom.current().nextInt(minInclusive,
> maxInclusive + 1);
> }
> @@ -474,7 +474,7 @@ public final class RandomStringGenerator {
> private int generateRandomNumber(final List<Character> characterList)
> {
> final int listSize = characterList.size();
> if (random != null) {
> - return
> String.valueOf(characterList.get(random.nextInt(listSize))).codePointAt(0);
> + return
> String.valueOf(characterList.get(random.applyAsInt(listSize))).codePointAt(0);
> }
> return
> String.valueOf(characterList.get(ThreadLocalRandom.current().nextInt(0,
> listSize))).codePointAt(0);
> }
> diff --git a/src/main/java/org/apache/commons/text/TextRandomProvider.java
> b/src/main/java/org/apache/commons/text/TextRandomProvider.java
> index 0190d9cb..23ba9173 100644
> --- a/src/main/java/org/apache/commons/text/TextRandomProvider.java
> +++ b/src/main/java/org/apache/commons/text/TextRandomProvider.java
> @@ -16,6 +16,8 @@
> */
> package org.apache.commons.text;
>
> +import java.util.function.IntUnaryOperator;
> +
> /**
> * TextRandomProvider implementations are used by {@link
> RandomStringGenerator}
> * as a source of randomness. It is highly recommended that the
> @@ -23,27 +25,43 @@ package org.apache.commons.text;
> * library be used to provide the random number generation.
> *
> * <p>
> - * When using Java 8 or later, TextRandomProvider is a functional
> interface and
> - * need not be explicitly implemented. For example:
> + * {@code TextRandomProvider} is a functional interface and need not be
> explicitly implemented.
> + * </p>
> + * <p>
> + * For example:
> * </p>
> * <pre>
> * {@code
> * UniformRandomProvider rng = RandomSource.create(...);
> * RandomStringGenerator gen = RandomStringGenerator.builder()
> - * .usingRandom(rng::nextInt)
> + * .usingRandom(rng::applyAsInt)
>
This is not a valid example. The UniformRandomProvider interface does not
have a 'applyAsInt' method, so the code would not compile.
> * // additional builder calls as needed
> * .build();
> * }
> * </pre>
> * @since 1.1
> */
> -public interface TextRandomProvider {
> +public interface TextRandomProvider extends IntUnaryOperator {
> +
> + /**
> + * Generates an int value between 0 (inclusive) and the specified
> value (exclusive).
> + *
> + * @param max Bound on the random number to be returned. Must be
> positive.
> + * @return a random int value between 0 (inclusive) and max
> (exclusive).
> + * @since 1.14.0
> + */
> + @Override
> + default int applyAsInt(final int max) {
> + return nextInt(max);
> + }
>
> /**
> - * Generates an int value between 0 (inclusive) and the specified
> value
> - * (exclusive).
> - * @param max Bound on the random number to be returned. Must be
> positive.
> - * @return a random int value between 0 (inclusive) and n (exclusive).
> + * Generates an int value between 0 (inclusive) and the specified
> value (exclusive).
> + *
> + * @param max Bound on the random number to be returned. Must be
> positive.
> + * @return a random int value between 0 (inclusive) and max
> (exclusive).
> + * @deprecated Use {@link #applyAsInt(int)}.
> */
> + @Deprecated
> int nextInt(int max);
> }
>
>