array.h

mgcp协议源代码。支持多种编码：g711

  //@{
    /**Construct a new dynamic array of unsigned longs.
       The array is initialised to all zeros.
     */
    PBaseArray(
      PINDEX initialSize = 0  /// Initial number of elements in the array.
    );

    /**Construct a new dynamic array of DWORDs.
     */
    PBaseArray(
      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
PDECLARE_BASEARRAY(PDWORDArray, DWORD);
  public:
  /**@name Overrides from class PObject */
  //@{
    /// Print the array
    virtual void PrintOn(
      ostream & strm /// Stream to output to.
    ) const;
  //@}

    virtual long GetNumberValueAt(PINDEX idx) const;
};


///////////////////////////////////////////////////////////////////////////////
// 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.

       All objects are shifted down to fill the vacated position.

       Note if the index is beyond the size of the collection then the
       function will assert.

       @return
       pointer to the object being removed, or NULL if it was deleted.
     */
    virtual PObject * RemoveAt(
      PINDEX index   /// Index position in collection to place the object.
    );

    /**Set the object at the specified ordinal position to the new value. This
       will overwrite the existing entry. If the AllowDeleteObjects option is
       set then the old object is also deleted.

       @return
       TRUE if the object was successfully added.
     */
    virtual BOOL SetAt(
      PINDEX index,   /// Index position in collection to set.
      PObject * val   /// New value to place into the collection.
    );

    /**Get the object at the specified ordinal position. If the index was
       greater than the size of the collection then NULL is returned.

       @return
       pointer to object at the specified index.
     */
    virtual PObject * GetAt(
      PINDEX index  /// Index position in the collection of the object.
    ) const;

    /**Search the collection for the specific instance of the object. The
       object pointers are compared, not the values. A simple linear search
       from ordinal position zero is performed.

       @return
       ordinal index position of the object, or P_MAX_INDEX.
     */
    virtual PINDEX GetObjectsIndex(
      const PObject * obj  /// Object to find.
    ) const;

    /**Search the collection for the specified value of the object. The object
       values are compared, not the pointers.  So the objects in the
       collection must correctly implement the #PObject::Compare()#
       function. A simple linear search from ordinal position zero is
       performed.

       @return
       ordinal index position of the object, or P_MAX_INDEX.
     */
    virtual PINDEX GetValuesIndex(
      const PObject & obj   // Object to find equal of.
    ) const;

    /**Remove all of the elements in the collection. This operates by
       continually calling #RemoveAt()# until there are no objects left.

       The objects are removed from the last, at index
       #(GetSize()-1)# toward the first at index zero.
     */
    virtual void RemoveAll();
  //@}

  protected:
    PBASEARRAY(ObjPtrArray, PObject *);
    ObjPtrArray * theArray;
};


#ifdef PHAS_TEMPLATES

/**This template class maps the PArrayObjects to a specific object type.
The functions in this class primarily do all the appropriate casting of types.

Note that if templates are not used the #PARRAY# macro will
simulate the template instantiation.
*/
template <class T> class PArray : public PArrayObjects
{
  PCLASSINFO(PArray, PArrayObjects);

  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.
     */
    PArray( 
      PINDEX initialSize = 0  /// Initial number of objects in the array.
    ) : PArrayObjects(initialSize) { }
  //@}

  /**@name Overrides from class PObject */
  //@{
    /** Make a complete duplicate of the array. Note that all objects in the
       array are also cloned, so this will make a complete copy of the array.
     */
    virtual PObject * Clone() const
      { return PNEW PArray(0, this); }
  //@}

  /**@name New functions for class */
  //@{
    /**Retrieve a reference  to the object in the array. If there was not an
       object at that ordinal position or the index was beyond the size of the
       array then the function asserts.

       @return
       reference to the object at #index# position.
     */
    T & operator[](
      PINDEX index  /// Index position in the collection of the object.
    ) const { PAssert(GetAt(index) != NULL, PInvalidArrayElement);
                                                   return *(T *)GetAt(index); }
  //@}

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


/** Declare an array to a specific type of object.
This macro is used to declare a descendent of PArrayObjects class,
customised for a particular object 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 #PArray# template class.

See the #PBaseArray# class and #PDECLARE_ARRAY# macro for more
information.
*/
#define PARRAY(cls, T) typedef PArray<T> cls


/** Begin declaration an array to a specific type of object.
This macro is used to declare a descendent of PArrayObjects class,
customised for a particular object type {\bf T}.

If the compilation is using templates then this macro produces a descendent
of the #PArray# template class. If templates are not being used then
the macro defines a set of inline functions to do all casting of types. The
resultant classes have an identical set of functions in either case.

See the #PBaseArray# and #PAbstractArray# classes for more
information.
*/
#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) { } \
    inline 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) { } \
    inline virtual PObject * Clone() const \
      { return PNEW cls(0, this); } \
    inline T & operator[](PINDEX index) const\
      { PAssert((*theArray)[index] != NULL, PInvalidArrayElement); \
                                           return *(T *)(*theArray)[index]; } \
  }

#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) { } \
    inline virtual PObject * Clone() const \
      { return PNEW cls(0, this); } \

#endif // PHAS_TEMPLATES


// End Of File ///////////////////////////////////////////////////////////////