Skip to content

Commit

Permalink
Javadoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@garydgregory
garydgregory committed Mar 2, 2025
1 parent fb42e80 commit 625d904
Showing 1 changed file with 132 additions and 45 deletions.
177 changes: 132 additions & 45 deletions src/main/java/org/apache/commons/lang3/ArrayUtils.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.lang.reflect.Type;
import java.security.SecureRandom;
import java.util.Arrays;
import java.util.BitSet;
import java.util.Comparator;
Expand Down Expand Up @@ -4721,6 +4722,11 @@ public static <T> T[] nullToEmpty(final T[] array, final Class<T[]> type) {
return array;
}

/**
* Gets the {@link ThreadLocalRandom} for {@code shuffle} methods that don't take a {@link Random} argument.
*
* @return the current ThreadLocalRandom.
*/
private static ThreadLocalRandom random() {
return ThreadLocalRandom.current();
}
Expand Down Expand Up @@ -7640,9 +7646,17 @@ public static void shift(final short[] array, int startIndexInclusive, int endIn
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
* <p>
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
* </p>
* <p>
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
* with a {@link SecureRandom} argument.
* </p>
*
* @param array the array to shuffle
* @param array the array to shuffle.
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7651,10 +7665,11 @@ public static void shuffle(final boolean[] array) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
*
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7665,9 +7680,17 @@ public static void shuffle(final boolean[] array, final Random random) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
* <p>
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
* </p>
* <p>
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
* with a {@link SecureRandom} argument.
* </p>
*
* @param array the array to shuffle
* @param array the array to shuffle.
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7676,10 +7699,11 @@ public static void shuffle(final byte[] array) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
*
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7690,9 +7714,17 @@ public static void shuffle(final byte[] array, final Random random) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
* <p>
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
* </p>
* <p>
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
* with a {@link SecureRandom} argument.
* </p>
*
* @param array the array to shuffle
* @param array the array to shuffle.
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7701,10 +7733,11 @@ public static void shuffle(final char[] array) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
*
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7715,9 +7748,17 @@ public static void shuffle(final char[] array, final Random random) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
* <p>
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
* </p>
* <p>
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
* with a {@link SecureRandom} argument.
* </p>
*
* @param array the array to shuffle
* @param array the array to shuffle.
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7726,10 +7767,11 @@ public static void shuffle(final double[] array) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
*
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7740,9 +7782,17 @@ public static void shuffle(final double[] array, final Random random) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
* <p>
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
* </p>
* <p>
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
* with a {@link SecureRandom} argument.
* </p>
*
* @param array the array to shuffle
* @param array the array to shuffle.
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7751,10 +7801,11 @@ public static void shuffle(final float[] array) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
*
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7765,9 +7816,17 @@ public static void shuffle(final float[] array, final Random random) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
* <p>
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
* </p>
* <p>
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
* with a {@link SecureRandom} argument.
* </p>
*
* @param array the array to shuffle
* @param array the array to shuffle.
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7776,10 +7835,11 @@ public static void shuffle(final int[] array) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
*
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7790,9 +7850,17 @@ public static void shuffle(final int[] array, final Random random) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
* <p>
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
* </p>
* <p>
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
* with a {@link SecureRandom} argument.
* </p>
*
* @param array the array to shuffle
* @param array the array to shuffle.
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7801,10 +7869,11 @@ public static void shuffle(final long[] array) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
*
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7815,9 +7884,17 @@ public static void shuffle(final long[] array, final Random random) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
* <p>
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
* </p>
* <p>
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
* with a {@link SecureRandom} argument.
* </p>
*
* @param array the array to shuffle
* @param array the array to shuffle.
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7826,10 +7903,11 @@ public static void shuffle(final Object[] array) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
*
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7840,9 +7918,17 @@ public static void shuffle(final Object[] array, final Random random) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
* <p>
* This method uses the current {@link ThreadLocalRandom} as its random number generator.
* </p>
* <p>
* Instances of {@link ThreadLocalRandom} are not cryptographically secure. For security-sensitive applications, consider using a {@code shuffle} method
* with a {@link SecureRandom} argument.
* </p>
*
* @param array the array to shuffle
* @param array the array to shuffle.
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand All @@ -7851,10 +7937,11 @@ public static void shuffle(final short[] array) {
}

/**
* Randomly permutes the elements of the specified array using the Fisher-Yates algorithm.
* 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
* algorithm</a>.
*
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @param array the array to shuffle
* @param random the source of randomness used to permute the elements
* @see <a href="https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle">Fisher-Yates shuffle algorithm</a>
* @since 3.6
*/
Expand Down

0 comments on commit 625d904

Please sign in to comment.