0028978: Coding rules - suppress GCC compiler warnings -Warray-bounds within NCollect...
[occt.git] / src / NCollection / NCollection_Array1.hxx
1 // Created on: 2002-04-15
2 // Created by: Alexander Kartomin (akm)
3 // Copyright (c) 2002-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 NCollection_Array1_HeaderFile
17 #define NCollection_Array1_HeaderFile
18
19 #include <Standard_DimensionMismatch.hxx>
20 #include <Standard_OutOfMemory.hxx>
21 #include <Standard_OutOfRange.hxx>
22
23 #include <NCollection_DefineAlloc.hxx>
24 #include <NCollection_StlIterator.hxx>
25
26 // *********************************************** Template for Array1 class
27
28 /**
29 * Purpose:     The class Array1 represents unidimensional arrays 
30 *              of fixed size known at run time. 
31 *              The range of the index is user defined.
32 *              An array1 can be constructed with a "C array".
33 *              This functionality is useful to call methods expecting
34 *              an Array1. It allows to carry the bounds inside the arrays.
35 *              
36 * Examples:    Item tab[100]; //  An example with a C array
37 *              Array1OfItem ttab (tab[0],1,100);
38 *              
39 *              Array1OfItem tttab (ttab(10),10,20); // a slice of ttab
40 *              
41 *              If you want to reindex an array from 1 to Length do :
42 *              
43 *              Array1 tab1(tab(tab.Lower()),1,tab.Length());
44 *                          
45 * Warning:     Programs client of such a class must be independant
46 *              of the range of the first element. Then, a C++ for
47 *              loop must be written like this
48 *              
49 *              for (i = A.Lower(); i <= A.Upper(); i++)
50 *              
51 * Changes:     In  comparison  to  TCollection  the  flag  isAllocated  was
52 *              renamed into myDeletable (alike in  the Array2).  For naming
53 *              compatibility the method IsAllocated remained in class along
54 *              with IsDeletable.
55 */              
56 template <class TheItemType>
57 class NCollection_Array1
58 {
59 public:
60   //! STL-compliant typedef for value type
61   typedef TheItemType value_type;
62
63 public:
64   //! Implementation of the Iterator interface.
65   class Iterator
66   {
67   public:
68
69     //! Empty constructor - for later Init
70     Iterator (void) :
71       myPtrCur (NULL),
72       myPtrEnd (NULL)
73     {
74       //
75     }
76
77     //! Constructor with initialization
78     Iterator (const NCollection_Array1& theArray, Standard_Boolean theToEnd = Standard_False) :
79       myPtrEnd (const_cast<TheItemType*> (&theArray.Last() + 1))
80     {
81       myPtrCur = theToEnd ? myPtrEnd : const_cast<TheItemType*> (&theArray.First());
82     }
83
84     //! Initialisation
85     void Init (const NCollection_Array1& theArray)
86     { 
87       myPtrCur = const_cast<TheItemType*> (&theArray.First());
88       myPtrEnd = const_cast<TheItemType*> (&theArray.Last() + 1);
89     }
90
91     //! Assignment
92     Iterator& operator= (const Iterator& theOther)
93     {
94       myPtrCur = theOther.myPtrCur;
95       myPtrEnd = theOther.myPtrEnd;
96       return *this;
97     }
98
99     //! Check end
100     Standard_Boolean More (void) const
101     { return myPtrCur < myPtrEnd; }
102     
103     //! Increment operator
104     void Next (void)
105     { ++myPtrCur; }
106
107     //! Decrement operator
108     void Previous()
109     { --myPtrCur; }
110
111     //! Offset operator.
112     void Offset (ptrdiff_t theOffset)
113     { myPtrCur += theOffset; }
114
115     //! Difference operator.
116     ptrdiff_t Differ (const Iterator& theOther) const
117     { return myPtrCur - theOther.myPtrCur; }
118
119     //! Constant value access
120     const TheItemType& Value (void) const
121     { return *myPtrCur; }
122
123     //! Variable value access
124     TheItemType& ChangeValue (void) const 
125     { return *myPtrCur; }
126
127     //! Performs comparison of two iterators
128     Standard_Boolean IsEqual (const Iterator& theOther) const
129     { return myPtrCur == theOther.myPtrCur; }
130
131   private:
132     TheItemType* myPtrCur; //!< Pointer to the current element in the array
133     TheItemType* myPtrEnd; //!< Pointer to the past-the-end element in the array
134   }; // End of the nested class Iterator
135
136   //! Shorthand for a regular iterator type.
137   typedef NCollection_StlIterator<std::random_access_iterator_tag, Iterator, TheItemType, false> iterator;
138
139   //! Shorthand for a constant iterator type.
140   typedef NCollection_StlIterator<std::random_access_iterator_tag, Iterator, TheItemType, true> const_iterator;
141
142   //! Returns an iterator pointing to the first element in the array.
143   iterator begin() const { return Iterator (*this, false); }
144
145   //! Returns an iterator referring to the past-the-end element in the array.
146   iterator end() const { return Iterator (*this, true); }
147   
148   //! Returns a const iterator pointing to the first element in the array.
149   const_iterator cbegin() const { return Iterator (*this, false); }
150
151   //! Returns a const iterator referring to the past-the-end element in the array.
152   const_iterator cend() const { return Iterator (*this, true); }
153
154  public:
155   // ---------- PUBLIC METHODS ------------
156
157   //! Empty constructor; should be used with caution.
158   NCollection_Array1()
159   : myLowerBound (1),
160     myUpperBound (0),
161     myDeletable  (Standard_False),
162     myData (NULL)
163   {
164     //
165   }
166
167   //! Constructor
168   NCollection_Array1(const Standard_Integer theLower,
169                      const Standard_Integer theUpper) :
170                 myLowerBound                             (theLower),
171                 myUpperBound                             (theUpper),
172                 myDeletable                              (Standard_True)
173   {
174     Standard_RangeError_Raise_if (theUpper < theLower, "NCollection_Array1::Create");
175     TheItemType* pBegin = new TheItemType[Length()];
176     Standard_OutOfMemory_Raise_if (!pBegin, "NCollection_Array1 : Allocation failed");
177
178     myData = pBegin - theLower;
179   }
180
181   //! Copy constructor 
182   NCollection_Array1 (const NCollection_Array1& theOther) :
183     myLowerBound                                (theOther.Lower()),
184     myUpperBound                                (theOther.Upper()),
185     myDeletable                                 (Standard_True)
186   {
187     TheItemType* pBegin = new TheItemType[Length()];
188     Standard_OutOfMemory_Raise_if (!pBegin, "NCollection_Array1 : Allocation failed");
189     myData = pBegin - myLowerBound;
190
191     *this = theOther;
192   }
193
194   //! Move constructor
195   NCollection_Array1 (NCollection_Array1&& theOther)
196   : myLowerBound (theOther.myLowerBound),
197     myUpperBound (theOther.myUpperBound),
198     myDeletable  (theOther.myDeletable),
199     myData       (theOther.myData)
200   {
201     theOther.myUpperBound = theOther.myLowerBound - 1;
202     theOther.myDeletable  = false;
203     theOther.myData       = NULL;
204   }
205
206   //! C array-based constructor
207   NCollection_Array1 (const TheItemType& theBegin,
208                       const Standard_Integer theLower,
209                       const Standard_Integer theUpper) :
210     myLowerBound                                (theLower),
211     myUpperBound                                (theUpper),
212     myDeletable                                 (Standard_False)
213   {
214     Standard_RangeError_Raise_if (theUpper < theLower, "NCollection_Array1::Create");
215   #if (defined(__GNUC__) && __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6))
216     // gcc emits -Warray-bounds warning when NCollection_Array1 is initialized
217     // from local array with lower index 1 (so that (&theBegin - 1) points out of array bounds).
218     // NCollection_Array1 initializes myData with a shift to avoid this shift within per-element access.
219     // It is undesired changing this logic, and -Warray-bounds is not useful here.
220     #pragma GCC diagnostic push
221     #pragma GCC diagnostic ignored "-Warray-bounds"
222   #endif
223     myData = (TheItemType *) &theBegin - theLower;
224   #if (defined(__GNUC__) && __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6))
225     #pragma GCC diagnostic pop
226   #endif
227   }
228
229   //! Initialise the items with theValue
230   void Init (const TheItemType& theValue) 
231   {
232     TheItemType *pCur = &myData[myLowerBound], *pEnd=&myData[myUpperBound];
233     for(; pCur <= pEnd; pCur++)
234       *pCur = (TheItemType&) theValue;
235   }
236
237   //! Size query
238   Standard_Integer Size (void) const
239   { return Length(); }
240   //! Length query (the same)
241   Standard_Integer Length (void) const
242   { return (myUpperBound-myLowerBound+1); }
243
244   //! Return TRUE if array has zero length.
245   Standard_Boolean IsEmpty() const { return myUpperBound < myLowerBound; }
246
247   //! Lower bound
248   Standard_Integer Lower (void) const
249   { return myLowerBound; }
250   //! Upper bound
251   Standard_Integer Upper (void) const
252   { return myUpperBound; }
253
254   //! myDeletable flag
255   Standard_Boolean IsDeletable (void) const
256   { return myDeletable; }
257
258   //! IsAllocated flag - for naming compatibility
259   Standard_Boolean IsAllocated (void) const
260   { return myDeletable; }
261
262   //! Assignment
263   NCollection_Array1& Assign (const NCollection_Array1& theOther)
264   {
265     if (&theOther == this)
266       return *this;
267
268     Standard_DimensionMismatch_Raise_if (Length() != theOther.Length(), "NCollection_Array1::operator=");
269     if (myData == NULL)
270     {
271       return *this;
272     }
273
274     TheItemType * pMyItem        = &myData[myLowerBound];
275     TheItemType * const pEndItem = &(theOther.myData)[theOther.myUpperBound];
276     TheItemType * pItem          = &(theOther.myData)[theOther.myLowerBound];
277     while (pItem <= pEndItem) * pMyItem ++ = * pItem ++;
278     return *this;
279   }
280
281   //! Move assignment
282   NCollection_Array1& Move (NCollection_Array1&& theOther)
283   {
284     if (&theOther == this)
285     {
286       return *this;
287     }
288
289     if (myDeletable)
290     {
291       delete[] &myData[myLowerBound];
292     }
293     myLowerBound = theOther.myLowerBound;
294     myUpperBound = theOther.myUpperBound;
295     myDeletable  = theOther.myDeletable;
296     myData       = theOther.myData;
297
298     theOther.myUpperBound = theOther.myLowerBound - 1;
299     theOther.myDeletable  = Standard_False;
300     theOther.myData       = NULL;
301     return *this;
302   }
303
304   //! Assignment operator
305   NCollection_Array1& operator= (const NCollection_Array1& theOther)
306   { 
307     return Assign (theOther);
308   }
309
310   //! Move assignment operator.
311   NCollection_Array1& operator= (NCollection_Array1&& theOther)
312   {
313     return Move (std::move (theOther));
314   }
315
316   //! @return first element
317   const TheItemType& First() const
318   {
319     return myData[myLowerBound];
320   }
321
322   //! @return first element
323   TheItemType& ChangeFirst()
324   {
325     return myData[myLowerBound];
326   }
327
328   //! @return last element
329   const TheItemType& Last() const
330   {
331     return myData[myUpperBound];
332   }
333
334   //! @return last element
335   TheItemType& ChangeLast()
336   {
337     return myData[myUpperBound];
338   }
339
340   //! Constant value access
341   const TheItemType& Value (const Standard_Integer theIndex) const
342   {
343     Standard_OutOfRange_Raise_if (theIndex < myLowerBound || theIndex > myUpperBound, "NCollection_Array1::Value");
344     return myData[theIndex];
345   }
346
347   //! operator() - alias to Value
348   const TheItemType& operator() (const Standard_Integer theIndex) const
349   { return Value (theIndex); }
350
351   //! Variable value access
352   TheItemType& ChangeValue (const Standard_Integer theIndex)
353   {
354     Standard_OutOfRange_Raise_if (theIndex < myLowerBound || theIndex > myUpperBound, "NCollection_Array1::ChangeValue");
355     return myData[theIndex];
356   }
357
358   //! operator() - alias to ChangeValue
359   TheItemType& operator() (const Standard_Integer theIndex)
360   { return ChangeValue (theIndex); }
361
362   //! Set value 
363   void SetValue (const Standard_Integer theIndex,
364                  const TheItemType&     theItem)
365   {
366     Standard_OutOfRange_Raise_if (theIndex < myLowerBound || theIndex > myUpperBound, "NCollection_Array1::SetValue");
367     myData[theIndex] = theItem;
368   }
369
370   //! Resizes the array to specified bounds.
371   //! No re-allocation will be done if length of array does not change,
372   //! but existing values will not be discarded if theToCopyData set to FALSE.
373   //! @param theLower new lower bound of array
374   //! @param theUpper new upper bound of array
375   //! @param theToCopyData flag to copy existing data into new array
376   void Resize (const Standard_Integer theLower,
377                const Standard_Integer theUpper,
378                const Standard_Boolean theToCopyData)
379   {
380     Standard_RangeError_Raise_if (theUpper < theLower, "NCollection_Array1::Resize");
381     const Standard_Integer anOldLen   = Length();
382     const Standard_Integer aNewLen    = theUpper - theLower + 1;
383     const Standard_Integer aLowerOld  = myLowerBound;
384
385     TheItemType* aBeginOld = &myData[aLowerOld];
386     myLowerBound = theLower;
387     myUpperBound = theUpper;
388     if (aNewLen == anOldLen)
389     {
390       myData = aBeginOld - theLower;
391       return;
392     }
393
394     if (!theToCopyData && myDeletable)
395     {
396       delete[] aBeginOld;
397     }
398     TheItemType* aBeginNew = new TheItemType[aNewLen];
399     Standard_OutOfMemory_Raise_if (aBeginNew == NULL, "NCollection_Array1 : Allocation failed");
400     myData = aBeginNew - theLower;
401     if (!theToCopyData)
402     {
403       myDeletable = Standard_True;
404       return;
405     }
406
407     const Standard_Integer aLenCopy = Min (anOldLen, aNewLen);
408     for (Standard_Integer anIter = 0; anIter < aLenCopy; ++anIter)
409     {
410       aBeginNew[anIter] = aBeginOld[anIter];
411     }
412     if (myDeletable)
413     {
414       delete[] aBeginOld;
415     }
416     myDeletable = Standard_True;
417   }
418
419   //! Destructor - releases the memory
420   ~NCollection_Array1 (void)
421   { if (myDeletable) delete [] &(myData[myLowerBound]); }
422
423  protected:
424   // ---------- PROTECTED FIELDS -----------
425   Standard_Integer     myLowerBound;
426   Standard_Integer     myUpperBound;
427   Standard_Boolean     myDeletable; //!< Flag showing who allocated the array
428   TheItemType*         myData;      //!< Pointer to '0'th array item
429 };
430
431 #endif