Package org.apache.commons.text
Class RandomStringGenerator
java.lang.Object
org.apache.commons.text.RandomStringGenerator
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 the
RandomStringGenerator.Builder class to see available properties.
// Generates a 20 code point string, using only the letters a-z
RandomStringGenerator generator = 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 = 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 method
Builder.usingRandom(TextRandomProvider), thread-safety
must be ensured externally.
- Since:
- 1.1
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classA builder for generatingRandomStringGeneratorinstances. -
Method Summary
Modifier and TypeMethodDescriptionbuilder()Constructs a new builder.generate(int length) Generates a random string, containing the specified number of code points.generate(int minLengthInclusive, int maxLengthInclusive) Generates a random string, containing between the minimum (inclusive) and the maximum (inclusive) number of code points.
-
Method Details
-
builder
Constructs a new builder.- Returns:
- a new builder.
- Since:
- 1.11.0
-
generate
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
charcode units generated will exceedlengthif the string contains supplementary characters. See theCharacterdocumentation to understand how Java stores Unicode values.- Parameters:
length- the number of code points to generate- Returns:
- The generated string
- Throws:
IllegalArgumentException- iflength < 0
-
generate
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:
IllegalArgumentException- ifminLengthInclusive < 0, ormaxLengthInclusive < minLengthInclusive- Since:
- 1.2
- See Also:
-