Apache
/
commons-lang
mirror of https://github.com/apache/commons-lang.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve Javadoc based on the discussion of the GitHub PR #459.

This commit is contained in:
Gary Gregory 2019-10-05 09:21:40 -04:00
parent 4f3d3b4318
commit c1fbeee23e
1 changed files with 16 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
src/main/java/org/apache/commons/lang3/RandomStringUtils.java
View File

@ -19,8 +19,22 @@ package org.apache.commons.lang3;
import java.util.Random; import java.util.Random;
/** /**
* <p>Operations for random {@code String}s.</p> * <p>Generates random {@code String}s.</p>
* <p>Currently <em>private high surrogate</em> characters are ignored. *
* <p><b>Caveat: Instances of {@link Random}, upon which the implementation of this
* class relies, are not cryptographically secure.</b></p>
*
* <p>RandomStringUtils is intended for simple use cases. For more advanced
* use cases consider using Apache Commons Text's
* <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/RandomStringGenerator.html">
* RandomStringGenerator</a> instead.</p>
*
* <p>The Apache Commons project provides
* <a href="https://commons.apache.org/rng">Commons RNG</a> dedicated to pseudo-random number generation, that may be
* a better choice for applications with more stringent requirements
* (performance and/or correctness).</p>
*
* <p>Note that <em>private high surrogate</em> characters are ignored.
* These are Unicode characters that fall between the values 56192 (db80) * These are Unicode characters that fall between the values 56192 (db80)
* and 56319 (dbff) as we don't know how to handle them. * and 56319 (dbff) as we don't know how to handle them.
* High and low surrogates are correctly dealt with - that is if a * High and low surrogates are correctly dealt with - that is if a
@ -28,19 +42,6 @@ import java.util.Random;
* then it is followed by a low surrogate. If a low surrogate is chosen, * 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 * 56320 (dc00) to 57343 (dfff) then it is placed after a randomly
* chosen high surrogate.</p> * chosen high surrogate.</p>
* <p>RandomStringUtils is intended for simple use cases. For more advanced
* use cases consider using commons-text
* <a href="https://commons.apache.org/proper/commons-text/javadocs/api-release/org/apache/commons/text/RandomStringGenerator.html">
* RandomStringGenerator</a> instead.</p>
*
* <p>Caveat: Instances of {@link Random}, upon which the implementation of this
* class relies, are not cryptographically secure.</p>
*
* <p>Please note that the Apache Commons project provides a component
* dedicated to pseudo-random number generation, namely
* <a href="https://commons.apache.org/rng">Commons RNG</a>, that may be
* a better choice for applications with more stringent requirements
* (performance and/or correctness).</p>
* *
* <p>#ThreadSafe#</p> * <p>#ThreadSafe#</p>
* @since 1.0 * @since 1.0