0026377: Passing Handle objects as arguments to functions as non-const reference...
[occt.git] / src / XSControl / XSControl_Utils.hxx
1 // Created on: 1995-12-04
2 // Created by: Christian CAILLET
3 // Copyright (c) 1995-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 _XSControl_Utils_HeaderFile
18 #define _XSControl_Utils_HeaderFile
19
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
23
24 #include <Standard_CString.hxx>
25 #include <Standard_Boolean.hxx>
26 #include <Standard_Type.hxx>
27 #include <Standard_Integer.hxx>
28 #include <TColStd_HSequenceOfTransient.hxx>
29 #include <Standard_ExtString.hxx>
30 #include <TColStd_HSequenceOfHAsciiString.hxx>
31 #include <TColStd_HSequenceOfHExtendedString.hxx>
32 #include <TopTools_HSequenceOfShape.hxx>
33 #include <TopAbs_ShapeEnum.hxx>
34 #include <TColStd_HSequenceOfInteger.hxx>
35 class Standard_TypeMismatch;
36 class Standard_Transient;
37 class TCollection_HAsciiString;
38 class TCollection_AsciiString;
39 class TCollection_HExtendedString;
40 class TCollection_ExtendedString;
41 class TopoDS_Shape;
42
43
44 //! This class provides various useful utility routines, to
45 //! facilitate handling of most common data structures :
46 //! transients (type, type name ...),
47 //! strings (ascii or extended, pointed or handled or ...),
48 //! shapes (reading, writing, testing ...),
49 //! sequences & arrays (of strings, of transients, of shapes ...),
50 //! ...
51 //!
52 //! Also it gives some helps on some data structures from XSTEP,
53 //! such as printing on standard trace file, recignizing most
54 //! currently used auxiliary types (Binder,Mapper ...)
55 class XSControl_Utils 
56 {
57 public:
58
59   DEFINE_STANDARD_ALLOC
60
61   
62   //! the only use of this, is to allow a frontal to get one
63   //! distinct "Utils" set per separate engine
64   Standard_EXPORT XSControl_Utils();
65   
66   //! Just prints a line into the current Trace File. This allows to
67   //! better characterise the various trace outputs, as desired.
68   Standard_EXPORT void TraceLine (const Standard_CString line) const;
69   
70   //! Just prints a line or a set of lines into the current Trace
71   //! File. <lines> can be a HAscii/ExtendedString (produces a print
72   //! without ending line) or a HSequence or HArray1 Of ..
73   //! (one new line per item)
74   Standard_EXPORT void TraceLines (const Handle(Standard_Transient)& lines) const;
75   
76   Standard_EXPORT Standard_Boolean IsKind (const Handle(Standard_Transient)& item, const Handle(Standard_Type)& what) const;
77   
78   //! Returns the name of the dynamic type of an object, i.e. :
79   //! If it is a Type, its Name
80   //! If it is a object not a type, the Name of its DynamicType
81   //! If it is Null, an empty string
82   //! If <nopk> is False (D), gives complete name
83   //! If <nopk> is True, returns class name without package
84   Standard_EXPORT Standard_CString TypeName (const Handle(Standard_Transient)& item, const Standard_Boolean nopk = Standard_False) const;
85   
86   Standard_EXPORT Handle(Standard_Transient) TraValue (const Handle(Standard_Transient)& list, const Standard_Integer num) const;
87   
88   Standard_EXPORT Handle(TColStd_HSequenceOfTransient) NewSeqTra() const;
89   
90   Standard_EXPORT void AppendTra (const Handle(TColStd_HSequenceOfTransient)& seqval, const Handle(Standard_Transient)& traval) const;
91   
92   Standard_EXPORT Standard_CString DateString (const Standard_Integer yy, const Standard_Integer mm, const Standard_Integer dd, const Standard_Integer hh, const Standard_Integer mn, const Standard_Integer ss) const;
93   
94   Standard_EXPORT void DateValues (const Standard_CString text, Standard_Integer& yy, Standard_Integer& mm, Standard_Integer& dd, Standard_Integer& hh, Standard_Integer& mn, Standard_Integer& ss) const;
95   
96   Standard_EXPORT Standard_CString ToCString (const Handle(TCollection_HAsciiString)& strval) const;
97   
98   Standard_EXPORT Standard_CString ToCString (const TCollection_AsciiString& strval) const;
99   
100   Standard_EXPORT Handle(TCollection_HAsciiString) ToHString (const Standard_CString strcon) const;
101   
102   Standard_EXPORT TCollection_AsciiString ToAString (const Standard_CString strcon) const;
103   
104   Standard_EXPORT Standard_ExtString ToEString (const Handle(TCollection_HExtendedString)& strval) const;
105   
106   Standard_EXPORT Standard_ExtString ToEString (const TCollection_ExtendedString& strval) const;
107   
108   Standard_EXPORT Handle(TCollection_HExtendedString) ToHString (const Standard_ExtString strcon) const;
109   
110   Standard_EXPORT TCollection_ExtendedString ToXString (const Standard_ExtString strcon) const;
111   
112   Standard_EXPORT Standard_ExtString AsciiToExtended (const Standard_CString str) const;
113   
114   Standard_EXPORT Standard_Boolean IsAscii (const Standard_ExtString str) const;
115   
116   Standard_EXPORT Standard_CString ExtendedToAscii (const Standard_ExtString str) const;
117   
118   Standard_EXPORT Standard_CString CStrValue (const Handle(Standard_Transient)& list, const Standard_Integer num) const;
119   
120   Standard_EXPORT Standard_ExtString EStrValue (const Handle(Standard_Transient)& list, const Standard_Integer num) const;
121   
122   Standard_EXPORT Handle(TColStd_HSequenceOfHAsciiString) NewSeqCStr() const;
123   
124   Standard_EXPORT void AppendCStr (const Handle(TColStd_HSequenceOfHAsciiString)& seqval, const Standard_CString strval) const;
125   
126   Standard_EXPORT Handle(TColStd_HSequenceOfHExtendedString) NewSeqEStr() const;
127   
128   Standard_EXPORT void AppendEStr (const Handle(TColStd_HSequenceOfHExtendedString)& seqval, const Standard_ExtString strval) const;
129   
130   //! Writes a Shape under the internal BRepTools form
131   //! (an internal help utility)
132   //! Returns True if writing has succeeded, False else
133   Standard_EXPORT Standard_Boolean WriteShape (const TopoDS_Shape& shape, const Standard_CString filename) const;
134   
135   //! Returns a new empty, undefined Shape, which can then be filled
136   //! by ReadShape
137   Standard_EXPORT TopoDS_Shape NewShape() const;
138   
139   //! Reads a Shape from the internal BRepTools form and returns it
140   //! (an internal help utility)
141   //! Returns True if reading has succeeded, False else
142   Standard_EXPORT Standard_Boolean ReadShape (TopoDS_Shape& shape, const Standard_CString filename) const;
143   
144   //! Returns True if a Shape is Null
145   Standard_EXPORT Standard_Boolean IsNullShape (const TopoDS_Shape& shape) const;
146   
147   //! Converts a list of Shapes to a Compound (a kind of Shape)
148   Standard_EXPORT TopoDS_Shape CompoundFromSeq (const Handle(TopTools_HSequenceOfShape)& seqval) const;
149   
150   //! Returns the type of a Shape : true type if <compound> is False
151   //! If <compound> is True and <shape> is a Compound, iterates on
152   //! its items. If all are of the same type, returns this type.
153   //! Else, returns COMPOUND. If it is empty, returns SHAPE
154   //! For a Null Shape, returns SHAPE
155   Standard_EXPORT TopAbs_ShapeEnum ShapeType (const TopoDS_Shape& shape, const Standard_Boolean compound) const;
156   
157   //! From a Shape, builds a Compound as follows :
158   //! explores it level by level
159   //! If <explore> is False, only COMPOUND items. Else, all items
160   //! Adds to the result, shapes which comply to <type>
161   //! + if <type> is WIRE, considers free edges (and makes wires)
162   //! + if <type> is SHELL, considers free faces (and makes shells)
163   //! If <compound> is True, gathers items in compounds which
164   //! correspond to starting COMPOUND,SOLID or SHELL containers, or
165   //! items directly contained in a Compound
166   Standard_EXPORT TopoDS_Shape SortedCompound (const TopoDS_Shape& shape, const TopAbs_ShapeEnum type, const Standard_Boolean explore, const Standard_Boolean compound) const;
167   
168   Standard_EXPORT TopoDS_Shape ShapeValue (const Handle(TopTools_HSequenceOfShape)& seqv, const Standard_Integer num) const;
169   
170   Standard_EXPORT Handle(TopTools_HSequenceOfShape) NewSeqShape() const;
171   
172   Standard_EXPORT void AppendShape (const Handle(TopTools_HSequenceOfShape)& seqv, const TopoDS_Shape& shape) const;
173   
174   //! Creates a Transient Object from a Shape : it is either a Binder
175   //! (used by functions which require a Transient but can process
176   //! a Shape, such as viewing functions) or a HShape (according to hs)
177   //! Default is a HShape
178   Standard_EXPORT Handle(Standard_Transient) ShapeBinder (const TopoDS_Shape& shape, const Standard_Boolean hs = Standard_True) const;
179   
180   //! From a Transient, returns a Shape.
181   //! In fact, recognizes ShapeBinder ShapeMapper and HShape
182   Standard_EXPORT TopoDS_Shape BinderShape (const Handle(Standard_Transient)& tr) const;
183   
184   Standard_EXPORT Standard_Integer SeqLength (const Handle(Standard_Transient)& list) const;
185   
186   Standard_EXPORT Handle(Standard_Transient) SeqToArr (const Handle(Standard_Transient)& seq, const Standard_Integer first = 1) const;
187   
188   Standard_EXPORT Handle(Standard_Transient) ArrToSeq (const Handle(Standard_Transient)& arr) const;
189   
190   Standard_EXPORT Standard_Integer SeqIntValue (const Handle(TColStd_HSequenceOfInteger)& list, const Standard_Integer num) const;
191
192
193
194
195 protected:
196
197
198
199
200
201 private:
202
203
204
205
206
207 };
208
209
210
211
212
213
214
215 #endif // _XSControl_Utils_HeaderFile