Skip to content

Commit 625d904

Browse files
garydgregorygarydgregory
committed
Javadoc
1 parent fb42e80 commit 625d904

File tree

1 file changed

+132
-45
lines changed

1 file changed

+132
-45
lines changed

‎src/main/java/org/apache/commons/lang3/ArrayUtils.java

+132-45
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
import java.lang.reflect.Field;
2121
import java.lang.reflect.Method;
2222
import java.lang.reflect.Type;
23+
import java.security.SecureRandom;
2324
import java.util.Arrays;
2425
import java.util.BitSet;
2526
import java.util.Comparator;
@@ -4721,6 +4722,11 @@ public static <T> T[] nullToEmpty(final T[] array, final Class<T[]> type) {
47214722
return array;
47224723
}
47234724

4725+
/**
4726+
* Gets the {@link ThreadLocalRandom} for {@code shuffle} methods that don't take a {@link Random} argument.
4727+
*
4728+
* @return the current ThreadLocalRandom.
4729+
*/
47244730
private static ThreadLocalRandom random() {
47254731
return ThreadLocalRandom.current();
47264732
}
@@ -7640,9 +7646,17 @@ public static void shift(final short[] array, int startIndexInclusive, int endIn
76407646
}
76417647

76427648
/**
7643-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7649+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7650+
* algorithm</a>.
7651+
* <p>
7652+
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
7653+
* </p>
7654+
* <p>
7655+
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
7656+
* with a {@link SecureRandom} argument.
7657+
* </p>
76447658
*
7645-
* @param array the array to shuffle
7659+
* @param array the array to shuffle.
76467660
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
76477661
* @since 3.6
76487662
*/
@@ -7651,10 +7665,11 @@ public static void shuffle(final boolean[] array) {
76517665
}
76527666

76537667
/**
7654-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7668+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7669+
* algorithm</a>.
76557670
*
7656-
* @param array the array to shuffle
7657-
* @param random the source of randomness used to permute the elements
7671+
* @param array the array to shuffle
7672+
* @param random the source of randomness used to permute the elements
76587673
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
76597674
* @since 3.6
76607675
*/
@@ -7665,9 +7680,17 @@ public static void shuffle(final boolean[] array, final Random random) {
76657680
}
76667681

76677682
/**
7668-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7683+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7684+
* algorithm</a>.
7685+
* <p>
7686+
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
7687+
* </p>
7688+
* <p>
7689+
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
7690+
* with a {@link SecureRandom} argument.
7691+
* </p>
76697692
*
7670-
* @param array the array to shuffle
7693+
* @param array the array to shuffle.
76717694
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
76727695
* @since 3.6
76737696
*/
@@ -7676,10 +7699,11 @@ public static void shuffle(final byte[] array) {
76767699
}
76777700

76787701
/**
7679-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7702+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7703+
* algorithm</a>.
76807704
*
7681-
* @param array the array to shuffle
7682-
* @param random the source of randomness used to permute the elements
7705+
* @param array the array to shuffle
7706+
* @param random the source of randomness used to permute the elements
76837707
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
76847708
* @since 3.6
76857709
*/
@@ -7690,9 +7714,17 @@ public static void shuffle(final byte[] array, final Random random) {
76907714
}
76917715

76927716
/**
7693-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7717+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7718+
* algorithm</a>.
7719+
* <p>
7720+
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
7721+
* </p>
7722+
* <p>
7723+
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
7724+
* with a {@link SecureRandom} argument.
7725+
* </p>
76947726
*
7695-
* @param array the array to shuffle
7727+
* @param array the array to shuffle.
76967728
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
76977729
* @since 3.6
76987730
*/
@@ -7701,10 +7733,11 @@ public static void shuffle(final char[] array) {
77017733
}
77027734

77037735
/**
7704-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7736+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7737+
* algorithm</a>.
77057738
*
7706-
* @param array the array to shuffle
7707-
* @param random the source of randomness used to permute the elements
7739+
* @param array the array to shuffle
7740+
* @param random the source of randomness used to permute the elements
77087741
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
77097742
* @since 3.6
77107743
*/
@@ -7715,9 +7748,17 @@ public static void shuffle(final char[] array, final Random random) {
77157748
}
77167749

77177750
/**
7718-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7751+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7752+
* algorithm</a>.
7753+
* <p>
7754+
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
7755+
* </p>
7756+
* <p>
7757+
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
7758+
* with a {@link SecureRandom} argument.
7759+
* </p>
77197760
*
7720-
* @param array the array to shuffle
7761+
* @param array the array to shuffle.
77217762
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
77227763
* @since 3.6
77237764
*/
@@ -7726,10 +7767,11 @@ public static void shuffle(final double[] array) {
77267767
}
77277768

77287769
/**
7729-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7770+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7771+
* algorithm</a>.
77307772
*
7731-
* @param array the array to shuffle
7732-
* @param random the source of randomness used to permute the elements
7773+
* @param array the array to shuffle
7774+
* @param random the source of randomness used to permute the elements
77337775
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
77347776
* @since 3.6
77357777
*/
@@ -7740,9 +7782,17 @@ public static void shuffle(final double[] array, final Random random) {
77407782
}
77417783

77427784
/**
7743-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7785+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7786+
* algorithm</a>.
7787+
* <p>
7788+
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
7789+
* </p>
7790+
* <p>
7791+
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
7792+
* with a {@link SecureRandom} argument.
7793+
* </p>
77447794
*
7745-
* @param array the array to shuffle
7795+
* @param array the array to shuffle.
77467796
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
77477797
* @since 3.6
77487798
*/
@@ -7751,10 +7801,11 @@ public static void shuffle(final float[] array) {
77517801
}
77527802

77537803
/**
7754-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7804+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7805+
* algorithm</a>.
77557806
*
7756-
* @param array the array to shuffle
7757-
* @param random the source of randomness used to permute the elements
7807+
* @param array the array to shuffle
7808+
* @param random the source of randomness used to permute the elements
77587809
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
77597810
* @since 3.6
77607811
*/
@@ -7765,9 +7816,17 @@ public static void shuffle(final float[] array, final Random random) {
77657816
}
77667817

77677818
/**
7768-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7819+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7820+
* algorithm</a>.
7821+
* <p>
7822+
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
7823+
* </p>
7824+
* <p>
7825+
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
7826+
* with a {@link SecureRandom} argument.
7827+
* </p>
77697828
*
7770-
* @param array the array to shuffle
7829+
* @param array the array to shuffle.
77717830
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
77727831
* @since 3.6
77737832
*/
@@ -7776,10 +7835,11 @@ public static void shuffle(final int[] array) {
77767835
}
77777836

77787837
/**
7779-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7838+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7839+
* algorithm</a>.
77807840
*
7781-
* @param array the array to shuffle
7782-
* @param random the source of randomness used to permute the elements
7841+
* @param array the array to shuffle
7842+
* @param random the source of randomness used to permute the elements
77837843
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
77847844
* @since 3.6
77857845
*/
@@ -7790,9 +7850,17 @@ public static void shuffle(final int[] array, final Random random) {
77907850
}
77917851

77927852
/**
7793-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7853+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7854+
* algorithm</a>.
7855+
* <p>
7856+
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
7857+
* </p>
7858+
* <p>
7859+
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
7860+
* with a {@link SecureRandom} argument.
7861+
* </p>
77947862
*
7795-
* @param array the array to shuffle
7863+
* @param array the array to shuffle.
77967864
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
77977865
* @since 3.6
77987866
*/
@@ -7801,10 +7869,11 @@ public static void shuffle(final long[] array) {
78017869
}
78027870

78037871
/**
7804-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7872+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7873+
* algorithm</a>.
78057874
*
7806-
* @param array the array to shuffle
7807-
* @param random the source of randomness used to permute the elements
7875+
* @param array the array to shuffle
7876+
* @param random the source of randomness used to permute the elements
78087877
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
78097878
* @since 3.6
78107879
*/
@@ -7815,9 +7884,17 @@ public static void shuffle(final long[] array, final Random random) {
78157884
}
78167885

78177886
/**
7818-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7887+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7888+
* algorithm</a>.
7889+
* <p>
7890+
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
7891+
* </p>
7892+
* <p>
7893+
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
7894+
* with a {@link SecureRandom} argument.
7895+
* </p>
78197896
*
7820-
* @param array the array to shuffle
7897+
* @param array the array to shuffle.
78217898
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
78227899
* @since 3.6
78237900
*/
@@ -7826,10 +7903,11 @@ public static void shuffle(final Object[] array) {
78267903
}
78277904

78287905
/**
7829-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7906+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7907+
* algorithm</a>.
78307908
*
7831-
* @param array the array to shuffle
7832-
* @param random the source of randomness used to permute the elements
7909+
* @param array the array to shuffle
7910+
* @param random the source of randomness used to permute the elements
78337911
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
78347912
* @since 3.6
78357913
*/
@@ -7840,9 +7918,17 @@ public static void shuffle(final Object[] array, final Random random) {
78407918
}
78417919

78427920
/**
7843-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7921+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7922+
* algorithm</a>.
7923+
* <p>
7924+
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
7925+
* </p>
7926+
* <p>
7927+
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
7928+
* with a {@link SecureRandom} argument.
7929+
* </p>
78447930
*
7845-
* @param array the array to shuffle
7931+
* @param array the array to shuffle.
78467932
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
78477933
* @since 3.6
78487934
*/
@@ -7851,10 +7937,11 @@ public static void shuffle(final short[] array) {
78517937
}
78527938

78537939
/**
7854-
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
7940+
* Shuffles randomly the elements of the specified array using the <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle
7941+
* algorithm</a>.
78557942
*
7856-
* @param array the array to shuffle
7857-
* @param random the source of randomness used to permute the elements
7943+
* @param array the array to shuffle
7944+
* @param random the source of randomness used to permute the elements
78587945
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
78597946
* @since 3.6
78607947
*/

0 commit comments

Comments
 (0)