View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3;
18  
19  import java.util.Random;
20  
21  /**
22   * <p>Operations for random {@code String}s.</p>
23   * <p>Currently <em>private high surrogate</em> characters are ignored.
24   * These are Unicode characters that fall between the values 56192 (db80)
25   * and 56319 (dbff) as we don't know how to handle them.
26   * High and low surrogates are correctly dealt with - that is if a
27   * high surrogate is randomly chosen, 55296 (d800) to 56191 (db7f)
28   * then it is followed by a low surrogate. If a low surrogate is chosen,
29   * 56320 (dc00) to 57343 (dfff) then it is placed after a randomly
30   * chosen high surrogate. </p>
31   *
32   * <p>#ThreadSafe#</p>
33   * @since 1.0
34   * @deprecated as of 3.6, use commons-text
35   * <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/RandomStringGenerator.html">
36   * RandomStringGenerator</a> instead
37   */
38  @Deprecated
39  public class RandomStringUtils {
40  
41      /**
42       * <p>Random object used by random method. This has to be not local
43       * to the random method so as to not return the same value in the
44       * same millisecond.</p>
45       */
46      private static final Random RANDOM = new Random();
47  
48      /**
49       * <p>{@code RandomStringUtils} instances should NOT be constructed in
50       * standard programming. Instead, the class should be used as
51       * {@code RandomStringUtils.random(5);}.</p>
52       *
53       * <p>This constructor is public to permit tools that require a JavaBean instance
54       * to operate.</p>
55       */
56      public RandomStringUtils() {
57        super();
58      }
59  
60      // Random
61      //-----------------------------------------------------------------------
62      /**
63       * <p>Creates a random string whose length is the number of characters
64       * specified.</p>
65       *
66       * <p>Characters will be chosen from the set of all characters.</p>
67       *
68       * @param count  the length of random string to create
69       * @return the random string
70       */
71      public static String random(final int count) {
72          return random(count, false, false);
73      }
74  
75      /**
76       * <p>Creates a random string whose length is the number of characters
77       * specified.</p>
78       *
79       * <p>Characters will be chosen from the set of characters whose
80       * ASCII value is between {@code 32} and {@code 126} (inclusive).</p>
81       *
82       * @param count  the length of random string to create
83       * @return the random string
84       */
85      public static String randomAscii(final int count) {
86          return random(count, 32, 127, false, false);
87      }
88  
89      /**
90       * <p>Creates a random string whose length is between the inclusive minimum and
91       * the exclusive maximum.</p>
92       *
93       * <p>Characters will be chosen from the set of characters whose
94       * ASCII value is between {@code 32} and {@code 126} (inclusive).</p>
95       *
96       * @param minLengthInclusive the inclusive minimum length of the string to generate
97       * @param maxLengthExclusive the exclusive maximum length of the string to generate
98       * @return the random string
99       * @since 3.5
100      */
101     public static String randomAscii(final int minLengthInclusive, final int maxLengthExclusive) {
102         return randomAscii(RandomUtils.nextInt(minLengthInclusive, maxLengthExclusive));
103     }
104 
105     /**
106      * <p>Creates a random string whose length is the number of characters
107      * specified.</p>
108      *
109      * <p>Characters will be chosen from the set of Latin alphabetic
110      * characters (a-z, A-Z).</p>
111      *
112      * @param count  the length of random string to create
113      * @return the random string
114      */
115     public static String randomAlphabetic(final int count) {
116         return random(count, true, false);
117     }
118 
119     /**
120      * <p>Creates a random string whose length is between the inclusive minimum and
121      * the exclusive maximum.</p>
122      *
123      * <p>Characters will be chosen from the set of Latin alphabetic characters (a-z, A-Z).</p>
124      *
125      * @param minLengthInclusive the inclusive minimum length of the string to generate
126      * @param maxLengthExclusive the exclusive maximum length of the string to generate
127      * @return the random string
128      * @since 3.5
129      */
130     public static String randomAlphabetic(final int minLengthInclusive, final int maxLengthExclusive) {
131         return randomAlphabetic(RandomUtils.nextInt(minLengthInclusive, maxLengthExclusive));
132     }
133 
134     /**
135      * <p>Creates a random string whose length is the number of characters
136      * specified.</p>
137      *
138      * <p>Characters will be chosen from the set of Latin alphabetic
139      * characters (a-z, A-Z) and the digits 0-9.</p>
140      *
141      * @param count  the length of random string to create
142      * @return the random string
143      */
144     public static String randomAlphanumeric(final int count) {
145         return random(count, true, true);
146     }
147 
148     /**
149      * <p>Creates a random string whose length is between the inclusive minimum and
150      * the exclusive maximum.</p>
151      *
152      * <p>Characters will be chosen from the set of Latin alphabetic
153      * characters (a-z, A-Z) and the digits 0-9.</p>
154      *
155      * @param minLengthInclusive the inclusive minimum length of the string to generate
156      * @param maxLengthExclusive the exclusive maximum length of the string to generate
157      * @return the random string
158      * @since 3.5
159      */
160     public static String randomAlphanumeric(final int minLengthInclusive, final int maxLengthExclusive) {
161         return randomAlphanumeric(RandomUtils.nextInt(minLengthInclusive, maxLengthExclusive));
162     }
163 
164     /**
165      * <p>Creates a random string whose length is the number of characters specified.</p>
166      *
167      * <p>Characters will be chosen from the set of characters which match the POSIX [:graph:]
168      * regular expression character class. This class contains all visible ASCII characters
169      * (i.e. anything except spaces and control characters).</p>
170      *
171      * @param count  the length of random string to create
172      * @return the random string
173      * @since 3.5
174      */
175     public static String randomGraph(final int count) {
176         return random(count, 33, 126, false, false);
177     }
178 
179     /**
180      * <p>Creates a random string whose length is between the inclusive minimum and
181      * the exclusive maximum.</p>
182      *
183      * <p>Characters will be chosen from the set of \p{Graph} characters.</p>
184      *
185      * @param minLengthInclusive the inclusive minimum length of the string to generate
186      * @param maxLengthExclusive the exclusive maximum length of the string to generate
187      * @return the random string
188      * @since 3.5
189      */
190     public static String randomGraph(final int minLengthInclusive, final int maxLengthExclusive) {
191         return randomGraph(RandomUtils.nextInt(minLengthInclusive, maxLengthExclusive));
192     }
193 
194     /**
195      * <p>Creates a random string whose length is the number of characters
196      * specified.</p>
197      *
198      * <p>Characters will be chosen from the set of numeric
199      * characters.</p>
200      *
201      * @param count  the length of random string to create
202      * @return the random string
203      */
204     public static String randomNumeric(final int count) {
205         return random(count, false, true);
206     }
207 
208     /**
209      * <p>Creates a random string whose length is between the inclusive minimum and
210      * the exclusive maximum.</p>
211      *
212      * <p>Characters will be chosen from the set of \p{Digit} characters.</p>
213      *
214      * @param minLengthInclusive the inclusive minimum length of the string to generate
215      * @param maxLengthExclusive the exclusive maximum length of the string to generate
216      * @return the random string
217      * @since 3.5
218      */
219     public static String randomNumeric(final int minLengthInclusive, final int maxLengthExclusive) {
220         return randomNumeric(RandomUtils.nextInt(minLengthInclusive, maxLengthExclusive));
221     }
222 
223     /**
224      * <p>Creates a random string whose length is the number of characters specified.</p>
225      *
226      * <p>Characters will be chosen from the set of characters which match the POSIX [:print:]
227      * regular expression character class. This class includes all visible ASCII characters and spaces
228      * (i.e. anything except control characters).</p>
229      *
230      * @param count  the length of random string to create
231      * @return the random string
232      * @since 3.5
233      */
234     public static String randomPrint(final int count) {
235         return random(count, 32, 126, false, false);
236     }
237 
238     /**
239      * <p>Creates a random string whose length is between the inclusive minimum and
240      * the exclusive maximum.</p>
241      *
242      * <p>Characters will be chosen from the set of \p{Print} characters.</p>
243      *
244      * @param minLengthInclusive the inclusive minimum length of the string to generate
245      * @param maxLengthExclusive the exclusive maximum length of the string to generate
246      * @return the random string
247      * @since 3.5
248      */
249     public static String randomPrint(final int minLengthInclusive, final int maxLengthExclusive) {
250         return randomPrint(RandomUtils.nextInt(minLengthInclusive, maxLengthExclusive));
251     }
252 
253     /**
254      * <p>Creates a random string whose length is the number of characters
255      * specified.</p>
256      *
257      * <p>Characters will be chosen from the set of alpha-numeric
258      * characters as indicated by the arguments.</p>
259      *
260      * @param count  the length of random string to create
261      * @param letters  if {@code true}, generated string may include
262      *  alphabetic characters
263      * @param numbers  if {@code true}, generated string may include
264      *  numeric characters
265      * @return the random string
266      */
267     public static String random(final int count, final boolean letters, final boolean numbers) {
268         return random(count, 0, 0, letters, numbers);
269     }
270 
271     /**
272      * <p>Creates a random string whose length is the number of characters
273      * specified.</p>
274      *
275      * <p>Characters will be chosen from the set of alpha-numeric
276      * characters as indicated by the arguments.</p>
277      *
278      * @param count  the length of random string to create
279      * @param start  the position in set of chars to start at
280      * @param end  the position in set of chars to end before
281      * @param letters  if {@code true}, generated string may include
282      *  alphabetic characters
283      * @param numbers  if {@code true}, generated string may include
284      *  numeric characters
285      * @return the random string
286      */
287     public static String random(final int count, final int start, final int end, final boolean letters, final boolean numbers) {
288         return random(count, start, end, letters, numbers, null, RANDOM);
289     }
290 
291     /**
292      * <p>Creates a random string based on a variety of options, using
293      * default source of randomness.</p>
294      *
295      * <p>This method has exactly the same semantics as
296      * {@link #random(int,int,int,boolean,boolean,char[],Random)}, but
297      * instead of using an externally supplied source of randomness, it uses
298      * the internal static {@link Random} instance.</p>
299      *
300      * @param count  the length of random string to create
301      * @param start  the position in set of chars to start at
302      * @param end  the position in set of chars to end before
303      * @param letters  only allow letters?
304      * @param numbers  only allow numbers?
305      * @param chars  the set of chars to choose randoms from.
306      *  If {@code null}, then it will use the set of all chars.
307      * @return the random string
308      * @throws ArrayIndexOutOfBoundsException if there are not
309      *  {@code (end - start) + 1} characters in the set array.
310      */
311     public static String random(final int count, final int start, final int end, final boolean letters, final boolean numbers, final char... chars) {
312         return random(count, start, end, letters, numbers, chars, RANDOM);
313     }
314 
315     /**
316      * <p>Creates a random string based on a variety of options, using
317      * supplied source of randomness.</p>
318      *
319      * <p>If start and end are both {@code 0}, start and end are set
320      * to {@code ' '} and {@code 'z'}, the ASCII printable
321      * characters, will be used, unless letters and numbers are both
322      * {@code false}, in which case, start and end are set to
323      * {@code 0} and {@link Character#MAX_CODE_POINT}.
324      *
325      * <p>If set is not {@code null}, characters between start and
326      * end are chosen.</p>
327      *
328      * <p>This method accepts a user-supplied {@link Random}
329      * instance to use as a source of randomness. By seeding a single
330      * {@link Random} instance with a fixed seed and using it for each call,
331      * the same random sequence of strings can be generated repeatedly
332      * and predictably.</p>
333      *
334      * @param count  the length of random string to create
335      * @param start  the position in set of chars to start at (inclusive)
336      * @param end  the position in set of chars to end before (exclusive)
337      * @param letters  only allow letters?
338      * @param numbers  only allow numbers?
339      * @param chars  the set of chars to choose randoms from, must not be empty.
340      *  If {@code null}, then it will use the set of all chars.
341      * @param random  a source of randomness.
342      * @return the random string
343      * @throws ArrayIndexOutOfBoundsException if there are not
344      *  {@code (end - start) + 1} characters in the set array.
345      * @throws IllegalArgumentException if {@code count} &lt; 0 or the provided chars array is empty.
346      * @since 2.0
347      */
348     public static String random(int count, int start, int end, final boolean letters, final boolean numbers,
349                                 final char[] chars, final Random random) {
350         if (count == 0) {
351             return StringUtils.EMPTY;
352         } else if (count < 0) {
353             throw new IllegalArgumentException("Requested random string length " + count + " is less than 0.");
354         }
355         if (chars != null && chars.length == 0) {
356             throw new IllegalArgumentException("The chars array must not be empty");
357         }
358 
359         if (start == 0 && end == 0) {
360             if (chars != null) {
361                 end = chars.length;
362             } else {
363                 if (!letters && !numbers) {
364                     end = Character.MAX_CODE_POINT;
365                 } else {
366                     end = 'z' + 1;
367                     start = ' ';
368                 }
369             }
370         } else {
371             if (end <= start) {
372                 throw new IllegalArgumentException("Parameter end (" + end + ") must be greater than start (" + start + ")");
373             }
374         }
375 
376         final int zero_digit_ascii = 48;
377         final int first_letter_ascii = 65;
378 
379         if (chars == null && (numbers && end <= zero_digit_ascii
380                 || letters && end <= first_letter_ascii)) {
381             throw new IllegalArgumentException("Parameter end (" + end + ") must be greater then (" + zero_digit_ascii + ") for generating digits " +
382                     "or greater then (" + first_letter_ascii + ") for generating letters.");
383         }
384 
385         StringBuilder builder = new StringBuilder(count);
386         final int gap = end - start;
387 
388         while (count-- != 0) {
389             int codePoint;
390             if (chars == null) {
391                 codePoint = random.nextInt(gap) + start;
392 
393                 switch (Character.getType(codePoint)) {
394                 case Character.UNASSIGNED:
395                 case Character.PRIVATE_USE:
396                 case Character.SURROGATE:
397                     count++;
398                     continue;
399                 }
400 
401             } else {
402                 codePoint = chars[random.nextInt(gap) + start];
403             }
404 
405             final int numberOfChars = Character.charCount(codePoint);
406             if (count == 0 && numberOfChars > 1) {
407                 count++;
408                 continue;
409             }
410 
411             if (letters && Character.isLetter(codePoint)
412                     || numbers && Character.isDigit(codePoint)
413                     || !letters && !numbers) {
414                 builder.appendCodePoint(codePoint);
415 
416                 if (numberOfChars == 2) {
417                     count--;
418                 }
419 
420             } else {
421                 count++;
422             }
423         }
424         return builder.toString();
425     }
426 
427 
428     /**
429      * <p>Creates a random string whose length is the number of characters
430      * specified.</p>
431      *
432      * <p>Characters will be chosen from the set of characters
433      * specified by the string, must not be empty.
434      * If null, the set of all characters is used.</p>
435      *
436      * @param count  the length of random string to create
437      * @param chars  the String containing the set of characters to use,
438      *  may be null, but must not be empty
439      * @return the random string
440      * @throws IllegalArgumentException if {@code count} &lt; 0 or the string is empty.
441      */
442     public static String random(final int count, final String chars) {
443         if (chars == null) {
444             return random(count, 0, 0, false, false, null, RANDOM);
445         }
446         return random(count, chars.toCharArray());
447     }
448 
449     /**
450      * <p>Creates a random string whose length is the number of characters
451      * specified.</p>
452      *
453      * <p>Characters will be chosen from the set of characters specified.</p>
454      *
455      * @param count  the length of random string to create
456      * @param chars  the character array containing the set of characters to use,
457      *  may be null
458      * @return the random string
459      * @throws IllegalArgumentException if {@code count} &lt; 0.
460      */
461     public static String random(final int count, final char... chars) {
462         if (chars == null) {
463             return random(count, 0, 0, false, false, null, RANDOM);
464         }
465         return random(count, 0, chars.length, false, false, chars, RANDOM);
466     }
467 
468 }