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}