Class ListSampler


  • public final class ListSampler
    extends java.lang.Object
    Sampling from a List.

    This class also contains utilities for shuffling a List in-place.

    Since:
    1.0
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static int RANDOM_ACCESS_SIZE_THRESHOLD
      The size threshold for using the random access algorithm when the list does not implement java.util.RandomAccess.
    • Constructor Summary

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

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T> java.util.List<T> sample​(UniformRandomProvider rng, java.util.List<T> collection, int k)
      Generates a list of size k whose entries are selected randomly, without repetition, from the items in the given collection.
      static <T> void shuffle​(UniformRandomProvider rng, java.util.List<T> list)
      Shuffles the entries of the given array, using the Fisher-Yates algorithm.
      static <T> void shuffle​(UniformRandomProvider rng, java.util.List<T> list, int start, boolean towardHead)
      Shuffles the entries of the given array, using the Fisher-Yates algorithm.
      private static void swap​(java.lang.Object[] array, int i, int j)
      Swaps the two specified elements in the array.
      private static <T> void swap​(java.util.List<T> list, int i, int j)
      Swaps the two specified elements in the list.
      • Methods inherited from class java.lang.Object

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

      • RANDOM_ACCESS_SIZE_THRESHOLD

        private static final int RANDOM_ACCESS_SIZE_THRESHOLD
        The size threshold for using the random access algorithm when the list does not implement java.util.RandomAccess.
        See Also:
        Constant Field Values
    • Constructor Detail

      • ListSampler

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

      • sample

        public static <T> java.util.List<T> sample​(UniformRandomProvider rng,
                                                   java.util.List<T> collection,
                                                   int k)
        Generates a list of size k whose entries are selected randomly, without repetition, from the items in the given collection.

        Sampling is without replacement; but if the source collection contains identical objects, the sample may include repeats.

        Sampling uses UniformRandomProvider.nextInt(int).

        Type Parameters:
        T - Type of the list items.
        Parameters:
        rng - Generator of uniformly distributed random numbers.
        collection - List to be sampled from.
        k - Size of the returned sample.
        Returns:
        a shuffled sample from the source collection.
        Throws:
        java.lang.IllegalArgumentException - if k <= 0 or k > collection.size().
      • shuffle

        public static <T> void shuffle​(UniformRandomProvider rng,
                                       java.util.List<T> list)
        Shuffles the entries of the given array, using the Fisher-Yates algorithm.

        Sampling uses UniformRandomProvider.nextInt(int).

        Type Parameters:
        T - Type of the list items.
        Parameters:
        rng - Random number generator.
        list - List whose entries will be shuffled (in-place).
      • shuffle

        public static <T> void shuffle​(UniformRandomProvider rng,
                                       java.util.List<T> list,
                                       int start,
                                       boolean towardHead)
        Shuffles the entries of the given array, using the Fisher-Yates algorithm.

        The start and pos parameters select which part of the array is randomized and which is left untouched.

        Sampling uses UniformRandomProvider.nextInt(int).

        Type Parameters:
        T - Type of the list items.
        Parameters:
        rng - Random number generator.
        list - List whose entries will be shuffled (in-place).
        start - Index at which shuffling begins.
        towardHead - Shuffling is performed for index positions between start and either the end (if false) or the beginning (if true) of the array.
      • swap

        private static <T> void swap​(java.util.List<T> list,
                                     int i,
                                     int j)
        Swaps the two specified elements in the list.
        Type Parameters:
        T - Type of the list items.
        Parameters:
        list - List.
        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.