RandomStringGenerator (Apache Commons Text 1.13.0 API)
Description: declaration: package: org.apache.commons.text, class: RandomStringGenerator

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 = 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 Classes
  Modifier and Type
  Class
  Description
  `static class`
  `RandomStringGenerator.Builder`
  A builder for generating `RandomStringGenerator` instances.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static RandomStringGenerator.Builder`
  `builder()`
  Constructs a new builder.
  `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

  - ### 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:
      - `generate(int)`