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