Class ArraySampler


  • public final class ArraySampler
    extends java.lang.Object
    Utilities for shuffling an array in-place.

    Shuffles use the Fisher-Yates algorithm.

    Since:
    1.6
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private ArraySampler()
      Class contains only static methods.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      private static int checkFromToIndex​(int fromIndex, int toIndex, int length)
      Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).
      static boolean[] shuffle​(UniformRandomProvider rng, boolean[] array)
      Shuffles the entries of the given array.
      static boolean[] shuffle​(UniformRandomProvider rng, boolean[] array, int from, int to)
      Shuffles the entries of the given array in the range [from, to).
      static byte[] shuffle​(UniformRandomProvider rng, byte[] array)
      Shuffles the entries of the given array.
      static byte[] shuffle​(UniformRandomProvider rng, byte[] array, int from, int to)
      Shuffles the entries of the given array in the range [from, to).
      static char[] shuffle​(UniformRandomProvider rng, char[] array)
      Shuffles the entries of the given array.
      static char[] shuffle​(UniformRandomProvider rng, char[] array, int from, int to)
      Shuffles the entries of the given array in the range [from, to).
      static double[] shuffle​(UniformRandomProvider rng, double[] array)
      Shuffles the entries of the given array.
      static double[] shuffle​(UniformRandomProvider rng, double[] array, int from, int to)
      Shuffles the entries of the given array in the range [from, to).
      static float[] shuffle​(UniformRandomProvider rng, float[] array)
      Shuffles the entries of the given array.
      static float[] shuffle​(UniformRandomProvider rng, float[] array, int from, int to)
      Shuffles the entries of the given array in the range [from, to).
      static int[] shuffle​(UniformRandomProvider rng, int[] array)
      Shuffles the entries of the given array.
      static int[] shuffle​(UniformRandomProvider rng, int[] array, int from, int to)
      Shuffles the entries of the given array in the range [from, to).
      static long[] shuffle​(UniformRandomProvider rng, long[] array)
      Shuffles the entries of the given array.
      static long[] shuffle​(UniformRandomProvider rng, long[] array, int from, int to)
      Shuffles the entries of the given array in the range [from, to).
      static short[] shuffle​(UniformRandomProvider rng, short[] array)
      Shuffles the entries of the given array.
      static short[] shuffle​(UniformRandomProvider rng, short[] array, int from, int to)
      Shuffles the entries of the given array in the range [from, to).
      static <T> T[] shuffle​(UniformRandomProvider rng, T[] array)
      Shuffles the entries of the given array.
      static <T> T[] shuffle​(UniformRandomProvider rng, T[] array, int from, int to)
      Shuffles the entries of the given array in the range [from, to).
      private static void swap​(boolean[] array, int i, int j)
      Swaps the two specified elements in the array.
      private static void swap​(byte[] array, int i, int j)
      Swaps the two specified elements in the array.
      private static void swap​(char[] array, int i, int j)
      Swaps the two specified elements in the array.
      private static void swap​(double[] array, int i, int j)
      Swaps the two specified elements in the array.
      private static void swap​(float[] array, int i, int j)
      Swaps the two specified elements in the array.
      private static void swap​(int[] array, int i, int j)
      Swaps the two specified elements in the array.
      private static void swap​(long[] array, int i, int j)
      Swaps the two specified elements in the array.
      private static void swap​(short[] array, int i, int j)
      Swaps the two specified elements in the array.
      private static void swap​(java.lang.Object[] array, int i, int j)
      Swaps the two specified elements in the array.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • ArraySampler

        private ArraySampler()
        Class contains only static methods.
    • Method Detail

      • shuffle

        public static boolean[] shuffle​(UniformRandomProvider rng,
                                        boolean[] array)
        Shuffles the entries of the given array.
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        Returns:
        a reference to the given array
      • shuffle

        public static byte[] shuffle​(UniformRandomProvider rng,
                                     byte[] array)
        Shuffles the entries of the given array.
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        Returns:
        a reference to the given array
      • shuffle

        public static char[] shuffle​(UniformRandomProvider rng,
                                     char[] array)
        Shuffles the entries of the given array.
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        Returns:
        a reference to the given array
      • shuffle

        public static double[] shuffle​(UniformRandomProvider rng,
                                       double[] array)
        Shuffles the entries of the given array.
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        Returns:
        a reference to the given array
      • shuffle

        public static float[] shuffle​(UniformRandomProvider rng,
                                      float[] array)
        Shuffles the entries of the given array.
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        Returns:
        a reference to the given array
      • shuffle

        public static int[] shuffle​(UniformRandomProvider rng,
                                    int[] array)
        Shuffles the entries of the given array.
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        Returns:
        a reference to the given array
      • shuffle

        public static long[] shuffle​(UniformRandomProvider rng,
                                     long[] array)
        Shuffles the entries of the given array.
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        Returns:
        a reference to the given array
      • shuffle

        public static short[] shuffle​(UniformRandomProvider rng,
                                      short[] array)
        Shuffles the entries of the given array.
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        Returns:
        a reference to the given array
      • shuffle

        public static <T> T[] shuffle​(UniformRandomProvider rng,
                                      T[] array)
        Shuffles the entries of the given array.
        Type Parameters:
        T - Type of the items.
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        Returns:
        a reference to the given array
      • shuffle

        public static boolean[] shuffle​(UniformRandomProvider rng,
                                        boolean[] array,
                                        int from,
                                        int to)
        Shuffles the entries of the given array in the range [from, to).
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        from - Lower-bound (inclusive) of the sub-range.
        to - Upper-bound (exclusive) of the sub-range.
        Returns:
        a reference to the given array
        Throws:
        java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds
      • shuffle

        public static byte[] shuffle​(UniformRandomProvider rng,
                                     byte[] array,
                                     int from,
                                     int to)
        Shuffles the entries of the given array in the range [from, to).
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        from - Lower-bound (inclusive) of the sub-range.
        to - Upper-bound (exclusive) of the sub-range.
        Returns:
        a reference to the given array
        Throws:
        java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds
      • shuffle

        public static char[] shuffle​(UniformRandomProvider rng,
                                     char[] array,
                                     int from,
                                     int to)
        Shuffles the entries of the given array in the range [from, to).
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        from - Lower-bound (inclusive) of the sub-range.
        to - Upper-bound (exclusive) of the sub-range.
        Returns:
        a reference to the given array
        Throws:
        java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds
      • shuffle

        public static double[] shuffle​(UniformRandomProvider rng,
                                       double[] array,
                                       int from,
                                       int to)
        Shuffles the entries of the given array in the range [from, to).
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        from - Lower-bound (inclusive) of the sub-range.
        to - Upper-bound (exclusive) of the sub-range.
        Returns:
        a reference to the given array
        Throws:
        java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds
      • shuffle

        public static float[] shuffle​(UniformRandomProvider rng,
                                      float[] array,
                                      int from,
                                      int to)
        Shuffles the entries of the given array in the range [from, to).
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        from - Lower-bound (inclusive) of the sub-range.
        to - Upper-bound (exclusive) of the sub-range.
        Returns:
        a reference to the given array
        Throws:
        java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds
      • shuffle

        public static int[] shuffle​(UniformRandomProvider rng,
                                    int[] array,
                                    int from,
                                    int to)
        Shuffles the entries of the given array in the range [from, to).
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        from - Lower-bound (inclusive) of the sub-range.
        to - Upper-bound (exclusive) of the sub-range.
        Returns:
        a reference to the given array
        Throws:
        java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds
      • shuffle

        public static long[] shuffle​(UniformRandomProvider rng,
                                     long[] array,
                                     int from,
                                     int to)
        Shuffles the entries of the given array in the range [from, to).
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        from - Lower-bound (inclusive) of the sub-range.
        to - Upper-bound (exclusive) of the sub-range.
        Returns:
        a reference to the given array
        Throws:
        java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds
      • shuffle

        public static short[] shuffle​(UniformRandomProvider rng,
                                      short[] array,
                                      int from,
                                      int to)
        Shuffles the entries of the given array in the range [from, to).
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        from - Lower-bound (inclusive) of the sub-range.
        to - Upper-bound (exclusive) of the sub-range.
        Returns:
        a reference to the given array
        Throws:
        java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds
      • shuffle

        public static <T> T[] shuffle​(UniformRandomProvider rng,
                                      T[] array,
                                      int from,
                                      int to)
        Shuffles the entries of the given array in the range [from, to).
        Type Parameters:
        T - Type of the items.
        Parameters:
        rng - Source of randomness.
        array - Array whose entries will be shuffled (in-place).
        from - Lower-bound (inclusive) of the sub-range.
        to - Upper-bound (exclusive) of the sub-range.
        Returns:
        a reference to the given array
        Throws:
        java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds
      • swap

        private static void swap​(boolean[] array,
                                 int i,
                                 int j)
        Swaps the two specified elements in the array.
        Parameters:
        array - Array.
        i - First index.
        j - Second index.
      • swap

        private static void swap​(byte[] array,
                                 int i,
                                 int j)
        Swaps the two specified elements in the array.
        Parameters:
        array - Array.
        i - First index.
        j - Second index.
      • swap

        private static void swap​(char[] array,
                                 int i,
                                 int j)
        Swaps the two specified elements in the array.
        Parameters:
        array - Array.
        i - First index.
        j - Second index.
      • swap

        private static void swap​(double[] array,
                                 int i,
                                 int j)
        Swaps the two specified elements in the array.
        Parameters:
        array - Array.
        i - First index.
        j - Second index.
      • swap

        private static void swap​(float[] array,
                                 int i,
                                 int j)
        Swaps the two specified elements in the array.
        Parameters:
        array - Array.
        i - First index.
        j - Second index.
      • swap

        private static void swap​(int[] array,
                                 int i,
                                 int j)
        Swaps the two specified elements in the array.
        Parameters:
        array - Array.
        i - First index.
        j - Second index.
      • swap

        private static void swap​(long[] array,
                                 int i,
                                 int j)
        Swaps the two specified elements in the array.
        Parameters:
        array - Array.
        i - First index.
        j - Second index.
      • swap

        private static void swap​(short[] array,
                                 int i,
                                 int j)
        Swaps the two specified elements in the array.
        Parameters:
        array - Array.
        i - First index.
        j - Second index.
      • swap

        private static void swap​(java.lang.Object[] array,
                                 int i,
                                 int j)
        Swaps the two specified elements in the array.
        Parameters:
        array - Array.
        i - First index.
        j - Second index.
      • checkFromToIndex

        private static int checkFromToIndex​(int fromIndex,
                                            int toIndex,
                                            int length)
        Checks if the sub-range from fromIndex (inclusive) to toIndex (exclusive) is within the bounds of range from 0 (inclusive) to length (exclusive).

        This function provides the functionality of java.utils.Objects.checkFromToIndex introduced in JDK 9. The Objects javadoc has been reproduced for reference.

        The sub-range is defined to be out of bounds if any of the following inequalities is true:

        • fromIndex < 0
        • fromIndex > toIndex
        • toIndex > length
        • length < 0, which is implied from the former inequalities
        Parameters:
        fromIndex - Lower-bound (inclusive) of the sub-range.
        toIndex - Upper-bound (exclusive) of the sub-range.
        length - Upper-bound (exclusive) of the range
        Returns:
        fromIndex if the sub-range is within the bounds of the range
        Throws:
        java.lang.IndexOutOfBoundsException - if the sub-range is out of bounds