47b4f807baabb3d3642145f96561e3b95a43873d
[occt.git] / src / TColStd / TColStd_PackedMapOfInteger.hxx
1 // Created on: 2005-11-05
2 // Created by: Alexander GRIGORIEV
3 // Copyright (c) 2005-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 TColStd_PackedMapOfInteger_HeaderFile
17 #define TColStd_PackedMapOfInteger_HeaderFile
18
19 #include <Standard_DefineAlloc.hxx>
20 #include <TCollection_BasicMap.hxx>
21
22 /**
23  * Optimized Map of integer values. Each block of 32 integers is stored in 8 bytes in memory.
24  */
25 class TColStd_PackedMapOfInteger : private TCollection_BasicMap
26 {
27  public:
28   // operators new and delete must be defined explicitly 
29   // since inherited ones are not accessible
30   DEFINE_STANDARD_ALLOC
31   
32  public:
33   // ---------- PUBLIC METHODS ----------
34
35   /// Constructor
36   inline  TColStd_PackedMapOfInteger  (const Standard_Integer NbBuckets = 1)
37     : TCollection_BasicMap (NbBuckets, Standard_True),
38       myExtent             (0) {}
39
40   inline TColStd_PackedMapOfInteger&
41                           operator =  (const TColStd_PackedMapOfInteger& Other) 
42   { return Assign(Other); }
43
44   Standard_EXPORT TColStd_PackedMapOfInteger&
45                           Assign        (const TColStd_PackedMapOfInteger&);
46   Standard_EXPORT  void   ReSize        (const Standard_Integer NbBuckets);
47   Standard_EXPORT  void   Clear         ();
48   ~TColStd_PackedMapOfInteger() { Clear(); }
49   Standard_EXPORT  Standard_Boolean
50                           Add           (const Standard_Integer aKey);
51   Standard_EXPORT  Standard_Boolean
52                           Contains      (const Standard_Integer aKey) const;
53   Standard_EXPORT  Standard_Boolean
54                           Remove        (const Standard_Integer aKey);
55
56   inline Standard_Integer NbBuckets     () const
57   { return TCollection_BasicMap::NbBuckets(); }
58
59   inline Standard_Integer Extent        () const
60   { return Standard_Integer (myExtent); }
61
62   inline Standard_Integer IsEmpty       () const
63   { return TCollection_BasicMap::IsEmpty(); }
64
65   inline void             Statistics    (Standard_OStream& outStream) const
66   { TCollection_BasicMap::Statistics (outStream); }
67
68   /**
69    * Query the minimal contained key value.
70    */
71   Standard_EXPORT Standard_Integer GetMinimalMapped () const;
72
73   /**
74    * Query the maximal contained key value.
75    */
76   Standard_EXPORT Standard_Integer GetMaximalMapped () const;
77
78 public:
79   //!@name Boolean operations with maps as sets of integers
80   //!@{
81
82   /**
83    * Sets this Map to be the result of union (aka addition, fuse, merge, boolean OR) operation between two given Maps.
84    * The new Map contains the values that are contained either in the first map or in the second map or in both.
85    * All previous contents of this Map is cleared. This map (result of the boolean operation) can also be passed as one of operands.
86    */
87   Standard_EXPORT void Union (const TColStd_PackedMapOfInteger&,
88                               const TColStd_PackedMapOfInteger&);
89
90   /**
91    * Apply to this Map the boolean operation union (aka addition, fuse, merge, boolean OR) with another (given) Map.
92    * The result contains the values that were previously contained in this map or contained in the given (operand) map.
93    * This algorithm is similar to method Union().
94    * @return True if content of this map is changed
95    */
96   Standard_EXPORT Standard_Boolean Unite (const TColStd_PackedMapOfInteger&);
97
98   /**
99    * Overloaded operator version of Unite().
100    */
101   TColStd_PackedMapOfInteger& operator |= (const TColStd_PackedMapOfInteger& MM)
102   { Unite(MM); return *this; }
103
104   /**
105    * Sets this Map to be the result of intersection (aka multiplication, common, boolean AND) operation between two given Maps.
106    * The new Map contains only the values that are contained in both map operands.
107    * All previous contents of this Map is cleared. This same map (result of the boolean operation) can also be used as one of operands.
108    * The order of operands makes no difference; the method minimizes internally the number of iterations using the smallest map for the loop.
109    */
110   Standard_EXPORT void Intersection (const TColStd_PackedMapOfInteger&,
111                                      const TColStd_PackedMapOfInteger&);
112
113   /**
114    * Apply to this Map the intersection operation (aka multiplication, common,  boolean AND) with another (given) Map.
115    * The result contains only the values that are contained in both this and the given maps.
116    * This algorithm is similar to method Intersection().
117    * @return True if content of this map is changed
118    */
119   Standard_EXPORT Standard_Boolean Intersect (const TColStd_PackedMapOfInteger&);
120
121   /**
122    * Overloaded operator version of Intersect().
123    */
124   TColStd_PackedMapOfInteger& operator &= (const TColStd_PackedMapOfInteger& MM)
125   { Intersect(MM); return *this; }
126
127   /**
128    * Sets this Map to be the result of subtraction
129    * (aka set-theoretic difference, relative complement, exclude, cut, boolean NOT) operation between two given Maps.
130    * The new Map contains only the values that are contained in the first map operands and not contained in the second one.
131    * All previous contents of this Map is cleared.
132    * This map (result of the boolean operation) can also be used as the first operand.
133    */
134   Standard_EXPORT void Subtraction (const TColStd_PackedMapOfInteger&,
135                                     const TColStd_PackedMapOfInteger&);
136
137   /**
138    * Apply to this Map the subtraction (aka set-theoretic difference, relative complement, exclude, cut, boolean NOT) operation with another (given) Map.
139    * The result contains only the values that were previously contained in this map and not contained in this map.
140    * This algorithm is similar to method Subtract() with two operands.
141    * @return True if contents of this map is changed
142    */
143   Standard_EXPORT Standard_Boolean Subtract (const TColStd_PackedMapOfInteger&);
144
145   /**
146    * Overloaded operator version of Subtract().
147    */
148   TColStd_PackedMapOfInteger& operator -= (const TColStd_PackedMapOfInteger& MM)
149   { Subtract(MM); return *this; }
150
151   /**
152    * Sets this Map to be the result of symmetric difference (aka exclusive disjunction, boolean XOR) operation between two given Maps.
153    * The new Map contains the values that are contained only in the first or the second operand maps but not in both.
154    * All previous contents of this Map is cleared.
155    * This map (result of the boolean operation) can also be used as one of operands.
156    */
157   Standard_EXPORT void Difference (const TColStd_PackedMapOfInteger&,
158                                    const TColStd_PackedMapOfInteger&);
159
160   /**
161    * Apply to this Map the symmetric difference (aka exclusive disjunction, boolean XOR) operation with another (given) Map.
162    * The result contains the values that are contained only in this or the operand map, but not in both.
163    * This algorithm is similar to method Difference().
164    * @return True if contents of this map is changed
165    */
166   Standard_EXPORT Standard_Boolean Differ (const TColStd_PackedMapOfInteger&);
167
168   /**
169    * Overloaded operator version of Differ().
170    */
171   TColStd_PackedMapOfInteger& operator ^= (const TColStd_PackedMapOfInteger& MM)
172   { Differ(MM); return *this; }
173
174   /**
175    * Returns True if this map is equal to the given one, i.e. they contain the
176    * same sets of elements
177    */
178   Standard_EXPORT Standard_Boolean IsEqual (const TColStd_PackedMapOfInteger&) const;
179
180   /**
181    * Overloaded operator version of IsEqual().
182    */
183   Standard_Boolean operator == (const TColStd_PackedMapOfInteger& MM) const
184   { return IsEqual(MM); }
185
186   /**
187    * Returns True if this map is subset of the given one, i.e. all elements 
188    * contained in this map is contained also in the operand map.
189    * if this map is empty that this method returns true for any operand map.
190    */
191   Standard_EXPORT Standard_Boolean IsSubset (const TColStd_PackedMapOfInteger&) const;
192
193   /**
194    * Overloaded operator version of IsSubset().
195    */
196   Standard_Boolean operator <= (const TColStd_PackedMapOfInteger& MM) const
197   { return IsSubset(MM); }
198
199   /**
200    * Returns True if this map has common items with the given one.
201    */
202   Standard_EXPORT Standard_Boolean HasIntersection (const TColStd_PackedMapOfInteger&) const;
203
204   //!@}
205   
206  protected:
207   // ---------- PROTECTED METHODS ----------
208   inline Standard_Integer InternalExtent () const
209   { return TCollection_BasicMap::Extent(); }
210
211
212  private:
213   // ----------- PRIVATE (PROHIBITED) methods
214   /// Copy constructor - prohibited.
215   TColStd_PackedMapOfInteger (const TColStd_PackedMapOfInteger& theOther);
216
217
218   // ---------- PRIVATE FIELDS ----------
219
220   size_t                myExtent;
221
222   friend class TColStd_MapIteratorOfPackedMapOfInteger;
223 };
224
225 #endif