Package org.apache.commons.text
Class RandomStringGenerator
- java.lang.Object
-
- org.apache.commons.text.RandomStringGenerator
-
public final class RandomStringGenerator extends java.lang.Object
Generates random Unicode strings containing the specified number of code points. Instances are created using a builder class, which allows the callers to define the properties of the generator. See the documentation for theRandomStringGenerator.Builder
class to see available properties.// Generates a 20 code point string, using only the letters a-z RandomStringGenerator generator = new RandomStringGenerator.Builder() .withinRange('a', 'z').build(); String randomLetters = generator.generate(20);
// Using Apache Commons RNG for randomness UniformRandomProvider rng = RandomSource.create(...); // Generates a 20 code point string, using only the letters a-z RandomStringGenerator generator = new RandomStringGenerator.Builder() .withinRange('a', 'z') .usingRandom(rng::nextInt) // uses Java 8 syntax .build(); String randomLetters = generator.generate(20);
RandomStringGenerator
instances are thread-safe when using the default random number generator (RNG). If a custom RNG is set by calling the methodBuilder.usingRandom(TextRandomProvider)
, thread-safety must be ensured externally.- Since:
- 1.1
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
RandomStringGenerator.Builder
A builder for generatingRandomStringGenerator
instances.
-
Field Summary
Fields Modifier and Type Field Description private java.util.List<java.lang.Character>
characterList
The source of provided characters.private java.util.Set<CharacterPredicate>
inclusivePredicates
Filters for code points.private int
maximumCodePoint
The largest allowed code point (inclusive).private int
minimumCodePoint
The smallest allowed code point (inclusive).private TextRandomProvider
random
The source of randomness for this generator.
-
Constructor Summary
Constructors Modifier Constructor Description private
RandomStringGenerator(int minimumCodePoint, int maximumCodePoint, java.util.Set<CharacterPredicate> inclusivePredicates, TextRandomProvider random, java.util.List<java.lang.Character> characterList)
Constructs the generator.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.lang.String
generate(int length)
Generates a random string, containing the specified number of code points.java.lang.String
generate(int minLengthInclusive, int maxLengthInclusive)
Generates a random string, containing between the minimum (inclusive) and the maximum (inclusive) number of code points.private int
generateRandomNumber(int minInclusive, int maxInclusive)
Generates a random number within a range, using aThreadLocalRandom
instance or the user-supplied source of randomness.private int
generateRandomNumber(java.util.List<java.lang.Character> characterList)
Generates a random number within a range, using aThreadLocalRandom
instance or the user-supplied source of randomness.
-
-
-
Field Detail
-
minimumCodePoint
private final int minimumCodePoint
The smallest allowed code point (inclusive).
-
maximumCodePoint
private final int maximumCodePoint
The largest allowed code point (inclusive).
-
inclusivePredicates
private final java.util.Set<CharacterPredicate> inclusivePredicates
Filters for code points.
-
random
private final TextRandomProvider random
The source of randomness for this generator.
-
characterList
private final java.util.List<java.lang.Character> characterList
The source of provided characters.
-
-
Constructor Detail
-
RandomStringGenerator
private RandomStringGenerator(int minimumCodePoint, int maximumCodePoint, java.util.Set<CharacterPredicate> inclusivePredicates, TextRandomProvider random, java.util.List<java.lang.Character> characterList)
Constructs the generator.- Parameters:
minimumCodePoint
- smallest allowed code point (inclusive)maximumCodePoint
- largest allowed code point (inclusive)inclusivePredicates
- filters for code pointsrandom
- source of randomnesscharacterList
- list of predefined set of characters.
-
-
Method Detail
-
generate
public java.lang.String generate(int length)
Generates a random string, containing the specified number of code points.Code points are randomly selected between the minimum and maximum values defined in the generator. Surrogate and private use characters are not returned, although the resulting string may contain pairs of surrogates that together encode a supplementary character.
Note: the number of
char
code units generated will exceedlength
if the string contains supplementary characters. See theCharacter
documentation to understand how Java stores Unicode values.- Parameters:
length
- the number of code points to generate- Returns:
- The generated string
- Throws:
java.lang.IllegalArgumentException
- iflength < 0
-
generate
public java.lang.String generate(int minLengthInclusive, int maxLengthInclusive)
Generates a random string, containing between the minimum (inclusive) and the maximum (inclusive) number of code points.- Parameters:
minLengthInclusive
- the minimum (inclusive) number of code points to generatemaxLengthInclusive
- the maximum (inclusive) number of code points to generate- Returns:
- The generated string
- Throws:
java.lang.IllegalArgumentException
- ifminLengthInclusive < 0
, ormaxLengthInclusive < minLengthInclusive
- Since:
- 1.2
- See Also:
generate(int)
-
generateRandomNumber
private int generateRandomNumber(int minInclusive, int maxInclusive)
Generates a random number within a range, using aThreadLocalRandom
instance or the user-supplied source of randomness.- Parameters:
minInclusive
- the minimum value allowedmaxInclusive
- the maximum value allowed- Returns:
- The random number.
-
generateRandomNumber
private int generateRandomNumber(java.util.List<java.lang.Character> characterList)
Generates a random number within a range, using aThreadLocalRandom
instance or the user-supplied source of randomness.- Parameters:
characterList
- predefined char list.- Returns:
- The random number.
-
-