package java.util;

import java.util.function.UnaryOperator;

/**
 * 一個有序的集合，也稱作序列，繼承於Collection。每個插入List的元素都有嚴格控制。可通過所以獲取元素。
 * 不同於集合，序列允許重複元素。正式點講，即允許兩個equals為true的元素，允許多個null。
 * List還提供了一個特殊的迭代器，即ListIterator，它允許元素新增和替換和雙向獲取元素。
 * @since 1.2
 */

public interface List<E> extends Collection<E> {
    // Query Operations 查詢操作

     /**
      * 同Collection
     */
    int size();

    /**
     * 同Collection
     */
    boolean isEmpty();

    /**
     * 同Collection
     */
    boolean contains(Object o);

    /**
     * 同Iterable
     */
    Iterator<E> iterator();

    /**
     * 同Collection
     */
    Object[] toArray();

    /**
     * 同Collection
     */
    <T> T[] toArray(T[] a);


    // Modification Operations

    /**
     * 同Collection
     */
    boolean add(E e);

    /**
     * 同Collection
     */
    boolean remove(Object o);


    // Bulk Modification Operations

    /**
     * 同Collection
     */
    boolean containsAll(Collection<?> c);

    /**
     * 同Collection
     */
    boolean addAll(Collection<? extends E> c);

    /**
     * 在特定的位置，插入入參集合裡的所有元素。
     * @throws UnsupportedOperationException
     * @throws ClassCastException
     * @throws NullPointerException
     * @throws IllegalArgumentException
     * @throws IndexOutOfBoundsException index 小於0 或 大於size()s
     */
    boolean addAll(int index, Collection<? extends E> c);

    /**
     * 同Collection
     */
    boolean removeAll(Collection<?> c);

    /**
     * 同Collection
     *
     * @throws UnsupportedOperationException
     * @throws ClassCastException
     * @throws NullPointerException
     */
    boolean retainAll(Collection<?> c);

    /**
     * 將所有元素替換為operator操作後的元素
     * @throws UnsupportedOperationException
     * @throws NullPointerException
     * @since 1.8
     */
    default void replaceAll(UnaryOperator<E> operator) {
        Objects.requireNonNull(operator);
        final ListIterator<E> li = this.listIterator();
        while (li.hasNext()) {
            li.set(operator.apply(li.next()));
        }
    }

    /**
     * 將陣列按照給定的Comparator排序。
     * 預設實現為將List的元素存放到陣列中，利用Arrays.sort進行排序。
     * 再利用迭代器遍歷，將元素設定回List
     * @throws ClassCastException
     * @throws UnsupportedOperationException
     * @throws IllegalArgumentException
     * @since 1.8
     */
    @SuppressWarnings({"unchecked", "rawtypes"})
    default void sort(Comparator<? super E> c) {
        Object[] a = this.toArray();
        Arrays.sort(a, (Comparator) c);
        ListIterator<E> i = this.listIterator();
        for (Object e : a) {
            i.next();
            i.set((E) e);
        }
    }

    /**
     * 同Collection
     */
    void clear();


    // Comparison and hashing

    /**
     * 同Collection
     */
    boolean equals(Object o);

    /**
     * 同Collection
     */
    int hashCode();


    // Positional Access Operations

    /**
     * 返回位置index上的元素
     * @throws IndexOutOfBoundsException index < 0 || index >= size()
     */
    E get(int index);

    /**
     * 設定位置index上的元素
     * @throws UnsupportedOperationException
     * @throws ClassCastException
     * @throws NullPointerException
     * @throws IllegalArgumentException
     * @throws IndexOutOfBoundsException
     */
    E set(int index, E element);

    /**
     * 在位置index上新增元素，如果成功，剩餘元素後移一位。
     * @throws UnsupportedOperationException
     * @throws ClassCastException
     * @throws NullPointerException
     * @throws IllegalArgumentException
     * @throws IndexOutOfBoundsException
     */
    void add(int index, E element);

    /**
     * 在位置index上移除元素，如果成功，剩餘元素後移一位。
     * @throws UnsupportedOperationException
     * @throws IndexOutOfBoundsException
     */
    E remove(int index);


    // Search Operations

    /**
     * 返回入參o在List中第一次出現的位置，如果不存在，返回-1
     * @throws ClassCastException
     */
    int indexOf(Object o);

    /**
     * 返回入參o在List中最後一次出現的位置，如果不存在，則返回-1。
     * @throws ClassCastException
     * @throws NullPointerException
     */
    int lastIndexOf(Object o);


    // List Iterators

    /**
     * 返回ListIterator
     */
    ListIterator<E> listIterator();

    /**
     * 帶索引的ListIterator。index對應的位置上的元素即為next()返回的元素
     * @throws IndexOutOfBoundsException
     */
    ListIterator<E> listIterator(int index);

    // View

    /**
     * 返回子List[fromIndex, toIndex)。若fromIndex和toIndex相等，為空List。
     * 不改變原來的List
     * @throws IndexOutOfBoundsException
     */
    List<E> subList(int fromIndex, int toIndex);

    /**
     * 新建Spliterator，基於List的元素。
     * 順序特徵
     * @since 1.8
     */
    @Override
    default Spliterator<E> spliterator() {
        return Spliterators.spliterator(this, Spliterator.ORDERED);
    }
}