Module org.klojang.collections
Package org.klojang.collections

Class WiredList<E>

java.lang.Object
org.klojang.collections.WiredList<E>
Type Parameters:
E - the type of the elements in the list
All Implemented Interfaces:
Iterable<E>, Collection<E>, List<E>
public final class WiredList<E> extends Object
A doubly-linked list, much like the JDK's LinkedList, but exclusively focused on list manipulation while disregarding the queue-like aspects of linked lists. As with any doubly-linked list, index-based retrieval is relatively costly compared to ArrayList. It is very efficient, however, at inserting, deleting and moving around chunks of list elements (i.e. structural changes). The larger the chunks, the bigger the gain - again compared to ArrayList.

Iteration

You should always use an Iterator to iterate over the elements in the list (which you implicitly would when executing a forEach loop). Using an index/get loop is possible, but performs poorly. The Iterator and ListIterator implementations prescribed by the List interface are no-frills iterators that throw an UnsupportedOperationException from all methods designated as optional by the specification. In addition, the WiredList class also features a reverseIterator0() and a wiredIterator() method. The latter returns an instance of the WiredIterator interface. Unlike a ListIterator, this is a one-way-only iterator, but it still provides the same functionality, and it does implement the methods that are optional in the ListIterator interface.

Fluent API

Many of the methods that go beyond those prescribed by the List interface form part of a fluent API. This causes some overlap in functionality between List methods and methods taking part in the fluent API. They are implemented exactly alike, so there is intrinsic reason to prefer one over the other.

Thread safety

List edits are always destructive, and nearly always don't just change the values in the list, but the underlying data structure itself. The WiredList class is not thread-safe. Multiple threads mutating the same list can leave it in a seriously corrupted state, with "dangling wires" between the list elements (i.e. null pointers). While the iterators make a light-touch effort to detect and trap concurrent modifications on the list, WiredList itself doesn't. Therefore, synchronize carefully when multiple threads access the same list.

Author:
Ayco Holleman

  • Constructor Summary

    Constructors
    Constructor
    Description
    WiredList()
    Creates a new, empty WiredList.
    WiredList(Collection<? extends E> c)
    Creates a new WiredList containing the elements in the specified Collection.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(int index, E element)
    Inserts the specified element at the specified position in this list.
    boolean
    add(E e)
    Appends the specified element to the end of this list.
    boolean
    addAll(int index, Collection<? extends E> c)
    Inserts all elements in the specified collection into this list at the specified position (optional operation).
    boolean
    addAll(Collection<? extends E> c)
    Appends all elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's iterator.
    WiredList<E>
    append(E value)
    Appends the specified value to the end of the list.
    WiredList<E>
    appendAll(Collection<? extends E> values)
    Appends the specified collection to this WiredList.
    WiredList<E>
    attach(WiredList<? extends E> other)
    Appends the specified list to this list.
    void
    clear()
    Removes all elements from this list.
    boolean
    contains(Object o)
    Returns true if this list contains the specified element.
    boolean
    containsAll(Collection<?> c)
    Returns true if this list contains all of the elements of the specified collection.
    WiredList<E>
    copy()
    Returns a copy of this WiredList.
    WiredList<E>
    copy(int fromIndex, int toIndex)
    Returns a copy of the specified segment.
    WiredList<E>
    cut(int fromIndex, int toIndex)
    Removes and returns a segment from the list.
    WiredList<E>
    defragment(boolean keepRemainder, List<Predicate<? super E>> criteria)
    Reorders the elements according to the specified criteria.
    WiredList<E>
    defragment(List<Predicate<? super E>> criteria)
    Reorders the elements according to the specified criteria.
    WiredList<E>
    embed(int index, WiredList<? extends E> other)
    Embeds the specified list in this list.
    WiredList<E>
    embed(int myIndex, WiredList<? extends E> other, int itsFromIndex, int itsToIndex)
    Removes a segment from the specified list and embeds it in this list.
    boolean
    equals(Object o)
    Compares the specified object with this list for equality.
    WiredList<E>
    exchange(int myFromIndex, int myToIndex, WiredList<E> other, int itsFromIndex, int itsToIndex)
    Exchanges list segments between this list and the specified list.
    E
    first()
    Returns the first element of the list.
    E
    get(int index)
    Returns the element at the specified position in this list.
    <L0 extends List<E>, L1 extends List<L0>>
    L1
    group(Predicate<? super E> criterion)
    Groups the elements in those that do, and elements that do not satisfy the specified criterion.
    <L0 extends List<E>, L1 extends List<L0>>
    L1
    group(List<Predicate<? super E>> criteria)
    Groups the elements according to the provided criteria.
    int
    hashCode()
    Returns the hash code value for this list.
    int
    indexOf(Object o)
    Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element.
    WiredList<E>
    insert(int index, E value)
    Inserts a value into the list.
    WiredList<E>
    insertAll(int index, Collection<? extends E> values)
    Inserts the specified collection at the specified index, right-shifting the elements at and following the index.
    boolean
    isEmpty()
    Returns true if this list contains no elements.
    Iterator<E>
    iterator()
    Returns an Iterator that traverses the list from the first element to the last.
    static <E> WiredList<E>
    join(List<WiredList<E>> lists)
    Concatenates the provided WiredList instances.
    E
    last()
    Returns the last element of the list.
    int
    lastIndexOf(Object o)
    Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element.
    WiredList<E>
    lchop(Predicate<? super E> criterion)
    Removes and returns a segment from the start of the list.
    ListIterator<E>
    listIterator()
    Returns a list iterator over the elements in this list (in proper sequence).
    ListIterator<E>
    listIterator(int index)
    Returns a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list.
    WiredList<E>
    move(int fromIndex, int toIndex, int newFromIndex)
    Moves a list segment forwards or backwards through the list.
    static <E> WiredList<E>
    of()
    Returns a new, empty WiredList.
    static <E> WiredList<E>
    of(E e)
    Returns a new WiredList containing the specified element.
    static <E> WiredList<E>
    of(E e0, E e1)
    Returns a new WiredList containing the specified elements.
    static <E> WiredList<E>
    of(E e0, E e1, E e2, E... moreElems)
    Returns a new WiredList containing the specified elements.
    static <E> WiredList<E>
    ofElements(E[] elements)
    Returns a new WiredList containing the specified elements.
    <L0 extends List<E>, L1 extends List<L0>>
    L1
    partition(int size)
    Splits this WiredList into multiple WiredList instances of the specified size.
    WiredList<? super E>
    paste(WiredList<? super E> into, int index)
    Inserts this list into the specified list at the specified position.
    WiredList<E>
    prepend(E value)
    Inserts the specified value at the start of the list, right-shifting the original elements.
    WiredList<E>
    prependAll(Collection<? extends E> values)
    Inserts the specified collection at the start of the list, right-shifting the original elements.
    WiredList<E>
    rchop(Predicate<? super E> criterion)
    Removes and returns a segment from the end of the list.
    Object[]
    regionToArray(int fromIndex, int toIndex)
    Returns an array containing the elements within the specified region of this list.
    void
    regionToArray(int fromIndex, int toIndex, Object[] target, int offset)
    Copies the specified region within this list to the specified position within the specified array.
    E
    remove(int index)
    Removes the element at the specified position in this list.
    boolean
    remove(Object o)
    Removes the first occurrence of the specified element from this list, if it is present.
    boolean
    removeAll(Collection<?> c)
     
    E
    removeFirst()
    Removes the first element from the list, left-shifting the remaining elements.
    boolean
    removeIf(Predicate<? super E> filter)
    Removes all elements of this collection that satisfy the given predicate.
    E
    removeLast()
    Removes the last element from the list.
    WiredList<E>
    replace(int fromIndex, int toIndex, WiredList<? extends E> other)
    Replaces the segment between fromIndex and toIndex with the elements in the specified list.
    WiredList<E>
    replaceAll(int fromIndex, int toIndex, Collection<? extends E> values)
    Replaces the segment between fromIndex and toIndex with the elements in the specified collection.
    void
    replaceAll(UnaryOperator<E> operator)
    Replaces each element of this list with the result of applying the operator to that element.
    boolean
    retainAll(Collection<?> c)
     
    WiredList<E>
    reverse()
    Reverses the order of the elements in this WiredList.
    Iterator<E>
    reverseIterator()
    Returns an Iterator that traverses the list from the last element to the first.
    E
    set(int index, E element)
    Replaces the element at the specified position in this list with the specified element.
    WiredList<E>
    set(int index, E e0, E e1, E... moreElems)
    Overwrites the elements at, and following the specified index with the provided values.
    E
    setIf(int index, Predicate<? super E> condition, E value)
    Sets the element at the specified index to the specified value if the original value passes the specified test.
    WiredList<E>
    shrink(int fromIndex, int toIndex)
    Shrinks the list to between the specified boundaries.
    int
    size()
    Returns the number of elements in this list.
    <L0 extends List<E>, L1 extends List<L0>>
    L1
    split(int numPartitions)
    Splits this WiredList into the specified number of equally-sized WiredList instances.
    List<E>
    subList(int fromIndex, int toIndex)
    Throws an UnsupportedOperationException.
    WiredList<E>
    swap(int from1, int to1, int from2, int to2)
    Swaps the two list segments defined by the specified boundary indexes.
    Object[]
    toArray()
    Returns an array containing all elements in this list in proper sequence (from first to last element).
    <T> T[]
    toArray(T[] a)
    Returns an array containing all elements in this list in proper sequence (from first to last element); the runtime type of the returned array is that of the specified array.
    String
    toString()
    Returns a String representation of this list.
    WiredIterator<E>
    wiredIterator()
    Returns a WiredIterator that traverses the list from the first element to the last.
    WiredIterator<E>
    wiredIterator(boolean reverse)
    Returns a WiredIterator that traverses the list from the first element to the last, or the other way round, depending on the value of the argument

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.util.Collection

    parallelStream, stream, toArray

    Methods inherited from interface java.lang.Iterable

    forEach

    Methods inherited from interface java.util.List

    sort, spliterator

  • Constructor Details

    • WiredList

      public WiredList()
      Creates a new, empty WiredList.

    • WiredList

      public WiredList(Collection<? extends E> c)
      Creates a new WiredList containing the elements in the specified Collection.
      Parameters:
      c - the collection whose elements to copy to this WiredList

  • Method Details

    • of

      public static <E> WiredList<E> of()
      Returns a new, empty WiredList. Note that, although the of(..) methods look like the List.of(...) methods, they return ordinary, mutable, null-accepting WiredList instances.
      Type Parameters:
      E - the type of the elements in the list
      Returns:
      a new, empty WiredList

    • of

      public static <E> WiredList<E> of(E e)
      Returns a new WiredList containing the specified element.
      Type Parameters:
      E - the type of the elements in the list
      Parameters:
      e - the element
      Returns:
      a new WiredList containing the specified elements

    • of

      public static <E> WiredList<E> of(E e0, E e1)
      Returns a new WiredList containing the specified elements.
      Type Parameters:
      E - the type of the elements in the list
      Parameters:
      e0 - the first element in the list
      e1 - the second element in the list
      Returns:
      a new WiredList containing the specified elements

    • of

      @SafeVarargs public static <E> WiredList<E> of(E e0, E e1, E e2, E... moreElems)
      Returns a new WiredList containing the specified elements.
      Type Parameters:
      E - the type of the elements in the list
      Parameters:
      e0 - the first element in the list
      e1 - the second element in the list
      e2 - the third element in the list
      moreElems - more elements to include in the list
      Returns:
      a new WiredList containing the specified elements

    • ofElements

      public static <E> WiredList<E> ofElements(E[] elements)
      Returns a new WiredList containing the specified elements.
      Type Parameters:
      E - the type of the elements in the list
      Parameters:
      elements - the elements to add to the list
      Returns:
      a new WiredList containing the specified elements

    • join

      public static <E> WiredList<E> join(List<WiredList<E>> lists)
      Concatenates the provided WiredList instances. This is a destructive operation for the WiredList instances in the provided List. They will be empty when the method returns.
      Type Parameters:
      E - the type of the elements in the list
      Parameters:
      lists - the WiredList instances to concatenate
      Returns:
      a new WiredList containing the elements in the individual WiredList instances
      See Also:

    • set

      public WiredList<E> set(int index, E e0, E e1, E... moreElems)
      Overwrites the elements at, and following the specified index with the provided values. For linked lists this is more efficient than setting each of the elements individually, especially if the elements are somewhere in the middle of the lists. The number of values must not exceed list.size() - index.
      Parameters:
      index - the index of the first element the set
      e0 - the first value to write
      e1 - the second value to write
      moreElems - more values to write
      Returns:
      this instance

    • setIf

      public E setIf(int index, Predicate<? super E> condition, E value)
      Sets the element at the specified index to the specified value if the original value passes the specified test. This method mitigates the relatively large cost of index-based retrieval with linked lists, which would double if you had to execute a get-compare-set sequence.
      Parameters:
      index - the index of the element to set
      condition - The test that the original value has to pass in order to be replaced with the new value. The original value is passed to the predicate's test method.
      value - The value to set
      Returns:
      The original value

    • remove

      public E remove(int index)
      Removes the element at the specified position in this list.
      Parameters:
      index - the index of the element to be removed
      Returns:
      the element previously at the specified position
      Throws:
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())

    • remove

      public boolean remove(Object o)
      Removes the first occurrence of the specified element from this list, if it is present.
      Parameters:
      o - element to be removed from this list, if present
      Returns:
      true if this list contained the specified element

    • removeIf

      public boolean removeIf(Predicate<? super E> filter)
      Removes all elements of this collection that satisfy the given predicate.
      Parameters:
      filter - a predicate which returns true for elements to be removed
      Returns:
      true if any elements were removed

    • first

      public E first()
      Returns the first element of the list. A NoSuchElementException is thrown if the list is empty.
      Returns:
      the first element of the list

    • last

      public E last()
      Returns the last element of the list. A NoSuchElementException is thrown if the list is empty.
      Returns:
      the last element of the list

    • prepend

      public WiredList<E> prepend(E value)
      Inserts the specified value at the start of the list, right-shifting the original elements.
      Parameters:
      value - The value to insert
      Returns:
      this instance

    • prependAll

      public WiredList<E> prependAll(Collection<? extends E> values)
      Inserts the specified collection at the start of the list, right-shifting the original elements.
      Parameters:
      values - The values to prepend to the list
      Returns:
      this instance

    • append

      public WiredList<E> append(E value)
      Appends the specified value to the end of the list. Equivalent to add(value).
      Parameters:
      value - The value to append to the list
      Returns:
      this instance

    • appendAll

      public WiredList<E> appendAll(Collection<? extends E> values)
      Appends the specified collection to this WiredList.
      Parameters:
      values - The values to append to the list
      Returns:
      this instance
      See Also:

    • insert

      public WiredList<E> insert(int index, E value)
      Inserts a value into the list. All elements at and following the specified index will be right-shifted. The index value must be >= 0 and <= list.size(). Specifying 0 (zero) is equivalent to prepend(value). Specifying list.size() is equivalent to append(value and add(value).
      Parameters:
      index - the index at which to insert the value
      value - the value
      Returns:
      this instance

    • insertAll

      public WiredList<E> insertAll(int index, Collection<? extends E> values)
      Inserts the specified collection at the specified index, right-shifting the elements at and following the index.
      Parameters:
      index - the index at which to insert the collection
      values - The collection to insert into the list
      Returns:
      this instance
      See Also:

    • removeFirst

      public E removeFirst()
      Removes the first element from the list, left-shifting the remaining elements. A NoSuchElementException is thrown if the list is empty.
      Returns:
      this instance

    • removeLast

      public E removeLast()
      Removes the last element from the list. A NoSuchElementException is thrown if the list is empty.
      Returns:
      this instance

    • replaceAll

      public void replaceAll(UnaryOperator<E> operator)
      Replaces each element of this list with the result of applying the operator to that element. Errors or runtime exceptions thrown by the operator are relayed to the caller.
      Parameters:
      operator - the operator to apply to each element
      Throws:
      UnsupportedOperationException - if this list is unmodifiable. Implementations may throw this exception if an element cannot be replaced or if, in general, modification is not supported

    • replaceAll

      public WiredList<E> replaceAll(int fromIndex, int toIndex, Collection<? extends E> values)
      Replaces the segment between fromIndex and toIndex with the elements in the specified collection.
      Parameters:
      fromIndex - the start index (inclusive) of the segment to replace
      toIndex - the end index (exclusive) of
      values - The values to replace the segment with
      Returns:
      this instance
      See Also:

    • replace

      public WiredList<E> replace(int fromIndex, int toIndex, WiredList<? extends E> other)
      Replaces the segment between fromIndex and toIndex with the elements in the specified list. This method is functionally equivalent to replace, but more efficient. However, it will leave the specified list empty. If you don't want this to happen, use replace.
      Parameters:
      fromIndex - the start index (inclusive) of the segment to replace
      toIndex - the end index (exclusive) of
      other - the values to replace the segment with
      Returns:
      this instance

    • copy

      public WiredList<E> copy()
      Returns a copy of this WiredList. Changes made to the copy will not propagate to this instance, and vice versa.
      Returns:
      a deep copy of this WiredList

    • copy

      public WiredList<E> copy(int fromIndex, int toIndex)
      Returns a copy of the specified segment. Changes made to the copy will not propagate to this instance, and vice versa.
      Parameters:
      fromIndex - the start index (inclusive) of the segment
      toIndex - the end index (exclusive) of the segment
      Returns:
      a deep copy of the specified segment

    • shrink

      public WiredList<E> shrink(int fromIndex, int toIndex)
      Shrinks the list to between the specified boundaries. If toIndex is equal to fromIndex, the list will, in effect, be cleared.
      Parameters:
      fromIndex - the index (inclusive) of the new start of the list
      toIndex - the index (exclusive) of the new end of the list
      Returns:
      this instance

    • cut

      public WiredList<E> cut(int fromIndex, int toIndex)
      Removes and returns a segment from the list.
      Parameters:
      fromIndex - the start index (inclusive) of the segment to delete
      toIndex - the end index (exclusive) of the segment to delete
      Returns:
      the deleted segment

    • paste

      public WiredList<? super E> paste(WiredList<? super E> into, int index)
      Inserts this list into the specified list at the specified position. Equivalent to into.embed(index, this). This list will be empty afterwards. Note that this method does not return this list but the paste-into list.
      Parameters:
      into - the list into which to insert this list
      index - the index at which to insert this list
      Returns:
      the specified list

    • embed

      public WiredList<E> embed(int index, WiredList<? extends E> other)
      Embeds the specified list in this list. This method is functionally equivalent to insertAll and addAll, but more efficient. However, it is a destructive operation for the provided list. It will be empty afterwards. If you don't want this to happen, use insertAll or addAll.
      Parameters:
      index - the index at which to embed the list
      other - the list to embed
      Returns:
      this instance

    • swap

      public WiredList<E> swap(int from1, int to1, int from2, int to2)
      Swaps the two list segments defined by the specified boundary indexes. In other words, once this method returns, the first list segment will start where the second list segment originally started, and vice versa. The list segments must not overlap and they must both contain at least one element. They need not have the same number of elements, though.
      Parameters:
      from1 - the from-index (inclusive) of the first segment
      to1 - the to-index (exclusive) of the first segment
      from2 - the from-index (inclusive) of the second segment
      to2 - the to-index (exclusive) of the second segment
      Returns:
      this instance

    • exchange

      public WiredList<E> exchange(int myFromIndex, int myToIndex, WiredList<E> other, int itsFromIndex, int itsToIndex)
      Exchanges list segments between this list and the specified list.
      Parameters:
      myFromIndex - the start index (inclusive) of the segment within this list
      myToIndex - the end index (exclusive) of the segment within this list
      other - the list to exchange segments with
      itsFromIndex - the start index (inclusive) of the segment within the other list
      itsToIndex - the end index (exclusive) of the segment within the other list
      Returns:
      this instance

    • embed

      public WiredList<E> embed(int myIndex, WiredList<? extends E> other, int itsFromIndex, int itsToIndex)
      Removes a segment from the specified list and embeds it in this list.
      Parameters:
      myIndex - the index at which to insert segment
      other - the list to remove the segment from
      itsFromIndex - the start index of the segment (inclusive)
      itsToIndex - the end index of the segment (exclusive)
      Returns:
      this instance

    • attach

      public WiredList<E> attach(WiredList<? extends E> other)
      Appends the specified list to this list. This method is functionally equivalent appendAll and addAll, but more efficient. However, it will leave the specified list empty. If you don't want this to happen, use appendAll or addAll.
      Parameters:
      other - the list to embed
      Returns:
      this instance
      See Also:

    • defragment

      public WiredList<E> defragment(List<Predicate<? super E>> criteria)
      Reorders the elements according to the specified criteria. The elements satisfying the first criterion (if any) will come first in the list, the elements satisfying the second criterion (if any) will come second, etc. The elements that did not satisfy any criterion will come last in the list.
      Parameters:
      criteria - the criteria used to group the elements
      Returns:
      this instance

    • defragment

      public WiredList<E> defragment(boolean keepRemainder, List<Predicate<? super E>> criteria)
      Reorders the elements according to the specified criteria. The elements satisfying the first criterion (if any) will come first in the list, the elements satisfying the second criterion (if any) will come second, etc.
      Parameters:
      keepRemainder - whether to keep the elements that did not satisfy any criterion, and move them to the end of the list
      criteria - the criteria used to group the elements
      Returns:
      this instance

    • group

      public <L0 extends List<E>, L1 extends List<L0>> L1 group(Predicate<? super E> criterion)
      Groups the elements in those that do, and elements that do not satisfy the specified criterion.
      Type Parameters:
      L0 - the type of the lists within the returned list
      L1 - the type of returned list
      Parameters:
      criterion - the test to submit the list elements to
      Returns:
      a list containing two lists representing the two groups
      See Also:

    • group

      public <L0 extends List<E>, L1 extends List<L0>> L1 group(List<Predicate<? super E>> criteria)

      Groups the elements according to the provided criteria. The return value is a list-of-lists where each inner List constitutes a group. This WiredList is left with all elements that did not satisfy any criterion, and it will be the last element in the returned list-of-lists. In other words, the size of the returned list-of-lists is the number of criteria plus one. You can use the join method to create a single "defragmented" list again.

      Elements will never be placed in more than one group. As soon as an element is found to satisfy a criterion it is placed in the corresponding group and the remaining criteria are skipped.

      The runtime type of the returned list-of-lists WiredList<WiredList<E>>. If you don't care about the exact type of the returned List, you can simply write: 

      
 WiredList<String> wl = ...;
 List<List<String>> groups = wl.group(...);

      Otherwise use any combination of List and WiredList that suits your needs.

      Type Parameters:
      L0 - the type of the lists within the returned list
      L1 - the type of returned list
      Parameters:
      criteria - the criteria used to group the elements
      Returns:
      a list of element groups

    • partition

      public <L0 extends List<E>, L1 extends List<L0>> L1 partition(int size)
      Splits this WiredList into multiple WiredList instances of the specified size. The partitions are chopped off from the WiredList and then placed in a separate WiredList. The last element in the returned list-of-lists is this WiredList, and it will now contain at most size elements.

      The runtime type of the return value is WiredList<WiredList<E>>. If you don't care about the exact type of the returned List, you can simply write: 

      
 WiredList<String> wl = ...;
 List<List<String>> partitions = wl.partition(3);

      Otherwise use any combination of List and WiredList that suits your needs.

      Type Parameters:
      L0 - the type of the lists within the returned list
      L1 - the type of returned list
      Parameters:
      size - The desired size of the partitions
      Returns:
      a list of WiredList instances of the specified size

    • split

      public <L0 extends List<E>, L1 extends List<L0>> L1 split(int numPartitions)
      Splits this WiredList into the specified number of equally-sized WiredList instances. The last element in the returned list-of-lists is this WiredList, and it will contain the remainder of the elements after dividing the list size by numPartitions. The runtime type of the return value is WiredList<WiredList<E>>. If you don't care about the exact type of the returned List, you can simply write: 
      
 WiredList<String> wl = ...;
 List<List<String>> partitions = wl.split(3);

      Otherwise use any combination of List and WiredList that suits your needs.

      Type Parameters:
      L0 - the type of the lists within the returned list
      L1 - the type of returned list
      Parameters:
      numPartitions - The number of WiredList instances to split this WiredList into
      Returns:
      a list containing the specified number of WiredList instances

    • lchop

      public WiredList<E> lchop(Predicate<? super E> criterion)
      Removes and returns a segment from the start of the list. The segment will include all elements up to (but not including) the first element that does not satisfy the specified condition. In other words, all elements in the returned list will satisfy the condition. If the condition is never satisfied, this list remains unchanged and an empty list is returned. If all elements satisfy the condition, the list remains unchanged and is itself returned.
      Parameters:
      criterion - the criterion that the elements in the returned segment will satisfy
      Returns:
      a WiredList containing all elements preceding the first element that does not satisfy the condition; possibly this instance

    • rchop

      public WiredList<E> rchop(Predicate<? super E> criterion)
      Removes and returns a segment from the end of the list. The segment will include all elements following the last element that does not satisfy the specified condition. In other words, all elements in the returned list will satisfy the condition. If the condition is never satisfied, the list remains unchanged and an empty list is returned. If all elements satisfy the condition, the list remains unchanged and is itself returned.
      Parameters:
      criterion - the criterion that the elements in the returned segment will satisfy
      Returns:
      a WiredList containing all elements following the last element that does not satisfy the condition; possibly this instance

    • reverse

      public WiredList<E> reverse()
      Reverses the order of the elements in this WiredList.
      Returns:
      this instance

    • move

      public WiredList<E> move(int fromIndex, int toIndex, int newFromIndex)
      Moves a list segment forwards or backwards through the list.
      Parameters:
      fromIndex - the start index of the segment (inclusive)
      toIndex - the end index of the segment (exclusive)
      newFromIndex - the index to which to move the segment. To move the segment to the very start of the list, specify 0 (zero). To move the segment to the very end of the list specify the size of the list
      Returns:
      this instance

    • clear

      public void clear()
      Removes all elements from this list. The list will be empty after this call returns.

    • reverseIterator

      public Iterator<E> reverseIterator()
      Returns an Iterator that traverses the list from the last element to the first. See also List.iterator().
      Returns:
      an Iterator that traverses the list from the last element to the first

    • wiredIterator

      public WiredIterator<E> wiredIterator()
      Returns a WiredIterator that traverses the list from the first element to the last.
      Returns:
      a WiredIterator that traverses the list from the first element to the last

    • wiredIterator

      public WiredIterator<E> wiredIterator(boolean reverse)
      Returns a WiredIterator that traverses the list from the first element to the last, or the other way round, depending on the value of the argument
      Parameters:
      reverse - Whether to iterate from the first to the last (false), or from the last to the first (true)
      Returns:
      a WiredIterator that traverses the list from the first element to the last, or the other way round

    • regionToArray

      public Object[] regionToArray(int fromIndex, int toIndex)
      Returns an array containing the elements within the specified region of this list.
      Parameters:
      fromIndex - the start index (inclusive) of the region
      toIndex - the end index (exclusive) of the region
      Returns:
      an array containing the elements within the specified region of this list

    • regionToArray

      public void regionToArray(int fromIndex, int toIndex, Object[] target, int offset)
      Copies the specified region within this list to the specified position within the specified array. The array must be large enough to copy the entire region to the specified position.
      Parameters:
      fromIndex - the start index (inclusive) of the region
      toIndex - the end index (exclusive) of the region
      target - the array to which to copy the elements
      offset - the offset within the array

    • subList

      public List<E> subList(int fromIndex, int toIndex)
      Throws an UnsupportedOperationException. The specification for this method requires that non-structural changes in the returned list are reflected in the original list (and vice versa). However, except for the List.set(int, Object) method, all changes to a WiredList are structural changes. WiredList does provide a method that returns a sublist (copySegment). It just has no relation to the original list any longer.

    • indexOf

      public int indexOf(Object o)
      Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element. More formally, returns the lowest index i such that Objects.equals(o, get(i)), or -1 if there is no such index.
      Specified by:
      indexOf in interface List<E>
      Parameters:
      o - element to search for
      Returns:
      the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element

    • lastIndexOf

      public int lastIndexOf(Object o)
      Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element. More formally, returns the highest index i such that Objects.equals(o, get(i)), or -1 if there is no such index.
      Specified by:
      lastIndexOf in interface List<E>
      Parameters:
      o - element to search for
      Returns:
      the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element

    • get

      public E get(int index)
      Returns the element at the specified position in this list.
      Specified by:
      get in interface List<E>
      Parameters:
      index - index of the element to return
      Returns:
      the element at the specified position in this list
      Throws:
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())

    • set

      public E set(int index, E element)
      Replaces the element at the specified position in this list with the specified element.
      Specified by:
      set in interface List<E>
      Parameters:
      index - index of the element to replace
      element - element to be stored at the specified position
      Returns:
      the element previously at the specified position

    • add

      public boolean add(E e)
      Appends the specified element to the end of this list.
      Specified by:
      add in interface Collection<E>
      Specified by:
      add in interface List<E>
      Parameters:
      e - element to be appended to this list
      Returns:
      true (as specified by Collection.add(E))

    • add

      public void add(int index, E element)
      Inserts the specified element at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).
      Specified by:
      add in interface List<E>
      Parameters:
      index - index at which the specified element is to be inserted
      element - element to be inserted

    • addAll

      public boolean addAll(Collection<? extends E> c)
      Appends all elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's iterator.
      Specified by:
      addAll in interface Collection<E>
      Specified by:
      addAll in interface List<E>
      Parameters:
      c - collection containing elements to be added to this list
      Returns:
      true if this list changed as a result of the call
      See Also:

    • addAll

      public boolean addAll(int index, Collection<? extends E> c)
      Inserts all elements in the specified collection into this list at the specified position (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices).
      Specified by:
      addAll in interface List<E>
      Parameters:
      index - index at which to insert the first element from the specified collection
      c - collection containing elements to be added to this list
      Returns:
      true if this list changed as a result of the call

    • size

      public int size()
      Returns the number of elements in this list. If this list contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
      Specified by:
      size in interface Collection<E>
      Specified by:
      size in interface List<E>
      Returns:
      the number of elements in this list

    • isEmpty

      public boolean isEmpty()
      Returns true if this list contains no elements.
      Specified by:
      isEmpty in interface Collection<E>
      Specified by:
      isEmpty in interface List<E>
      Returns:
      true if this list contains no elements

    • contains

      public boolean contains(Object o)
      Returns true if this list contains the specified element. More formally, returns true if and only if this list contains at least one element e such that Objects.equals(o, e).
      Specified by:
      contains in interface Collection<E>
      Specified by:
      contains in interface List<E>
      Parameters:
      o - element whose presence in this list is to be tested
      Returns:
      true if this list contains the specified element

    • containsAll

      public boolean containsAll(Collection<?> c)
      Returns true if this list contains all of the elements of the specified collection.
      Specified by:
      containsAll in interface Collection<E>
      Specified by:
      containsAll in interface List<E>
      Parameters:
      c - collection to be checked for containment in this list
      Returns:
      true if this list contains all of the elements of the specified collection
      See Also:

    • removeAll

      public boolean removeAll(Collection<?> c)
      Specified by:
      removeAll in interface Collection<E>
      Specified by:
      removeAll in interface List<E>

    • retainAll

      public boolean retainAll(Collection<?> c)
      Specified by:
      retainAll in interface Collection<E>
      Specified by:
      retainAll in interface List<E>

    • iterator

      public Iterator<E> iterator()
      Returns an Iterator that traverses the list from the first element to the last.
      Specified by:
      iterator in interface Collection<E>
      Specified by:
      iterator in interface Iterable<E>
      Specified by:
      iterator in interface List<E>
      Returns:
      an Iterator that traverses the list's elements from first to the last

    • listIterator

      public ListIterator<E> listIterator()
      Returns a list iterator over the elements in this list (in proper sequence).
      Specified by:
      listIterator in interface List<E>
      Returns:
      a list iterator over the elements in this list (in proper sequence)

    • listIterator

      public ListIterator<E> listIterator(int index)
      Returns a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list. The specified index indicates the first element that would be returned by an initial call to next. An initial call to previous would return the element with the specified index minus one.
      Specified by:
      listIterator in interface List<E>
      Parameters:
      index - index of the first element to be returned from the list iterator (by a call to next)
      Returns:
      a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list
      Throws:
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size())

    • equals

      public boolean equals(Object o)
      Compares the specified object with this list for equality. Returns true if and only if the specified object is also a list, both lists have the same size, and all corresponding pairs of elements in the two lists are equal. (Two elements e1 and e2 are equal if Objects.equals(e1, e2).) In other words, two lists are defined to be equal if they contain the same elements in the same order. This definition ensures that the equals method works properly across different implementations of the List interface.
      Specified by:
      equals in interface Collection<E>
      Specified by:
      equals in interface List<E>
      Overrides:
      equals in class Object
      Parameters:
      o - the object to be compared for equality with this list
      Returns:
      true if the specified object is equal to this list

    • hashCode

      public int hashCode()
      Returns the hash code value for this list.
      Specified by:
      hashCode in interface Collection<E>
      Specified by:
      hashCode in interface List<E>
      Overrides:
      hashCode in class Object
      Returns:
      the hash code value for this list
      See Also:

    • toString

      public String toString()
      Returns a String representation of this list.
      Overrides:
      toString in class Object
      Returns:
      a String representation of this list

    • toArray

      public Object[] toArray()
      Returns an array containing all elements in this list in proper sequence (from first to last element).
      Specified by:
      toArray in interface Collection<E>
      Specified by:
      toArray in interface List<E>
      Returns:
      an array containing all elements in this list in proper sequence
      See Also:

    • toArray

      public <T> T[] toArray(T[] a)
      Returns an array containing all elements in this list in proper sequence (from first to last element); the runtime type of the returned array is that of the specified array.
      Specified by:
      toArray in interface Collection<E>
      Specified by:
      toArray in interface List<E>
      Parameters:
      a - the array into which the elements of this list are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
      Returns:
      an array containing the elements of this list
      Throws:
      ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this list
      NullPointerException - if the specified array is null