Interface TextElementSequence

All Known Implementing Classes:
TextElementList
public interface TextElementSequence
Contract for a specialized sequence of TextElements with enhanced search and modification capabilities for lexical preservation operations.

Unlike standard List, this interface provides:

  • Index-based search with predicates (findFirst, findLast, findNext, findPrevious)
  • Element-based search (indexOf, lastIndexOf with overloads)
  • Controlled mutations (insert, remove) where caller manages index adjustments

Thread safety: Implementations are not required to be thread-safe.

Index management: Mutation operations modify the underlying list directly. Callers are responsible for tracking index changes after mutations.

Since:
3.28.0

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    allMatch(Predicate<TextElement> predicate)
    Tests whether all elements in this sequence match the given predicate.
    boolean
    anyMatch(Predicate<TextElement> predicate)
    Tests whether any element in this sequence matches the given predicate.
    int
    findFirst(Predicate<TextElement> predicate)
    Finds the first index where the predicate matches, searching forward from index 0.
    int
    findLast(Predicate<TextElement> predicate)
    Finds the last index where the predicate matches, searching backward from the end.
    int
    findNext(int fromIndex, Predicate<TextElement> predicate)
    Finds the next index where the predicate matches, searching forward from fromIndex (inclusive).
    int
    findPrevious(int fromIndex, Predicate<TextElement> predicate)
    Finds the previous index where the predicate matches, searching backward from fromIndex (inclusive).
    TextElement
    get(int index)
    Returns the element at the specified index.
    default int
    indexOf(int fromIndex, TextElement element)
    Finds the next occurrence of element starting from fromIndex (inclusive).
    default int
    indexOf(TextElement element)
    Finds the first occurrence of the specified element.
    void
    insert(int index, TextElement element)
    Inserts element at the specified index.
    void
    insertAll(int index, List<TextElement> elements)
    Inserts all elements at the specified index.
    boolean
    isEmpty()
    Checks if this sequence is empty.
    boolean
    isValidIndex(int index)
    Checks if the index is valid (0 invalid input: '<'= index invalid input: '<' size).
    default TextElementIterator
    iterator()
    Returns an iterator starting at index 0.
    TextElementIterator
    iterator(int fromIndex)
    Returns an iterator starting at the specified index.
    default int
    lastIndexOf(int fromIndex, TextElement element)
    Finds the previous occurrence of element before fromIndex (inclusive).
    default int
    lastIndexOf(TextElement element)
    Finds the last occurrence of the specified element.
    boolean
    noneMatch(Predicate<TextElement> predicate)
    Tests whether no elements in this sequence match the given predicate.
    void
    remove(int index)
    Removes the element at the specified index.
    void
    removeRange(int fromIndex, int toIndex)
    Removes elements in range [fromIndex, toIndex] (inclusive on both ends).
    int
    size()
    Returns the number of elements in this sequence.
    default Stream<TextElement>
    stream()
    Returns a stream of elements for functional operations.
    List<TextElement>
    subList(int fromIndex, int toIndex)
    Returns a sublist view [fromIndex, toIndex).
    List<TextElement>
    takeWhile(Predicate<TextElement> predicate)
    Returns a new list containing elements from the start until the predicate fails.
    List<TextElement>
    toList()
    Returns an unmodifiable view of the underlying list.
    List<TextElement>
    toMutableList()
    Returns the underlying mutable list.

  • Method Details

    • findFirst

      int findFirst(Predicate<TextElement> predicate)
      Finds the first index where the predicate matches, searching forward from index 0.
      Parameters:
      predicate - the condition to test
      Returns:
      the first matching index, or -1 if no match found
      Throws:
      NullPointerException - if predicate is null

    • findLast

      int findLast(Predicate<TextElement> predicate)
      Finds the last index where the predicate matches, searching backward from the end.
      Parameters:
      predicate - the condition to test
      Returns:
      the last matching index, or -1 if no match found
      Throws:
      NullPointerException - if predicate is null

    • findNext

      int findNext(int fromIndex, Predicate<TextElement> predicate)
      Finds the next index where the predicate matches, searching forward from fromIndex (inclusive).
      Parameters:
      fromIndex - the starting index (inclusive)
      predicate - the condition to test
      Returns:
      the next matching index, or -1 if no match found
      Throws:
      NullPointerException - if predicate is null

    • findPrevious

      int findPrevious(int fromIndex, Predicate<TextElement> predicate)
      Finds the previous index where the predicate matches, searching backward from fromIndex (inclusive).
      Parameters:
      fromIndex - the starting index (inclusive)
      predicate - the condition to test
      Returns:
      the previous matching index, or -1 if no match found
      Throws:
      NullPointerException - if predicate is null

    • anyMatch

      boolean anyMatch(Predicate<TextElement> predicate)
      Tests whether any element in this sequence matches the given predicate.

      This is a short-circuiting terminal operation: it stops as soon as a matching element is found and returns true immediately.

      Examples: 

      // Check if list contains any comment
boolean hasComment = list.anyMatch(TextElement::isComment);

// Check if list contains any token with specific text
boolean hasIdentifier = list.anyMatch(el ->
    el instanceof TokenTextElement &&
    ((TokenTextElement) el).getText().equals("myVar")
);
      Parameters:
      predicate - the predicate to test elements against
      Returns:
      true if any element matches the predicate, false otherwise (returns false for empty sequences)
      Throws:
      NullPointerException - if predicate is null

    • allMatch

      boolean allMatch(Predicate<TextElement> predicate)
      Tests whether all elements in this sequence match the given predicate.

      This is a short-circuiting terminal operation: it stops as soon as a non-matching element is found and returns false immediately.

      Returns true for empty sequences (vacuous truth).

      Examples: 

      // Check if all elements are whitespace
boolean allWhitespace = list.allMatch(TextElement::isSpaceOrTab);

// Check if all elements are comments
boolean allComments = list.allMatch(TextElement::isComment);
      Parameters:
      predicate - the predicate to test elements against
      Returns:
      true if all elements match the predicate (or sequence is empty), false otherwise
      Throws:
      NullPointerException - if predicate is null

    • noneMatch

      boolean noneMatch(Predicate<TextElement> predicate)
      Tests whether no elements in this sequence match the given predicate.

      This is a short-circuiting terminal operation: it stops as soon as a matching element is found and returns false immediately.

      Returns true for empty sequences.

      Equivalent to !anyMatch(predicate).

      Examples: 

      // Check if list has no comments
boolean noComments = list.noneMatch(TextElement::isComment);

// Check if list has no newlines
boolean noNewlines = list.noneMatch(TextElement::isNewline);
      Parameters:
      predicate - the predicate to test elements against
      Returns:
      true if no elements match the predicate (or sequence is empty), false otherwise
      Throws:
      NullPointerException - if predicate is null

    • indexOf

      default int indexOf(TextElement element)
      Finds the first occurrence of the specified element. Equivalent to findFirst(e -> Objects.equals(e, element)).
      Parameters:
      element - the element to search for (may be null)
      Returns:
      the first occurrence index, or -1 if not found

    • lastIndexOf

      default int lastIndexOf(TextElement element)
      Finds the last occurrence of the specified element. Equivalent to findLast(e -> Objects.equals(e, element)).
      Parameters:
      element - the element to search for (may be null)
      Returns:
      the last occurrence index, or -1 if not found

    • indexOf

      default int indexOf(int fromIndex, TextElement element)
      Finds the next occurrence of element starting from fromIndex (inclusive). Equivalent to findNext(fromIndex, e -> Objects.equals(e, element)).
      Parameters:
      fromIndex - the starting index (inclusive)
      element - the element to search for (may be null)
      Returns:
      the next occurrence index, or -1 if not found

    • lastIndexOf

      default int lastIndexOf(int fromIndex, TextElement element)
      Finds the previous occurrence of element before fromIndex (inclusive). Equivalent to findPrevious(fromIndex, e -> Objects.equals(e, element)).
      Parameters:
      fromIndex - the starting index (inclusive)
      element - the element to search for (may be null)
      Returns:
      the previous occurrence index, or -1 if not found

    • takeWhile

      List<TextElement> takeWhile(Predicate<TextElement> predicate)
      Returns a new list containing elements from the start until the predicate fails. The returned list is independent of this sequence.
      Parameters:
      predicate - the condition to test
      Returns:
      a new list of matching elements
      Throws:
      NullPointerException - if predicate is null

    • subList

      List<TextElement> subList(int fromIndex, int toIndex)
      Returns a sublist view [fromIndex, toIndex). The returned list is backed by this sequence, so changes affect both.
      Parameters:
      fromIndex - low endpoint (inclusive)
      toIndex - high endpoint (exclusive)
      Returns:
      a sublist view
      Throws:
      IndexOutOfBoundsException - if indices are out of range

    • insert

      void insert(int index, TextElement element)
      Inserts element at the specified index. WARNING: Caller must adjust subsequent indices manually.
      Parameters:
      index - position to insert at
      element - element to insert
      Throws:
      IndexOutOfBoundsException - if index is out of range
      NullPointerException - if element is null

    • insertAll

      void insertAll(int index, List<TextElement> elements)
      Inserts all elements at the specified index. WARNING: Caller must adjust subsequent indices manually.
      Parameters:
      index - position to insert at
      elements - elements to insert
      Throws:
      IndexOutOfBoundsException - if index is out of range
      NullPointerException - if elements is null

    • remove

      void remove(int index)
      Removes the element at the specified index. WARNING: Caller must adjust subsequent indices manually.
      Parameters:
      index - position to remove from
      Throws:
      IndexOutOfBoundsException - if index is out of range

    • removeRange

      void removeRange(int fromIndex, int toIndex)
      Removes elements in range [fromIndex, toIndex] (inclusive on both ends). WARNING: Caller must adjust subsequent indices manually.
      Parameters:
      fromIndex - start of range (inclusive)
      toIndex - end of range (inclusive)
      Throws:
      IndexOutOfBoundsException - if indices are out of range or fromIndex > toIndex

    • get

      TextElement get(int index)
      Returns the element at the specified index.
      Parameters:
      index - the index
      Returns:
      the element at that position
      Throws:
      IndexOutOfBoundsException - if index is out of range

    • isValidIndex

      boolean isValidIndex(int index)
      Checks if the index is valid (0 invalid input: '<'= index invalid input: '<' size).
      Parameters:
      index - the index to check
      Returns:
      true if index is valid

    • size

      int size()
      Returns the number of elements in this sequence.
      Returns:
      the size

    • isEmpty

      boolean isEmpty()
      Checks if this sequence is empty.
      Returns:
      true if size is 0

    • toList

      List<TextElement> toList()
      Returns an unmodifiable view of the underlying list. Changes to the original list are visible in the returned view.
      Returns:
      an unmodifiable list view

    • toMutableList

      List<TextElement> toMutableList()
      Returns the underlying mutable list.

      WARNING: This exposes the internal list directly. Modifications will affect this sequence.

      Returns:
      the mutable list

    • iterator

      TextElementIterator iterator(int fromIndex)
      Returns an iterator starting at the specified index.
      Parameters:
      fromIndex - the starting position
      Returns:
      an iterator with position tracking
      Throws:
      IndexOutOfBoundsException - if fromIndex is out of range

    • iterator

      default TextElementIterator iterator()
      Returns an iterator starting at index 0.
      Returns:
      an iterator from the beginning

    • stream

      default Stream<TextElement> stream()
      Returns a stream of elements for functional operations.
      Returns:
      a stream over the elements