src/Dico/Dico_Dictionary.cdl

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