contain.h

Go to the documentation of this file.

/*
 * contain.h
 *
 * Umbrella include for 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: contain.h,v $
 * Revision 1.67  2007/08/01 05:20:48  rjongbloed
 * Changes to container classes to become compatible with advanced DevStudio 2005 "Visualizers".
 *
 * Revision 1.66  2006/04/10 23:57:27  csoutheren
 * Checked in changes to remove some warnings with gcc effc++ flag
 *
 * Revision 1.65  2005/11/25 03:43:47  csoutheren
 * Fixed function argument comments to be compatible with Doxygen
 *
 * Revision 1.64  2004/04/15 22:44:52  csoutheren
 * Re-applied gcc 2.95 patch as CVS screwed up
 *
 * Revision 1.63  2004/04/14 23:34:52  csoutheren
 * Added plugin for data access
 *
 * Revision 1.61  2004/04/12 00:36:04  csoutheren
 * Added new class PAtomicInteger and added Windows implementation
 *
 * Revision 1.60  2004/04/11 06:15:27  csoutheren
 * Modified to use Atomic_word if available
 *
 * Revision 1.59  2004/04/11 02:55:17  csoutheren
 * Added PCriticalSection for Windows
 * Added compile time option for PContainer to use critical sections to provide thread safety under some circumstances
 *
 * Revision 1.58  2004/04/09 03:42:34  csoutheren
 * Removed all usages of "virtual inline" and "inline virtual"
 *
 * Revision 1.57  2003/09/17 05:41:58  csoutheren
 * Removed recursive includes
 *
 * Revision 1.56  2003/09/17 01:18:02  csoutheren
 * Removed recursive include file system and removed all references
 * to deprecated coooperative threading support
 *
 * Revision 1.55  2003/03/31 01:23:56  robertj
 * Added ReadFrom functions for standard container classes such as
 *   PIntArray and PStringList etc
 *
 * Revision 1.54  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.53  2001/02/13 04:39:08  robertj
 * Fixed problem with operator= in container classes. Some containers will
 *   break unless the copy is virtual (eg PStringStream's buffer pointers) so
 *   needed to add a new AssignContents() function to all containers.
 *
 * Revision 1.52  1999/11/30 00:22:54  robertj
 * Updated documentation for doc++
 *
 * Revision 1.51  1999/08/22 12:13:42  robertj
 * Fixed warning when using inlines on older GNU compiler
 *
 * Revision 1.50  1999/08/17 03:46:40  robertj
 * Fixed usage of inlines in optimised version.
 *
 * Revision 1.49  1999/03/09 02:59:49  robertj
 * Changed comments to doc++ compatible documentation.
 *
 * Revision 1.48  1999/02/16 08:07:11  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.47  1998/09/23 06:20:23  robertj
 * Added open source copyright license.
 *
 * Revision 1.46  1997/07/08 13:15:04  robertj
 * DLL support.
 *
 * Revision 1.45  1996/08/17 10:00:20  robertj
 * Changes for Windows DLL support.
 *
 * Revision 1.44  1996/08/08 10:08:41  robertj
 * Directory structure changes for common files.
 *
 * Revision 1.43  1995/06/17 11:12:26  robertj
 * Documentation update.
 *
 * Revision 1.42  1995/03/14 12:41:13  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.41  1995/01/09  12:36:18  robertj
 * Removed unnecesary return value from I/O functions.
 * Changes due to Mac port.
 *
 * Revision 1.40  1994/12/13  11:50:45  robertj
 * Added MakeUnique() function to all container classes.
 *
 * Revision 1.39  1994/12/12  10:16:18  robertj
 * Restructuring and documentation of container classes.
 * Renaming of some macros for declaring container classes.
 * Added some extra functionality to PString.
 * Added start to 2 byte characters in PString.
 * Fixed incorrect overrides in PCaselessString.
 *
 * Revision 1.38  1994/12/05  11:18:58  robertj
 * Moved SetMinSize from PAbstractArray to PContainer.
 *
 * Revision 1.37  1994/11/28  12:33:44  robertj
 * Added dummy parameter for cls* constructor in containers. This prevents some very
 * strange an undesirable default construction of clones.
 *
 * Revision 1.36  1994/10/30  11:50:09  robertj
 * Split into Object classes and Container classes.
 * Changed mechanism for doing notification callback functions.
 *
 * Revision 1.35  1994/10/23  04:40:50  robertj
 * Made container * constractor protected.
 * Shorted OS Error assert.
 * Added printf constructor to PString.
 *
 * Revision 1.34  1994/09/25  10:36:41  robertj
 * Improved const behavious of container class macros.
 *
 * Revision 1.33  1994/08/23  11:32:52  robertj
 * Oops
 *
 * Revision 1.32  1994/08/22  00:46:48  robertj
 * Added pragma fro GNU C++ compiler.
 *
 * Revision 1.31  1994/08/21  23:43:02  robertj
 * Changed parameter before variable argument list to NOT be a reference.
 * Added object serialisation classes.
 *
 * Revision 1.30  1994/08/04  11:51:39  robertj
 * Rewrite of memory check functions.
 *
 * Revision 1.29  1994/07/27  05:58:07  robertj
 * Synchronisation.
 *
 * Revision 1.28  1994/07/25  03:33:50  robertj
 * Extra memory tests.
 *
 * Revision 1.27  1994/07/17  10:46:06  robertj
 * Added functions to strings in containers.
 *
 * Revision 1.26  1994/07/02  03:03:49  robertj
 * Addition of container searching facilities.
 *
 * Revision 1.25  1994/06/25  11:55:15  robertj
 * Unix version synchronisation.
 *
 * Revision 1.24  1994/04/20  12:17:44  robertj
 * Added code to assert
 *
 * Revision 1.23  1994/04/11  14:17:27  robertj
 * Made standard operators new and delete only declared for GNU C++
 *
 * Revision 1.22  1994/04/01  14:09:46  robertj
 * Removed PDECLARE_ABSTRACT_CONTAINER.
 * Added string stream class.
 * Added string containers.
 *
 * Revision 1.21  1994/03/07  07:38:19  robertj
 * Major enhancementsacross the board.
 *
 * Revision 1.20  1994/01/13  08:42:29  robertj
 * Fixed missing copy constuctor and assignment operator for PString.
 *
 * Revision 1.19  1994/01/13  05:33:41  robertj
 * Added contructor to get caseless string from ordinary string.
 *
 * Revision 1.18  1994/01/03  04:42:23  robertj
 * Mass changes to common container classes and interactors etc etc etc.
 *
 * Revision 1.17  1993/12/31  06:40:34  robertj
 * Made inlines optional for debugging purposes.
 * Added default to DeleteObjects() function.
 *
 * Revision 1.16  1993/12/24  04:20:52  robertj
 * Mac CFront port.
 *
 * Revision 1.15  1993/12/16  00:51:46  robertj
 * Made some container functions const.
 *
 * Revision 1.14  1993/12/15  21:10:10  robertj
 * Changes to fix inadequate reference system for containers.
 *
 * Revision 1.13  1993/12/14  18:44:56  robertj
 * Added RemoveAll() to collection classes.
 * Fixed incorrect destruction of objects in containers.
 *
 * Revision 1.12  1993/12/04  05:23:58  robertj
 * Added more string functions
 *
 * Revision 1.11  1993/09/27  16:35:25  robertj
 * Fixed bug in sorted lists.
 * Changed simple function for array of strings to a constructor.
 * Capitalised all macros.
 *
 * Revision 1.10  1993/08/27  18:17:47  robertj
 * Fixed bug with default number of elements in a collection.
 * Added missing Compare function to PAbstractSortedList
 * Added inline keywords for CFront compatibility.
 *
 * Revision 1.9  1993/08/21  01:50:33  robertj
 * Made Clone() function optional, default will assert if called.
 *
 * Revision 1.8  1993/08/19  18:00:32  robertj
 * Added two more standard base array classes
 *
 * Revision 1.7  1993/08/01  14:05:27  robertj
 * Added const to ToLower() and ToUpper() in the PString class.
 *
 * Revision 1.6  1993/07/16  14:40:55  robertj
 * Added PString constructor for individual characters.
 * Added string to C style literal format.
 *
 * Revision 1.5  1993/07/15  05:02:57  robertj
 * Removed redundant word in PString enum for string types.
 *
 * Revision 1.4  1993/07/15  04:23:39  robertj
 * Added constructor to PString to allow conversion from other string formats.
 * Fixed problem with variable parameter lists in sprintf() functions.
 *
 * Revision 1.3  1993/07/14  12:49:16  robertj
 * Fixed RCS keywords.
 *
 */

#ifndef _CONTAIN_H
#define _CONTAIN_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptlib/object.h>
#include <ptlib/critsec.h>

// Abstract container class

// The type below cannot be nested into PContainer as DevStudio 2005 AUTOEXP.DAT doesn't like it
class PContainerReference {
  public:
    inline PContainerReference(PINDEX initialSize)
      : size(initialSize), count(1), deleteObjects(TRUE)
    {
    }

    inline PContainerReference(const PContainerReference & ref)
      : size(ref.size), count(1), deleteObjects(ref.deleteObjects)
    {  
    }

    PINDEX   size;         // Size of what the container contains
    PAtomicInteger count;  // reference count to the container content - guaranteed to be atomic
    BOOL deleteObjects;    // Used by PCollection but put here for efficiency

  private:
    PContainerReference & operator=(const PContainerReference &) 
    { return *this; }
};

class PContainer : public PObject
{
  PCLASSINFO(PContainer, PObject);

  public:
    PContainer(
      PINDEX initialSize = 0  
    );

    PContainer(
      const PContainer & cont  
    );

    PContainer & operator=(
      const PContainer & cont  
    );

    virtual ~PContainer()
    { Destruct(); }


    virtual PINDEX GetSize() const;

    virtual BOOL SetSize(
      PINDEX newSize  
    ) = 0;

    BOOL SetMinSize(
      PINDEX minSize  
    );

    virtual BOOL IsEmpty() const;

    BOOL IsUnique() const;

    virtual BOOL MakeUnique();

  protected:
    PContainer(
      int dummy,        
      const PContainer * cont  
    );

    virtual void DestroyContents() = 0;

    virtual void AssignContents(const PContainer & c);

    void CopyContents(const PContainer & c);

    void CloneContents(const PContainer * src);

    void Destruct();


    PContainerReference * reference;
};



#define PCONTAINERINFO(cls, par) \
    PCLASSINFO(cls, par) \
  public: \
    cls(const cls & c) : par(c) { CopyContents(c); } \
    cls & operator=(const cls & c) \
      { AssignContents(c); return *this; } \
    virtual ~cls() { Destruct(); } \
    virtual BOOL MakeUnique() \
      { if(par::MakeUnique())return TRUE; CloneContents(this);return FALSE; } \
  protected: \
    cls(int dummy, const cls * c) : par(dummy, c) { CloneContents(c); } \
    virtual void DestroyContents(); \
    void CloneContents(const cls * c); \
    void CopyContents(const cls & c); \
    virtual void AssignContents(const PContainer & c) \
      { par::AssignContents(c); CopyContents((const cls &)c); }


// Abstract collection of objects class

class PCollection : public PContainer
{
  PCLASSINFO(PCollection, PContainer);

  public:
    PCollection(
      PINDEX initialSize = 0  
    );

    virtual void PrintOn(
      ostream &strm   
    ) const;

    virtual PINDEX Append(
      PObject * obj   
    ) = 0;

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

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

    virtual BOOL Remove(
      const PObject * obj   
    ) = 0;

    virtual PObject * RemoveAt(
      PINDEX index   
    ) = 0;

    virtual void RemoveAll();

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

    virtual PObject * GetAt(
      PINDEX index  
    ) const = 0;

    virtual PINDEX GetObjectsIndex(
      const PObject * obj  
    ) const = 0;

    virtual PINDEX GetValuesIndex(
      const PObject & obj  
    ) const = 0;

    PINLINE void AllowDeleteObjects(
      BOOL yes = TRUE   
    );

    void DisallowDeleteObjects();

  protected:
    PINLINE PCollection(
      int dummy,        
      const PCollection * coll  
    );
};



// The abstract array class

#include <ptlib/array.h>

// The abstract array class

#include <ptlib/lists.h>

// PString class (specialised version of PBASEARRAY(char))

#include <ptlib/dict.h>


// PString class

#include <ptlib/pstring.h>



// Fill in all the inline functions

#if P_USE_INLINES
#include <ptlib/contain.inl>
#endif

#endif // _CONTAIN_H


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

---