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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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} < 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}