array.h

pwlib源码库

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

/// Array of short integers.
#ifdef DOC_PLUS_PLUS
class PShortArray : public PBaseArray {
  public:
  /**@name Construction */
  //@{
    /**Construct a new dynamic array of shorts.
       The array is initialised to all zeros.
     */
    PShortArray(
      PINDEX initialSize = 0  /// Initial number of elements in the array.
    );

    /**Construct a new dynamic array of shorts.
     */
    PShortArray(
      short const * buffer,   /// Pointer to an array of shorts.
      PINDEX length,      /// Number of elements pointed to by #buffer#.
      BOOL dynamic = TRUE /// Buffer is copied and dynamically allocated.
    );
  //@}
};
#endif
PSCALAR_ARRAY(PShortArray, short);


/// Array of integers.
#ifdef DOC_PLUS_PLUS
class PIntArray : public PBaseArray {
  public:
  /**@name Construction */
  //@{
    /**Construct a new dynamic array of ints.
       The array is initialised to all zeros.
     */
    PIntArray(
      PINDEX initialSize = 0  /// Initial number of elements in the array.
    );

    /**Construct a new dynamic array of ints.
     */
    PIntArray(
      int const * buffer,   /// Pointer to an array of ints.
      PINDEX length,      /// Number of elements pointed to by #buffer#.
      BOOL dynamic = TRUE /// Buffer is copied and dynamically allocated.
    );
  //@}
};
#endif
PSCALAR_ARRAY(PIntArray, int);


/// Array of long integers.
#ifdef DOC_PLUS_PLUS
class PLongArray : public PBaseArray {
  public:
  /**@name Construction */
  //@{
    /**Construct a new dynamic array of longs.
       The array is initialised to all zeros.
     */
    PLongArray(
      PINDEX initialSize = 0  /// Initial number of elements in the array.
    );

    /**Construct a new dynamic array of longs.
     */
    PLongArray(
      long const * buffer,   /// Pointer to an array of longs.
      PINDEX length,      /// Number of elements pointed to by #buffer#.
      BOOL dynamic = TRUE /// Buffer is copied and dynamically allocated.
    );
  //@}
};
#endif
PSCALAR_ARRAY(PLongArray, long);


/// Array of unsigned characters.
#ifdef DOC_PLUS_PLUS
class PBYTEArray : public PBaseArray {
  public:
  /**@name Construction */
  //@{
    /**Construct a new dynamic array of unsigned chars.
       The array is initialised to all zeros.
     */
    PBYTEArray(
      PINDEX initialSize = 0  /// Initial number of elements in the array.
    );

    /**Construct a new dynamic array of unsigned chars.
     */
    PBYTEArray(
      BYTE const * buffer,   /// Pointer to an array of BYTEs.
      PINDEX length,      /// Number of elements pointed to by #buffer#.
      BOOL dynamic = TRUE /// Buffer is copied and dynamically allocated.
    );
  //@}
};
#endif
PDECLARE_BASEARRAY(PBYTEArray, BYTE);
  public:
  /**@name Overrides from class PObject */
  //@{
    /// Print the array
    virtual void PrintOn(
      ostream & strm /// Stream to output to.
    ) const;
    /// Read the array
    virtual void ReadFrom(
      istream &strm   // Stream to read the objects contents from.
    );
  //@}
};


/// Array of unsigned short integers.
#ifdef DOC_PLUS_PLUS
class PWORDArray : public PBaseArray {
  public:
  /**@name Construction */
  //@{
    /**Construct a new dynamic array of unsigned shorts.
       The array is initialised to all zeros.
     */
    PWORDArray(
      PINDEX initialSize = 0  /// Initial number of elements in the array.
    );

    /**Construct a new dynamic array of unsigned shorts.
     */
    PWORDArray(
      WORD const * buffer,   /// Pointer to an array of WORDs.
      PINDEX length,      /// Number of elements pointed to by #buffer#.
      BOOL dynamic = TRUE /// Buffer is copied and dynamically allocated.
    );
  //@}
};
#endif
PSCALAR_ARRAY(PWORDArray, WORD);


/// Array of unsigned integers.
#ifdef DOC_PLUS_PLUS
class PUnsignedArray : public PBaseArray {
  public:
  /**@name Construction */
  //@{
    /**Construct a new dynamic array of unsigned ints.
       The array is initialised to all zeros.
     */
    PUnsignedArray(
      PINDEX initialSize = 0  /// Initial number of elements in the array.
    );

    /**Construct a new dynamic array of unsigned ints.
     */
    PUnsignedArray(
      unsigned const * buffer,   /// Pointer to an array of unsigned ints.
      PINDEX length,      /// Number of elements pointed to by #buffer#.
      BOOL dynamic = TRUE /// Buffer is copied and dynamically allocated.
    );
  //@}
};
#endif
PSCALAR_ARRAY(PUnsignedArray, unsigned);


/// Array of unsigned long integers.
#ifdef DOC_PLUS_PLUS
class PDWORDArray : public PBaseArray {
  public:
  /**@name Construction */
  //@{
    /**Construct a new dynamic array of unsigned longs.
       The array is initialised to all zeros.
     */
    PDWORDArray(
      PINDEX initialSize = 0  /// Initial number of elements in the array.
    );

    /**Construct a new dynamic array of DWORDs.
     */
    PDWORDArray(
      DWORD const * buffer,   /// Pointer to an array of DWORDs.
      PINDEX length,      /// Number of elements pointed to by #buffer#.
      BOOL dynamic = TRUE /// Buffer is copied and dynamically allocated.
    );
  //@}
#endif
PSCALAR_ARRAY(PDWORDArray, DWORD);


///////////////////////////////////////////////////////////////////////////////
// Linear array of objects

/** An array of objects.
This class is a collection of objects which are descendents of the
#PObject# class. It is implemeted as a dynamic, linear array of
pointers to the objects.

The implementation of an array allows very fast random access to items in
the collection, but has severe penalties for inserting and deleting objects
as all other objects must be moved to accommodate the change.

An array of objects may have "gaps" in it. These are array entries that
contain NULL as the object pointer.

The PArrayObjects class would very rarely be descended from directly by
the user. The #PARRAY# macro would normally be used to create a class.
That will instantiate the template based on #PArray# or directly declare
and define the class (using inline functions) if templates are not being used.

The #PArray# class or #PARRAY# macro will define the
correctly typed operators for pointer access (#operator const T *#) and
subscript access (#operator[]#).
*/
class PArrayObjects : public PCollection
{
  PCONTAINERINFO(PArrayObjects, PCollection);

  public:
  /**@name Construction */
  //@{
    /**Create a new array of objects. The array is initially set to the
       specified size with each entry having NULL as is pointer value.

       Note that by default, objects placed into the list will be deleted when
       removed or when all references to the list are destroyed.
     */
    PINLINE PArrayObjects(
      PINDEX initialSize = 0  /// Initial number of objects in the array.
    );
  //@}

  /**@name Overrides from class PObject */
  //@{
    /**Get the relative rank of the two arrays. The following algorithm is
       employed for the comparison:
\begin{description}
        \item[EqualTo]      if the two array memory blocks are identical in
                            length and each objects values, not pointer, are
                            equal.

        \item[LessThan]     if the instances object value at an ordinal
                            position is less than the corresponding objects
                            value in the #obj# parameters array.
                          
                            This is also returned if all objects are equal and
                            the instances array length is less than the
                            #obj# parameters array length.

        \item[GreaterThan]  if the instances object value at an ordinal
                            position is greater than the corresponding objects
                            value in the #obj# parameters array.
                          
                            This is also returned if all objects are equal and
                            the instances array length is greater than the
                            #obj# parameters array length.
\end{description}

       @return
       comparison of the two objects, #EqualTo# for same,
       #LessThan# for #obj# logically less than the
       object and #GreaterThan# for #obj# logically
       greater than the object.
     */
    virtual Comparison Compare(
      const PObject & obj   /// Other #PAbstractArray# to compare against.
    ) const;
  //@}

  /**@name Overrides from class PContainer */
  //@{
    /// Get size of array
    virtual PINDEX GetSize() const;

    /**Set the size of the array in objects. A new array may be allocated to
       accomodate the new number of objects. If the array increases in size
       then the new object pointers are initialised to NULL. If the array is
       made smaller then the data beyond the new size is lost.

       @return
       TRUE if the memory for the array was allocated successfully.
     */
    virtual BOOL SetSize(
      PINDEX newSize  /// New size of the array in objects.
    );
  //@}

  /**@name Overrides from class PCollection */
  //@{
    /**Append a new object to the collection. This will increase the size of
       the array by one and place the new object at that position.
    
       @return
       index of the newly added object.
     */
    virtual PINDEX Append(
      PObject * obj   /// New object to place into the collection.
    );

    /**Insert a new object immediately before the specified object. If the
       object to insert before is not in the collection then the equivalent of
       the #Append()# function is performed.

       All objects, including the #before# object are shifted up
       one in the array.

       Note that the object values are compared for the search of the
       #before# parameter, not the pointers. So the objects in the
       collection must correctly implement the #PObject::Compare()#
       function.

       @return
       index of the newly inserted object.
     */
    virtual PINDEX Insert(
      const PObject & before,   /// Object value to insert before.
      PObject * obj             /// New object to place into the collection.
    );

    /** Insert a new object at the specified ordinal index. If the index is
       greater than the number of objects in the collection then the
       equivalent of the #Append()# function is performed.

       All objects, including the #index# position object are
       shifted up one in the array.

       @return
       index of the newly inserted object.
     */
    virtual PINDEX InsertAt(
      PINDEX index,   /// Index position in collection to place the object.
      PObject * obj   /// New object to place into the collection.
    );

    /**Remove the object from the collection. If the AllowDeleteObjects option
       is set then the object is also deleted.

       All objects are shifted down to fill the vacated position.

       @return
       TRUE if the object was in the collection.
     */
    virtual BOOL Remove(
      const PObject * obj   /// Existing object to remove from the collection.
    );

    /**Remove the object at the specified ordinal index from the collection.
       If the AllowDeleteObjects option is set then the object is also deleted.