-- File:	TCollection_SList.cdl
-- Created:	Fri Feb 26 13:38:35 1993
-- Author:	Remi LEQUETTE
--		<rle@phylox>
---Copyright:	 Matra Datavision 1993


generic class SList from TCollection (Item as any)

	---Purpose: An SList is a LISP like list of Items.
	-- An SList is :
	--   . Empty.
	--   . Or it has a Value and a  Tail  which is an other SList. 
	-- 
	-- The Tail of an empty list is an empty list.
	-- SList are  shared.  It  means   that they  can  be
	-- modified through other lists.
	-- SList may  be used  as Iterators. They  have Next,
	-- More, and value methods. To iterate on the content
	-- of the list S just do.
	-- 
	-- SList Iterator;
	-- for (Iterator = S; Iterator.More(); Iterator.Next())
	--   X = Iterator.Value();
	-- 
        --  Memory usage  is  automatically managed for  SLists
	--  (using reference counts).
      	---Example:
	-- If S1 and S2 are SLists :
	-- if S1.Value() is X.
	-- 
	-- And the following is done :
	-- S2 = S1;
	-- S2.SetValue(Y);
	-- 
	-- S1.Value() becomes also Y.   So SList must be used
	-- with   care.  Mainly  the SetValue()    method  is
	-- dangerous. 

raises
    NoSuchObject from Standard
    
    class SListNode from TCollection
    inherits TShared from MMgt
    is
       Create(I : Item; aTail :  SList from TCollection) returns mutable SListNode from TCollection;
       ---C++:inline

       Count(me) returns Integer;
       ---C++:inline
       ---C++: return &
       
       Tail(me) returns SList from TCollection;
       ---C++:inline
       ---C++: return &
       
       Value(me) returns Item;
       ---C++:inline
       ---C++: return &

    fields
	myTail :  SList from TCollection;
    	myValue : Item;
    end;

is
    Create returns SList from TCollection;
	---Purpose: Creates an empty List.
	
    Create(anItem : Item; aTail : SList from TCollection)
    returns SList from TCollection;
	---Purpose: Creates a List with <anItem> as value  and <aTail> as tail.
	
    Create(Other : SList from TCollection)
    returns SList from TCollection;
	---Purpose: Creates a list from an other one. The lists  are shared. 
	
    Assign(me : in out; Other : SList from TCollection)
    returns SList from TCollection
        ---Level: Public
	---Purpose: Sets  a list  from  an  other  one. The  lists are
	-- shared. The list itself is returned.
	---C++: alias operator =
	---C++: return &
    is static;
    
    IsEmpty(me) returns Boolean
        ---Level: Public
	---C++: inline
    is static;
    
    Clear(me : in out)
        ---Level: Public
	---Purpose: Sets the list to be empty.
	---C++: alias ~
    is static;
	
    Value(me) returns any Item
        ---Level: Public
	---Purpose: Returns the current value of the list. An error is
	-- raised  if the list is empty.
	---C++: return const &
    raises
    	NoSuchObject from Standard
    is static;
    
    ChangeValue(me : in out) returns any Item
        ---Level: Public
	---Purpose: Returns the current value of the list. An error is
	-- raised if the  list  is empty.   This value may be
	-- modified.   A   method modifying the  value can be
	-- called. The value will be modified in the list.
	---Example: AList.ChangeValue().Modify()
	---C++: return &
    raises
    	NoSuchObject from Standard
    is static;
    
    SetValue(me : in out; anItem : Item)
        ---Level: Public
	---Purpose: Changes the current value in the list. An error is
	-- raised if the list is empty.
    raises
    	NoSuchObject from Standard
    is static;
    
    Tail(me) returns SList from TCollection
        ---Level: Public
	---Purpose: Returns the current tail of  the list. On an empty
	-- list the tail is the list itself.
	---C++: return const &
    is static;
    
    ChangeTail(me : in out) returns SList from TCollection
        ---Level: Public
	---Purpose: Returns the current  tail of the list.   This tail
	-- may be modified.  A method modifying the  tail can
	-- be called. The tail will be modified in the list.
	---Example: AList.ChangeTail().Modify()
	---C++: return &
    is static;
    
    SetTail(me : in out; aList : SList from TCollection)
        ---Level: Public
	---Purpose: Changes the current tail  in the list. On an empty
	-- list SetTail is Assign.
    is static;
    
    Construct(me : in out; anItem : Item)  
        ---Level: Public
	---Purpose: Replaces the list by a list with <anItem> as Value
	-- and the  list <me> as  tail.
	---C++: inline
    is static;
    
    Constructed(me; anItem : Item) returns SList from TCollection
        ---Level: Public
	---Purpose: Returns a new list  with  <anItem> as Value an the
	-- list <me> as tail.
	---C++: inline
    is static;
    
    ToTail(me :  in out)
        ---Level: Public
	---Purpose: Replaces the list <me> by its tail.
	---C++: inline
    is static;
        
    Initialize(me : in out; aList : SList from TCollection)
        ---Level: Public
	---Purpose: Sets  the iterator  to iterate   on the content of
	-- <aList>. This is Assign().
	---C++: inline
    is static;
    
    More(me) returns Boolean
        ---Level: Public
	---Purpose: Returns True if the iterator  has a current value.
	-- This is !IsEmpty()
	---C++: inline
    is static;
    
    Next(me : in out)
        ---Level: Public
	---Purpose: Moves the iterator to the next object in the list.
	-- If the iterator is empty it will  stay empty. This is ToTail()
	---C++: inline
    is static;
    
fields
    myNode : SListNode from TCollection;

end SList;