Package org.apache.juneau.commons.collections

Class ReversedList<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractList<E>
org.apache.juneau.commons.collections.ReversedList<E>
Type Parameters:
E - The element type.
All Implemented Interfaces:
Iterable<E>, Collection<E>, List<E>, RandomAccess
public class ReversedList<E> extends AbstractList<E> implements RandomAccess
A reversed view of a list that does not modify the underlying list.

This class provides a read-only reversed view of a list, where element access is transparently reversed without copying or modifying the original list. All read operations (get, iterator, etc.) operate on the underlying list in reverse order.

Features:
  • Zero-copy reverse view - no data duplication
  • Efficient random access via index translation
  • Reflects changes in the underlying list automatically
  • Read-only - modification operations throw UnsupportedOperationException
  • Iterator and ListIterator support in reversed order
Usage:

// Create a list List<String> original = List.of("A", "B", "C"); // Create reversed view List<String> reversed = new ReversedList<>(original); // Access in reverse order reversed.get(0); // Returns "C" reversed.get(1); // Returns "B" reversed.get(2); // Returns "A" // Iterate in reverse for (String s : reversed) { // Iterates: "C", "B", "A" }

Notes:
  • The underlying list must not be null
  • Changes to the underlying list are immediately visible in the reversed view
  • All modification operations (add, remove, set, clear) throw UnsupportedOperationException
  • Size changes in the underlying list are reflected in this view

  • Constructor Details

    • ReversedList

      public ReversedList(List<E> list)
      Creates a new reversed view of the specified list.
      Parameters:
      list - The list to reverse. Must not be null.
      Throws:
      IllegalArgumentException - if list is null.

  • Method Details

    • add

      public void add(int index, E element)
      Not supported - this is a read-only view.
      Specified by:
      add in interface List<E>
      Overrides:
      add in class AbstractList<E>
      Throws:
      UnsupportedOperationException - always

    • clear

      public void clear()
      Not supported - this is a read-only view.
      Specified by:
      clear in interface Collection<E>
      Specified by:
      clear in interface List<E>
      Overrides:
      clear in class AbstractList<E>
      Throws:
      UnsupportedOperationException - always

    • get

      public E get(int index)
      Returns the element at the specified position in this reversed view.

      The position is translated to access the underlying list in reverse order. For example, index 0 returns the last element of the underlying list.

      Specified by:
      get in interface List<E>
      Specified by:
      get in class AbstractList<E>
      Parameters:
      index - The index of the element to return (0-based, in reversed order).
      Returns:
      The element at the specified position in the reversed view.
      Throws:
      IndexOutOfBoundsException - if the index is out of range.

    • iterator

      public Iterator<E> iterator()
      Returns an iterator over the elements in this reversed view in proper sequence.

      The iterator traverses the underlying list in reverse order.

      Specified by:
      iterator in interface Collection<E>
      Specified by:
      iterator in interface Iterable<E>
      Specified by:
      iterator in interface List<E>
      Overrides:
      iterator in class AbstractList<E>
      Returns:
      An iterator over the elements in reversed order.

    • listIterator

      public ListIterator<E> listIterator()
      Returns a list iterator over the elements in this reversed view.

      The iterator traverses the underlying list in reverse order.

      Specified by:
      listIterator in interface List<E>
      Overrides:
      listIterator in class AbstractList<E>
      Returns:
      A list iterator over the elements in reversed order.

    • listIterator

      public ListIterator<E> listIterator(int index)
      Returns a list iterator over the elements in this reversed view, starting at the specified position.

      The iterator traverses the underlying list in reverse order, starting from the translated position.

      Specified by:
      listIterator in interface List<E>
      Overrides:
      listIterator in class AbstractList<E>
      Parameters:
      index - The index of the first element to be returned from the list iterator (in reversed order).
      Returns:
      A list iterator over the elements in reversed order.
      Throws:
      IndexOutOfBoundsException - if the index is out of range.

    • remove

      public E remove(int index)
      Not supported - this is a read-only view.
      Specified by:
      remove in interface List<E>
      Overrides:
      remove in class AbstractList<E>
      Throws:
      UnsupportedOperationException - always

    • set

      public E set(int index, E element)
      Not supported - this is a read-only view.
      Specified by:
      set in interface List<E>
      Overrides:
      set in class AbstractList<E>
      Throws:
      UnsupportedOperationException - always

    • size

      public int size()
      Returns the number of elements in this reversed view.

      This is always equal to the size of the underlying list.

      Specified by:
      size in interface Collection<E>
      Specified by:
      size in interface List<E>
      Specified by:
      size in class AbstractCollection<E>
      Returns:
      The number of elements in this reversed view.

    • subList

      public List<E> subList(int fromIndex, int toIndex)
      Returns a view of the portion of this reversed list between the specified indices.

      The returned sublist is also a reversed view and reflects changes in the underlying list.

      Specified by:
      subList in interface List<E>
      Overrides:
      subList in class AbstractList<E>
      Parameters:
      fromIndex - Low endpoint (inclusive) of the subList.
      toIndex - High endpoint (exclusive) of the subList.
      Returns:
      A view of the specified range within this reversed list.
      Throws:
      IndexOutOfBoundsException - if the indices are out of range.

    • toString

      public String toString()
      Returns a string representation of this reversed list.

      The format follows the standard Java list convention: "[element1, element2, ...]" Elements are shown in reversed order (as they appear in this view).

      Overrides:
      toString in class AbstractCollection<E>
      Returns:
      A string representation of this reversed list.

    • 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. In other words, two lists are defined to be equal if they contain the same elements in the same order.

      This implementation compares elements in the reversed order as they appear in this view.

      Specified by:
      equals in interface Collection<E>
      Specified by:
      equals in interface List<E>
      Overrides:
      equals in class AbstractList<E>
      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.

      The hash code of a list is defined to be the result of the following calculation:

      int hashCode = 1; for (E e : list) hashCode = 31 * hashCode + (e == null ? 0 : e.hashCode());

      This ensures that list1.equals(list2) implies that list1.hashCode()==list2.hashCode() for any two lists list1 and list2, as required by the general contract of Object.hashCode().

      This implementation computes the hash code from the elements in reversed order as they appear in this view.

      Specified by:
      hashCode in interface Collection<E>
      Specified by:
      hashCode in interface List<E>
      Overrides:
      hashCode in class AbstractList<E>
      Returns:
      The hash code value for this list.