contain.h

Go to the documentation of this file.
00001 /*
00002  * contain.h
00003  *
00004  * Umbrella include for Container Classes.
00005  *
00006  * Portable Windows Library
00007  *
00008  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
00009  *
00010  * The contents of this file are subject to the Mozilla Public License
00011  * Version 1.0 (the "License"); you may not use this file except in
00012  * compliance with the License. You may obtain a copy of the License at
00013  * http://www.mozilla.org/MPL/
00014  *
00015  * Software distributed under the License is distributed on an "AS IS"
00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
00017  * the License for the specific language governing rights and limitations
00018  * under the License.
00019  *
00020  * The Original Code is Portable Windows Library.
00021  *
00022  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
00023  *
00024  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
00025  * All Rights Reserved.
00026  *
00027  * Contributor(s): ______________________________________.
00028  *
00029  * $Log: contain.h,v $
00030  * Revision 1.66  2006/04/10 23:57:27  csoutheren
00031  * Checked in changes to remove some warnings with gcc effc++ flag
00032  *
00033  * Revision 1.65  2005/11/25 03:43:47  csoutheren
00034  * Fixed function argument comments to be compatible with Doxygen
00035  *
00036  * Revision 1.64  2004/04/15 22:44:52  csoutheren
00037  * Re-applied gcc 2.95 patch as CVS screwed up
00038  *
00039  * Revision 1.63  2004/04/14 23:34:52  csoutheren
00040  * Added plugin for data access
00041  *
00042  * Revision 1.61  2004/04/12 00:36:04  csoutheren
00043  * Added new class PAtomicInteger and added Windows implementation
00044  *
00045  * Revision 1.60  2004/04/11 06:15:27  csoutheren
00046  * Modified to use Atomic_word if available
00047  *
00048  * Revision 1.59  2004/04/11 02:55:17  csoutheren
00049  * Added PCriticalSection for Windows
00050  * Added compile time option for PContainer to use critical sections to provide thread safety under some circumstances
00051  *
00052  * Revision 1.58  2004/04/09 03:42:34  csoutheren
00053  * Removed all usages of "virtual inline" and "inline virtual"
00054  *
00055  * Revision 1.57  2003/09/17 05:41:58  csoutheren
00056  * Removed recursive includes
00057  *
00058  * Revision 1.56  2003/09/17 01:18:02  csoutheren
00059  * Removed recursive include file system and removed all references
00060  * to deprecated coooperative threading support
00061  *
00062  * Revision 1.55  2003/03/31 01:23:56  robertj
00063  * Added ReadFrom functions for standard container classes such as
00064  *   PIntArray and PStringList etc
00065  *
00066  * Revision 1.54  2002/09/16 01:08:59  robertj
00067  * Added #define so can select if #pragma interface/implementation is used on
00068  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00069  *
00070  * Revision 1.53  2001/02/13 04:39:08  robertj
00071  * Fixed problem with operator= in container classes. Some containers will
00072  *   break unless the copy is virtual (eg PStringStream's buffer pointers) so
00073  *   needed to add a new AssignContents() function to all containers.
00074  *
00075  * Revision 1.52  1999/11/30 00:22:54  robertj
00076  * Updated documentation for doc++
00077  *
00078  * Revision 1.51  1999/08/22 12:13:42  robertj
00079  * Fixed warning when using inlines on older GNU compiler
00080  *
00081  * Revision 1.50  1999/08/17 03:46:40  robertj
00082  * Fixed usage of inlines in optimised version.
00083  *
00084  * Revision 1.49  1999/03/09 02:59:49  robertj
00085  * Changed comments to doc++ compatible documentation.
00086  *
00087  * Revision 1.48  1999/02/16 08:07:11  robertj
00088  * MSVC 6.0 compatibility changes.
00089  *
00090  * Revision 1.47  1998/09/23 06:20:23  robertj
00091  * Added open source copyright license.
00092  *
00093  * Revision 1.46  1997/07/08 13:15:04  robertj
00094  * DLL support.
00095  *
00096  * Revision 1.45  1996/08/17 10:00:20  robertj
00097  * Changes for Windows DLL support.
00098  *
00099  * Revision 1.44  1996/08/08 10:08:41  robertj
00100  * Directory structure changes for common files.
00101  *
00102  * Revision 1.43  1995/06/17 11:12:26  robertj
00103  * Documentation update.
00104  *
00105  * Revision 1.42  1995/03/14 12:41:13  robertj
00106  * Updated documentation to use HTML codes.
00107  *
00108  * Revision 1.41  1995/01/09  12:36:18  robertj
00109  * Removed unnecesary return value from I/O functions.
00110  * Changes due to Mac port.
00111  *
00112  * Revision 1.40  1994/12/13  11:50:45  robertj
00113  * Added MakeUnique() function to all container classes.
00114  *
00115  * Revision 1.39  1994/12/12  10:16:18  robertj
00116  * Restructuring and documentation of container classes.
00117  * Renaming of some macros for declaring container classes.
00118  * Added some extra functionality to PString.
00119  * Added start to 2 byte characters in PString.
00120  * Fixed incorrect overrides in PCaselessString.
00121  *
00122  * Revision 1.38  1994/12/05  11:18:58  robertj
00123  * Moved SetMinSize from PAbstractArray to PContainer.
00124  *
00125  * Revision 1.37  1994/11/28  12:33:44  robertj
00126  * Added dummy parameter for cls* constructor in containers. This prevents some very
00127  * strange an undesirable default construction of clones.
00128  *
00129  * Revision 1.36  1994/10/30  11:50:09  robertj
00130  * Split into Object classes and Container classes.
00131  * Changed mechanism for doing notification callback functions.
00132  *
00133  * Revision 1.35  1994/10/23  04:40:50  robertj
00134  * Made container * constractor protected.
00135  * Shorted OS Error assert.
00136  * Added printf constructor to PString.
00137  *
00138  * Revision 1.34  1994/09/25  10:36:41  robertj
00139  * Improved const behavious of container class macros.
00140  *
00141  * Revision 1.33  1994/08/23  11:32:52  robertj
00142  * Oops
00143  *
00144  * Revision 1.32  1994/08/22  00:46:48  robertj
00145  * Added pragma fro GNU C++ compiler.
00146  *
00147  * Revision 1.31  1994/08/21  23:43:02  robertj
00148  * Changed parameter before variable argument list to NOT be a reference.
00149  * Added object serialisation classes.
00150  *
00151  * Revision 1.30  1994/08/04  11:51:39  robertj
00152  * Rewrite of memory check functions.
00153  *
00154  * Revision 1.29  1994/07/27  05:58:07  robertj
00155  * Synchronisation.
00156  *
00157  * Revision 1.28  1994/07/25  03:33:50  robertj
00158  * Extra memory tests.
00159  *
00160  * Revision 1.27  1994/07/17  10:46:06  robertj
00161  * Added functions to strings in containers.
00162  *
00163  * Revision 1.26  1994/07/02  03:03:49  robertj
00164  * Addition of container searching facilities.
00165  *
00166  * Revision 1.25  1994/06/25  11:55:15  robertj
00167  * Unix version synchronisation.
00168  *
00169  * Revision 1.24  1994/04/20  12:17:44  robertj
00170  * Added code to assert
00171  *
00172  * Revision 1.23  1994/04/11  14:17:27  robertj
00173  * Made standard operators new and delete only declared for GNU C++
00174  *
00175  * Revision 1.22  1994/04/01  14:09:46  robertj
00176  * Removed PDECLARE_ABSTRACT_CONTAINER.
00177  * Added string stream class.
00178  * Added string containers.
00179  *
00180  * Revision 1.21  1994/03/07  07:38:19  robertj
00181  * Major enhancementsacross the board.
00182  *
00183  * Revision 1.20  1994/01/13  08:42:29  robertj
00184  * Fixed missing copy constuctor and assignment operator for PString.
00185  *
00186  * Revision 1.19  1994/01/13  05:33:41  robertj
00187  * Added contructor to get caseless string from ordinary string.
00188  *
00189  * Revision 1.18  1994/01/03  04:42:23  robertj
00190  * Mass changes to common container classes and interactors etc etc etc.
00191  *
00192  * Revision 1.17  1993/12/31  06:40:34  robertj
00193  * Made inlines optional for debugging purposes.
00194  * Added default to DeleteObjects() function.
00195  *
00196  * Revision 1.16  1993/12/24  04:20:52  robertj
00197  * Mac CFront port.
00198  *
00199  * Revision 1.15  1993/12/16  00:51:46  robertj
00200  * Made some container functions const.
00201  *
00202  * Revision 1.14  1993/12/15  21:10:10  robertj
00203  * Changes to fix inadequate reference system for containers.
00204  *
00205  * Revision 1.13  1993/12/14  18:44:56  robertj
00206  * Added RemoveAll() to collection classes.
00207  * Fixed incorrect destruction of objects in containers.
00208  *
00209  * Revision 1.12  1993/12/04  05:23:58  robertj
00210  * Added more string functions
00211  *
00212  * Revision 1.11  1993/09/27  16:35:25  robertj
00213  * Fixed bug in sorted lists.
00214  * Changed simple function for array of strings to a constructor.
00215  * Capitalised all macros.
00216  *
00217  * Revision 1.10  1993/08/27  18:17:47  robertj
00218  * Fixed bug with default number of elements in a collection.
00219  * Added missing Compare function to PAbstractSortedList
00220  * Added inline keywords for CFront compatibility.
00221  *
00222  * Revision 1.9  1993/08/21  01:50:33  robertj
00223  * Made Clone() function optional, default will assert if called.
00224  *
00225  * Revision 1.8  1993/08/19  18:00:32  robertj
00226  * Added two more standard base array classes
00227  *
00228  * Revision 1.7  1993/08/01  14:05:27  robertj
00229  * Added const to ToLower() and ToUpper() in the PString class.
00230  *
00231  * Revision 1.6  1993/07/16  14:40:55  robertj
00232  * Added PString constructor for individual characters.
00233  * Added string to C style literal format.
00234  *
00235  * Revision 1.5  1993/07/15  05:02:57  robertj
00236  * Removed redundant word in PString enum for string types.
00237  *
00238  * Revision 1.4  1993/07/15  04:23:39  robertj
00239  * Added constructor to PString to allow conversion from other string formats.
00240  * Fixed problem with variable parameter lists in sprintf() functions.
00241  *
00242  * Revision 1.3  1993/07/14  12:49:16  robertj
00243  * Fixed RCS keywords.
00244  *
00245  */
00246 
00247 #ifndef _CONTAIN_H
00248 #define _CONTAIN_H
00249 
00250 #ifdef P_USE_PRAGMA
00251 #pragma interface
00252 #endif
00253 
00254 #include <ptlib/object.h>
00255 #include <ptlib/critsec.h>
00256 
00258 // Abstract container class
00259 
00282 class PContainer : public PObject
00283 {
00284   PCLASSINFO(PContainer, PObject);
00285 
00286   public:
00291     PContainer(
00292       PINDEX initialSize = 0  
00293     );
00294 
00299     PContainer(
00300       const PContainer & cont  
00301     );
00302 
00310     PContainer & operator=(
00311       const PContainer & cont  
00312     );
00313 
00318     virtual ~PContainer()
00319     { Destruct(); }
00320 
00322 
00331     virtual PINDEX GetSize() const;
00332 
00346     virtual BOOL SetSize(
00347       PINDEX newSize  
00348     ) = 0;
00349 
00355     BOOL SetMinSize(
00356       PINDEX minSize  
00357     );
00358 
00365     virtual BOOL IsEmpty() const;
00366 
00373     BOOL IsUnique() const;
00374 
00383     virtual BOOL MakeUnique();
00385 
00386   protected:
00397     PContainer(
00398       int dummy,        
00399       const PContainer * cont  
00400     );
00401 
00412     virtual void DestroyContents() = 0;
00413 
00423     virtual void AssignContents(const PContainer & c);
00424 
00436     void CopyContents(const PContainer & c);
00437 
00454     void CloneContents(const PContainer * src);
00455 
00459     void Destruct();
00460 
00461 
00462     class Reference {
00463       public:
00464         inline Reference(PINDEX initialSize)
00465           : size(initialSize), count(1), deleteObjects(TRUE) { }
00466 
00467         Reference(const Reference & ref)
00468           : size(ref.size), count(1), deleteObjects(ref.deleteObjects)
00469         {  
00470         }
00471 
00472         PINDEX   size;         // Size of what the container contains
00473         PAtomicInteger count;  // reference count to the container content - guaranteed to be atomic
00474         BOOL deleteObjects;    // Used by PCollection but put here for efficiency
00475 
00476       private:
00477         Reference & operator=(const Reference &) 
00478         { return *this; }
00479     } * reference;
00480 };
00481 
00482 
00483 
00531 #define PCONTAINERINFO(cls, par) \
00532     PCLASSINFO(cls, par) \
00533   public: \
00534     cls(const cls & c) : par(c) { CopyContents(c); } \
00535     cls & operator=(const cls & c) \
00536       { AssignContents(c); return *this; } \
00537     virtual ~cls() { Destruct(); } \
00538     virtual BOOL MakeUnique() \
00539       { if(par::MakeUnique())return TRUE; CloneContents(this);return FALSE; } \
00540   protected: \
00541     cls(int dummy, const cls * c) : par(dummy, c) { CloneContents(c); } \
00542     virtual void DestroyContents(); \
00543     void CloneContents(const cls * c); \
00544     void CopyContents(const cls & c); \
00545     virtual void AssignContents(const PContainer & c) \
00546       { par::AssignContents(c); CopyContents((const cls &)c); }
00547 
00548 
00550 // Abstract collection of objects class
00551 
00583 class PCollection : public PContainer
00584 {
00585   PCLASSINFO(PCollection, PContainer);
00586 
00587   public:
00592     PCollection(
00593       PINDEX initialSize = 0  
00594     );
00596 
00612     virtual void PrintOn(
00613       ostream &strm   
00614     ) const;
00616 
00628     virtual PINDEX Append(
00629       PObject * obj   
00630     ) = 0;
00631 
00648     virtual PINDEX Insert(
00649       const PObject & before,   
00650       PObject * obj             
00651     ) = 0;
00652 
00664     virtual PINDEX InsertAt(
00665       PINDEX index,   
00666       PObject * obj   
00667     ) = 0;
00668 
00678     virtual BOOL Remove(
00679       const PObject * obj   
00680     ) = 0;
00681 
00690     virtual PObject * RemoveAt(
00691       PINDEX index   
00692     ) = 0;
00693 
00700     virtual void RemoveAll();
00701 
00715     virtual BOOL SetAt(
00716       PINDEX index,   
00717       PObject * val   
00718     ) = 0;
00719 
00725     virtual PObject * GetAt(
00726       PINDEX index  
00727     ) const = 0;
00728 
00735     virtual PINDEX GetObjectsIndex(
00736       const PObject * obj  
00737     ) const = 0;
00738 
00747     virtual PINDEX GetValuesIndex(
00748       const PObject & obj  
00749     ) const = 0;
00750 
00764     PINLINE void AllowDeleteObjects(
00765       BOOL yes = TRUE   
00766     );
00767 
00771     void DisallowDeleteObjects();
00773 
00774   protected:
00785     PINLINE PCollection(
00786       int dummy,        
00787       const PCollection * coll  
00788     );
00789 };
00790 
00791 
00792 
00794 // The abstract array class
00795 
00796 #include <ptlib/array.h>
00797 
00799 // The abstract array class
00800 
00801 #include <ptlib/lists.h>
00802 
00804 // PString class (specialised version of PBASEARRAY(char))
00805 
00806 #include <ptlib/dict.h>
00807 
00808 
00810 // PString class
00811 
00812 #include <ptlib/pstring.h>
00813 
00814 
00815 
00817 // Fill in all the inline functions
00818 
00819 #if P_USE_INLINES
00820 #include <ptlib/contain.inl>
00821 #endif
00822 
00823 #endif // _CONTAIN_H
00824 
00825 
00826 // End Of File ///////////////////////////////////////////////////////////////

Generated on Fri Feb 29 13:37:09 2008 for PWLib by  doxygen 1.5.5