ADT Dynamic Linked List - Retrieval Operation

[jacknight]

I have finished writing my Dynamic, Linked-List implementation of the ADT List, but I can't figure out what the book includes the "void retrieve" function for. Insertion, deletion, the constructors, deconstructors, etc. all have clear purposes, but what is the purpose of the retrieval operation? The header file (class declaration) looks like this:

typedef int ListItemType;

class List
{
    public:
       List(); //constructor
       
       List(const List& aList); // copy constructor
       
       ~List(); //destructor
       
       void display(); //output
       bool isEmpty() const; //checks for empty
       int getLength() const;
       void insert_node(int index, const ListItemType& newItem) //inserts node
           throw (ListIndexOutOfRangeException, ListException);
       void delete_node(int index) //deletes node
           throw (ListIndexOutOfRangeException);
       void retrieve (int index, ListItemType& dataItem) const
            throw (ListIndexOutOfRangeException);
       
    private:
        struct ListNode            //A node on the list
        {
           ListItemType item;
           ListNode *next;
        }; //end ListNode
           
           int size;
           ListNode *head;
           ListNode *find(int index) const;
}; //end List

[Narue]

>but what is the purpose of the retrieval operation?
I would assume it's a search member function that gives you the node at a particular index or with a particular value.

[jacknight]

>but what is the purpose of the retrieval operation?
I would assume it's a search member function that gives you the node at a particular index or with a particular value.

In what way could I use it? I need to demonstrate all the functions but I don't understand what exactly this one does. They suggest you define it as such:

void List::retrieve(int index, ListItemType& dataItem) const
     throw (ListIndexOutOfRangeException)
{
     if ((index < 1) || (index > getLength()) )
        throw ListIndexOutOfRangeException( "ListIndexOutOfRangeException:retrieve index out of range");
     else
     { //get pointer to the node, then data in the node
        ListNode *cur = find(index);
        dataItem = cur->item;
     } // end if statement
} //end retrieve

[Narue]

>They suggest you define it as such:
It's just like indexing an array then:

try {
  ListItemType result;

  my_list.retrieve ( i, result );
  std::cout<<"Found "<< result <<'\n';
}
catch ( const ListIndexOutOfRangeException& ex ) {
  // Handle the error
}