[occt.git] / src / Dico / Dico_Dictionary.cdl

-- File:	Dictionary.cdl
-- Created:	Tue Jul 28 16:06:13 1992
-- Author:	Christian CAILLET
--		<cky@phylox>
---Copyright:	 Matra Datavision 1992


generic class Dictionary  from Dico  (TheItem as any)  inherits TShared

    ---Purpose : Defines an alphanumeric dictionary in a cellular way,
    --           corresponding to an indexed tree.
    --           (note that an "entry" is a cell with a value associated,
    --            other cells are accessed by dictionary nmanagenent only) 
    --           For each level, cells follow by "next" chaining.
    --           To pass to next level, cells follow by "sub" chaining
    --           
    --  Warning : Because of implementation as a tree of cells, beware about
    --           size of TheItem class if it is not identified by Handle) : if
    --           this size is big, it can cause problems of memory spending

uses OStream, Integer, Boolean, Character, AsciiString --, Iterator

raises NoSuchObject


    	-- --   Nested class : Iterator (on Dictionary)   -- --

    class Iterator

    ---Purpose : Defines an iterator on a Dictionary
    --           Iteration is alphabetic (due to dictionary construction)
    --           Each entry is defined by its Name and its item Value
    --	         Remark : The stack used by the Iterator is able to give
    --	         complete name by scanning it

    uses Boolean, AsciiString  -- , StackItem , Dictionary

    raises NoSuchObject

    is

    	Create (acell : Dictionary) returns Iterator;
        ---Purpose : Creates an iterator which will work on all the dictionary
    
    	Create (acell : Dictionary; basename : CString) returns Iterator;
        ---Purpose : Creates an iterator which will consider only entries
        --           which name begin by the string given as basename (subpart)

    	Create (acell : Dictionary; basename : AsciiString) returns Iterator;
        ---Purpose : Creates an iterator which will consider only entries
        --           which name begin by the string given as basename (subpart)
        --           Same as above, but basename is String instead of CString
    
    	Start (me : in out)  is static;
    	---Purpose : Allows to Start a new Iteration from beginning
    
    	More (me : in out) returns Boolean  is static;
    	---Purpose : Returns True if there are more entries to return
    
    	Next (me : in out)  is static;
    	---Purpose : Go to the next entry
    	--           (if there is not, Value will raise an exception)
    
    	Value (me) returns any TheItem
    	---Purpose : Returns item value of current entry
    	    raises NoSuchObject  is static;
    	--           Exception raised if there is no current Item
    	---C++ : return const &
    
    	Name  (me) returns AsciiString
    	---Purpose : Returns name of current entry
    	    raises NoSuchObject  is static;
    	--           Exception raised if there is no current Item

    	AppendStack (me : in out; val : Dictionary)  is static private;
	---Purpose : Appends a new value to the Iteration Stack

    fields

    	thebase : Dictionary;
    	thename : AsciiString;    -- base name (if not empty)
    	thelast : StackItem; -- Iteration Stack
    	thenb   : Integer;
    	themore : Boolean;   -- More called before Next ?
    	theinit : Boolean;   -- current cell processed ?
    	thenext : Boolean;   -- unstack -> Next cell to choose

    end Iterator;


    private class StackItem  inherits TShared
    
    	---Purpose : Defines an Item for the Stack used by the Iterator

    --  uses Dictionary

    is
    
    	Create returns mutable StackItem;
	---Purpose : Creates a StackItem with no Previous one
    
    	Create (previous : mutable StackItem) returns mutable StackItem;
	---Purpose : Creates a StackItem with a Previous one

    	Previous (me) returns mutable StackItem  is static;
	---Purpose : Returns the Previous Item (is Null if no Previous defined)

    	Value (me) returns Dictionary  is static;
	---Purpose : Returns the Dictionary Cell corresponding to an Item

    	SetValue (me : mutable; cval : Dictionary)  is static;
	---Purpose : Sets a new Dictionary Cell as Value of an Item

     fields
     
     	thevalue : Dictionary;
	theprev  : StackItem;

    end StackItem;

is

    	    	-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
    	    	--                                           --
    	    	-- --  Description of Dictionary itself   -- --
    	    	--                                           --
    	    	-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
    	-- (methods having a String argument are duplicated String-CString)

    Create returns mutable Dictionary;
    ---Purpose : Creates a Dictionary cell.
    --           A Dictionary is always created then handled by its first cell
    --           After creating a Dictionary, user can call methods HasItem,
    --           Item, SetItem ... (internal cells and entries are also
    --           defined as objects from the same class)
    --           Also iteration can be made, by an Iterator on this Dictionary

    SetChar (me : mutable; car : Character)  is static private;
    ---Purpose : Defines cell's character (internal use, to build dict. tree)


    HasItem (me; name : CString; exact : Boolean = Standard_False)
    	returns Boolean  is static;
    ---Purpose : Returns True if an Item is bound to a Name in the Dictionnary
    --           <exact> : if True, commands exact matching
    --             if False, accept completion, only if ONE AND ONLY ONE
    --             Dictionnary Entry has <name> as beginning of its name

    HasItem (me; name : AsciiString; exact : Boolean = Standard_True)
    	returns Boolean  is static;
    ---Purpose : Works as above method but accepts a String from TCollection

    Item (me; name : CString; exact : Boolean = Standard_True)
    	returns any TheItem
    ---Purpose : Returns item bound to a name in the Dictionnary
    --           <exact> : same as for HasItem
    	raises NoSuchObject  is static;
    --           Error if <name> corresponds to no entry
    ---C++ : return const &

    Item (me; name : AsciiString; exact : Boolean = Standard_True)
        returns any TheItem  raises NoSuchObject  is static;
    ---Purpose : Works as above method but accepts a String from TCollection
    ---C++ : return const &


    GetItem (me; name : CString; anitem : out any TheItem;
    	     exact : Boolean = Standard_True)
    	returns Boolean  is static;
    ---Purpose : Gathers HasItem and Item, in a less regular but faster way
    --           If return is True, <anitem> is returned too, else it is not
    --           <exact> : same as for HasItem

    GetItem (me; name : AsciiString; anitem : out TheItem;
    	     exact : Boolean = Standard_True)
    	returns Boolean  is static;
    ---Purpose : Works as above method but accepts a String from TCollection
    
    SetItem (me : mutable; name : CString;
        anitem : any TheItem; exact : Boolean = Standard_True)  is static;
    ---Purpose : Binds an item to a dictionnary entry
    --           If <name> is already known in the dictionary, its value
    --           is changed. Else, the dictionary entry is created.
    --           If <exact> is given False, completion is tried, it is accepted
    --           If it gives a UNIQUE entry : hence this one will be modified
    --           Else, new entry is created with the exact name given

    SetItem (me : mutable; name : AsciiString;
    	anitem : any TheItem; exact : Boolean = Standard_True)  is static;
    ---Purpose : Works as above method but accepts a String from TCollection

    NewItem (me : mutable; name : CString; isvalued : out Boolean;
    	     exact : Boolean = Standard_True)  returns any TheItem
    ---Purpose : Returns the Item AS AN ADDRESS which corresponds to a Name,
    --           in order to be changed or set.
    --           If this name is not yet recorded, the Dictionary creates it.
    --           <isvalued> is returned True if the Item is recorded in the
    --           Dictionary, False else, in that case the Item is reserved and
    --           the name is noted as beeing valued now.
    	raises NoSuchObject  is static;
    --	         Error if no Item could be found or created (this means that
    --	         the Dictionary is corrupted and should be rebuilt)
    ---C++ : return &

    NewItem (me : mutable; name : AsciiString; isvalued : out Boolean;
    	     exact : Boolean = Standard_True)  returns any TheItem
    ---Purpose : Works as above method but accepts a String from TCollection
    	raises NoSuchObject  is static;
    --           Error as above
    ---C++ : return &

    RemoveItem (me : mutable; name : CString;
    	cln : Boolean = Standard_True; exact : Boolean = Standard_True)
    	returns Boolean  is static;
    ---Purpose : Removes a dictionary entry given by its name then Returns True
    --           If the entry does not exists, Does nothing then Returns False
    --           <exact> : as for HasItem, if completion works, the found entry
    --           is removed (else returned value is False)
    --           <cln> commands cleaning dictionary (to recover memory space)
    --           For an isolated call, it is recommanded to give it at True
    --           For a sequence of calls, rather give False, then call Clean

    RemoveItem (me : mutable; name : AsciiString;
    	cln : Boolean = Standard_True; exact : Boolean = Standard_True)
    	returns Boolean  is static;
    ---Purpose : Works as above method but accepts a String from TCollection

    Clean (me : mutable)  is static;
    ---Purpose : Deletes physically in one step the entries which were removed
    --           (can be used for a more efficient Memory Management : first
    --           Remove several Items (<cln> = False), then Clean the Memory)


    IsEmpty (me) returns Boolean  is static;
    ---Purpose : Returns True if no Item is recorded

    Clear (me : mutable)  is static;
    ---Purpose : Clears all the Dictionary : all recorded Items are removed

    Copy (me) returns mutable Dictionary  is static;
    ---Purpose : Copies the Dictionary as a Tree, without Copying the Items

    	-- --    Internal methods    -- --
    
    HasSub (me) returns Boolean  is static private;
    ---Purpose : Returns True if this cell has a subcell

    Sub (me) returns mutable Dictionary  is static private;
    ---Purpose : Returns subcell

    HasNext (me) returns Boolean  is static private;    
    ---Purpose : Returns True if this cell has a next cell

    Next (me) returns mutable Dictionary  is static private;
    ---Purpose : Returns next cell
    
    SetSub  (me : mutable; acell : mutable Dictionary)  is static private;
    ---Purpose : Defines subcell

    SetNext (me : mutable; acell : mutable Dictionary)  is static private;
    ---Purpose : Defines next cell

    SearchCell (me; name : CString; lmax : Integer;
    	        car : Character; level : Integer;
    	    	acell : out mutable Dictionary; reslev : out Integer;
    	        stat : out Integer)  is static private;
    ---Purpose : Internal method used to get an entry from a given name

    NewCell (me : mutable; name : CString; namlen : Integer;
    	     acell : in out mutable Dictionary; reslev,stat : Integer)
	     is static private;
    ---Purpose : Internal method used to create a new entry for a name

    Complete (me; acell : out mutable Dictionary) returns Boolean  is static;
    ---Purpose : Internal routine used for completion (returns True if success)

    HasIt (me) returns Boolean  is static private;
    ---Purpose : Returns True if a cell has an associated item value

    It (me) returns any TheItem  is static private;
    ---Purpose : Returns item value associated to a cell
    ---C++ : return const &

    ItAdr (me : mutable) returns any TheItem  is static private;
    ---Purpose : Returns item address associated to a cell
    ---C++ : return &

    SetIt (me : mutable; anitem : any TheItem)  is static private;
    ---Purpose : Binds an item value to a cell

    DeclIt (me : mutable)  is static private;
    ---Purpose : Declares a cell as Valued : used by NewItem (when an Item
    --           is created if it did not exist and is returned)

    RemoveIt (me : mutable)  is static private;
    ---Purpose : Removes item bound to a cell (cancels effect of DeclIt)

    CellChar (me) returns Character  is static private;
    ---Purpose : Returns cell's character as a node feature

    GetCopied (me : mutable; fromcell : Dictionary)  is static private;
    ---Purpose : Performs Copy from an original <fromcell> to <me>
    --           Called by Copy

fields

    thecars : Character[4];
    thesub  : Dictionary;
    thenext : Dictionary;
    theitem : TheItem;

friends

    class Iterator

end Dictionary;
Commit	Line	Data
7fd59977	1	-- File: Dictionary.cdl
	2	-- Created: Tue Jul 28 16:06:13 1992
	3	-- Author: Christian CAILLET
	4	-- <cky@phylox>
	5	---Copyright: Matra Datavision 1992
	6
	7
	8	generic class Dictionary from Dico (TheItem as any) inherits TShared
	9
	10	---Purpose : Defines an alphanumeric dictionary in a cellular way,
	11	-- corresponding to an indexed tree.
	12	-- (note that an "entry" is a cell with a value associated,
	13	-- other cells are accessed by dictionary nmanagenent only)
	14	-- For each level, cells follow by "next" chaining.
	15	-- To pass to next level, cells follow by "sub" chaining
	16	--
	17	-- Warning : Because of implementation as a tree of cells, beware about
	18	-- size of TheItem class if it is not identified by Handle) : if
	19	-- this size is big, it can cause problems of memory spending
	20
	21	uses OStream, Integer, Boolean, Character, AsciiString --, Iterator
	22
	23	raises NoSuchObject
	24
	25
	26	-- -- Nested class : Iterator (on Dictionary) -- --
	27
	28	class Iterator
	29
	30	---Purpose : Defines an iterator on a Dictionary
	31	-- Iteration is alphabetic (due to dictionary construction)
	32	-- Each entry is defined by its Name and its item Value
	33	-- Remark : The stack used by the Iterator is able to give
	34	-- complete name by scanning it
	35
	36	uses Boolean, AsciiString -- , StackItem , Dictionary
	37
	38	raises NoSuchObject
	39
	40	is
	41
	42	Create (acell : Dictionary) returns Iterator;
	43	---Purpose : Creates an iterator which will work on all the dictionary
	44
	45	Create (acell : Dictionary; basename : CString) returns Iterator;
	46	---Purpose : Creates an iterator which will consider only entries
	47	-- which name begin by the string given as basename (subpart)
	48
	49	Create (acell : Dictionary; basename : AsciiString) returns Iterator;
	50	---Purpose : Creates an iterator which will consider only entries
	51	-- which name begin by the string given as basename (subpart)
	52	-- Same as above, but basename is String instead of CString
	53
	54	Start (me : in out) is static;
	55	---Purpose : Allows to Start a new Iteration from beginning
	56
	57	More (me : in out) returns Boolean is static;
	58	---Purpose : Returns True if there are more entries to return
	59
	60	Next (me : in out) is static;
	61	---Purpose : Go to the next entry
	62	-- (if there is not, Value will raise an exception)
	63
	64	Value (me) returns any TheItem
65	---Purpose : Returns item value of current entry
66	raises NoSuchObject is static;
67	-- Exception raised if there is no current Item
68	---C++ : return const &
69
70	Name (me) returns AsciiString
71	---Purpose : Returns name of current entry
72	raises NoSuchObject is static;
73	-- Exception raised if there is no current Item
74
75	AppendStack (me : in out; val : Dictionary) is static private;
76	---Purpose : Appends a new value to the Iteration Stack
77
78	fields
79
80	thebase : Dictionary;
81	thename : AsciiString; -- base name (if not empty)
82	thelast : StackItem; -- Iteration Stack
83	thenb : Integer;
84	themore : Boolean; -- More called before Next ?
85	theinit : Boolean; -- current cell processed ?
86	thenext : Boolean; -- unstack -> Next cell to choose
87
88	end Iterator;
89
90
91	private class StackItem inherits TShared
92
93	---Purpose : Defines an Item for the Stack used by the Iterator
94
95	-- uses Dictionary
96
97	is
98
99	Create returns mutable StackItem;
100	---Purpose : Creates a StackItem with no Previous one
101
102	Create (previous : mutable StackItem) returns mutable StackItem;
103	---Purpose : Creates a StackItem with a Previous one
104
105	Previous (me) returns mutable StackItem is static;
106	---Purpose : Returns the Previous Item (is Null if no Previous defined)
107
108	Value (me) returns Dictionary is static;
109	---Purpose : Returns the Dictionary Cell corresponding to an Item
110
111	SetValue (me : mutable; cval : Dictionary) is static;
112	---Purpose : Sets a new Dictionary Cell as Value of an Item
113
114	fields
115
116	thevalue : Dictionary;
117	theprev : StackItem;
118
119	end StackItem;
120
121	is
122
123	-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
124	-- --
125	-- -- Description of Dictionary itself -- --
126	-- --
127	-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
128	-- (methods having a String argument are duplicated String-CString)
129
130	Create returns mutable Dictionary;
131	---Purpose : Creates a Dictionary cell.
132	-- A Dictionary is always created then handled by its first cell
133	-- After creating a Dictionary, user can call methods HasItem,
134	-- Item, SetItem ... (internal cells and entries are also
135	-- defined as objects from the same class)
136	-- Also iteration can be made, by an Iterator on this Dictionary
137
138	SetChar (me : mutable; car : Character) is static private;
139	---Purpose : Defines cell's character (internal use, to build dict. tree)
140
141
142	HasItem (me; name : CString; exact : Boolean = Standard_False)
143	returns Boolean is static;
144	---Purpose : Returns True if an Item is bound to a Name in the Dictionnary
145	-- <exact> : if True, commands exact matching
146	-- if False, accept completion, only if ONE AND ONLY ONE
147	-- Dictionnary Entry has <name> as beginning of its name
148
149	HasItem (me; name : AsciiString; exact : Boolean = Standard_True)
150	returns Boolean is static;
151	---Purpose : Works as above method but accepts a String from TCollection
152
153	Item (me; name : CString; exact : Boolean = Standard_True)
154	returns any TheItem
155	---Purpose : Returns item bound to a name in the Dictionnary
156	-- <exact> : same as for HasItem
157	raises NoSuchObject is static;
158	-- Error if <name> corresponds to no entry
159	---C++ : return const &
160
161	Item (me; name : AsciiString; exact : Boolean = Standard_True)
162	returns any TheItem raises NoSuchObject is static;
163	---Purpose : Works as above method but accepts a String from TCollection
164	---C++ : return const &
165
166
167	GetItem (me; name : CString; anitem : out any TheItem;
168	exact : Boolean = Standard_True)
169	returns Boolean is static;
170	---Purpose : Gathers HasItem and Item, in a less regular but faster way
171	-- If return is True, <anitem> is returned too, else it is not
172	-- <exact> : same as for HasItem
173
174	GetItem (me; name : AsciiString; anitem : out TheItem;
175	exact : Boolean = Standard_True)
176	returns Boolean is static;
177	---Purpose : Works as above method but accepts a String from TCollection
178
179	SetItem (me : mutable; name : CString;
180	anitem : any TheItem; exact : Boolean = Standard_True) is static;
181	---Purpose : Binds an item to a dictionnary entry
182	-- If <name> is already known in the dictionary, its value
183	-- is changed. Else, the dictionary entry is created.
184	-- If <exact> is given False, completion is tried, it is accepted
185	-- If it gives a UNIQUE entry : hence this one will be modified
186	-- Else, new entry is created with the exact name given
187
188	SetItem (me : mutable; name : AsciiString;
189	anitem : any TheItem; exact : Boolean = Standard_True) is static;
190	---Purpose : Works as above method but accepts a String from TCollection
191
192	NewItem (me : mutable; name : CString; isvalued : out Boolean;
193	exact : Boolean = Standard_True) returns any TheItem
194	---Purpose : Returns the Item AS AN ADDRESS which corresponds to a Name,
195	-- in order to be changed or set.
196	-- If this name is not yet recorded, the Dictionary creates it.
197	-- <isvalued> is returned True if the Item is recorded in the
198	-- Dictionary, False else, in that case the Item is reserved and
199	-- the name is noted as beeing valued now.
200	raises NoSuchObject is static;
201	-- Error if no Item could be found or created (this means that
202	-- the Dictionary is corrupted and should be rebuilt)
203	---C++ : return &
204
205	NewItem (me : mutable; name : AsciiString; isvalued : out Boolean;
206	exact : Boolean = Standard_True) returns any TheItem
207	---Purpose : Works as above method but accepts a String from TCollection
208	raises NoSuchObject is static;
209	-- Error as above
210	---C++ : return &
211
212	RemoveItem (me : mutable; name : CString;
213	cln : Boolean = Standard_True; exact : Boolean = Standard_True)
214	returns Boolean is static;
215	---Purpose : Removes a dictionary entry given by its name then Returns True
216	-- If the entry does not exists, Does nothing then Returns False
217	-- <exact> : as for HasItem, if completion works, the found entry
218	-- is removed (else returned value is False)
219	-- <cln> commands cleaning dictionary (to recover memory space)
220	-- For an isolated call, it is recommanded to give it at True
221	-- For a sequence of calls, rather give False, then call Clean
222
223	RemoveItem (me : mutable; name : AsciiString;
224	cln : Boolean = Standard_True; exact : Boolean = Standard_True)
225	returns Boolean is static;
226	---Purpose : Works as above method but accepts a String from TCollection
227
228	Clean (me : mutable) is static;
229	---Purpose : Deletes physically in one step the entries which were removed
230	-- (can be used for a more efficient Memory Management : first
231	-- Remove several Items (<cln> = False), then Clean the Memory)
232
233
234	IsEmpty (me) returns Boolean is static;
235	---Purpose : Returns True if no Item is recorded
236
237	Clear (me : mutable) is static;
238	---Purpose : Clears all the Dictionary : all recorded Items are removed
239
240	Copy (me) returns mutable Dictionary is static;
241	---Purpose : Copies the Dictionary as a Tree, without Copying the Items
242
243	-- -- Internal methods -- --
244
245	HasSub (me) returns Boolean is static private;
246	---Purpose : Returns True if this cell has a subcell
247
248	Sub (me) returns mutable Dictionary is static private;
249	---Purpose : Returns subcell
250
251	HasNext (me) returns Boolean is static private;
252	---Purpose : Returns True if this cell has a next cell
253
254	Next (me) returns mutable Dictionary is static private;
255	---Purpose : Returns next cell
256
257	SetSub (me : mutable; acell : mutable Dictionary) is static private;
258	---Purpose : Defines subcell
259
260	SetNext (me : mutable; acell : mutable Dictionary) is static private;
261	---Purpose : Defines next cell
262
263	SearchCell (me; name : CString; lmax : Integer;
264	car : Character; level : Integer;
265	acell : out mutable Dictionary; reslev : out Integer;
266	stat : out Integer) is static private;
267	---Purpose : Internal method used to get an entry from a given name
268
269	NewCell (me : mutable; name : CString; namlen : Integer;
270	acell : in out mutable Dictionary; reslev,stat : Integer)
271	is static private;
272	---Purpose : Internal method used to create a new entry for a name
273
274	Complete (me; acell : out mutable Dictionary) returns Boolean is static;
275	---Purpose : Internal routine used for completion (returns True if success)
276
277	HasIt (me) returns Boolean is static private;
278	---Purpose : Returns True if a cell has an associated item value
279
280	It (me) returns any TheItem is static private;
281	---Purpose : Returns item value associated to a cell
282	---C++ : return const &
283
284	ItAdr (me : mutable) returns any TheItem is static private;
285	---Purpose : Returns item address associated to a cell
286	---C++ : return &
287
288	SetIt (me : mutable; anitem : any TheItem) is static private;
289	---Purpose : Binds an item value to a cell
290
291	DeclIt (me : mutable) is static private;
292	---Purpose : Declares a cell as Valued : used by NewItem (when an Item
293	-- is created if it did not exist and is returned)
294
295	RemoveIt (me : mutable) is static private;
296	---Purpose : Removes item bound to a cell (cancels effect of DeclIt)
297
298	CellChar (me) returns Character is static private;
299	---Purpose : Returns cell's character as a node feature
300
301	GetCopied (me : mutable; fromcell : Dictionary) is static private;
302	---Purpose : Performs Copy from an original <fromcell> to <me>
303	-- Called by Copy
304
305	fields
306
307	thecars : Character[4];
308	thesub : Dictionary;
309	thenext : Dictionary;
310	theitem : TheItem;
311
312	friends
313
314	class Iterator
315
316	end Dictionary;