array.h

Go to the documentation of this file.

/*
 * array.h
 *
 * Linear Array Container classes.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: array.h,v $
 * Revision 1.36  2007/08/01 05:20:48  rjongbloed
 * Changes to container classes to become compatible with advanced DevStudio 2005 "Visualizers".
 *
 * Revision 1.35  2006/06/30 00:56:31  csoutheren
 * Applied 1494931 - various pwlib bug fixes and enhancement
 * Thanks to Frederich Heem
 *
 * Revision 1.34  2005/11/25 03:43:47  csoutheren
 * Fixed function argument comments to be compatible with Doxygen
 *
 * Revision 1.33  2005/08/08 07:01:58  rjongbloed
 * Minor changes to remove possible ambiguity where virtual and non-virtual
 *   functions are overloaded.
 * Removed commented out code.
 *
 * Revision 1.32  2005/05/02 09:02:35  csoutheren
 * Fixed previous fix to contain.cxx which broke PString::MakeUnique
 *
 * Revision 1.31  2004/05/13 02:07:14  dereksmithies
 * Fixes, so it works with doc++
 *
 * Revision 1.30  2004/04/09 03:42:34  csoutheren
 * Removed all usages of "virtual inline" and "inline virtual"
 *
 * Revision 1.29  2004/04/03 06:54:21  rjongbloed
 * Many and various changes to support new Visual C++ 2003
 *
 * Revision 1.28  2004/03/02 10:29:59  rjongbloed
 * Changed base array declaration macro to be consistent with the
 *   object array one, thanks Guilhem Tardy
 *
 * Revision 1.27  2003/04/17 07:24:47  robertj
 * Fixed GNU 3.x problem (why no other compiler?)
 *
 * Revision 1.26  2003/04/15 07:08:36  robertj
 * Changed read and write from streams for base array classes so operates in
 *   the same way for both PIntArray and PArray<int> etc
 *
 * Revision 1.25  2003/03/31 01:23:56  robertj
 * Added ReadFrom functions for standard container classes such as
 *   PIntArray and PStringList etc
 *
 * Revision 1.24  2002/09/16 01:08:59  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 1.23  2002/06/20 06:08:59  robertj
 * Fixed GNU warning
 *
 * Revision 1.22  2002/06/14 13:20:37  robertj
 * Added PBitArray class.
 *
 * Revision 1.21  2002/02/14 23:37:53  craigs
 * Added fix for optimisation for PArray [] operator, thanks to Vyacheslav Frolov
 *
 * Revision 1.20  2002/02/14 05:11:50  robertj
 * Minor optimisation in the operator[] for arrays of PObjects.
 *
 * Revision 1.19  1999/11/30 00:22:54  robertj
 * Updated documentation for doc++
 *
 * Revision 1.18  1999/09/03 15:08:38  robertj
 * Fixed typo in ancestor class name
 *
 * Revision 1.17  1999/08/22 12:13:42  robertj
 * Fixed warning when using inlines on older GNU compiler
 *
 * Revision 1.16  1999/08/20 03:07:44  robertj
 * Fixed addded Concatenate function for non-template version.
 *
 * Revision 1.15  1999/08/18 01:45:12  robertj
 * Added concatenation function to "base type" arrays.
 *
 * Revision 1.14  1999/03/09 02:59:49  robertj
 * Changed comments to doc++ compatible documentation.
 *
 * Revision 1.13  1999/02/16 08:07:11  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.12  1998/09/23 06:20:16  robertj
 * Added open source copyright license.
 *
 * Revision 1.11  1998/08/21 05:23:57  robertj
 * Added hex dump capability to base array types.
 * Added ability to have base arrays of static memory blocks.
 *
 * Revision 1.10  1997/06/08 04:49:10  robertj
 * Fixed non-template class descendent order.
 *
 * Revision 1.9  1996/08/17 09:54:34  robertj
 * Optimised RemoveAll() for object arrays.
 *
 * Revision 1.8  1996/01/02 11:48:46  robertj
 * Removed requirement that PArray elements have parameterless constructor..
 *
 * Revision 1.7  1995/10/14 14:52:33  robertj
 * Changed arrays to not break references.
 *
 * Revision 1.6  1995/06/17 11:12:18  robertj
 * Documentation update.
 *
 * Revision 1.5  1995/03/14 12:40:58  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.4  1995/02/22  10:50:26  robertj
 * Changes required for compiling release (optimised) version.
 *
 * Revision 1.3  1995/01/15  04:49:09  robertj
 * Fixed errors in template version.
 *
 * Revision 1.2  1994/12/21  11:52:46  robertj
 * Documentation and variable normalisation.
 *
 * Revision 1.1  1994/12/12  09:59:29  robertj
 * Initial revision
 *
 */

#ifndef _ARRAY_H_
#define _ARRAY_H_

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptlib/contain.h>

// The abstract array class

class PAbstractArray : public PContainer
{
  PCONTAINERINFO(PAbstractArray, PContainer);

  public:
    PAbstractArray(
      PINDEX elementSizeInBytes,  

      PINDEX initialSize = 0      
    );

    PAbstractArray(
      PINDEX elementSizeInBytes,   

      const void *buffer,          
      PINDEX bufferSizeInElements, 
      BOOL dynamicAllocation       
    );

    virtual void PrintOn(
      ostream &strm   // Stream to print the object into.
    ) const;

    virtual void ReadFrom(
      istream &strm   // Stream to read the objects contents from.
    );

    virtual Comparison Compare(
      const PObject & obj   
    ) const;

    virtual BOOL SetSize(
      PINDEX newSize  
    );

    void Attach(
      const void *buffer, 
      PINDEX bufferSize   
    );

    void * GetPointer(
      PINDEX minSize = 1  
    );

    BOOL Concatenate(
      const PAbstractArray & array  
    );

  protected:
    BOOL InternalSetSize(PINDEX newSize, BOOL force);

    virtual void PrintElementOn(
      ostream & stream,
      PINDEX index
    ) const;
    virtual void ReadElementFrom(
      istream & stream,
      PINDEX index
    );

    PINDEX elementSize;

    char * theArray;

    BOOL allocatedDynamically;

  friend class PArrayObjects;
};


// An array of some base type

#ifdef PHAS_TEMPLATES

template <class T> class PBaseArray : public PAbstractArray
{
  PCLASSINFO(PBaseArray, PAbstractArray);

  public:
    PBaseArray(
      PINDEX initialSize = 0  
    ) : PAbstractArray(sizeof(T), initialSize) { }
    
    PBaseArray(
      T const * buffer,   
      PINDEX length,      
      BOOL dynamic = TRUE 
    ) : PAbstractArray(sizeof(T), buffer, length, dynamic) { }

    virtual PObject * Clone() const
    { 
      return PNEW PBaseArray<T>(*this, GetSize());
    }

    BOOL SetAt(
      PINDEX index,   
      T val           
    ) {
      return SetMinSize(index+1) && val==(((T *)theArray)[index] = val);
    }

    T GetAt(
      PINDEX index  
    ) const {
      PASSERTINDEX(index);
      return index < GetSize() ? ((T *)theArray)[index] : (T)0;
    }

    void Attach(
      const T * buffer,   
      PINDEX bufferSize   
    ) {
      PAbstractArray::Attach(buffer, bufferSize);
    }

    T * GetPointer(
      PINDEX minSize = 0    
    ) {
      return (T *)PAbstractArray::GetPointer(minSize);
    }

    T operator[](
      PINDEX index  
    ) const {
      return GetAt(index);
    }

    T & operator[](
      PINDEX index  
    ) {
      PASSERTINDEX(index);
      PAssert(SetMinSize(index+1), POutOfMemory);
      return ((T *)theArray)[index];
    }

    operator T const *() const {
      return (T const *)theArray;
    }

    BOOL Concatenate(
      const PBaseArray & array  
    ) {
      return PAbstractArray::Concatenate(array);
    }

  protected:
    virtual void PrintElementOn(
      ostream & stream,
      PINDEX index
    ) const {
      stream << GetAt(index);
    }
};

/*Declare a dynamic array base type.
   This macro is used to declare a descendent of PAbstractArray class,
   customised for a particular element type {\bf T}. This macro closes the
   class declaration off so no additional members can be added.

   If the compilation is using templates then this macro produces a typedef
   of the #PBaseArray# template class.
 */
#define PBASEARRAY(cls, T) typedef PBaseArray<T> cls

#define PDECLARE_BASEARRAY(cls, T) \
  PDECLARE_CLASS(cls, PBaseArray<T>) \
    cls(PINDEX initialSize = 0) \
      : PBaseArray<T>(initialSize) { } \
    cls(T const * buffer, PINDEX length, BOOL dynamic = TRUE) \
      : PBaseArray<T>(buffer, length, dynamic) { } \
    virtual PObject * Clone() const \
      { return PNEW cls(*this, GetSize()); } \


template <class T> class PScalarArray : public PBaseArray<T>
{
  public:
    PScalarArray(
      PINDEX initialSize = 0  
    ) : PBaseArray<T>(initialSize) { }
    
    PScalarArray(
      T const * buffer,   
      PINDEX length,      
      BOOL dynamic = TRUE 
    ) : PBaseArray<T>(buffer, length, dynamic) { }

  protected:
    virtual void ReadElementFrom(
      istream & stream,
      PINDEX index
    ) {
      T t;
      stream >> t;
      if (!stream.fail())
        SetAt(index, t);
    }
};


/*Declare a dynamic array base type.
   This macro is used to declare a descendent of PAbstractArray class,
   customised for a particular element type {\bf T}. This macro closes the
   class declaration off so no additional members can be added.

   If the compilation is using templates then this macro produces a typedef
   of the #PBaseArray# template class.
 */
#define PSCALAR_ARRAY(cls, T) typedef PScalarArray<T> cls

#else // PHAS_TEMPLATES

#define PBASEARRAY(cls, T) \
  typedef T P_##cls##_Base_Type; \
  class cls : public PAbstractArray { \
    PCLASSINFO(cls, PAbstractArray) \
  public: \
    inline cls(PINDEX initialSize = 0) \
      : PAbstractArray(sizeof(P_##cls##_Base_Type), initialSize) { } \
    inline cls(P_##cls##_Base_Type const * buffer, PINDEX length, BOOL dynamic = TRUE) \
      : PAbstractArray(sizeof(P_##cls##_Base_Type), buffer, length, dynamic) { } \
    virtual PObject * Clone() const \
      { return PNEW cls(*this, GetSize()); } \
    inline BOOL SetAt(PINDEX index, P_##cls##_Base_Type val) \
      { return SetMinSize(index+1) && \
                     val==(((P_##cls##_Base_Type *)theArray)[index] = val); } \
    inline P_##cls##_Base_Type GetAt(PINDEX index) const \
      { PASSERTINDEX(index); return index < GetSize() ? \
          ((P_##cls##_Base_Type*)theArray)[index] : (P_##cls##_Base_Type)0; } \
    inline P_##cls##_Base_Type operator[](PINDEX index) const \
      { PASSERTINDEX(index); return GetAt(index); } \
    inline P_##cls##_Base_Type & operator[](PINDEX index) \
      { PASSERTINDEX(index); PAssert(SetMinSize(index+1), POutOfMemory); \
        return ((P_##cls##_Base_Type *)theArray)[index]; } \
    inline void Attach(const P_##cls##_Base_Type * buffer, PINDEX bufferSize) \
      { PAbstractArray::Attach(buffer, bufferSize); } \
    inline P_##cls##_Base_Type * GetPointer(PINDEX minSize = 0) \
      { return (P_##cls##_Base_Type *)PAbstractArray::GetPointer(minSize); } \
    inline operator P_##cls##_Base_Type const *() const \
      { return (P_##cls##_Base_Type const *)theArray; } \
    inline BOOL Concatenate(cls const & array) \
      { return PAbstractArray::Concatenate(array); } \
  }

#define PDECLARE_BASEARRAY(cls, T) \
  PBASEARRAY(cls##_PTemplate, T); \
  PDECLARE_CLASS(cls, cls##_PTemplate) \
    cls(PINDEX initialSize = 0) \
      : cls##_PTemplate(initialSize) { } \
    cls(T const * buffer, PINDEX length, BOOL dynamic = TRUE) \
      : cls##_PTemplate(buffer, length, dynamic) { } \
    virtual PObject * Clone() const \
      { return PNEW cls(*this, GetSize()); } \

#define PSCALAR_ARRAY(cls, T) PBASEARRAY(cls, T)

#endif // PHAS_TEMPLATES


#ifdef DOC_PLUS_PLUS
class PCharArray : public PBaseArray {
  public:
    PCharArray(
      PINDEX initialSize = 0  
    );

    PCharArray(
      char const * buffer,   
      PINDEX length,      
      BOOL dynamic = TRUE 
    );
#endif
PDECLARE_BASEARRAY(PCharArray, char);
  public:

    virtual void PrintOn(
      ostream & strm 
    ) const;
    virtual void ReadFrom(
      istream &strm   // Stream to read the objects contents from.
    );
};

#ifdef DOC_PLUS_PLUS
class PShortArray : public PBaseArray {
  public:
    PShortArray(
      PINDEX initialSize = 0  
    );

    PShortArray(
      short const * buffer,   
      PINDEX length,      
      BOOL dynamic = TRUE 
    );
};
#endif
PSCALAR_ARRAY(PShortArray, short);


#ifdef DOC_PLUS_PLUS
class PIntArray : public PBaseArray {
  public:
    PIntArray(
      PINDEX initialSize = 0  
    );

    PIntArray(
      int const * buffer,   
      PINDEX length,      
      BOOL dynamic = TRUE 
    );
};
#endif
PSCALAR_ARRAY(PIntArray, int);


#ifdef DOC_PLUS_PLUS
class PLongArray : public PBaseArray {
  public:
    PLongArray(
      PINDEX initialSize = 0  
    );

    PLongArray(
      long const * buffer,   
      PINDEX length,      
      BOOL dynamic = TRUE 
    );
};
#endif
PSCALAR_ARRAY(PLongArray, long);


#ifdef DOC_PLUS_PLUS
class PBYTEArray : public PBaseArray {
  public:
    PBYTEArray(
      PINDEX initialSize = 0  
    );

    PBYTEArray(
      BYTE const * buffer,   
      PINDEX length,      
      BOOL dynamic = TRUE 
    );
};
#endif
PDECLARE_BASEARRAY(PBYTEArray, BYTE);
  public:

    virtual void PrintOn(
      ostream & strm 
    ) const;
    virtual void ReadFrom(
      istream &strm   
    );
};


#ifdef DOC_PLUS_PLUS
class PWORDArray : public PBaseArray {
  public:
    PWORDArray(
      PINDEX initialSize = 0  
    );

    PWORDArray(
      WORD const * buffer,   
      PINDEX length,      
      BOOL dynamic = TRUE 
    );
};
#endif
PSCALAR_ARRAY(PWORDArray, WORD);


#ifdef DOC_PLUS_PLUS
class PUnsignedArray : public PBaseArray {
  public:
    PUnsignedArray(
      PINDEX initialSize = 0  
    );

    PUnsignedArray(
      unsigned const * buffer,   
      PINDEX length,      
      BOOL dynamic = TRUE 
    );
};
#endif
PSCALAR_ARRAY(PUnsignedArray, unsigned);


#ifdef DOC_PLUS_PLUS
class PDWORDArray : public PBaseArray {
  public:
    PDWORDArray(
      PINDEX initialSize = 0  
    );

    PDWORDArray(
      DWORD const * buffer,   
      PINDEX length,      
      BOOL dynamic = TRUE 
    );
#endif
PSCALAR_ARRAY(PDWORDArray, DWORD);


// Linear array of objects

class PArrayObjects : public PCollection
{
  PCONTAINERINFO(PArrayObjects, PCollection);

  public:
    PINLINE PArrayObjects(
      PINDEX initialSize = 0  
    );

    virtual Comparison Compare(
      const PObject & obj   
    ) const;


    virtual PINDEX GetSize() const;

    virtual BOOL SetSize(
      PINDEX newSize  
    );

    virtual PINDEX Append(
      PObject * obj   
    );

    virtual PINDEX Insert(
      const PObject & before,   
      PObject * obj             
    );

    virtual PINDEX InsertAt(
      PINDEX index,   
      PObject * obj   
    );

    virtual BOOL Remove(
      const PObject * obj   
    );

    virtual PObject * RemoveAt(
      PINDEX index   
    );

    virtual BOOL SetAt(
      PINDEX index,   
      PObject * val   
    );

    virtual PObject * GetAt(
      PINDEX index  
    ) const;

    virtual PINDEX GetObjectsIndex(
      const PObject * obj  
    ) const;

    virtual PINDEX GetValuesIndex(
      const PObject & obj   // Object to find equal of.
    ) const;

    virtual void RemoveAll();

  protected:
    // The type below cannot be nested as DevStudio 2005 AUTOEXP.DAT doesn't like it
    PBaseArray<PObject *> * theArray;
};


#ifdef PHAS_TEMPLATES

template <class T> class PArray : public PArrayObjects
{
  PCLASSINFO(PArray, PArrayObjects);

  public:
    PArray( 
      PINDEX initialSize = 0  
    ) : PArrayObjects(initialSize) { }

    virtual PObject * Clone() const
      { return PNEW PArray(0, this); }

    T & operator[](
      PINDEX index  
    ) const {
      PObject * obj = GetAt(index);
      PAssert(obj != NULL, PInvalidArrayElement);
      return (T &)*obj;
    }

  protected:
    PArray(int dummy, const PArray * c) : PArrayObjects(dummy, c) { }
};


#define PARRAY(cls, T) typedef PArray<T> cls


#define PDECLARE_ARRAY(cls, T) \
  PARRAY(cls##_PTemplate, T); \
  PDECLARE_CLASS(cls, cls##_PTemplate) \
  protected: \
    inline cls(int dummy, const cls * c) \
      : cls##_PTemplate(dummy, c) { } \
  public: \
    inline cls(PINDEX initialSize = 0) \
      : cls##_PTemplate(initialSize) { } \
    virtual PObject * Clone() const \
      { return PNEW cls(0, this); } \

#else // PHAS_TEMPLATES


#define PARRAY(cls, T) \
  class cls : public PArrayObjects { \
  PCLASSINFO(cls, PArrayObjects); \
  protected: \
    inline cls(int dummy, const cls * c) \
      : PArrayObjects(dummy, c) { } \
  public: \
    inline cls(PINDEX initialSize = 0) \
      : PArrayObjects(initialSize) { } \
    virtual PObject * Clone() const \
      { return PNEW cls(0, this); } \
    inline T & operator[](PINDEX index) const\
      { PObject * obj = GetAt(index); \
        PAssert(obj != NULL, PInvalidArrayElement); \
        /* want to do to this, but gcc 3.0 complains --> return *(T *)obj; } */ \
        return (T &)*obj; } \
  }

#define PDECLARE_ARRAY(cls, T) \
  PARRAY(cls##_PTemplate, T); \
  PDECLARE_CLASS(cls, cls##_PTemplate) \
  protected: \
    inline cls(int dummy, const cls * c) \
      : cls##_PTemplate(dummy, c) { } \
  public: \
    inline cls(PINDEX initialSize = 0) \
      : cls##_PTemplate(initialSize) { } \
    virtual PObject * Clone() const \
      { return PNEW cls(0, this); } \

#endif // PHAS_TEMPLATES


class PBitArray : public PBYTEArray
{
  PCLASSINFO(PBitArray, PBYTEArray);

  public:
    PBitArray(
      PINDEX initialSize = 0  
    );
    
    PBitArray(
      const void * buffer,   
      PINDEX length,         
      BOOL dynamic = TRUE    
    );

    virtual PObject * Clone() const;

    virtual PINDEX GetSize() const;

    virtual BOOL SetSize(
      PINDEX newSize  
    );

    BOOL SetAt(
      PINDEX index,   
      BOOL val           
    );

    BOOL GetAt(
      PINDEX index  
    ) const;

    void Attach(
      const void * buffer,   
      PINDEX bufferSize      
    );

    BYTE * GetPointer(
      PINDEX minSize = 0    
    );

    BOOL operator[](
      PINDEX index  
    ) const { return GetAt(index); }

    PBitArray & operator+=(
      PINDEX index  
    ) { SetAt(index, TRUE); return *this; }

    PBitArray & operator-=(
      PINDEX index  
    ) { SetAt(index, FALSE); return *this; }

    BOOL Concatenate(
      const PBitArray & array  
    );
};


#endif
// End Of File ///////////////////////////////////////////////////////////////

---