0031939: Coding - correction of spelling errors in comments
[occt.git] / src / IGESData / IGESData_ParamReader.hxx
1 // Created on: 1992-04-06
2 // Created by: Christian CAILLET
3 // Copyright (c) 1992-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
5 //
6 // This file is part of Open CASCADE Technology software library.
7 //
8 // This library is free software; you can redistribute it and/or modify it under
9 // the terms of the GNU Lesser General Public License version 2.1 as published
10 // by the Free Software Foundation, with special exception defined in the file
11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 // distribution for complete text of the license and disclaimer of any warranty.
13 //
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
16
17 #ifndef _IGESData_ParamReader_HeaderFile
18 #define _IGESData_ParamReader_HeaderFile
19
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
23
24 #include <Standard_Integer.hxx>
25 #include <IGESData_ReadStage.hxx>
26 #include <Standard_Boolean.hxx>
27 #include <Interface_ParamType.hxx>
28 #include <Standard_CString.hxx>
29 #include <Standard_Real.hxx>
30 #include <IGESData_Status.hxx>
31 #include <Standard_Type.hxx>
32 #include <TColStd_HArray1OfInteger.hxx>
33 #include <TColStd_HArray1OfReal.hxx>
34 #include <Interface_HArray1OfHAsciiString.hxx>
35 #include <IGESData_HArray1OfIGESEntity.hxx>
36 class Interface_ParamList;
37 class Interface_Check;
38 class Interface_InterfaceError;
39 class IGESData_IGESEntity;
40 class IGESData_IGESReaderData;
41 class IGESData_ParamCursor;
42 class Message_Msg;
43 class gp_XY;
44 class gp_XYZ;
45 class TCollection_HAsciiString;
46 class Interface_EntityList;
47
48
49 //! access to a list of parameters, with management of read stage
50 //! (owned parameters, properties, associativities) and current
51 //! parameter number, read errors (which feed a Check), plus
52 //! convenient facilities to read parameters, in particular :
53 //! - first parameter is ignored (it repeats entity type), hence
54 //! number 1 gives 2nd parameter, etc...
55 //! - lists are not explicit, list-reading methods are provided
56 //! which manage a current param. number
57 //! - interpretation is made as possible (texts, reals, entities ...)
58 //! (in particular, Reading a Real accepts an Integer)
59 class IGESData_ParamReader 
60 {
61 public:
62
63   DEFINE_STANDARD_ALLOC
64
65   
66   //! Prepares a ParamReader, stage "Own", current param = 1
67   //! It considers a part of the list, from <base> (excluded) for
68   //! <nbpar> parameters; <nbpar> = 0 commands to take list length.
69   //! Default is (1 to skip type)
70   Standard_EXPORT IGESData_ParamReader(const Handle(Interface_ParamList)& list, const Handle(Interface_Check)& ach, const Standard_Integer base = 1, const Standard_Integer nbpar = 0, const Standard_Integer num = 0);
71   
72   //! Returns the entity number in the file
73   Standard_EXPORT Standard_Integer EntityNumber() const;
74   
75   //! resets state (stage, current param number, check with no fail)
76   Standard_EXPORT void Clear();
77   
78   //! returns the current parameter number
79   //! This notion is involved by the organisation of an IGES list of
80   //! parameter : it can be ended by two lists (Associativities and
81   //! Properties), which can be empty, or even absent. Hence, it is
82   //! necessary to know, at the end of specific reading, how many
83   //! parameters have been read : the optionnal lists follow
84   Standard_EXPORT Standard_Integer CurrentNumber() const;
85   
86   //! sets current parameter number to a new value
87   //! must be done at end of each step : set on first parameter
88   //! following last read one; is done by some Read... methods
89   //! (must be done directly if these method are not used)
90   //! num greater than NbParams means that following lists are empty
91   //! If current num is not managed, it remains at 1, which probably
92   //! will cause error when successive steps of reading are made
93   Standard_EXPORT void SetCurrentNumber (const Standard_Integer num);
94   
95   //! gives current stage (Own-Props-Assocs-End, begins at Own)
96   Standard_EXPORT IGESData_ReadStage Stage() const;
97   
98   //! passes to next stage (must be linked with setting Current)
99   Standard_EXPORT void NextStage();
100   
101   //! passes directly to the end of reading process
102   Standard_EXPORT void EndAll();
103   
104   //! returns number of parameters (minus the first one)
105   //! following method skip the first parameter (1 gives the 2nd)
106   Standard_EXPORT Standard_Integer NbParams() const;
107   
108   //! returns type of parameter; note that "Ident" or "Sub" cannot
109   //! be encountered, they correspond to "Integer", see also below
110   Standard_EXPORT Interface_ParamType ParamType (const Standard_Integer num) const;
111   
112   //! returns literal value of a parameter, as it was in file
113   Standard_EXPORT Standard_CString ParamValue (const Standard_Integer num) const;
114   
115   //! says if a parameter is defined (not void)
116   //! See also DefinedElseSkip
117   Standard_EXPORT Standard_Boolean IsParamDefined (const Standard_Integer num) const;
118   
119   //! says if a parameter can be regarded as an entity reference
120   //! (see Prepare from IGESReaderData for more explanation)
121   //! Note that such a parameter can seen as be a plain Integer too
122   Standard_EXPORT Standard_Boolean IsParamEntity (const Standard_Integer num) const;
123   
124   //! returns entity number corresponding to a parameter if there is
125   //! otherwise zero (according criterium IsParamEntity)
126   Standard_EXPORT Standard_Integer ParamNumber (const Standard_Integer num) const;
127   
128   //! directly returns entity referenced by a parameter
129   Standard_EXPORT Handle(IGESData_IGESEntity) ParamEntity (const Handle(IGESData_IGESReaderData)& IR, const Standard_Integer num);
130   
131   //! Creates a ParamCursor from the Current Number, to read one
132   //! parameter, and to advance Current Number after reading
133   Standard_EXPORT IGESData_ParamCursor Current() const;
134   
135   //! Creates a ParamCursor from the Current Number, to read a list
136   //! of "nb" items, and to advance Current Number after reading
137   //! By default, each item is made of one parameter
138   //! If size is given, it precises the number of params per item
139   Standard_EXPORT IGESData_ParamCursor CurrentList (const Standard_Integer nb, const Standard_Integer size = 1) const;
140   
141   //! Allows to simply process a parameter which can be defaulted.
142   //! Waits on the Current Number a defined parameter or skips it :
143   //! If the parameter <num> is defined, changes nothing and returns True
144   //! Hence, the next reading with current cursor will concern <num>
145   //! If it is void, advances Current Position by one, and returns False
146   //! The next reading will concern <num+1> (except if <num> = NbParams)
147   //!
148   //! This allows to process Default values as follows (C++) :
149   //! if (PR.DefinedElseSkip()) {
150   //! .. PR.Read... (current parameter);
151   //! } else {
152   //! <current parameter> = default value
153   //! .. nothing else to do with ParamReader
154   //! }
155   //! For Message
156   Standard_EXPORT Standard_Boolean DefinedElseSkip();
157   
158   Standard_EXPORT Standard_Boolean ReadInteger (const IGESData_ParamCursor& PC, Standard_Integer& val);
159   
160   //! Reads an Integer value designated by PC
161   //! The method Current designates the current parameter and
162   //! advances the Current Number by one after reading
163   //! Note that if a count (not 1) is given, it is ignored
164   //! If it is not an Integer, fills Check with a Fail (using mess)
165   //! and returns False
166   Standard_EXPORT Standard_Boolean ReadInteger (const IGESData_ParamCursor& PC, const Standard_CString mess, Standard_Integer& val);
167   
168   Standard_EXPORT Standard_Boolean ReadBoolean (const IGESData_ParamCursor& PC, const Message_Msg& amsg, Standard_Boolean& val, const Standard_Boolean exact = Standard_True);
169   
170   //! Reads a Boolean value from parameter "num"
171   //! A Boolean is given as an Integer value 0 (False) or 1 (True)
172   //! Anyway, an Integer is demanded (else, Check is filled)
173   //! If exact is given True, those precise values are demanded
174   //! Else, Correction is done, as False for 0 or <0, True for >0
175   //! (with a Warning error message, and return is True)
176   //! In case of error (not an Integer, or not 0/1 and exact True),
177   //! Check is filled with a Fail (using mess) and return is False
178   Standard_EXPORT Standard_Boolean ReadBoolean (const IGESData_ParamCursor& PC, const Standard_CString mess, Standard_Boolean& val, const Standard_Boolean exact = Standard_True);
179   
180   Standard_EXPORT Standard_Boolean ReadReal (const IGESData_ParamCursor& PC, Standard_Real& val);
181   
182   //! Reads a Real value from parameter "num"
183   //! An Integer is accepted (Check is filled with a Warning
184   //! message) and causes return to be True (as normal case)
185   //! In other cases, Check is filled with a Fail and return is False
186   Standard_EXPORT Standard_Boolean ReadReal (const IGESData_ParamCursor& PC, const Standard_CString mess, Standard_Real& val);
187   
188   Standard_EXPORT Standard_Boolean ReadXY (const IGESData_ParamCursor& PC, Message_Msg& amsg, gp_XY& val);
189   
190   //! Reads a couple of Real values (X,Y) from parameter "num"
191   //! Integers are accepted (Check is filled with a Warning
192   //! message) and cause return to be True (as normal case)
193   //! In other cases, Check is filled with a Fail and return is False
194   Standard_EXPORT Standard_Boolean ReadXY (const IGESData_ParamCursor& PC, const Standard_CString mess, gp_XY& val);
195   
196   Standard_EXPORT Standard_Boolean ReadXYZ (const IGESData_ParamCursor& PC, Message_Msg& amsg, gp_XYZ& val);
197   
198   //! Reads a triplet of Real values (X,Y,Z) from parameter "num"
199   //! Integers are accepted (Check is filled with a Warning
200   //! message) and cause return to be True (as normal case)
201   //! In other cases, Check is filled with a Fail and return is False
202   //! For Message
203   Standard_EXPORT Standard_Boolean ReadXYZ (const IGESData_ParamCursor& PC, const Standard_CString mess, gp_XYZ& val);
204   
205   Standard_EXPORT Standard_Boolean ReadText (const IGESData_ParamCursor& PC, const Message_Msg& amsg, Handle(TCollection_HAsciiString)& val);
206   
207   //! Reads a Text value from parameter "num", as a String from
208   //! Collection, that is, Hollerith text without leading "nnnH"
209   //! If it is not a String, fills Check with a Fail (using mess)
210   //! and returns False
211   Standard_EXPORT Standard_Boolean ReadText (const IGESData_ParamCursor& PC, const Standard_CString mess, Handle(TCollection_HAsciiString)& val);
212   
213   Standard_EXPORT Standard_Boolean ReadEntity (const Handle(IGESData_IGESReaderData)& IR, const IGESData_ParamCursor& PC, IGESData_Status& aStatus, Handle(IGESData_IGESEntity)& val, const Standard_Boolean canbenul = Standard_False);
214   
215   //! Reads an IGES entity from parameter "num"
216   //! An Entity is known by its reference, which has the form of an
217   //! odd Integer Value (a number in the Directory)
218   //! If <canbenul> is given True, a Reference can also be Null :
219   //! in this case, the result is a Null Handle with no Error
220   //! If <canbenul> is False, a Null Reference causes an Error
221   //! If the parameter cannot refer to an entity (or null), fills
222   //! Check with a Fail (using mess) and returns False
223   Standard_EXPORT Standard_Boolean ReadEntity (const Handle(IGESData_IGESReaderData)& IR, const IGESData_ParamCursor& PC, const Standard_CString mess, Handle(IGESData_IGESEntity)& val, const Standard_Boolean canbenul = Standard_False);
224   
225   Standard_EXPORT Standard_Boolean ReadEntity (const Handle(IGESData_IGESReaderData)& IR, const IGESData_ParamCursor& PC, IGESData_Status& aStatus, const Handle(Standard_Type)& type, Handle(IGESData_IGESEntity)& val, const Standard_Boolean canbenul = Standard_False);
226   
227   //! Safe variant for arbitrary type of argument
228   template <class T> 
229   Standard_Boolean ReadEntity (const Handle(IGESData_IGESReaderData)& IR, const IGESData_ParamCursor& PC, IGESData_Status& aStatus, const Handle(Standard_Type)& type, Handle(T)& val, const Standard_Boolean canbenul = Standard_False)
230   {
231     Handle(IGESData_IGESEntity) aVal = val;
232     Standard_Boolean aRes = ReadEntity (IR, PC, aStatus, type, aVal, canbenul);
233     val = Handle(T)::DownCast(aVal);
234     return aRes && (canbenul || ! val.IsNull());
235   }
236
237   //! Works as ReadEntity without Type, but in addition checks the
238   //! Type of the Entity, which must be "kind of" a given <type>
239   //! Then, gives the same fail cases as ReadEntity without Type,
240   //! plus the case "Incorrect Type"
241   //! (in such a case, returns False and givel <val> = Null)
242   Standard_EXPORT Standard_Boolean ReadEntity (const Handle(IGESData_IGESReaderData)& IR, const IGESData_ParamCursor& PC, const Standard_CString mess, const Handle(Standard_Type)& type, Handle(IGESData_IGESEntity)& val, const Standard_Boolean canbenul = Standard_False);
243   
244   //! Safe variant for arbitrary type of argument
245   template <class T> 
246   Standard_Boolean ReadEntity (const Handle(IGESData_IGESReaderData)& IR, const IGESData_ParamCursor& PC, const Standard_CString mess, const Handle(Standard_Type)& type, Handle(T)& val, const Standard_Boolean canbenul = Standard_False)
247   {
248     Handle(IGESData_IGESEntity) aVal = val;
249     Standard_Boolean aRes = ReadEntity (IR, PC, mess, type, aVal, canbenul);
250     val = Handle(T)::DownCast(aVal);
251     return aRes && (canbenul || ! val.IsNull());
252   }
253
254   Standard_EXPORT Standard_Boolean ReadInts (const IGESData_ParamCursor& PC, const Message_Msg& amsg, Handle(TColStd_HArray1OfInteger)& val, const Standard_Integer index = 1);
255   
256   //! Reads a list of Integer values, defined by PC (with a count of
257   //! parameters). PC can start from Current Number and command it
258   //! to advance after reading (use method CurrentList to do this)
259   //! The list is given as a HArray1, numered from "index"
260   //! If all params are not Integer, Check is filled (using mess)
261   //! and return value is False
262   Standard_EXPORT Standard_Boolean ReadInts (const IGESData_ParamCursor& PC, const Standard_CString mess, Handle(TColStd_HArray1OfInteger)& val, const Standard_Integer index = 1);
263   
264   Standard_EXPORT Standard_Boolean ReadReals (const IGESData_ParamCursor& PC, Message_Msg& amsg, Handle(TColStd_HArray1OfReal)& val, const Standard_Integer index = 1);
265   
266   //! Reads a list of Real values defined by PC
267   //! Same conditions as for ReadInts, for PC and index
268   //! An Integer parameter is accepted, if at least one parameter is
269   //! Integer, Check is filled with a "Warning" message
270   //! If all params are neither Real nor Integer, Check is filled
271   //! (using mess) and return value is False
272   Standard_EXPORT Standard_Boolean ReadReals (const IGESData_ParamCursor& PC, const Standard_CString mess, Handle(TColStd_HArray1OfReal)& val, const Standard_Integer index = 1);
273   
274   Standard_EXPORT Standard_Boolean ReadTexts (const IGESData_ParamCursor& PC, const Message_Msg& amsg, Handle(Interface_HArray1OfHAsciiString)& val, const Standard_Integer index = 1);
275   
276   //! Reads a list of Hollerith Texts, defined by PC
277   //! Texts are read as Hollerith texts without leading "nnnH"
278   //! Same conditions as for ReadInts, for PC and index
279   //! If all params are not Text, Check is filled (using mess)
280   //! and return value is False
281   Standard_EXPORT Standard_Boolean ReadTexts (const IGESData_ParamCursor& PC, const Standard_CString mess, Handle(Interface_HArray1OfHAsciiString)& val, const Standard_Integer index = 1);
282   
283   Standard_EXPORT Standard_Boolean ReadEnts (const Handle(IGESData_IGESReaderData)& IR, const IGESData_ParamCursor& PC, const Message_Msg& amsg, Handle(IGESData_HArray1OfIGESEntity)& val, const Standard_Integer index = 1);
284   
285   //! Reads a list of Entities defined by PC
286   //! Same conditions as for ReadInts, for PC and index
287   //! The list is given as a HArray1, numered from "index"
288   //! If all params cannot be read as Entities, Check is filled
289   //! (using mess) and return value is False
290   //! Remark : Null references are accepted, they are ignored
291   //! (negative pointers too : they provoke a Warning message)
292   //! If the caller wants to check them, a loop on ReadEntity should
293   //! be used
294   Standard_EXPORT Standard_Boolean ReadEnts (const Handle(IGESData_IGESReaderData)& IR, const IGESData_ParamCursor& PC, const Standard_CString mess, Handle(IGESData_HArray1OfIGESEntity)& val, const Standard_Integer index = 1);
295   
296   Standard_EXPORT Standard_Boolean ReadEntList (const Handle(IGESData_IGESReaderData)& IR, const IGESData_ParamCursor& PC, Message_Msg& amsg, Interface_EntityList& val, const Standard_Boolean ord = Standard_True);
297   
298   //! Reads a list of Entities defined by PC
299   //! Same conditions as for ReadEnts, for PC
300   //! The list is given as an EntityList
301   //! (index has no meaning; the EntityList starts from clear)
302   //! If "ord" is given True (default), entities will be added to
303   //! the list in their original order
304   //! Remark : Negative or Null Pointers are ignored
305   //! Else ("ord" False), order is not garanteed (faster mode)
306   //! If all params cannot be read as Entities, same as above
307   //! Warning  Give "ord" to False ONLY if order is not significant
308   Standard_EXPORT Standard_Boolean ReadEntList (const Handle(IGESData_IGESReaderData)& IR, const IGESData_ParamCursor& PC, const Standard_CString mess, Interface_EntityList& val, const Standard_Boolean ord = Standard_True);
309   
310   Standard_EXPORT Standard_Boolean ReadingReal (const Standard_Integer num, Standard_Real& val);
311   
312   //! Routine which reads a Real parameter, given its number
313   //! Same conditions as ReadReal for mess, val, and return value
314   Standard_EXPORT Standard_Boolean ReadingReal (const Standard_Integer num, const Standard_CString mess, Standard_Real& val);
315   
316   Standard_EXPORT Standard_Boolean ReadingEntityNumber (const Standard_Integer num, Standard_Integer& val);
317   
318   //! Routine which reads an Entity Number (which allows to read the
319   //! Entity in the IGESReaderData by BoundEntity), given its number
320   //! in the list of Parameters
321   //! Same conditions as ReadEntity for mess, val, and return value
322   //! In particular, returns True and val to zero means Null Entity,
323   //! and val not zero means Entity read by BoundEntity
324   Standard_EXPORT Standard_Boolean ReadingEntityNumber (const Standard_Integer num, const Standard_CString mess, Standard_Integer& val);
325   
326   Standard_EXPORT void SendFail (const Message_Msg& amsg);
327   
328   Standard_EXPORT void SendWarning (const Message_Msg& amsg);
329   
330   Standard_EXPORT void AddFail (const Standard_CString afail, const Standard_CString bfail = "");
331   
332   //! feeds the Check with a new fail (as a String or as a CString)
333   Standard_EXPORT void AddFail (const Handle(TCollection_HAsciiString)& af, const Handle(TCollection_HAsciiString)& bf);
334   
335   Standard_EXPORT void AddWarning (const Standard_CString awarn, const Standard_CString bwarn = "");
336   
337   //! feeds the Check with a new Warning message
338   Standard_EXPORT void AddWarning (const Handle(TCollection_HAsciiString)& aw, const Handle(TCollection_HAsciiString)& bw);
339   
340   Standard_EXPORT void Mend (const Standard_CString pref = "");
341   
342   //! says if fails have been recorded into the Check
343   Standard_EXPORT Standard_Boolean HasFailed() const;
344   
345   //! returns the Check
346   //! Note that any error signaled above is also recorded into it
347   Standard_EXPORT const Handle(Interface_Check)& Check() const;
348   
349   //! returns the check in a way which allows to work on it directly
350   //! (i.e. messages added to the Check are added to ParamReader too)
351   Standard_EXPORT Handle(Interface_Check)& CCheck();
352   
353   //! Returns True if the Check is Empty
354   //! Else, it has to be recorded with the Read Entity
355   Standard_EXPORT Standard_Boolean IsCheckEmpty() const;
356
357
358
359
360 protected:
361
362
363
364
365
366 private:
367
368   
369   Standard_EXPORT Standard_Boolean PrepareRead (const IGESData_ParamCursor& PC, const Standard_Boolean several, const Standard_Integer size = 1);
370   
371   //! Prepares work for Read... methods which call it to begin
372   //! The required count of parameters must not overpass NbParams.
373   //! If several is given False, PC count must be one.
374   //! If size is given, the TermSize from ParmCursor must be a
375   //! multiple count of this size.
376   //! If one of above condition is not satisfied, a Fail Message is
377   //! recorded into Check, using the root "mess" and return is False
378   Standard_EXPORT Standard_Boolean PrepareRead (const IGESData_ParamCursor& PC, const Standard_CString mess, const Standard_Boolean several, const Standard_Integer size = 1);
379   
380   //! Gets the first parameter number to be read, determined from
381   //! ParamCursor data read by PrepareRead (Start + Offset)
382   //! Then commands to skip 1 parameter (default) or nb if given
383   Standard_EXPORT Standard_Integer FirstRead (const Standard_Integer nb = 1);
384   
385   //! Gets the next parameter number to be read. Skips to next Item
386   //! if TermSize has been read.
387   //! Then commands to skip 1 parameter (default) or nb if given
388   Standard_EXPORT Standard_Integer NextRead (const Standard_Integer nb = 1);
389   
390   //! internal method which builds a Fail message from an
391   //! identification "idm" and a diagnostic ("afail")
392   //! Also feeds LastReadStatus
393   //! <af> for final message, bf (can be different) for original
394   Standard_EXPORT void AddFail (const Standard_CString idm, const Handle(TCollection_HAsciiString)& af, const Handle(TCollection_HAsciiString)& bf);
395   
396   //! Same as above but with CString
397   //! <bf> empty means = <af>
398   Standard_EXPORT void AddFail (const Standard_CString idm, const Standard_CString afail, const Standard_CString bfail);
399   
400   //! internal method which builds a Warning message from an
401   //! identification "idm" and a diagnostic
402   //! <aw> is final message, bw is original (can be different)
403   //! Also feeds LastReadStatus
404   Standard_EXPORT void AddWarning (const Standard_CString idm, const Handle(TCollection_HAsciiString)& aw, const Handle(TCollection_HAsciiString)& bw);
405   
406   //! Same as above but with CString
407   //! <bw> empty means = <aw>
408   Standard_EXPORT void AddWarning (const Standard_CString idm, const Standard_CString aw, const Standard_CString bw);
409
410
411   Handle(Interface_ParamList) theparams;
412   Handle(Interface_Check) thecheck;
413   Standard_Integer thebase;
414   Standard_Integer thenbpar;
415   Standard_Integer thecurr;
416   IGESData_ReadStage thestage;
417   Standard_Boolean thelast;
418   Standard_Integer theindex;
419   Standard_Integer thenbitem;
420   Standard_Integer theitemsz;
421   Standard_Integer theoffset;
422   Standard_Integer thetermsz;
423   Standard_Integer themaxind;
424   Standard_Integer thenbterm;
425   Standard_Integer pbrealint;
426   Standard_Integer pbrealform;
427   Standard_Integer thenum;
428
429
430 };
431
432
433
434
435
436
437
438 #endif // _IGESData_ParamReader_HeaderFile