doublear.h

Go to the documentation of this file.

/**
 * \file doublear.h <mi32/doublear.h>
 * \brief Definitions for DOUBLE_ARRAY template
 *
 * \if NODOC
 * $Id: doublear.h_v 1.35 2005/11/11 22:21:00 mju Exp $
 *
 * $Log: doublear.h_v $
 * Revision 1.35  2005/11/11 22:21:00  mju
 * Fix copy() method to specify starting item in call to setItems.
 *
 * Revision 1.34  2004/11/23 18:50:06  dwilliss
 * Fixed allocation size if sizeof(_CT) is not divisible by sizeof(double)
 *
 * Revision 1.33  2004/11/03 22:02:21  scowan
 * Divide the size to allocate by sizeof double sinde mi double array multiplies by sizeof double.
 *
 * Revision 1.32  2004/10/15 16:50:31  scowan
 * Added remove item method.
 *
 * Revision 1.31  2004/09/24 14:23:24  mju
 * Add isEmpty method.
 *
 * Revision 1.30  2004/07/09 14:22:06  mju
 * In append need to multiply by item size when reserve.
 *
 * Revision 1.29  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.28  2003/07/31 14:13:24  mju
 * Include string.h for memset/memcpy.
 *
 * Revision 1.27  2003/07/28 13:41:52  mju
 * Remove deprecated methods.
 *
 * Revision 1.26  2003/07/28 13:12:56  mju
 * Remove 'allocincrement' stuff, when append resize by doubling allocation.
 * Fix deprecated setitems method to not reference firstitem.
 *
 * Revision 1.25  2003/07/25 20:59:15  mju
 * Add Assign(), deprecate old SetItems().
 * Add SetItems variant which does not shrink array.
 *
 * Revision 1.24  2003/04/09 20:14:52  dwilliss
 * Don't use _T in template. Mac's ctype.h defines global _T. Thanks Apple!
 *
 * Revision 1.23  2002/01/02 21:06:14  scowan
 * Fixed GetItems().
 *
 * Revision 1.22  2001/11/06 17:09:05  dwilliss
 * Method TransferOwnerFrom() was trying to access non-existant member.
 * Should have been m_numitems, not numitems
 *
 * Revision 1.21  2001/11/01 16:44:15  mju
 * Add GetItems() method.
 *
 * Revision 1.20  2001/06/20 16:25:12  scowan
 * More errors.
 *
 * Revision 1.19  2001/06/20 15:43:10  scowan
 * Fixed append.
 *
 * Revision 1.18  2001/05/24 17:07:37  scowan
 * Uses new base mi double array class for storage.
 * Now supports Attach and Detach paradigm.
 *
 * Revision 1.17  2001/02/02 20:52:18  scowan
 * Stupid G++ compiler will not let me friend a instantiated template.
 *
 * Revision 1.16  2001/01/29 23:31:39  scowan
 * Attempt to fix UNIX g++ errors.
 *
 * Revision 1.15  2001/01/26 14:51:13  scowan
 * Added new transfer owner from method that is a template.
 *
 * Revision 1.14  2001/01/19 14:57:22  mju
 * Add DeleteItem().
 *
 * Revision 1.13  2001/01/17 17:33:36  mju
 * Add 'addinc' parm to Reserve() and use in Resize().
 *
 * Revision 1.12  2001/01/05 20:59:10  scowan
 * No change.
 *
 * Revision 1.11  2000/12/04 16:31:19  mju
 * Fix genitor 'end ignore' tag.
 *
 * Revision 1.10  2000/11/17 23:02:00  scowan
 * Added transfer method.
 *
 * Revision 1.9  2000/11/02 15:15:59  mju
 * Add ReserveExc/ResizeExc.
 *
 * Revision 1.8  2000/10/13 22:22:26  scowan
 * Added mac array operator overload specific crap.
 *
 * Revision 1.6  2000/08/17 16:12:45  scowan
 * Added unsigned array operators.
 *
 * Revision 1.4  2000/08/03 22:23:10  scowan
 * Added free and updated error reporting.
 *
 * Revision 1.3  2000/08/02 21:43:56  mju
 * Add Resize().
 * Fix methods taking DOUBLE_ARRAY<_CT>& parms.
 * Retire SetNumItems().
 *
 * Revision 1.2  2000/06/22 14:52:34  mju
 * Fix ClearItems to not clear past specified ending item.
 *
 * Revision 1.1  2000/06/21 22:59:40  scowan
 * Initial revision
 *
 * \endif
**/

#ifndef  INC_MI32_DOUBLEAR_H
#define  INC_MI32_DOUBLEAR_H

#ifndef  INC_MI32_MIODEFNS_H
#include <mi32/miodefns.h>    //! For MmAlloc/Realloc/Free defns
#endif

#ifndef  INC_MI32_MEMBUF_H
#include <mi32/membuf.h>      //! For SwapBytes() defn
#endif

#ifndef  INC_STRING_H
#include <string.h>           //! For memset/memcpy
#define  INC_STRING_H
#endif

#ifndef  INC_MI32_MIDBLARY_H
#include <mi32/midblary.h>    //! For MIDOUBLEARRAY defn
#endif

//! Double array template.
//!
//! This template is designed to contain an array of items which can be allocated
//! using MmAlloc/MmRealloc.  The primary purpose of this template is to replace
//! allocated arrays where direct access to both array elements and the ability
//! to access a pointer to the first element (as for a C array) is required.
//!
//! For maximum efficiency, only minimal validation of access to array elements is performed.
//! No initialization of array items is performed by the template.
//!
//! This class is also designed to handle the 4 byte off alignment issue in regards to systems
//! that have a 4 byte allocation granularity.
//!
//! Best if used as DOUBLE_ARRAY<double>, DOUBLE_ARRAY<DPOINT2D>, DOUBLE_ARRAY<DPOINT3D>, 
//! DOUBLE_ARRAY<DRECT2D>, and DOUBLE_ARRAY<DRECT3D>

template <class _CT> class DOUBLE_ARRAY {

   public:

      //! Default constructor.
      DOUBLE_ARRAY (
         ):
         m_data(0),
         m_numitems(0),
         m_spare(0)
         { }

      //! Copy constructor
      DOUBLE_ARRAY (
         const DOUBLE_ARRAY<_CT>& rhs
         ) :
         m_items(rhs.m_items),
         m_numitems(rhs.m_numitems),
         m_spare(0)
         {
         m_data = reinterpret_cast<_CT*>(m_items.GetPointer());
         }

      ~DOUBLE_ARRAY (
         ) {}

      //! Assignment.
      DOUBLE_ARRAY<_CT>& operator= (
         const DOUBLE_ARRAY<_CT>& rhs
         ) {
         if (this != &rhs) {
            m_items = rhs.m_items;
            m_numitems = rhs.m_numitems;
            m_data = reinterpret_cast<_CT*>(m_items.GetPointer());
            }
         return (*this);
         }

      //! Equality operator.
      bool operator== (
         const DOUBLE_ARRAY<_CT>& rhs
         ) const {
         if (m_numitems != rhs.m_numitems) return (false);
         if (m_numitems == 0) return (true);
         return (memcmp(m_data,m_data,m_numitems*sizeof(_CT)) == 0);
         }

      //! Inequality operator.
      bool operator!= (
         const DOUBLE_ARRAY<_CT>& rhs
         ) const {
         return (!operator==(rhs));
         }

      //! Cast to const array of template type.
      operator const _CT*(
         ) const {
         return (m_data);
         }

      //! Cast to array of template type.
      operator _CT*(
         ) {
         return (m_data);
         }

      //! Read (const) access to array element.
      //!
      //! @note Does not verify that index is within valid range.
      const _CT& operator[] (
         int index
         ) const {
         return (m_data[index]);
         }

      //! Write (non-const) access to array element.
      //!
      //! @note Does not verify that index is within valid range.
      _CT& operator[] (
         int index
         ) {
         return (m_data[index]);
         }

      #ifndef GENERATING_DOXYGEN_OUTPUT
      #ifdef MAC_NATIVE
         //! Fixes ambiguity error on Macintosh.
         
         //! Read (const) access to array element.
         //!
         //! @note Does not verify that index is within valid range.
         const _CT& operator[] (
            long index
            ) const {
            return (m_data[index]);
            }

         //! Write (non-const) access to array element.
         //!
         //! @note Does not verify that index is within valid range.
         _CT& operator[] (
            long index
            ) {
            return (m_data[index]);
            }
      #endif
      #endif //!< GENERATING_DOXYGEN_OUTPUT

      //! Append item to end of array, extending if necessary.
      ERRVALUE Append (
         const _CT& item
         ) {
         if (m_numitems >= GetMaxItems()) {
            int err;
            if ((err = m_items.Reserve(MAX(16,2*m_numitems*(sizeof(_CT) / sizeof(double))), true)) < 0) return (err);
            m_data = reinterpret_cast<_CT*>(m_items.GetPointer());
            }
         m_data[m_numitems++] = item;
         return (0);
         }
         
      //! Assign from C array, reserving space if needed.
      //! Resizes the array to the specified number of items.
      ERRVALUE Assign (
         const _CT *items,                //!< Items to copy to array
         int numitems                     //!< Number of items to copy
         ) {
         ERRVALUE err;
         if ((err = Reserve(numitems,true)) < 0) return (err);
         memcpy(m_data,items,numitems*sizeof(_CT));
         m_numitems = numitems;
         return (0);
         }

      //! Attach a buffer to the DOUBLE_ARRAY.
      //! After passing a buffer to Attach(), the DOUBLE_ARRAY "<b>owns</b>" the
      //! buffer and will free it in its destructor.  
      //! @param items Reference to a pointer to the templated data type.
      //! @param numitems The number of items being attached
      //!
      //! The reason it's a reference is that after recording the pointer,
      //! Attach() will set <i>your</i> pointer to 0.  This will prevent you
      //! from accidently freeing a pointer you no longer own.  If you want
      //! it back, call the Detach() method
      void Attach (
         MIDOUBLEARRAY& items,
         int numitems
         ) {
         m_items.Attach(items);
         m_numitems = numitems;
         m_data = reinterpret_cast<_CT*>(m_items.GetPointer());
         return;
         }
         
      //! Clear the array, does not free resources.
      void Clear (
         ) { m_numitems = 0; }

      //! Clear items in the array
      void ClearItems (
         int start = 0,
         int end = -1                  //!< Default -1, use number of items
         ) {
         if (end < start) end = m_numitems - 1;
         memset(m_data + start, 0, (end - start + 1) * sizeof(_CT));
         return;
         }

      //! Copy the contents of another DOUBLE_ARRAY.
      //! Same as assignment, but returns an error code instead of throwing an exception.
      ERRVALUE Copy (
         const DOUBLE_ARRAY<_CT>& rhs
         ) {
         if (this != &rhs) {
            return (SetItems(0, rhs, rhs.m_numitems));
            }
         return (0);
         }

      //! Delete item in the array.
      //! Use with care as this is not efficient for large arrays.
      void DeleteItem (
         int index
         ) {
         if (index >= 0 && index < m_numitems) {
            --m_numitems;
            if (index < m_numitems) {
               memmove(m_data+index,m_data+index+1,(m_numitems-index)*sizeof(_CT));
               }
            }
         return;
         }
         
      //! Detach the buffer from the DOUBLE_ARRAY.
      //!
      //! This turns ownership of the buffer over to the caller, who is then
      //! responsibile for seeing that it gets disposed of.
      //! After calling Detach(), the DOUBLE_ARRAY will behave as if it had
      //! just been constructed.  In other words, it will be a NULL pointer
      //! pointing to 0 items.
      //! This means that if you want to know how many items are in the
      //! array returned, you'd better find out @{before} you call Detach()!
      void Detach (
         MIDOUBLEARRAY& items
         ) {
         items.Attach(m_items);
         m_numitems = 0;
         m_data = 0;
         return;
         }
         
      // See above comment on Attach() for Detach() method bad idea.

      //! Free the array.
      void Free (
         ) {
         m_items.Free();
         m_numitems = 0;
         m_data = 0;
         return;
         }

      //! Get items from array.
      void GetItems (
         _CT *items,                      //!< Buffer to hold items
         int numitems,                    //!< Number of items to copy
         int firstitem = 0                //!< First array item to retrieve
         ) const {
         memcpy(items,m_data+firstitem,MIN(m_numitems-firstitem, numitems)*sizeof(_CT));
         return;
         }

      //! Get maximum number of items in array.
      int GetMaxItems (
         ) const {
         return (m_items.GetNumReserved() / (sizeof(_CT) / sizeof(double)));
         }

      //! Get number of items in array.
      int GetNumItems (
         ) const { return (m_numitems); }

      //! Get size of array required to hold current number of items in bytes.
      int GetSizeInBytes (
         ) const { return (m_numitems*sizeof(_CT)); }

      //! Determine if array is empty.
      bool IsEmpty (
         ) const { return (m_numitems == 0); }

      //! Remove item at specified index, maintaining order.
      //! Note that this is inefficient for large arrays.
      void RemoveItem (
         INT32 item
         ) {
         if (item < m_numitems && item >= 0) {
            --m_numitems;
            if (item < m_numitems) { memmove(&m_data[item], &m_data[item+1], (m_numitems - item) * sizeof(_CT)); }
            }
         return;
         }

      //! Reserve space in array for up to specified number of items.
      ERRVALUE Reserve (
         int newmaxitems,                 //!< New maximum number of items
         bool clear = false,              //!< Clear the array by resetting number of items to 0
         bool addinc = false              //!< Add alloation increment to requested size if actually need to resize
         ) {
         if (clear) m_numitems = 0;
         if (newmaxitems > GetMaxItems()) {
            ERRVALUE err;
            if ((err = m_items.Reserve((newmaxitems * sizeof(_CT) + sizeof(double) - 1) / sizeof(double), true)) < 0) return (err);
            m_data = reinterpret_cast<_CT*>(m_items.GetPointer());
            }
         return (0);
         }

      //! Reserve space in array for up to specified number of items, throw exception on failure.
      void ReserveExc (
         int newmaxitems,                 //!< New maximum number of items
         bool clear = false,              //!< Clear the array by resetting number of items to 0
         bool addinc = false              //!< Add alloation increment to requested size if actually need to resize
         ) {
         if (clear) m_numitems = 0;
         if (newmaxitems > GetMaxItems()) {
            m_items.ReserveExc((newmaxitems * sizeof(_CT) + sizeof(double) - 1) / sizeof(double), true);
            m_data = reinterpret_cast<_CT*>(m_items.GetPointer());
            }
         return;
         }

      //! Resize array to specified number of items.
      //! If the new size is larger than the previous size and the array is
      //! not cleared the new array entries will have indeterminant values.
      ERRVALUE Resize (
         int numitems,                    //!< New number of items desired
         bool keepold = true,             //!< Keep old array entries
         bool clear = false               //!< Clear new entries to zeros, will clear all if keepold is false
         ) {
         int err;
         if ((err = Reserve(numitems,!keepold,true)) < 0) return (err);
         if (clear && numitems > m_numitems) memset(m_data+m_numitems,0,(numitems-m_numitems)*sizeof(_CT));
         m_numitems = numitems;
         return (0);
         }

      //! Resize array to specified number of items, throw exception on failure.
      //! If the new size is larger than the previous size and the array is
      //! not cleared the new array entries will have indeterminant values.
      void ResizeExc (
         int numitems,                    //!< New number of items desired
         bool keepold = true,             //!< Keep old array entries
         bool clear = false               //!< Clear new entries to zeros, will clear all if keepold is false
         ) {
         ReserveExc(numitems,!keepold,true);
         if (clear && numitems > m_numitems) memset(m_data+m_numitems,0,(numitems-m_numitems)*sizeof(_CT));
         m_numitems = numitems;
         return;
         }

      //! Reverse order of items in array.
      void Reverse (
         ) {
         for (int i = 0; (i < m_numitems/2); ++i) {
            _CT temp(m_data[i]);
            m_data[i] = m_data[m_numitems-i-1];
            m_data[m_numitems-i-1] = temp;
            }
         return;
         }

      //! Set array items from C array, expanding if needed.
      //! Will not reduce the number of items in the array.
      ERRVALUE SetItems (
         int firstitem,                   //!< First array item to replace
         const _CT *items,                //!< Items to copy to array
         int numitems                     //!< Number of items to copy
         ) {
         ERRVALUE err;
         if ((err = Reserve(firstitem+numitems,true)) < 0) return (err);
         memcpy(m_data+firstitem,items,numitems*sizeof(_CT));
         if (m_numitems < firstitem + numitems) m_numitems = firstitem + numitems;
         return (0);
         }

      //! Swap two DOUBLE_ARRAYs.
      void Swap (
         DOUBLE_ARRAY<_CT>& rhs
         ) {
         m_items.Swap(rhs.m_items);
         _CT *t_data = m_data;
         m_data = rhs.m_data;
         rhs.m_data = t_data;
         int t_numitems = m_numitems;
         m_numitems = rhs.m_numitems;
         rhs.m_numitems = t_numitems;
         return;
         }
         
      //! Swap bytes in a DOUBLE_ARRAY, assume that there is an overload to swap a _CT
      void SwapBytes (
         ) { for (int i = 0;(i < m_numitems);++i) ::SwapBytes(m_data[i]); }
         
      //! Transfer data ownership from 'rhs' to 'this'.
      void TransferOwnerFrom (
         DOUBLE_ARRAY<_CT>& rhs
         ) {
         MIDOUBLEARRAY temp;
         int numitems = rhs.GetNumItems();
         rhs.Detach(temp);
         Attach(temp, numitems);
         return;
         }
         
      //! Transfer data ownership from 'rhs' to 'this'.
      template <class _T2> void TransferOwnerFromExt (
         DOUBLE_ARRAY<_T2>& rhs
         ) {
         MIDOUBLEARRAY temp;
         int numitems = rhs.GetNumItems();
         rhs.Detach(temp);
         
         int T1 = sizeof(_CT) / sizeof(double);
         int T2 = sizeof(_T2) / sizeof(double);
         numitems = (numitems * T2) / T1;
         Attach(temp, numitems);
         rhs.Clear();
         return;
         }
         
   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      MIDOUBLEARRAY m_items;              //!< The accessed array
      _CT* m_data;                        //!< Pointer to the data for fast access
      int m_numitems;                     //!< Number of valid items
      int m_spare;
      #endif // GENERATING_DOXYGEN_OUTPUT
   };

#endif   //!< INC_MI32_DOUBLEAR_H

---