2021-11-11

Java 集合

Collections

**此类仅包含对集合进行操作或返回集合的静态方法。**它包含对集合进行操作的多态算法、“包装器”，它返回由指定集合支持的新集合，以及其他一些零碎的东西。
如果提供给它们的集合或类对象为空，则此类的方法都将抛出 NullPointerException。
此类中包含的多态算法的文档通常包括对实现的简要说明。此类描述应被视为实现说明，而不是规范的一部分。只要遵守规范本身，实现者应该可以随意替换其他算法。 （例如，sort 使用的算法不一定是归并排序，但它必须是稳定的。）
此类中包含的“破坏性”算法，即修改它们操作的集合的算法，如果集合不支持适当的变异原语（例如 set 方法），则指定为抛出 UnsupportedOperationException。如果调用对集合没有影响，则这些算法可能（但不是必需）抛出此异常。例如，对已排序的不可修改列表调用 sort 方法可能会也可能不会抛出 UnsupportedOperationException。
此类是 Java 集合框架的成员。

public class Collections{

根据其元素的自然顺序，将指定列表按升序排序。列表中的所有元素都必须实现 Comparable 接口。
此外，列表中的所有元素必须相互比较（即，e1.compareTo(e2) 不得为列表中的任何元素 e1 和 e2 抛出 ClassCastException）。
这种排序保证是稳定的：相等的元素不会因排序而重新排序。
指定的列表必须是可修改的，但不需要可调整大小。
参数：
list – 要排序的列表。
类型参数：
<T> – 列表中对象的类
抛出：
ClassCastException – 如果列表包含不可相互比较的元素（例如，字符串和整数）。
UnsupportedOperationException – 如果指定列表的列表迭代器不支持设置操作。
IllegalArgumentException –（可选）如果实现检测到发现列表元素的自然顺序违反了 Comparable 契约
实施注意事项：
此实现遵循使用指定列表和空比较器的 List.sort(Comparator) 方法。
也可以看看：
List.sort（比较器）
public static <T extends Comparable<? super T>> void sort(List<T> list) {
        list.sort(null);
    }


根据由指定比较器产生的顺序对指定列表进行排序。列表中的所有元素必须使用指定的比较器相互比较（即，对于列表中的任何元素 e1 和 e2，c.compare(e1, e2) 不得抛出 ClassCastException）。
这种排序保证是稳定的：相等的元素不会因排序而重新排序。
指定的列表必须是可修改的，但不需要可调整大小。
参数：
list – 要排序的列表。
c – 确定列表顺序的比较器。空值表示应该使用元素的自然顺序。
类型参数：
<T> – 列表中对象的类
抛出：
ClassCastException – 如果列表包含使用指定比较器不能相互比较的元素。
UnsupportedOperationException – 如果指定列表的列表迭代器不支持设置操作。
IllegalArgumentException –（可选）如果发现比较器违反了比较器合同
实施注意事项：
此实现遵循使用指定列表和比较器的 List.sort(Comparator) 方法。
也可以看看：
List.sort（比较器）
 public static <T> void sort(List<T> list, Comparator<? super T> c) {
        list.sort(c);
    }

使用二进制搜索算法在指定列表中搜索指定对象。在进行此调用之前，必须根据其元素的自然顺序（如 sort(List) 方法）将列表按升序排序。如果未排序，则结果未定义。如果列表包含多个与指定对象相等的元素，则无法保证会找到哪一个。
此方法在 log(n) 时间内运行，用于“随机访问”列表（提供近乎恒定时间的位置访问）。如果指定的列表没有实现 RandomAccess 接口并且很大，则此方法将执行基于迭代器的二进制搜索，执行 O(n) 链接遍历和 O(log n) 元素比较。
参数：
list – 要搜索的列表。
key – 要搜索的键。
类型参数：
<T> – 列表中对象的类
返回：
搜索关键字的索引，如果它包含在列表中；否则，(-(插入点) - 1)。插入点定义为将键插入列表的点：大于键的第一个元素的索引，如果列表中的所有元素都小于指定的键，则为 list.size() 。请注意，这保证当且仅当找到键时返回值将 >= 0。
抛出：
ClassCastException – 如果列表包含不可相互比较的元素（例如，字符串和整数），或者搜索关键字与列表元素不可相互比较。
  public static <T>
    int binarySearch(List<? extends Comparable<? super T>> list, T key) {
        if (list instanceof RandomAccess || list.size()<BINARYSEARCH_THRESHOLD)
            return Collections.indexedBinarySearch(list, key);
        else
            return Collections.iteratorBinarySearch(list, key);
    }


使用默认的随机源随机排列指定的列表。所有排列都以近似相等的可能性发生。
在前面的描述中使用了“大约”对冲，因为默认随机源只是大约独立选择位的无偏源。如果它是随机选择位的完美来源，那么该算法将选择具有完美一致性的排列。
此实现向后遍历列表，从最后一个元素到第二个元素，反复将随机选择的元素交换到“当前位置”。从列表中从第一个元素到当前位置（含）的部分中随机选择元素。
此方法在线性时间内运行。如果指定的列表未实现 RandomAccess 接口并且很大，则此实现将指定的列表转储到数组中，然后再将其混洗，并将混洗后的数组转储回列表。这避免了由于将“顺序访问”列表改组到位而导致的二次行为。
参数：
list – 要洗牌的列表。
抛出：
UnsupportedOperationException – 如果指定的列表或其列表迭代器不支持设置操作。
 public static void shuffle(List<?> list) {
        Random rnd = r;
        if (rnd == null)
            r = rnd = new Random(); // harmless race.
        shuffle(list, rnd);
    }



使用指定的随机源随机排列指定的列表。假设随机源是公平的，所有排列都以相同的可能性发生。
此实现向后遍历列表，从最后一个元素到第二个元素，反复将随机选择的元素交换到“当前位置”。从列表中从第一个元素到当前位置（含）的部分中随机选择元素。
此方法在线性时间内运行。如果指定的列表未实现 RandomAccess 接口并且很大，则此实现将指定的列表转储到数组中，然后再将其混洗，并将混洗后的数组转储回列表。这避免了由于将“顺序访问”列表改组到位而导致的二次行为。
参数：
list – 要洗牌的列表。
rnd – 用于打乱列表的随机源。
抛出：
UnsupportedOperationException – 如果指定的列表或其列表迭代器不支持设置操作。
   public static void shuffle(List<?> list, Random rnd) {
        int size = list.size();
        if (size < SHUFFLE_THRESHOLD || list instanceof RandomAccess) {
            for (int i=size; i>1; i--)
                swap(list, i-1, rnd.nextInt(i));
        } else {
            Object[] arr = list.toArray();

            // Shuffle array
            for (int i=size; i>1; i--)
                swap(arr, i-1, rnd.nextInt(i));
            // Dump array back into list
            // instead of using a raw type here, it's possible to capture
            // the wildcard but it will require a call to a supplementary
            // private method
            ListIterator it = list.listIterator();
            for (int i=0; i<arr.length; i++) {
                it.next();
                it.set(arr[i]);
            }
        }
    }

按指定距离旋转指定列表中的元素。调用此方法后，索引 i 处的元素将是之前索引 (i - 距离) mod list.size() 处的元素，对于 i 的所有值，在 0 和 list.size()-1 之间，包括这两个值。 （此方法对列表的大小没有影响。）
例如，假设列表包含 [t, a, n, k, s]。调用 Collections.rotate(list, 1)（或 Collections.rotate(list, -4)）后，列表将包含 [s, t, a, n, k]。
请注意，此方法可以有效地应用于子列表，以在保持其余元素顺序的同时移动列表中的一个或多个元素。例如，以下习语将索引 j 处的元素向前移动到位置 k（必须大于或等于 j）：
           Collections.rotate(list.subList(j, k+1), -1);
       
为了具体化，假设列表包含 [a, b, c, d, e]。要将索引 1 (b) 处的元素向前移动两个位置，请执行以下调用：
           Collections.rotate(l.subList(1, 4), -1);
       
结果列表是 [a, c, d, b, e]。
要向前移动多个元素，请增加旋转距离的绝对值。要向后移动元素，请使用正移动距离。
如果指定的列表很小或实现了 RandomAccess 接口，则此实现将第一个元素交换到它应该去的位置，然后重复地将被置换的元素交换到它应该去的位置，直到一个被置换的元素被交换到第一个元素。如有必要，对第二个和后续元素重复该过程，直到完成旋转。如果指定的列表很大且未实现 RandomAccess 接口，则此实现将列表围绕 index -distance mod size 分成两个子列表视图。然后在每个子列表视图上调用 reverse(List) 方法，最后在整个列表上调用它。有关这两种算法的更完整描述，请参阅 Jon Bentley 的 Programming Pearls（Addison-Wesley，1986 年）的第 2.3 节。
   public static void rotate(List<?> list, int distance) {
        if (list instanceof RandomAccess || list.size() < ROTATE_THRESHOLD)
            rotate1(list, distance);
        else
            rotate2(list, distance);
    }

}