-- $Date: 2004/01/02 10:01:37 $
-- $Revision: 1.8 $
-- $Author: jcrocholl $

with Ada.Strings.Unbounded;
use Ada.Strings.Unbounded;

with Lists;

package String_Lists is

   -- Local instantiation of generic package Lists with
   -- Unbounded_String as Content_Type.
   package US_Lists is new Lists(Unbounded_String);

   -- Instance of a list. There is no need to call a
   -- constructor. Uninitialized lists behave like regular empty
   -- ones.
   --
   -- This subtype renames the List type in the local package
   -- US_Lists.
   subtype List is US_Lists.List;

   --------------------
   -- List construction
   --------------------

   -- Insert an item at the end of the list.
   procedure Push
     (This    : in out List-- The list to modify.
      Content : in String);  -- The item to insert.

   -- Insert an item at the beginning of the list.
   procedure Unshift
     (This    : in out List-- The list to modify.
      Content : in String);  -- The item to insert.

   ----------------
   -- Item indexing
   ----------------

   -- Count items in this list. This operation is not O(n) but O(1)
   -- because the result comes straight from a counter variable.
   function Count
     (This : in List-- Get information about this list.
     return Natural   -- The number of items in the list.
     renames US_Lists.Count;

   -- Is the list empty? Returns True if and only if there are no
   -- items in the list.
   function Empty
     (This : in List-- Get information about this list.
     return Boolean   -- This list empty?
     renames US_Lists.Empty;

   -- Read the current iteration position as a number, starting with 1
   -- at the first item. An index of 0 means: no current item, so
   -- either we're not currently iterating or the iteration has
   -- finished.
   function Index
     (This : in List-- Get information about this list.
     return Natural   -- Iteration index of this list.
     renames US_Lists.Index;

   ------------------------
   -- Iterating over a list
   ------------------------

   -- Reset the iteration index to 0. This starts a new
   -- iteration. There must be a call to Next before the first item
   -- can be read from the function This.
   procedure Reset
     (This : in List-- The list to iterate over.
     renames US_Lists.Reset;

   -- Go to the next item.
   procedure Next
     (This : in List-- The list to iterate over.
     renames US_Lists.Next;

   -- Go to the next item. Return False if and only if we reached the
   -- end of the list.
   function Next
     (This : in List-- The list to iterate over.
     return Boolean   -- Successfully moved to next item?
     renames US_Lists.Next;

   -- End of list reached? Returns True if and only if we reached the
   -- end of the list. A call to Current would then fail because the
   -- current item pointer is null.
   function End_Of_List
     (This : in List-- The list to iterate over.
     return Boolean   -- Reached end of list?
     renames US_Lists.End_Of_List;

   -- Read the item at the current iteration pointer.
   function Current
     (This : in List-- The list to iterate over.
     return String;   -- Current item.

   --------------------------------------
   -- Manipulating a list while iterating
   --------------------------------------

   -- Update the item at the current iteration pointer.
   procedure Update_Current
     (This    : in out List-- The list to modify.
      Content : in String);  -- New content for the current item.

   -- Remove the item at the current iteration pointer from the list.
   procedure Remove_Current
     (This : in out List-- The list to modify.
     renames US_Lists.Remove_Current;

   -- Insert an item directly before the item at the current iteration
   -- pointer.
   procedure Insert_Before_Current
     (This    : in out List-- The list to modify.
      Content : in String);  -- The item to insert.

   -- Insert an item directly after the item at the current iteration
   -- pointer.
   procedure Insert_After_Current
     (This    : in out List-- The list to modify.
      Content : in String);  -- The item to insert.

end String_Lists;