Package org.apache.commons.text

Class RandomStringGenerator

java.lang.Object
org.apache.commons.text.RandomStringGenerator
public final class RandomStringGenerator
extends 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 the RandomStringGenerator.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 method Builder.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 generating RandomStringGenerator instances.

  • Method Summary

    Modifier and Type Method Description
    String generate​(int length)
    Generates a random string, containing the specified number of code points.
    String generate​(int minLengthInclusive, int maxLengthInclusive)
    Generates a random string, containing between the minimum (inclusive) and the maximum (inclusive) number of code points.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • generate

      public 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 exceed length if the string contains supplementary characters. See the Character documentation to understand how Java stores Unicode values.

      Parameters:
      length - the number of code points to generate
      Returns:
      The generated string
      Throws:
      IllegalArgumentException - if length < 0

    • generate

      public 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 generate
      maxLengthInclusive - the maximum (inclusive) number of code points to generate
      Returns:
      The generated string
      Throws:
      IllegalArgumentException - if minLengthInclusive < 0, or maxLengthInclusive < minLengthInclusive
      Since:
      1.2
      See Also:
      generate(int)