Package org.apache.commons.text

# Class RandomStringGenerator.Builder

java.lang.Object
org.apache.commons.text.RandomStringGenerator.Builder

All Implemented Interfaces:
  `Supplier<RandomStringGenerator>`, `Builder<RandomStringGenerator>`

Enclosing class:
  `RandomStringGenerator`

public static class RandomStringGenerator.Builder extends Object implements Builder<RandomStringGenerator>
A builder for generating `RandomStringGenerator` instances.

The behavior of a generator is controlled by properties set by this builder. Each property has a default value, which can be overridden by calling the methods defined in this class, prior to calling `build()`.

All the property setting methods return the `Builder` instance to allow for method chaining.

The minimum and maximum code point values are defined using `withinRange(int, int)`. The default values are `0` and `Character.MAX_CODE_POINT` respectively.

The source of randomness can be set using `usingRandom(TextRandomProvider)`, otherwise `ThreadLocalRandom` is used.

The type of code points returned can be filtered using `filteredBy(CharacterPredicate...)`, which defines a collection of tests that are applied to the randomly generated code points. The code points will only be included in the result if they pass at least one of the tests. Some commonly used predicates are provided by the `CharacterPredicates` enum.

This class is not thread safe.

Since:
  1.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_LENGTH`
  The default string length produced by this builder: 0.
  `static final int`
  `DEFAULT_MAXIMUM_CODE_POINT`
  The default maximum code point allowed: `Character.MAX_CODE_POINT` (1114111).
  `static final int`
  `DEFAULT_MINIMUM_CODE_POINT`
  The default minimum code point allowed: 0.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Builder()`
  Creates a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `RandomStringGenerator`
  `build()`
  Deprecated.
  Use `get()`.
  `RandomStringGenerator.Builder`
  `filteredBy(CharacterPredicate... predicates)`
  Limits the characters in the generated string to those that match at least one of the predicates supplied.
  `RandomStringGenerator`
  `get()`
  Builds a new `RandomStringGenerator`.
  `RandomStringGenerator.Builder`
  `selectFrom(char... chars)`
  Limits the characters in the generated string to those who match at supplied list of Character.
  `RandomStringGenerator.Builder`
  `setAccumulate(boolean accumulate)`
  Sets whether calls accumulates the source of provided characters.
  `RandomStringGenerator.Builder`
  `usingRandom(IntUnaryOperator random)`
  Overrides the default source of randomness.
  `RandomStringGenerator.Builder`
  `usingRandom(TextRandomProvider random)`
  Overrides the default source of randomness.
  `RandomStringGenerator.Builder`
  `withinRange(char[]... pairs)`
  Sets the array of minimum and maximum char allowed in the generated string.
  `RandomStringGenerator.Builder`
  `withinRange(int minimumCodePoint, int maximumCodePoint)`
  Sets the minimum and maximum code points allowed in the generated string.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### DEFAULT_MAXIMUM_CODE_POINT

    public static final int DEFAULT_MAXIMUM_CODE_POINT
    The default maximum code point allowed: `Character.MAX_CODE_POINT` (1114111).
    See Also:
      - Constant Field Values

  - ### DEFAULT_LENGTH

    public static final int DEFAULT_LENGTH
    The default string length produced by this builder: 0.
    See Also:
      - Constant Field Values

  - ### DEFAULT_MINIMUM_CODE_POINT

    public static final int DEFAULT_MINIMUM_CODE_POINT
    The default minimum code point allowed: 0.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Builder

    public Builder()
    Creates a new instance.

- ## Method Details

  - ### build

    @Deprecated public RandomStringGenerator build()
    Deprecated.
    Use `get()`.
    Builds a new `RandomStringGenerator`.
    Specified by:
      `build` in interface `Builder<RandomStringGenerator>`
    Returns:
      A new `RandomStringGenerator`

  - ### filteredBy

    public RandomStringGenerator.Builder filteredBy(CharacterPredicate... predicates)
    Limits the characters in the generated string to those that match at least one of the predicates supplied.

    Passing `null` or an empty array to this method will revert to the default behavior of allowing any character. Multiple calls to this method will replace the previously stored predicates.

    Parameters:
      `predicates` - the predicates, may be `null` or empty.
    Returns:
      `this` instance.

  - ### get

    public RandomStringGenerator get()
    Builds a new `RandomStringGenerator`.
    Specified by:
      `get` in interface `Supplier<RandomStringGenerator>`
    Returns:
      A new `RandomStringGenerator`.
    Since:
      1.12.0

  - ### selectFrom

    public RandomStringGenerator.Builder selectFrom(char... chars)
    Limits the characters in the generated string to those who match at supplied list of Character.

    Passing `null` or an empty array to this method will revert to the default behavior of allowing any character. Multiple calls to this method will replace the previously stored Character.

    Parameters:
      `chars` - set of predefined Characters for random string generation the Character can be, may be `null` or empty
    Returns:
      `this` instance.
    Since:
      1.2

  - ### setAccumulate

    public RandomStringGenerator.Builder setAccumulate(boolean accumulate)
    Sets whether calls accumulates the source of provided characters. The default is `false`.

             RandomStringGenerator gen = RandomStringGenerator.builder()
                 .setAccumulate(true)
                 .withinRange(new char[][] { { 'a', 'z' }, { 'A', 'Z' }, { '0', '9' } })
                 .selectFrom('!', '"', '#', '$', '&', '\'', '(', ')', ',', '.', ':', ';', '?', '@', '[',
                             '\\', ']', '^', '_', '`', '{', '|', '}', '~') // punctuation
                 // additional builder calls as needed
                 .build();

    Parameters:
      `accumulate` - whether calls accumulates the source of provided characters. The default is `false`.
    Returns:
      `this` instance.
    Since:
      1.14.0

  - ### usingRandom

    public RandomStringGenerator.Builder usingRandom(IntUnaryOperator random)
    Overrides the default source of randomness. It is highly recommended that a random number generator library like Apache Commons RNG be used to provide the random number generation.

    `TextRandomProvider` is a functional interface and need not be explicitly implemented:

             UniformRandomProvider rng = RandomSource.create(...);
             RandomStringGenerator gen = RandomStringGenerator.builder()
                 .usingRandom(rng::nextInt)
                 // additional builder calls as needed
                 .build();

    Passing `null` to this method will revert to the default source of randomness.

    Parameters:
      `random` - the source of randomness, may be `null`.
    Returns:
      `this` instance.
    Since:
      1.14.0

  - ### usingRandom

    public RandomStringGenerator.Builder usingRandom(TextRandomProvider random)
    Overrides the default source of randomness. It is highly recommended that a random number generator library like Apache Commons RNG be used to provide the random number generation.

    `TextRandomProvider` is a functional interface and need not be explicitly implemented:

             UniformRandomProvider rng = RandomSource.create(...);
             RandomStringGenerator gen = RandomStringGenerator.builder()
                 .usingRandom(rng::nextInt)
                 // additional builder calls as needed
                 .build();

    Passing `null` to this method will revert to the default source of randomness.

    Parameters:
      `random` - the source of randomness, may be `null`.
    Returns:
      `this` instance.

  - ### withinRange

    public RandomStringGenerator.Builder withinRange(char[]... pairs)
    Sets the array of minimum and maximum char allowed in the generated string. For example:

         char[][] pairs = { { '0', '9' } };
         char[][] pairs = { { 'a', 'z' } };
         char[][] pairs = { { 'a', 'z' }, { '0', '9' } };

    Parameters:
      `pairs` - array of characters array, expected is to pass min, max pairs through this arg.
    Returns:
      `this` instance.

  - ### withinRange

    public RandomStringGenerator.Builder withinRange(int minimumCodePoint, int maximumCodePoint)
    Sets the minimum and maximum code points allowed in the generated string.
    Parameters:
      `minimumCodePoint` - the smallest code point allowed (inclusive).
      `maximumCodePoint` - the largest code point allowed (inclusive).
    Returns:
      `this` instance.
    Throws:
      `IllegalArgumentException` - if `maximumCodePoint >` `Character.MAX_CODE_POINT`.
      `IllegalArgumentException` - if `minimumCodePoint < 0`.
      `IllegalArgumentException` - if `minimumCodePoint > maximumCodePoint`.