/* ListCursor.java 
** An instance of an implementing class serves as a cursor within a
** list represented by an instance of a class that implements the
** ListWithCursors interface.  A cursor is used for navigating among
** and accessing the items in such a list.
**
** Author: R. McCloskey
** Date: 2025
*/

public interface ListCursor<T> extends Cloneable {
   

   /****  observers  ****/

   /* Reports whether or not this cursor is at the front of its list. 
   */
   boolean atFront();


   /* Reports whether or not this cursor is at the rear of its list.
   */
   boolean atRear();


   /* Returns the item stored in the node at which this cursor is positioned.
   ** excep: if atRear(), throws ListCursorException 
   */
   T getItem() throws ListCursorException;


   /* Reports whether or not this cursor is at the same position as the
   ** specified cursor.
   */
   boolean equals(ListCursor<T> cur);


   /* Returns (a reference to) the list within which this cursor lies.
   */
   ListWithCursors<T> getList(); 


   /****  navigation mutators  ****/


   /* Places this cursor at the front of its list and returns a reference
   ** to itself.
   ** post: atFront()
   */
   ListCursor<T> toFront(); 


   /* Places this cursor at the rear of its list and returns a reference
   ** to itself.
   ** post: atRear()
   */
   ListCursor<T> toRear();


   /* Moves this cursor one position towards the rear of its list and
   ** returns a reference to itself.
   ** excep: if atRear(), throws a ListCursorException 
   */
   ListCursor<T> toNext() throws ListCursorException;


   /* Moves this cursor one position towards the front of its list
   ** and returns a reference to itself.
   ** excep: if atFront(), throws ListCursorException 
   */
   ListCursor<T> toPrev() throws ListCursorException;


   /* Moves this cursor to the same position as the given cursor
   ** and returns a reference to itself.
   ** post: equals(cur)
   ** excep: if getList() != cur.getList(), throws IllegalArgumentException
   */
   ListCursor<T> setTo(ListCursor<T> cur);


   /* Signals that this cursor logically has ceased to exist.
   */
   void dispose();


   /***  list mutation  ****/


   /* Inserts into this cursor's list a new node that becomes the predecessor
   ** of this cursor's position and in which is stored the specified item.
   */
   void insert(T item);


   /* Removes from this cursor's list the node at the cursor's position
   ** and returns the item stored in that node; the cursor's new position
   ** is what had been its successor.
   ** excep: if atRear(), throws ListCursorException 
   */
   T remove() throws ListCursorException;


   /* Replaces the item stored in the node at this cursor's position by 
   ** the specified item and returns (a reference to) the replaced item.
   ** excep: if atRear(), throws ListCursorException 
   */
   T replace(T item) throws ListCursorException;


   /** Swaps the items contained in the nodes indicated by this cursor and 
   **  the specified cursor.
   **  excep: if atRear() or c.atRear(), throws ListCursorException 
   */
   void swapItems(ListCursor<T> c) throws ListCursorException;


   /****  clone  ****/

   /** Returns a new cursor that is identical to this one.
   */
   ListCursor<T> clone();
}