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 = 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)
    .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

  • Field Details

    • 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 Set<CharacterPredicate> inclusivePredicates
      Filters for code points.

    • random

      private final IntUnaryOperator random
      The source of randomness for this generator.

    • characterList

      private final List<Character> characterList
      The source of provided characters.

  • Constructor Details

    • RandomStringGenerator

      private RandomStringGenerator(RandomStringGenerator.Builder builder)
      Constructs the generator.
      Parameters:
      minimumCodePoint - smallest allowed code point (inclusive).
      maximumCodePoint - largest allowed code point (inclusive).
      inclusivePredicates - filters for code points.
      random - source of randomness.
      characterSet - list of predefined set of characters.

  • Method Details

    • builder

      public static RandomStringGenerator.Builder builder()
      Constructs a new builder.
      Returns:
      a new builder.
      Since:
      1.11.0

    • 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:

    • generateRandomNumber

      private int generateRandomNumber(int minInclusive, int maxInclusive)
      Generates a random number within a range, using a ThreadLocalRandom instance or the user-supplied source of randomness.
      Parameters:
      minInclusive - the minimum value allowed.
      maxInclusive - the maximum value allowed.
      Returns:
      The random number.

    • generateRandomNumber

      private int generateRandomNumber(List<Character> characterList)
      Generates a random number within a range, using a ThreadLocalRandom instance or the user-supplied source of randomness.
      Parameters:
      characterList - predefined char list.
      Returns:
      The random number.