0024742: Remove rarely used collection classes: SList

[occt.git] / src / TopLoc / TopLoc_SListOfItemLocation.cdl

-- Created on: 1993-02-26
-- Created by: Remi LEQUETTE
-- Copyright (c) 1993-1999 Matra Datavision
-- Copyright (c) 1999-2014 OPEN CASCADE SAS
--
-- This file is part of Open CASCADE Technology software library.
--
-- This library is free software; you can redistribute it and/or modify it under
-- the terms of the GNU Lesser General Public License version 2.1 as published
-- by the Free Software Foundation, with special exception defined in the file
-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
-- distribution for complete text of the license and disclaimer of any warranty.
--
-- Alternatively, this file may be used under the terms of Open CASCADE
-- commercial license or contractual agreement.

private class SListOfItemLocation from TopLoc

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

uses
    SListNodeOfItemLocation from TopLoc,
    ItemLocation            from TopLoc
    
raises
    NoSuchObject from Standard

is
    Create returns SListOfItemLocation from TopLoc;
	---Purpose: Creates an empty List.
	
    Create(anItem : ItemLocation from TopLoc; aTail : SListOfItemLocation from TopLoc)
    returns SListOfItemLocation from TopLoc;
	---Purpose: Creates a List with <anItem> as value  and <aTail> as tail.
	
    Create(Other : SListOfItemLocation from TopLoc)
    returns SListOfItemLocation from TopLoc;
	---Purpose: Creates a list from an other one. The lists  are shared. 
	
    Assign(me : in out; Other : SListOfItemLocation from TopLoc)
    returns SListOfItemLocation from TopLoc
        ---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 ItemLocation from TopLoc
        ---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 ItemLocation from TopLoc
        ---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 : ItemLocation from TopLoc)
        ---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 SListOfItemLocation from TopLoc
        ---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 SListOfItemLocation from TopLoc
        ---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 : SListOfItemLocation from TopLoc)
        ---Level: Public
	---Purpose: Changes the current tail  in the list. On an empty
	-- list SetTail is Assign.
    is static;
    
    Construct(me : in out; anItem : ItemLocation from TopLoc)  
        ---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 : ItemLocation from TopLoc) returns SListOfItemLocation from TopLoc
        ---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 : SListOfItemLocation from TopLoc)
        ---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 : SListNodeOfItemLocation from TopLoc;

end SListOfItemLocation;