0031313: Foundation Classes - Dump improvement for classes
[occt.git] / src / TDataStd / TDataStd_NamedData.hxx
1 // Created on: 2007-05-29
2 // Created by: Vlad Romashko
3 // Copyright (c) 2007-2014 OPEN CASCADE SAS
4 //
5 // This file is part of Open CASCADE Technology software library.
6 //
7 // This library is free software; you can redistribute it and/or modify it under
8 // the terms of the GNU Lesser General Public License version 2.1 as published
9 // by the Free Software Foundation, with special exception defined in the file
10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11 // distribution for complete text of the license and disclaimer of any warranty.
12 //
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
15
16 #ifndef _TDataStd_NamedData_HeaderFile
17 #define _TDataStd_NamedData_HeaderFile
18
19 #include <TDF_Attribute.hxx>
20 #include <TColStd_DataMapOfStringInteger.hxx>
21 #include <TColStd_HArray1OfInteger.hxx>
22 #include <TColStd_HArray1OfReal.hxx>
23 #include <TDataStd_DataMapOfStringReal.hxx>
24 #include <TDataStd_DataMapOfStringString.hxx>
25 #include <TDataStd_DataMapOfStringByte.hxx>
26 #include <TDataStd_DataMapOfStringHArray1OfInteger.hxx>
27 #include <TDataStd_DataMapOfStringHArray1OfReal.hxx>
28
29 class TDataStd_HDataMapOfStringInteger;
30 class TDataStd_HDataMapOfStringReal;
31 class TDataStd_HDataMapOfStringString;
32 class TDataStd_HDataMapOfStringByte;
33 class TDataStd_HDataMapOfStringHArray1OfInteger;
34 class TDataStd_HDataMapOfStringHArray1OfReal;
35 class TCollection_ExtendedString;
36
37 class TDataStd_NamedData;
38 DEFINE_STANDARD_HANDLE(TDataStd_NamedData, TDF_Attribute)
39
40 //! Contains a named data.
41 class TDataStd_NamedData : public TDF_Attribute
42 {
43 public:
44
45   //! Returns the ID of the named data attribute.
46   Standard_EXPORT static const Standard_GUID& GetID();
47   
48   //! Finds or creates a named data attribute.
49   Standard_EXPORT static Handle(TDataStd_NamedData) Set (const TDF_Label& label);
50
51 public:
52
53   //! Empty constructor.
54   Standard_EXPORT TDataStd_NamedData();
55   
56   //! Returns true if at least one named integer value is kept in the attribute.
57   Standard_Boolean HasIntegers() const { return !myIntegers.IsNull(); }
58
59   //! Returns true if the attribute contains specified by Name
60   //! integer value.
61   Standard_EXPORT Standard_Boolean HasInteger (const TCollection_ExtendedString& theName) const;
62   
63   //! Returns the integer value specified by the Name.
64   //! It returns 0 if internal map doesn't contain the specified
65   //! integer (use HasInteger() to check before).
66   Standard_EXPORT Standard_Integer GetInteger (const TCollection_ExtendedString& theName);
67   
68   //! Defines a named integer.
69   //! If the integer already exists, it changes its value to <theInteger>.
70   Standard_EXPORT void SetInteger (const TCollection_ExtendedString& theName, const Standard_Integer theInteger);
71   
72   //! Returns the internal container of named integers.
73   Standard_EXPORT const TColStd_DataMapOfStringInteger& GetIntegersContainer();
74   
75   //! Replace the container content by new content of the <theIntegers>.
76   Standard_EXPORT void ChangeIntegers (const TColStd_DataMapOfStringInteger& theIntegers);
77
78   //! Returns true if at least one named real value is kept in the attribute.
79   Standard_Boolean HasReals() const { return !myReals.IsNull(); }
80
81   //! Returns true if the attribute contains a real specified by Name.
82   Standard_EXPORT Standard_Boolean HasReal (const TCollection_ExtendedString& theName) const;
83   
84   //! Returns the named real.
85   //! It returns 0.0 if there is no such a named real
86   //! (use HasReal()).
87   Standard_EXPORT Standard_Real GetReal (const TCollection_ExtendedString& theName);
88   
89   //! Defines a named real.
90   //! If the real already exists, it changes its value to <theReal>.
91   Standard_EXPORT void SetReal (const TCollection_ExtendedString& theName, const Standard_Real theReal);
92   
93   //! Returns the internal container of named reals.
94   Standard_EXPORT const TDataStd_DataMapOfStringReal& GetRealsContainer();
95   
96   //! Replace the container content by new content of the <theReals>.
97   Standard_EXPORT void ChangeReals (const TDataStd_DataMapOfStringReal& theReals);
98   
99   //! Returns true if there are some named strings in the attribute.
100   Standard_Boolean HasStrings() const { return !myStrings.IsNull(); }
101
102   //! Returns true if the attribute contains this named string.
103   Standard_EXPORT Standard_Boolean HasString (const TCollection_ExtendedString& theName) const;
104   
105   //! Returns the named string.
106   //! It returns an empty string if there is no such a named string
107   //! (use HasString()).
108   Standard_EXPORT const TCollection_ExtendedString& GetString (const TCollection_ExtendedString& theName);
109   
110   //! Defines a named string.
111   //! If the string already exists, it changes its value to <theString>.
112   Standard_EXPORT void SetString (const TCollection_ExtendedString& theName, const TCollection_ExtendedString& theString);
113   
114   //! Returns the internal container of named strings.
115   Standard_EXPORT const TDataStd_DataMapOfStringString& GetStringsContainer();
116   
117   //! Replace the container content by new content of the <theStrings>.
118   Standard_EXPORT void ChangeStrings (const TDataStd_DataMapOfStringString& theStrings);
119   
120   //! Returns true if there are some named bytes in the attribute.
121   Standard_Boolean HasBytes() const { return !myBytes.IsNull(); }
122
123   //! Returns true if the attribute contains this named byte.
124   Standard_EXPORT Standard_Boolean HasByte (const TCollection_ExtendedString& theName) const;
125   
126   //! Returns the named byte.
127   //! It returns 0 if there is no such a named byte
128   //! (use HasByte()).
129   Standard_EXPORT Standard_Byte GetByte (const TCollection_ExtendedString& theName);
130   
131   //! Defines a named byte.
132   //! If the byte already exists, it changes its value to <theByte>.
133   Standard_EXPORT void SetByte (const TCollection_ExtendedString& theName, const Standard_Byte theByte);
134   
135   //! Returns the internal container of named bytes.
136   Standard_EXPORT const TDataStd_DataMapOfStringByte& GetBytesContainer();
137   
138   //! Replace the container content by new content of the <theBytes>.
139   Standard_EXPORT void ChangeBytes (const TDataStd_DataMapOfStringByte& theBytes);
140   
141   //! Returns true if there are some named arrays of integer values in the attribute.
142   Standard_Boolean HasArraysOfIntegers() const { return !myArraysOfIntegers.IsNull(); }
143
144   //! Returns true if the attribute contains this named array of integer values.
145   Standard_EXPORT Standard_Boolean HasArrayOfIntegers (const TCollection_ExtendedString& theName) const;
146   
147   //! Returns the named array of integer values.
148   //! It returns a NULL Handle if there is no such a named array of integers
149   //! (use HasArrayOfIntegers()).
150   Standard_EXPORT const Handle(TColStd_HArray1OfInteger)& GetArrayOfIntegers (const TCollection_ExtendedString& theName);
151
152   //! Defines a named array of integer values.
153   //! @param theName [in] key
154   //! @param theArrayOfIntegers [in] new value, overrides existing (passed array will be copied by value!)
155   void SetArrayOfIntegers (const TCollection_ExtendedString& theName,
156                            const Handle(TColStd_HArray1OfInteger)& theArrayOfIntegers)
157   {
158     Backup();
159     setArrayOfIntegers (theName, theArrayOfIntegers);
160   }
161
162   //! Returns the internal container of named arrays of integer values.
163   Standard_EXPORT const TDataStd_DataMapOfStringHArray1OfInteger& GetArraysOfIntegersContainer();
164   
165   //! Replace the container content by new content of the <theArraysOfIntegers>.
166   Standard_EXPORT void ChangeArraysOfIntegers (const TDataStd_DataMapOfStringHArray1OfInteger& theArraysOfIntegers);
167   
168   //! Returns true if there are some named arrays of real values in the attribute.
169   Standard_Boolean HasArraysOfReals() const { return !myArraysOfReals.IsNull(); }
170
171   //! Returns true if the attribute contains this named array of real values.
172   Standard_EXPORT Standard_Boolean HasArrayOfReals (const TCollection_ExtendedString& theName) const;
173   
174   //! Returns the named array of real values.
175   //! It returns a NULL Handle if there is no such a named array of reals
176   //! (use HasArrayOfReals()).
177   Standard_EXPORT const Handle(TColStd_HArray1OfReal)& GetArrayOfReals (const TCollection_ExtendedString& theName);
178
179   //! Defines a named array of real values.
180   //! @param theName [in] key
181   //! @param theArrayOfIntegers [in] new value, overrides existing (passed array will be copied by value!)
182   void SetArrayOfReals (const TCollection_ExtendedString& theName,
183                         const Handle(TColStd_HArray1OfReal)& theArrayOfReals)
184   {
185     Backup();
186     setArrayOfReals (theName, theArrayOfReals);
187   }
188
189   //! Returns the internal container of named arrays of real values.
190   Standard_EXPORT const TDataStd_DataMapOfStringHArray1OfReal& GetArraysOfRealsContainer();
191   
192   //! Replace the container content by new content of the <theArraysOfReals>.
193   Standard_EXPORT void ChangeArraysOfReals (const TDataStd_DataMapOfStringHArray1OfReal& theArraysOfReals);
194
195   //! Clear data.
196   void Clear()
197   {
198     Backup();
199     clear();
200   }
201
202 public: //! @name late-load deferred data interface
203
204   //! Returns TRUE if some data is not loaded from deferred storage and can be loaded using LoadDeferredData().
205   //!
206   //! Late-load interface allows to avoid loading auxiliary data into memory until it is needed by application
207   //! and also speed up reader by skipping data chunks in file.
208   //! This feature requires file format having special structure, and usually implies read-only access,
209   //! therefore default implementation will return FALSE here.
210   //!
211   //! Late-load elements require special attention to ensure data consistency,
212   //! as such elements are created in undefined state (no data) and Undo/Redo mechanism will not work until deferred data being loaded.
213   //!
214   //! Usage scenarios:
215   //! - Application displays model in read-only way.
216   //!   Late-load elements are loaded temporarily on demand and immediatly unloaded.
217   //!     theNamedData->LoadDeferredData (true);
218   //!     TCollection_AsciiString aValue = theNamedData->GetString (theKey);
219   //!     theNamedData->UnloadDeferredData();
220   //! - Application saves the model into another format.
221   //!   All late-load elements should be loaded (at least temporary during operation).
222   //! - Application modifies the model.
223   //!   Late-load element should be loaded with removed link to deferred storage,
224   //!   so that Undo()/Redo() will work as expected since loading.
225   //!     theNamedData->LoadDeferredData (false);
226   //!     theNamedData->SetString (theKey, theNewValue);
227   virtual Standard_Boolean HasDeferredData() const { return false; }
228
229   //! Load data from deferred storage, without calling Backup().
230   //! As result, the content of the object will be overidden by data from deferred storage (which is normally read-only).
231   //! @param theToKeepDeferred [in] when TRUE, the link to deferred storage will be preserved
232   //!                               so that it will be possible calling UnloadDeferredData() afterwards for releasing memory
233   //! @return FALSE if deferred storage is unavailable or deferred data has been already loaded
234   virtual Standard_Boolean LoadDeferredData (Standard_Boolean theToKeepDeferred = false)
235   {
236     (void )theToKeepDeferred;
237     return false;
238   }
239
240   //! Releases data if object has connected deferred storage, without calling Backup().
241   //! WARNING! This operation does not unload modifications to deferred storage (normally it is read-only),
242   //! so that modifications will be discarded (if any).
243   //! @return FALSE if object has no deferred data
244   virtual Standard_Boolean UnloadDeferredData() { return false; }
245
246 public:
247
248   //! Clear data without calling Backup().
249   Standard_EXPORT void clear();
250
251   //! Defines a named integer (without calling Backup).
252   Standard_EXPORT void setInteger (const TCollection_ExtendedString& theName,
253                                    const Standard_Integer theInteger);
254
255   //! Defines a named real (without calling Backup).
256   Standard_EXPORT void setReal (const TCollection_ExtendedString& theName,
257                                 const Standard_Real theReal);
258
259   //! Defines a named string (without calling Backup).
260   Standard_EXPORT void setString (const TCollection_ExtendedString& theName,
261                                   const TCollection_ExtendedString& theString);
262
263   //! Defines a named byte (without calling Backup).
264   Standard_EXPORT void setByte (const TCollection_ExtendedString& theName,
265                                 const Standard_Byte theByte);
266
267   //! Defines a named array of integer values (without calling Backup).
268   Standard_EXPORT void setArrayOfIntegers (const TCollection_ExtendedString& theName,
269                                            const Handle(TColStd_HArray1OfInteger)& theArrayOfIntegers);
270
271   //! Defines a named array of real values (without calling Backup).
272   Standard_EXPORT void setArrayOfReals (const TCollection_ExtendedString& theName,
273                                         const Handle(TColStd_HArray1OfReal)& theArrayOfReals);
274
275 public: //! @name TDF_Attribute interface
276
277   Standard_EXPORT virtual const Standard_GUID& ID() const Standard_OVERRIDE;
278
279   Standard_EXPORT virtual void Restore (const Handle(TDF_Attribute)& With) Standard_OVERRIDE;
280
281   Standard_EXPORT virtual Handle(TDF_Attribute) NewEmpty() const Standard_OVERRIDE;
282
283   Standard_EXPORT virtual void Paste (const Handle(TDF_Attribute)& Into, const Handle(TDF_RelocationTable)& RT) const Standard_OVERRIDE;
284
285   Standard_EXPORT virtual Standard_OStream& Dump (Standard_OStream& anOS) const Standard_OVERRIDE;
286   
287   //! Dumps the content of me into the stream
288   Standard_EXPORT virtual void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const Standard_OVERRIDE;
289
290   DEFINE_STANDARD_RTTIEXT(TDataStd_NamedData,TDF_Attribute)
291
292 protected:
293
294   Handle(TDataStd_HDataMapOfStringInteger) myIntegers;
295   Handle(TDataStd_HDataMapOfStringReal) myReals;
296   Handle(TDataStd_HDataMapOfStringString) myStrings;
297   Handle(TDataStd_HDataMapOfStringByte) myBytes;
298   Handle(TDataStd_HDataMapOfStringHArray1OfInteger) myArraysOfIntegers;
299   Handle(TDataStd_HDataMapOfStringHArray1OfReal) myArraysOfReals;
300
301 };
302
303 #endif // _TDataStd_NamedData_HeaderFile