    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.lang3;
    018
    019import java.security.SecureRandom;
    020import java.security.Security;
    021import java.util.Random;
    022import java.util.concurrent.ThreadLocalRandom;
    023import java.util.function.Supplier;
    024
    025/**
    026 * Generates random {@link String}s.
    027 * <p>
    028 * Starting in version 3.16.0, this class uses {@link #secure()} for static methods and adds {@link #insecure()}.
    029 * </p>
    030 * <p>
    031 * Starting in version 3.15.0, this class uses {@link SecureRandom#getInstanceStrong()} for static methods.
    032 * </p>
    033 * <p>
    034 * Before version 3.15.0, this class used {@link ThreadLocalRandom#current()} for static methods, which is not
    035 * cryptographically secure.
    036 * </p>
    037 * <p>
    038 * Use {@link #secure()} to get the singleton instance based on {@link SecureRandom#getInstanceStrong()} which uses an
    039 * algorithms/providers specified in the {@code securerandom.strongAlgorithms} {@link Security} property.
    040 * </p>
    041 * <p>
    042 * Use {@link #insecure()} to get the singleton instance based on {@link ThreadLocalRandom#current()}; <b>which is not
    043 * cryptographically secure</b>.
    044 * </p>
    045 * <p>
    046 * RandomStringUtils is intended for simple use cases. For more advanced use cases consider using Apache Commons Text's
    047 * <a href=
    048 * "https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/RandomStringGenerator.html">
    049 * RandomStringGenerator</a> instead.
    050 * </p>
    051 * <p>
    052 * The Apache Commons project provides <a href="https://commons.apache.org/proper/commons-rng/">Commons RNG</a>
    053 * dedicated to pseudo-random number generation, that may be a better choice for applications with more stringent
    054 * requirements (performance and/or correctness).
    055 * </p>
    056 * <p>
    057 * Note that <em>private high surrogate</em> characters are ignored. These are Unicode characters that fall between the
    058 * values 56192 (db80) and 56319 (dbff) as we don't know how to handle them. High and low surrogates are correctly dealt
    059 * with - that is if a high surrogate is randomly chosen, 55296 (d800) to 56191 (db7f) then it is followed by a low
    060 * surrogate. If a low surrogate is chosen, 56320 (dc00) to 57343 (dfff) then it is placed after a randomly chosen high
    061 * surrogate.
    062 * </p>
    063 * <p>
    064 * #ThreadSafe#
    065 * </p>
    066 *
    067 * @see RandomUtils
    068 * @since 1.0
    069 */
    070public class RandomStringUtils {
    071
    072    private static final Supplier<RandomUtils> SECURE_SUPPLIER = RandomUtils::secure;
    073
    074    private static RandomStringUtils INSECURE = new RandomStringUtils(RandomUtils::insecure);
    075
    076    private static RandomStringUtils SECURE = new RandomStringUtils(SECURE_SUPPLIER);
    077
    078    private static final char[] ALPHANUMERICAL_CHARS = { 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l',
    079            'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', 'A', 'B', 'C', 'D', 'E', 'F', 'G',
    080            'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '0', '1',
    081            '2', '3', '4', '5', '6', '7', '8', '9' };
    082
    083    /**
    084     * Gets the singleton instance based on {@link ThreadLocalRandom#current()}; <b>which is not cryptographically
    085     * secure</b>; use {@link #secure()} to use an algorithms/providers specified in the
    086     * {@code securerandom.strongAlgorithms} {@link Security} property.
    087     * <p>
    088     * The method {@link ThreadLocalRandom#current()} is called on-demand.
    089     * </p>
    090     *
    091     * @return the singleton instance based on {@link ThreadLocalRandom#current()}.
    092     * @see ThreadLocalRandom#current()
    093     * @see #secure()
    094     * @since 3.16.0
    095     */
    096    public static RandomStringUtils insecure() {
    097        return INSECURE;
    098    }
    099
    100    /**
    101     * Creates a random string whose length is the number of characters specified.
    102     *
    103     * <p>
    104     * Characters will be chosen from the set of all characters.
    105     * </p>
    106     *
    107     * @param count the length of random string to create
    108     * @return the random string
    109     * @throws IllegalArgumentException if {@code count} &lt; 0.
    110     */
    111    public static String random(final int count) {
    112        return secure().next(count);
    113    }
    114
    115    /**
    116     * Creates a random string whose length is the number of characters specified.
    117     *
    118     * <p>
    119     * Characters will be chosen from the set of alpha-numeric characters as indicated by the arguments.
    120     * </p>
    121     *
    122     * @param count   the length of random string to create
    123     * @param letters if {@code true}, generated string may include alphabetic characters
    124     * @param numbers if {@code true}, generated string may include numeric characters
    125     * @return the random string
    126     * @throws IllegalArgumentException if {@code count} &lt; 0.
    127     */
    128    public static String random(final int count, final boolean letters, final boolean numbers) {
    129        return secure().next(count, letters, numbers);
    130    }
    131
    132    /**
    133     * Creates a random string whose length is the number of characters specified.
    134     *
    135     * <p>
    136     * Characters will be chosen from the set of characters specified.
    137     * </p>
    138     *
    139     * @param count the length of random string to create
    140     * @param chars the character array containing the set of characters to use, may be null
    141     * @return the random string
    142     * @throws IllegalArgumentException if {@code count} &lt; 0.
    143     */
    144    public static String random(final int count, final char... chars) {
    145        return secure().next(count, chars);
    146    }
    147
    148    /**
    149     * Creates a random string whose length is the number of characters specified.
    150     *
    151     * <p>
    152     * Characters will be chosen from the set of alpha-numeric characters as indicated by the arguments.
    153     * </p>
    154     *
    155     * @param count   the length of random string to create
    156     * @param start   the position in set of chars to start at
    157     * @param end     the position in set of chars to end before
    158     * @param letters if {@code true}, generated string may include alphabetic characters
    159     * @param numbers if {@code true}, generated string may include numeric characters
    160     * @return the random string
    161     * @throws IllegalArgumentException if {@code count} &lt; 0.
    162     */
    163    public static String random(final int count, final int start, final int end, final boolean letters,
    164            final boolean numbers) {
    165        return secure().next(count, start, end, letters, numbers);
    166    }
    167
    168    /**
    169     * Creates a random string based on a variety of options, using default source of randomness.
    170     *
    171     * <p>
    172     * This method has exactly the same semantics as {@link #random(int,int,int,boolean,boolean,char[],Random)}, but
    173     * instead of using an externally supplied source of randomness, it uses the internal static {@link Random}
    174     * instance.
    175     * </p>
    176     *
    177     * @param count   the length of random string to create
    178     * @param start   the position in set of chars to start at
    179     * @param end     the position in set of chars to end before
    180     * @param letters if {@code true}, generated string may include alphabetic characters
    181     * @param numbers if {@code true}, generated string may include numeric characters
    182     * @param chars   the set of chars to choose randoms from. If {@code null}, then it will use the set of all chars.
    183     * @return the random string
    184     * @throws ArrayIndexOutOfBoundsException if there are not {@code (end - start) + 1} characters in the set array.
    185     * @throws IllegalArgumentException       if {@code count} &lt; 0.
    186     */
    187    public static String random(final int count, final int start, final int end, final boolean letters,
    188            final boolean numbers, final char... chars) {
    189        return secure().next(count, start, end, letters, numbers, chars);
    190    }
    191
    192    /**
    193     * Creates a random string based on a variety of options, using supplied source of randomness.
    194     *
    195     * <p>
    196     * If start and end are both {@code 0}, start and end are set to {@code ' '} and {@code 'z'}, the ASCII printable
    197     * characters, will be used, unless letters and numbers are both {@code false}, in which case, start and end are set
    198     * to {@code 0} and {@link Character#MAX_CODE_POINT}.
    199     *
    200     * <p>
    201     * If set is not {@code null}, characters between start and end are chosen.
    202     * </p>
    203     *
    204     * <p>
    205     * This method accepts a user-supplied {@link Random} instance to use as a source of randomness. By seeding a single
    206     * {@link Random} instance with a fixed seed and using it for each call, the same random sequence of strings can be
    207     * generated repeatedly and predictably.
    208     * </p>
    209     *
    210     * @param count   the length of random string to create
    211     * @param start   the position in set of chars to start at (inclusive)
    212     * @param end     the position in set of chars to end before (exclusive)
    213     * @param letters if {@code true}, generated string may include alphabetic characters
    214     * @param numbers if {@code true}, generated string may include numeric characters
    215     * @param chars   the set of chars to choose randoms from, must not be empty. If {@code null}, then it will use the
    216     *                set of all chars.
    217     * @param random  a source of randomness.
    218     * @return the random string
    219     * @throws ArrayIndexOutOfBoundsException if there are not {@code (end - start) + 1} characters in the set array.
    220     * @throws IllegalArgumentException       if {@code count} &lt; 0 or the provided chars array is empty.
    221     * @since 2.0
    222     */
    223    public static String random(int count, int start, int end, final boolean letters, final boolean numbers,
    224            final char[] chars, final Random random) {
    225        if (count == 0) {
    226            return StringUtils.EMPTY;
    227        }
    228        if (count < 0) {
    229            throw new IllegalArgumentException("Requested random string length " + count + " is less than 0.");
    230        }
    231        if (chars != null && chars.length == 0) {
    232            throw new IllegalArgumentException("The chars array must not be empty");
    233        }
    234
    235        if (start == 0 && end == 0) {
    236            if (chars != null) {
    237                end = chars.length;
    238            } else if (!letters && !numbers) {
    239                end = Character.MAX_CODE_POINT;
    240            } else {
    241                end = 'z' + 1;
    242                start = ' ';
    243            }
    244        } else if (end <= start) {
    245            throw new IllegalArgumentException(
    246                    "Parameter end (" + end + ") must be greater than start (" + start + ")");
    247        } else if (start < 0 || end < 0) {
    248            throw new IllegalArgumentException("Character positions MUST be >= 0");
    249        }
    250
    251        if (end > Character.MAX_CODE_POINT) {
    252            // Technically, it should be `Character.MAX_CODE_POINT+1` as `end` is excluded
    253            // But the character `Character.MAX_CODE_POINT` is private use, so it would anyway be excluded
    254            end = Character.MAX_CODE_POINT;
    255        }
    256
    257        // Optimize generation of full alphanumerical characters
    258        // Normally, we would need to pick a 7-bit integer, since gap = 'z' - '0' + 1 = 75 > 64
    259        // In turn, this would make us reject the sampling with probability 1 - 62 / 2^7 > 1 / 2
    260        // Instead we can pick directly from the right set of 62 characters, which requires
    261        // picking a 6-bit integer and only rejecting with probability 2 / 64 = 1 / 32
    262        if (chars == null && letters && numbers && start <= '0' && end >= 'z' + 1) {
    263            return random(count, 0, 0, false, false, ALPHANUMERICAL_CHARS, random);
    264        }
    265
    266        // Optimize start and end when filtering by letters and/or numbers:
    267        // The range provided may be too large since we filter anyway afterward.
    268        // Note the use of Math.min/max (as opposed to setting start to '0' for example),
    269        // since it is possible the range start/end excludes some of the letters/numbers,
    270        // e.g., it is possible that start already is '1' when numbers = true, and start
    271        // needs to stay equal to '1' in that case.
    272        if (chars == null) {
    273            if (letters && numbers) {
    274                start = Math.max('0', start);
    275                end = Math.min('z' + 1, end);
    276            } else if (numbers) {
    277                // just numbers, no letters
    278                start = Math.max('0', start);
    279                end = Math.min('9' + 1, end);
    280            } else if (letters) {
    281                // just letters, no numbers
    282                start = Math.max('A', start);
    283                end = Math.min('z' + 1, end);
    284            }
    285        }
    286
    287        final int zeroDigitAscii = 48;
    288        final int firstLetterAscii = 65;
    289
    290        if (chars == null && (numbers && end <= zeroDigitAscii || letters && end <= firstLetterAscii)) {
    291            throw new IllegalArgumentException(
    292                    "Parameter end (" + end + ") must be greater then (" + zeroDigitAscii + ") for generating digits "
    293                            + "or greater then (" + firstLetterAscii + ") for generating letters.");
    294        }
    295
    296        final StringBuilder builder = new StringBuilder(count);
    297        final int gap = end - start;
    298        final int gapBits = Integer.SIZE - Integer.numberOfLeadingZeros(gap);
    299        // The size of the cache we use is an heuristic:
    300        // about twice the number of bytes required if no rejection
    301        // Ideally the cache size depends on multiple factor, including the cost of generating x bytes
    302        // of randomness as well as the probability of rejection. It is however not easy to know
    303        // those values programmatically for the general case.
    304        final CachedRandomBits arb = new CachedRandomBits((count * gapBits + 3) / 5 + 10, random);
    305
    306        while (count-- != 0) {
    307            // Generate a random value between start (included) and end (excluded)
    308            final int randomValue = arb.nextBits(gapBits) + start;
    309            // Rejection sampling if value too large
    310            if (randomValue >= end) {
    311                count++;
    312                continue;
    313            }
    314
    315            final int codePoint;
    316            if (chars == null) {
    317                codePoint = randomValue;
    318
    319                switch (Character.getType(codePoint)) {
    320                case Character.UNASSIGNED:
    321                case Character.PRIVATE_USE:
    322                case Character.SURROGATE:
    323                    count++;
    324                    continue;
    325                }
    326
    327            } else {
    328                codePoint = chars[randomValue];
    329            }
    330
    331            final int numberOfChars = Character.charCount(codePoint);
    332            if (count == 0 && numberOfChars > 1) {
    333                count++;
    334                continue;
    335            }
    336
    337            if (letters && Character.isLetter(codePoint) || numbers && Character.isDigit(codePoint)
    338                    || !letters && !numbers) {
    339                builder.appendCodePoint(codePoint);
    340
    341                if (numberOfChars == 2) {
    342                    count--;
    343                }
    344
    345            } else {
    346                count++;
    347            }
    348        }
    349        return builder.toString();
    350    }
    351
    352    /**
    353     * Creates a random string whose length is the number of characters specified.
    354     *
    355     * <p>
    356     * Characters will be chosen from the set of characters specified by the string, must not be empty. If null, the set
    357     * of all characters is used.
    358     * </p>
    359     *
    360     * @param count the length of random string to create
    361     * @param chars the String containing the set of characters to use, may be null, but must not be empty
    362     * @return the random string
    363     * @throws IllegalArgumentException if {@code count} &lt; 0 or the string is empty.
    364     */
    365    public static String random(final int count, final String chars) {
    366        return secure().next(count, chars);
    367    }
    368
    369    /**
    370     * Creates a random string whose length is the number of characters specified.
    371     *
    372     * <p>
    373     * Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z).
    374     * </p>
    375     *
    376     * @param count the length of random string to create
    377     * @return the random string
    378     * @throws IllegalArgumentException if {@code count} &lt; 0.
    379     */
    380    public static String randomAlphabetic(final int count) {
    381        return secure().nextAlphabetic(count);
    382    }
    383
    384    /**
    385     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    386     *
    387     * <p>
    388     * Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z).
    389     * </p>
    390     *
    391     * @param minLengthInclusive the inclusive minimum length of the string to generate
    392     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    393     * @return the random string
    394     * @since 3.5
    395     */
    396    public static String randomAlphabetic(final int minLengthInclusive, final int maxLengthExclusive) {
    397        return secure().nextAlphabetic(minLengthInclusive, maxLengthExclusive);
    398    }
    399
    400    /**
    401     * Creates a random string whose length is the number of characters specified.
    402     *
    403     * <p>
    404     * Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z) and the digits 0-9.
    405     * </p>
    406     *
    407     * @param count the length of random string to create
    408     * @return the random string
    409     * @throws IllegalArgumentException if {@code count} &lt; 0.
    410     */
    411    public static String randomAlphanumeric(final int count) {
    412        return secure().nextAlphanumeric(count);
    413    }
    414
    415    /**
    416     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    417     *
    418     * <p>
    419     * Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z) and the digits 0-9.
    420     * </p>
    421     *
    422     * @param minLengthInclusive the inclusive minimum length of the string to generate
    423     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    424     * @return the random string
    425     * @since 3.5
    426     */
    427    public static String randomAlphanumeric(final int minLengthInclusive, final int maxLengthExclusive) {
    428        return secure().nextAlphanumeric(minLengthInclusive, maxLengthExclusive);
    429    }
    430
    431    /**
    432     * Creates a random string whose length is the number of characters specified.
    433     *
    434     * <p>
    435     * Characters will be chosen from the set of characters whose ASCII value is between {@code 32} and {@code 126}
    436     * (inclusive).
    437     * </p>
    438     *
    439     * @param count the length of random string to create
    440     * @return the random string
    441     * @throws IllegalArgumentException if {@code count} &lt; 0.
    442     */
    443    public static String randomAscii(final int count) {
    444        return secure().nextAscii(count);
    445    }
    446
    447    /**
    448     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    449     *
    450     * <p>
    451     * Characters will be chosen from the set of characters whose ASCII value is between {@code 32} and {@code 126}
    452     * (inclusive).
    453     * </p>
    454     *
    455     * @param minLengthInclusive the inclusive minimum length of the string to generate
    456     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    457     * @return the random string
    458     * @since 3.5
    459     */
    460    public static String randomAscii(final int minLengthInclusive, final int maxLengthExclusive) {
    461        return secure().nextAscii(minLengthInclusive, maxLengthExclusive);
    462    }
    463
    464    /**
    465     * Creates a random string whose length is the number of characters specified.
    466     *
    467     * <p>
    468     * Characters will be chosen from the set of characters which match the POSIX [:graph:] regular expression character
    469     * class. This class contains all visible ASCII characters (i.e. anything except spaces and control characters).
    470     * </p>
    471     *
    472     * @param count the length of random string to create
    473     * @return the random string
    474     * @throws IllegalArgumentException if {@code count} &lt; 0.
    475     * @since 3.5
    476     */
    477    public static String randomGraph(final int count) {
    478        return secure().nextGraph(count);
    479    }
    480
    481    /**
    482     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    483     *
    484     * <p>
    485     * Characters will be chosen from the set of \p{Graph} characters.
    486     * </p>
    487     *
    488     * @param minLengthInclusive the inclusive minimum length of the string to generate
    489     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    490     * @return the random string
    491     * @since 3.5
    492     */
    493    public static String randomGraph(final int minLengthInclusive, final int maxLengthExclusive) {
    494        return secure().nextGraph(minLengthInclusive, maxLengthExclusive);
    495    }
    496
    497    /**
    498     * Creates a random string whose length is the number of characters specified.
    499     *
    500     * <p>
    501     * Characters will be chosen from the set of numeric characters.
    502     * </p>
    503     *
    504     * @param count the length of random string to create
    505     * @return the random string
    506     * @throws IllegalArgumentException if {@code count} &lt; 0.
    507     */
    508    public static String randomNumeric(final int count) {
    509        return secure().nextNumeric(count);
    510    }
    511
    512    /**
    513     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    514     *
    515     * <p>
    516     * Characters will be chosen from the set of \p{Digit} characters.
    517     * </p>
    518     *
    519     * @param minLengthInclusive the inclusive minimum length of the string to generate
    520     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    521     * @return the random string
    522     * @since 3.5
    523     */
    524    public static String randomNumeric(final int minLengthInclusive, final int maxLengthExclusive) {
    525        return secure().nextNumeric(minLengthInclusive, maxLengthExclusive);
    526    }
    527
    528    /**
    529     * Creates a random string whose length is the number of characters specified.
    530     *
    531     * <p>
    532     * Characters will be chosen from the set of characters which match the POSIX [:print:] regular expression character
    533     * class. This class includes all visible ASCII characters and spaces (i.e. anything except control characters).
    534     * </p>
    535     *
    536     * @param count the length of random string to create
    537     * @return the random string
    538     * @throws IllegalArgumentException if {@code count} &lt; 0.
    539     * @since 3.5
    540     */
    541    public static String randomPrint(final int count) {
    542        return secure().nextPrint(count);
    543    }
    544
    545    /**
    546     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    547     *
    548     * <p>
    549     * Characters will be chosen from the set of \p{Print} characters.
    550     * </p>
    551     *
    552     * @param minLengthInclusive the inclusive minimum length of the string to generate
    553     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    554     * @return the random string
    555     * @since 3.5
    556     */
    557    public static String randomPrint(final int minLengthInclusive, final int maxLengthExclusive) {
    558        return secure().nextPrint(minLengthInclusive, maxLengthExclusive);
    559    }
    560
    561    /**
    562     * Gets the singleton instance based on {@link SecureRandom#getInstanceStrong()} which uses an algorithms/providers
    563     * specified in the {@code securerandom.strongAlgorithms} {@link Security} property.
    564     * <p>
    565     * The method {@link SecureRandom#getInstanceStrong()} is called on-demand.
    566     * </p>
    567     *
    568     * @return the singleton instance based on {@link SecureRandom#getInstanceStrong()}.
    569     * @see SecureRandom#getInstanceStrong()
    570     * @since 3.16.0
    571     */
    572    public static RandomStringUtils secure() {
    573        return SECURE;
    574    }
    575
    576    private final Supplier<RandomUtils> random;
    577
    578    /**
    579     * {@link RandomStringUtils} instances should NOT be constructed in standard programming. Instead, the class should
    580     * be used as {@code RandomStringUtils.random(5);}.
    581     *
    582     * <p>
    583     * This constructor is public to permit tools that require a JavaBean instance to operate.
    584     * </p>
    585     *
    586     * @deprecated TODO Make private in 4.0.
    587     */
    588    @Deprecated
    589    public RandomStringUtils() {
    590        this(SECURE_SUPPLIER);
    591    }
    592
    593    private RandomStringUtils(final Supplier<RandomUtils> random) {
    594        this.random = random;
    595    }
    596
    597    /**
    598     * Creates a random string whose length is the number of characters specified.
    599     *
    600     * <p>
    601     * Characters will be chosen from the set of all characters.
    602     * </p>
    603     *
    604     * @param count the length of random string to create
    605     * @return the random string
    606     * @throws IllegalArgumentException if {@code count} &lt; 0.
    607     * @since 3.16.0
    608     */
    609    public String next(final int count) {
    610        return random(count, false, false);
    611    }
    612
    613    /**
    614     * Creates a random string whose length is the number of characters specified.
    615     *
    616     * <p>
    617     * Characters will be chosen from the set of alpha-numeric characters as indicated by the arguments.
    618     * </p>
    619     *
    620     * @param count   the length of random string to create
    621     * @param letters if {@code true}, generated string may include alphabetic characters
    622     * @param numbers if {@code true}, generated string may include numeric characters
    623     * @return the random string
    624     * @throws IllegalArgumentException if {@code count} &lt; 0.
    625     * @since 3.16.0
    626     */
    627    public String next(final int count, final boolean letters, final boolean numbers) {
    628        return random(count, 0, 0, letters, numbers);
    629    }
    630
    631    /**
    632     * Creates a random string whose length is the number of characters specified.
    633     *
    634     * <p>
    635     * Characters will be chosen from the set of characters specified.
    636     * </p>
    637     *
    638     * @param count the length of random string to create
    639     * @param chars the character array containing the set of characters to use, may be null
    640     * @return the random string
    641     * @throws IllegalArgumentException if {@code count} &lt; 0.
    642     * @since 3.16.0
    643     */
    644    public String next(final int count, final char... chars) {
    645        if (chars == null) {
    646            return random(count, 0, 0, false, false, null, random());
    647        }
    648        return random(count, 0, chars.length, false, false, chars, random());
    649    }
    650
    651    /**
    652     * Creates a random string whose length is the number of characters specified.
    653     *
    654     * <p>
    655     * Characters will be chosen from the set of alpha-numeric characters as indicated by the arguments.
    656     * </p>
    657     *
    658     * @param count   the length of random string to create
    659     * @param start   the position in set of chars to start at
    660     * @param end     the position in set of chars to end before
    661     * @param letters if {@code true}, generated string may include alphabetic characters
    662     * @param numbers if {@code true}, generated string may include numeric characters
    663     * @return the random string
    664     * @throws IllegalArgumentException if {@code count} &lt; 0.
    665     * @since 3.16.0
    666     */
    667    public String next(final int count, final int start, final int end, final boolean letters, final boolean numbers) {
    668        return random(count, start, end, letters, numbers, null, random());
    669    }
    670
    671    /**
    672     * Creates a random string based on a variety of options, using default source of randomness.
    673     *
    674     * <p>
    675     * This method has exactly the same semantics as {@link #random(int,int,int,boolean,boolean,char[],Random)}, but
    676     * instead of using an externally supplied source of randomness, it uses the internal static {@link Random}
    677     * instance.
    678     * </p>
    679     *
    680     * @param count   the length of random string to create
    681     * @param start   the position in set of chars to start at
    682     * @param end     the position in set of chars to end before
    683     * @param letters if {@code true}, generated string may include alphabetic characters
    684     * @param numbers if {@code true}, generated string may include numeric characters
    685     * @param chars   the set of chars to choose randoms from. If {@code null}, then it will use the set of all chars.
    686     * @return the random string
    687     * @throws ArrayIndexOutOfBoundsException if there are not {@code (end - start) + 1} characters in the set array.
    688     * @throws IllegalArgumentException       if {@code count} &lt; 0.
    689     */
    690    public String next(final int count, final int start, final int end, final boolean letters, final boolean numbers,
    691            final char... chars) {
    692        return random(count, start, end, letters, numbers, chars, random());
    693    }
    694
    695    /**
    696     * Creates a random string whose length is the number of characters specified.
    697     *
    698     * <p>
    699     * Characters will be chosen from the set of characters specified by the string, must not be empty. If null, the set
    700     * of all characters is used.
    701     * </p>
    702     *
    703     * @param count the length of random string to create
    704     * @param chars the String containing the set of characters to use, may be null, but must not be empty
    705     * @return the random string
    706     * @throws IllegalArgumentException if {@code count} &lt; 0 or the string is empty.
    707     * @since 3.16.0
    708     */
    709    public String next(final int count, final String chars) {
    710        if (chars == null) {
    711            return random(count, 0, 0, false, false, null, random());
    712        }
    713        return random(count, chars.toCharArray());
    714    }
    715
    716    /**
    717     * Creates a random string whose length is the number of characters specified.
    718     *
    719     * <p>
    720     * Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z).
    721     * </p>
    722     *
    723     * @param count the length of random string to create
    724     * @return the random string
    725     * @throws IllegalArgumentException if {@code count} &lt; 0.
    726     */
    727    public String nextAlphabetic(final int count) {
    728        return random(count, true, false);
    729    }
    730
    731    /**
    732     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    733     *
    734     * <p>
    735     * Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z).
    736     * </p>
    737     *
    738     * @param minLengthInclusive the inclusive minimum length of the string to generate
    739     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    740     * @return the random string
    741     * @since 3.5
    742     */
    743    public String nextAlphabetic(final int minLengthInclusive, final int maxLengthExclusive) {
    744        return randomAlphabetic(randomUtils().randomInt(minLengthInclusive, maxLengthExclusive));
    745    }
    746
    747    /**
    748     * Creates a random string whose length is the number of characters specified.
    749     *
    750     * <p>
    751     * Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z) and the digits 0-9.
    752     * </p>
    753     *
    754     * @param count the length of random string to create
    755     * @return the random string
    756     * @throws IllegalArgumentException if {@code count} &lt; 0.
    757     */
    758    public String nextAlphanumeric(final int count) {
    759        return random(count, true, true);
    760    }
    761
    762    /**
    763     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    764     *
    765     * <p>
    766     * Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z) and the digits 0-9.
    767     * </p>
    768     *
    769     * @param minLengthInclusive the inclusive minimum length of the string to generate
    770     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    771     * @return the random string
    772     * @since 3.5
    773     */
    774    public String nextAlphanumeric(final int minLengthInclusive, final int maxLengthExclusive) {
    775        return randomAlphanumeric(randomUtils().randomInt(minLengthInclusive, maxLengthExclusive));
    776    }
    777
    778    /**
    779     * Creates a random string whose length is the number of characters specified.
    780     *
    781     * <p>
    782     * Characters will be chosen from the set of characters whose ASCII value is between {@code 32} and {@code 126}
    783     * (inclusive).
    784     * </p>
    785     *
    786     * @param count the length of random string to create
    787     * @return the random string
    788     * @throws IllegalArgumentException if {@code count} &lt; 0.
    789     */
    790    public String nextAscii(final int count) {
    791        return random(count, 32, 127, false, false);
    792    }
    793
    794    /**
    795     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    796     *
    797     * <p>
    798     * Characters will be chosen from the set of characters whose ASCII value is between {@code 32} and {@code 126}
    799     * (inclusive).
    800     * </p>
    801     *
    802     * @param minLengthInclusive the inclusive minimum length of the string to generate
    803     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    804     * @return the random string
    805     * @since 3.5
    806     */
    807    public String nextAscii(final int minLengthInclusive, final int maxLengthExclusive) {
    808        return randomAscii(randomUtils().randomInt(minLengthInclusive, maxLengthExclusive));
    809    }
    810
    811    /**
    812     * Creates a random string whose length is the number of characters specified.
    813     *
    814     * <p>
    815     * Characters will be chosen from the set of characters which match the POSIX [:graph:] regular expression character
    816     * class. This class contains all visible ASCII characters (i.e. anything except spaces and control characters).
    817     * </p>
    818     *
    819     * @param count the length of random string to create
    820     * @return the random string
    821     * @throws IllegalArgumentException if {@code count} &lt; 0.
    822     * @since 3.5
    823     */
    824    public String nextGraph(final int count) {
    825        return random(count, 33, 126, false, false);
    826    }
    827
    828    /**
    829     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    830     *
    831     * <p>
    832     * Characters will be chosen from the set of \p{Graph} characters.
    833     * </p>
    834     *
    835     * @param minLengthInclusive the inclusive minimum length of the string to generate
    836     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    837     * @return the random string
    838     * @since 3.5
    839     */
    840    public String nextGraph(final int minLengthInclusive, final int maxLengthExclusive) {
    841        return randomGraph(randomUtils().randomInt(minLengthInclusive, maxLengthExclusive));
    842    }
    843
    844    /**
    845     * Creates a random string whose length is the number of characters specified.
    846     *
    847     * <p>
    848     * Characters will be chosen from the set of numeric characters.
    849     * </p>
    850     *
    851     * @param count the length of random string to create
    852     * @return the random string
    853     * @throws IllegalArgumentException if {@code count} &lt; 0.
    854     */
    855    public String nextNumeric(final int count) {
    856        return random(count, false, true);
    857    }
    858
    859    /**
    860     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    861     *
    862     * <p>
    863     * Characters will be chosen from the set of \p{Digit} characters.
    864     * </p>
    865     *
    866     * @param minLengthInclusive the inclusive minimum length of the string to generate
    867     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    868     * @return the random string
    869     * @since 3.5
    870     */
    871    public String nextNumeric(final int minLengthInclusive, final int maxLengthExclusive) {
    872        return randomNumeric(randomUtils().randomInt(minLengthInclusive, maxLengthExclusive));
    873    }
    874
    875    /**
    876     * Creates a random string whose length is the number of characters specified.
    877     *
    878     * <p>
    879     * Characters will be chosen from the set of characters which match the POSIX [:print:] regular expression character
    880     * class. This class includes all visible ASCII characters and spaces (i.e. anything except control characters).
    881     * </p>
    882     *
    883     * @param count the length of random string to create
    884     * @return the random string
    885     * @throws IllegalArgumentException if {@code count} &lt; 0.
    886     * @since 3.5
    887     * @since 3.16.0
    888     */
    889    public String nextPrint(final int count) {
    890        return random(count, 32, 126, false, false);
    891    }
    892
    893    /**
    894     * Creates a random string whose length is between the inclusive minimum and the exclusive maximum.
    895     *
    896     * <p>
    897     * Characters will be chosen from the set of \p{Print} characters.
    898     * </p>
    899     *
    900     * @param minLengthInclusive the inclusive minimum length of the string to generate
    901     * @param maxLengthExclusive the exclusive maximum length of the string to generate
    902     * @return the random string
    903     * @since 3.16.0
    904     */
    905    public String nextPrint(final int minLengthInclusive, final int maxLengthExclusive) {
    906        return randomPrint(randomUtils().randomInt(minLengthInclusive, maxLengthExclusive));
    907    }
    908
    909    /**
    910     * Gets the Random.
    911     *
    912     * @return the Random.
    913     */
    914    private Random random() {
    915        return randomUtils().random();
    916    }
    917
    918    /**
    919     * Gets the RandomUtils.
    920     *
    921     * @return the RandomUtils.
    922     */
    923    private RandomUtils randomUtils() {
    924        return random.get();
    925    }
    926
    927    @Override
    928    public String toString() {
    929        return "RandomStringUtils [random=" + random() + "]";
    930    }
    931
    932}