Class RandomStringGenerator


  • public final class RandomStringGenerator
    extends java.lang.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.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private RandomStringGenerator​(int minimumCodePoint, int maximumCodePoint, java.util.Set<CharacterPredicate> inclusivePredicates, TextRandomProvider random, java.util.List<java.lang.Character> characterList)
      Constructs the generator.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String generate​(int length)
      Generates a random string, containing the specified number of code points.
      java.lang.String generate​(int minLengthInclusive, int maxLengthInclusive)
      Generates a random string, containing between the minimum (inclusive) and the maximum (inclusive) number of code points.
      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.
      private int generateRandomNumber​(java.util.List<java.lang.Character> characterList)
      Generates a random number within a range, using a ThreadLocalRandom instance or the user-supplied source of randomness.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

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

        private final TextRandomProvider random
        The source of randomness for this generator.
      • characterList

        private final java.util.List<java.lang.Character> characterList
        The source of provided characters.
    • Constructor Detail

      • RandomStringGenerator

        private RandomStringGenerator​(int minimumCodePoint,
                                      int maximumCodePoint,
                                      java.util.Set<CharacterPredicate> inclusivePredicates,
                                      TextRandomProvider random,
                                      java.util.List<java.lang.Character> characterList)
        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
        characterList - list of predefined set of characters.
    • Method Detail

      • generate

        public java.lang.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:
        java.lang.IllegalArgumentException - if length < 0
      • generate

        public java.lang.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:
        java.lang.IllegalArgumentException - if minLengthInclusive < 0, or maxLengthInclusive < minLengthInclusive
        Since:
        1.2
        See Also:
        generate(int)
      • 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​(java.util.List<java.lang.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.