Package org.apache.commons.lang3

# Class RandomStringUtils

java.lang.Object
org.apache.commons.lang3.RandomStringUtils

public class RandomStringUtils extends Object
Generates random `String`s.

Caveat: Instances of `Random`, upon which the implementation of this class relies, are not cryptographically secure.

RandomStringUtils is intended for simple use cases. For more advanced use cases consider using Apache Commons Text's RandomStringGenerator instead.

The Apache Commons project provides Commons RNG dedicated to pseudo-random number generation, that may be a better choice for applications with more stringent requirements (performance and/or correctness).

Note that private high surrogate characters are ignored. These are Unicode characters that fall between the values 56192 (db80) and 56319 (dbff) as we don't know how to handle them. High and low surrogates are correctly dealt with - that is if a high surrogate is randomly chosen, 55296 (d800) to 56191 (db7f) then it is followed by a low surrogate. If a low surrogate is chosen, 56320 (dc00) to 57343 (dfff) then it is placed after a randomly chosen high surrogate.

#ThreadSafe#

Since:
  1.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RandomStringUtils()`
  `RandomStringUtils` instances should NOT be constructed in standard programming.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `random(int count)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `random(int count, boolean letters, boolean numbers)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `random(int count, char... chars)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `random(int count, int start, int end, boolean letters, boolean numbers)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `random(int count, int start, int end, boolean letters, boolean numbers, char... chars)`
  Creates a random string based on a variety of options, using default source of randomness.
  `static String`
  `random(int count, int start, int end, boolean letters, boolean numbers, char[] chars, Random random)`
  Creates a random string based on a variety of options, using supplied source of randomness.
  `static String`
  `random(int count, String chars)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `randomAlphabetic(int count)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `randomAlphabetic(int minLengthInclusive, int maxLengthExclusive)`
  Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
  `static String`
  `randomAlphanumeric(int count)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `randomAlphanumeric(int minLengthInclusive, int maxLengthExclusive)`
  Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
  `static String`
  `randomAscii(int count)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `randomAscii(int minLengthInclusive, int maxLengthExclusive)`
  Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
  `static String`
  `randomGraph(int count)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `randomGraph(int minLengthInclusive, int maxLengthExclusive)`
  Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
  `static String`
  `randomNumeric(int count)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `randomNumeric(int minLengthInclusive, int maxLengthExclusive)`
  Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
  `static String`
  `randomPrint(int count)`
  Creates a random string whose length is the number of characters specified.
  `static String`
  `randomPrint(int minLengthInclusive, int maxLengthExclusive)`
  Creates a random string whose length is between the inclusive minimum and the exclusive maximum.

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

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

- ## Constructor Details

  - ### RandomStringUtils

    public RandomStringUtils()
    `RandomStringUtils` instances should NOT be constructed in standard programming. Instead, the class should be used as `RandomStringUtils.random(5);`.

    This constructor is public to permit tools that require a JavaBean instance to operate.

- ## Method Details

  - ### random

    public static String random(int count)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of all characters.

    Parameters:
      `count` - the length of random string to create
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0.

  - ### random

    public static String random(int count, boolean letters, boolean numbers)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of alpha-numeric characters as indicated by the arguments.

    Parameters:
      `count` - the length of random string to create
      `letters` - if `true`, generated string may include alphabetic characters
      `numbers` - if `true`, generated string may include numeric characters
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0.

  - ### random

    public static String random(int count, char... chars)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of characters specified.

    Parameters:
      `count` - the length of random string to create
      `chars` - the character array containing the set of characters to use, may be null
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0.

  - ### random

    public static String random(int count, int start, int end, boolean letters, boolean numbers)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of alpha-numeric characters as indicated by the arguments.

    Parameters:
      `count` - the length of random string to create
      `start` - the position in set of chars to start at
      `end` - the position in set of chars to end before
      `letters` - if `true`, generated string may include alphabetic characters
      `numbers` - if `true`, generated string may include numeric characters
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0.

  - ### random

    public static String random(int count, int start, int end, boolean letters, boolean numbers, char... chars)
    Creates a random string based on a variety of options, using default source of randomness.

    This method has exactly the same semantics as `random(int,int,int,boolean,boolean,char[],Random)`, but instead of using an externally supplied source of randomness, it uses the internal static `Random` instance.

    Parameters:
      `count` - the length of random string to create
      `start` - the position in set of chars to start at
      `end` - the position in set of chars to end before
      `letters` - if `true`, generated string may include alphabetic characters
      `numbers` - if `true`, generated string may include numeric characters
      `chars` - the set of chars to choose randoms from. If `null`, then it will use the set of all chars.
    Returns:
      the random string
    Throws:
      `ArrayIndexOutOfBoundsException` - if there are not `(end - start) + 1` characters in the set array.
      `IllegalArgumentException` - if `count` < 0.

  - ### random

    public static String random(int count, int start, int end, boolean letters, boolean numbers, char[] chars, Random random)
    Creates a random string based on a variety of options, using supplied source of randomness.

    If start and end are both `0`, start and end are set to `' '` and `'z'`, the ASCII printable characters, will be used, unless letters and numbers are both `false`, in which case, start and end are set to `0` and `Character.MAX_CODE_POINT`.

    If set is not `null`, characters between start and end are chosen.

    This method accepts a user-supplied `Random` instance to use as a source of randomness. By seeding a single `Random` instance with a fixed seed and using it for each call, the same random sequence of strings can be generated repeatedly and predictably.

    Parameters:
      `count` - the length of random string to create
      `start` - the position in set of chars to start at (inclusive)
      `end` - the position in set of chars to end before (exclusive)
      `letters` - if `true`, generated string may include alphabetic characters
      `numbers` - if `true`, generated string may include numeric characters
      `chars` - the set of chars to choose randoms from, must not be empty. If `null`, then it will use the set of all chars.
      `random` - a source of randomness.
    Returns:
      the random string
    Throws:
      `ArrayIndexOutOfBoundsException` - if there are not `(end - start) + 1` characters in the set array.
      `IllegalArgumentException` - if `count` < 0 or the provided chars array is empty.
    Since:
      2.0

  - ### random

    public static String random(int count, String chars)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of characters specified by the string, must not be empty. If null, the set of all characters is used.

    Parameters:
      `count` - the length of random string to create
      `chars` - the String containing the set of characters to use, may be null, but must not be empty
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0 or the string is empty.

  - ### randomAlphabetic

    public static String randomAlphabetic(int count)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z).

    Parameters:
      `count` - the length of random string to create
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0.

  - ### randomAlphabetic

    public static String randomAlphabetic(int minLengthInclusive, int maxLengthExclusive)
    Creates a random string whose length is between the inclusive minimum and the exclusive maximum.

    Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z).

    Parameters:
      `minLengthInclusive` - the inclusive minimum length of the string to generate
      `maxLengthExclusive` - the exclusive maximum length of the string to generate
    Returns:
      the random string
    Since:
      3.5

  - ### randomAlphanumeric

    public static String randomAlphanumeric(int count)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z) and the digits 0-9.

    Parameters:
      `count` - the length of random string to create
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0.

  - ### randomAlphanumeric

    public static String randomAlphanumeric(int minLengthInclusive, int maxLengthExclusive)
    Creates a random string whose length is between the inclusive minimum and the exclusive maximum.

    Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z) and the digits 0-9.

    Parameters:
      `minLengthInclusive` - the inclusive minimum length of the string to generate
      `maxLengthExclusive` - the exclusive maximum length of the string to generate
    Returns:
      the random string
    Since:
      3.5

  - ### randomAscii

    public static String randomAscii(int count)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of characters whose ASCII value is between `32` and `126` (inclusive).

    Parameters:
      `count` - the length of random string to create
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0.

  - ### randomAscii

    public static String randomAscii(int minLengthInclusive, int maxLengthExclusive)
    Creates a random string whose length is between the inclusive minimum and the exclusive maximum.

    Characters will be chosen from the set of characters whose ASCII value is between `32` and `126` (inclusive).

    Parameters:
      `minLengthInclusive` - the inclusive minimum length of the string to generate
      `maxLengthExclusive` - the exclusive maximum length of the string to generate
    Returns:
      the random string
    Since:
      3.5

  - ### randomGraph

    public static String randomGraph(int count)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of characters which match the POSIX [:graph:] regular expression character class. This class contains all visible ASCII characters (i.e. anything except spaces and control characters).

    Parameters:
      `count` - the length of random string to create
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0.
    Since:
      3.5

  - ### randomGraph

    public static String randomGraph(int minLengthInclusive, int maxLengthExclusive)
    Creates a random string whose length is between the inclusive minimum and the exclusive maximum.

    Characters will be chosen from the set of \p{Graph} characters.

    Parameters:
      `minLengthInclusive` - the inclusive minimum length of the string to generate
      `maxLengthExclusive` - the exclusive maximum length of the string to generate
    Returns:
      the random string
    Since:
      3.5

  - ### randomNumeric

    public static String randomNumeric(int count)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of numeric characters.

    Parameters:
      `count` - the length of random string to create
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0.

  - ### randomNumeric

    public static String randomNumeric(int minLengthInclusive, int maxLengthExclusive)
    Creates a random string whose length is between the inclusive minimum and the exclusive maximum.

    Characters will be chosen from the set of \p{Digit} characters.

    Parameters:
      `minLengthInclusive` - the inclusive minimum length of the string to generate
      `maxLengthExclusive` - the exclusive maximum length of the string to generate
    Returns:
      the random string
    Since:
      3.5

  - ### randomPrint

    public static String randomPrint(int count)
    Creates a random string whose length is the number of characters specified.

    Characters will be chosen from the set of characters which match the POSIX [:print:] regular expression character class. This class includes all visible ASCII characters and spaces (i.e. anything except control characters).

    Parameters:
      `count` - the length of random string to create
    Returns:
      the random string
    Throws:
      `IllegalArgumentException` - if `count` < 0.
    Since:
      3.5

  - ### randomPrint

    public static String randomPrint(int minLengthInclusive, int maxLengthExclusive)
    Creates a random string whose length is between the inclusive minimum and the exclusive maximum.

    Characters will be chosen from the set of \p{Print} characters.

    Parameters:
      `minLengthInclusive` - the inclusive minimum length of the string to generate
      `maxLengthExclusive` - the exclusive maximum length of the string to generate
    Returns:
      the random string
    Since:
      3.5