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.65  2005/11/25 03:43:47  csoutheren
00031  * Fixed function argument comments to be compatible with Doxygen
00032  *
00033  * Revision 1.64  2004/04/15 22:44:52  csoutheren
00034  * Re-applied gcc 2.95 patch as CVS screwed up
00035  *
00036  * Revision 1.63  2004/04/14 23:34:52  csoutheren
00037  * Added plugin for data access
00038  *
00039  * Revision 1.61  2004/04/12 00:36:04  csoutheren
00040  * Added new class PAtomicInteger and added Windows implementation
00041  *
00042  * Revision 1.60  2004/04/11 06:15:27  csoutheren
00043  * Modified to use Atomic_word if available
00044  *
00045  * Revision 1.59  2004/04/11 02:55:17  csoutheren
00046  * Added PCriticalSection for Windows
00047  * Added compile time option for PContainer to use critical sections to provide thread safety under some circumstances
00048  *
00049  * Revision 1.58  2004/04/09 03:42:34  csoutheren
00050  * Removed all usages of "virtual inline" and "inline virtual"
00051  *
00052  * Revision 1.57  2003/09/17 05:41:58  csoutheren
00053  * Removed recursive includes
00054  *
00055  * Revision 1.56  2003/09/17 01:18:02  csoutheren
00056  * Removed recursive include file system and removed all references
00057  * to deprecated coooperative threading support
00058  *
00059  * Revision 1.55  2003/03/31 01:23:56  robertj
00060  * Added ReadFrom functions for standard container classes such as
00061  *   PIntArray and PStringList etc
00062  *
00063  * Revision 1.54  2002/09/16 01:08:59  robertj
00064  * Added #define so can select if #pragma interface/implementation is used on
00065  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00066  *
00067  * Revision 1.53  2001/02/13 04:39:08  robertj
00068  * Fixed problem with operator= in container classes. Some containers will
00069  *   break unless the copy is virtual (eg PStringStream's buffer pointers) so
00070  *   needed to add a new AssignContents() function to all containers.
00071  *
00072  * Revision 1.52  1999/11/30 00:22:54  robertj
00073  * Updated documentation for doc++
00074  *
00075  * Revision 1.51  1999/08/22 12:13:42  robertj
00076  * Fixed warning when using inlines on older GNU compiler
00077  *
00078  * Revision 1.50  1999/08/17 03:46:40  robertj
00079  * Fixed usage of inlines in optimised version.
00080  *
00081  * Revision 1.49  1999/03/09 02:59:49  robertj
00082  * Changed comments to doc++ compatible documentation.
00083  *
00084  * Revision 1.48  1999/02/16 08:07:11  robertj
00085  * MSVC 6.0 compatibility changes.
00086  *
00087  * Revision 1.47  1998/09/23 06:20:23  robertj
00088  * Added open source copyright license.
00089  *
00090  * Revision 1.46  1997/07/08 13:15:04  robertj
00091  * DLL support.
00092  *
00093  * Revision 1.45  1996/08/17 10:00:20  robertj
00094  * Changes for Windows DLL support.
00095  *
00096  * Revision 1.44  1996/08/08 10:08:41  robertj
00097  * Directory structure changes for common files.
00098  *
00099  * Revision 1.43  1995/06/17 11:12:26  robertj
00100  * Documentation update.
00101  *
00102  * Revision 1.42  1995/03/14 12:41:13  robertj
00103  * Updated documentation to use HTML codes.
00104  *
00105  * Revision 1.41  1995/01/09  12:36:18  robertj
00106  * Removed unnecesary return value from I/O functions.
00107  * Changes due to Mac port.
00108  *
00109  * Revision 1.40  1994/12/13  11:50:45  robertj
00110  * Added MakeUnique() function to all container classes.
00111  *
00112  * Revision 1.39  1994/12/12  10:16:18  robertj
00113  * Restructuring and documentation of container classes.
00114  * Renaming of some macros for declaring container classes.
00115  * Added some extra functionality to PString.
00116  * Added start to 2 byte characters in PString.
00117  * Fixed incorrect overrides in PCaselessString.
00118  *
00119  * Revision 1.38  1994/12/05  11:18:58  robertj
00120  * Moved SetMinSize from PAbstractArray to PContainer.
00121  *
00122  * Revision 1.37  1994/11/28  12:33:44  robertj
00123  * Added dummy parameter for cls* constructor in containers. This prevents some very
00124  * strange an undesirable default construction of clones.
00125  *
00126  * Revision 1.36  1994/10/30  11:50:09  robertj
00127  * Split into Object classes and Container classes.
00128  * Changed mechanism for doing notification callback functions.
00129  *
00130  * Revision 1.35  1994/10/23  04:40:50  robertj
00131  * Made container * constractor protected.
00132  * Shorted OS Error assert.
00133  * Added printf constructor to PString.
00134  *
00135  * Revision 1.34  1994/09/25  10:36:41  robertj
00136  * Improved const behavious of container class macros.
00137  *
00138  * Revision 1.33  1994/08/23  11:32:52  robertj
00139  * Oops
00140  *
00141  * Revision 1.32  1994/08/22  00:46:48  robertj
00142  * Added pragma fro GNU C++ compiler.
00143  *
00144  * Revision 1.31  1994/08/21  23:43:02  robertj
00145  * Changed parameter before variable argument list to NOT be a reference.
00146  * Added object serialisation classes.
00147  *
00148  * Revision 1.30  1994/08/04  11:51:39  robertj
00149  * Rewrite of memory check functions.
00150  *
00151  * Revision 1.29  1994/07/27  05:58:07  robertj
00152  * Synchronisation.
00153  *
00154  * Revision 1.28  1994/07/25  03:33:50  robertj
00155  * Extra memory tests.
00156  *
00157  * Revision 1.27  1994/07/17  10:46:06  robertj
00158  * Added functions to strings in containers.
00159  *
00160  * Revision 1.26  1994/07/02  03:03:49  robertj
00161  * Addition of container searching facilities.
00162  *
00163  * Revision 1.25  1994/06/25  11:55:15  robertj
00164  * Unix version synchronisation.
00165  *
00166  * Revision 1.24  1994/04/20  12:17:44  robertj
00167  * Added code to assert
00168  *
00169  * Revision 1.23  1994/04/11  14:17:27  robertj
00170  * Made standard operators new and delete only declared for GNU C++
00171  *
00172  * Revision 1.22  1994/04/01  14:09:46  robertj
00173  * Removed PDECLARE_ABSTRACT_CONTAINER.
00174  * Added string stream class.
00175  * Added string containers.
00176  *
00177  * Revision 1.21  1994/03/07  07:38:19  robertj
00178  * Major enhancementsacross the board.
00179  *
00180  * Revision 1.20  1994/01/13  08:42:29  robertj
00181  * Fixed missing copy constuctor and assignment operator for PString.
00182  *
00183  * Revision 1.19  1994/01/13  05:33:41  robertj
00184  * Added contructor to get caseless string from ordinary string.
00185  *
00186  * Revision 1.18  1994/01/03  04:42:23  robertj
00187  * Mass changes to common container classes and interactors etc etc etc.
00188  *
00189  * Revision 1.17  1993/12/31  06:40:34  robertj
00190  * Made inlines optional for debugging purposes.
00191  * Added default to DeleteObjects() function.
00192  *
00193  * Revision 1.16  1993/12/24  04:20:52  robertj
00194  * Mac CFront port.
00195  *
00196  * Revision 1.15  1993/12/16  00:51:46  robertj
00197  * Made some container functions const.
00198  *
00199  * Revision 1.14  1993/12/15  21:10:10  robertj
00200  * Changes to fix inadequate reference system for containers.
00201  *
00202  * Revision 1.13  1993/12/14  18:44:56  robertj
00203  * Added RemoveAll() to collection classes.
00204  * Fixed incorrect destruction of objects in containers.
00205  *
00206  * Revision 1.12  1993/12/04  05:23:58  robertj
00207  * Added more string functions
00208  *
00209  * Revision 1.11  1993/09/27  16:35:25  robertj
00210  * Fixed bug in sorted lists.
00211  * Changed simple function for array of strings to a constructor.
00212  * Capitalised all macros.
00213  *
00214  * Revision 1.10  1993/08/27  18:17:47  robertj
00215  * Fixed bug with default number of elements in a collection.
00216  * Added missing Compare function to PAbstractSortedList
00217  * Added inline keywords for CFront compatibility.
00218  *
00219  * Revision 1.9  1993/08/21  01:50:33  robertj
00220  * Made Clone() function optional, default will assert if called.
00221  *
00222  * Revision 1.8  1993/08/19  18:00:32  robertj
00223  * Added two more standard base array classes
00224  *
00225  * Revision 1.7  1993/08/01  14:05:27  robertj
00226  * Added const to ToLower() and ToUpper() in the PString class.
00227  *
00228  * Revision 1.6  1993/07/16  14:40:55  robertj
00229  * Added PString constructor for individual characters.
00230  * Added string to C style literal format.
00231  *
00232  * Revision 1.5  1993/07/15  05:02:57  robertj
00233  * Removed redundant word in PString enum for string types.
00234  *
00235  * Revision 1.4  1993/07/15  04:23:39  robertj
00236  * Added constructor to PString to allow conversion from other string formats.
00237  * Fixed problem with variable parameter lists in sprintf() functions.
00238  *
00239  * Revision 1.3  1993/07/14  12:49:16  robertj
00240  * Fixed RCS keywords.
00241  *
00242  */
00243 
00244 #ifndef _CONTAIN_H
00245 #define _CONTAIN_H
00246 
00247 #ifdef P_USE_PRAGMA
00248 #pragma interface
00249 #endif
00250 
00251 #include <ptlib/object.h>
00252 #include <ptlib/critsec.h>
00253 
00255 // Abstract container class
00256 
00279 class PContainer : public PObject
00280 {
00281   PCLASSINFO(PContainer, PObject);
00282 
00283   public:
00288     PContainer(
00289       PINDEX initialSize = 0  
00290     );
00291 
00296     PContainer(
00297       const PContainer & cont  
00298     );
00299 
00307     PContainer & operator=(
00308       const PContainer & cont  
00309     );
00310 
00315     virtual ~PContainer()
00316     { Destruct(); }
00317 
00319 
00328     virtual PINDEX GetSize() const;
00329 
00343     virtual BOOL SetSize(
00344       PINDEX newSize  
00345     ) = 0;
00346 
00352     BOOL SetMinSize(
00353       PINDEX minSize  
00354     );
00355 
00362     virtual BOOL IsEmpty() const;
00363 
00370     BOOL IsUnique() const;
00371 
00380     virtual BOOL MakeUnique();
00382 
00383   protected:
00394     PContainer(
00395       int dummy,        
00396       const PContainer * cont  
00397     );
00398 
00409     virtual void DestroyContents() = 0;
00410 
00420     virtual void AssignContents(const PContainer & c);
00421 
00433     void CopyContents(const PContainer & c);
00434 
00451     void CloneContents(const PContainer * src);
00452 
00456     void Destruct();
00457 
00458 
00459     class Reference {
00460       public:
00461         inline Reference(PINDEX initialSize)
00462           : size(initialSize), count(1), deleteObjects(TRUE) { }
00463 
00464         Reference(const Reference & ref)
00465           : count(1)
00466         {  
00467 #if PCONTAINER_USES_CRITSEC
00468           PEnterAndLeave m(((Reference &)ref).critSec);
00469 #endif
00470           size          = ref.size; 
00471           deleteObjects = ref.deleteObjects; 
00472         }
00473 
00474         PINDEX   size;         // Size of what the container contains
00475         PAtomicInteger count;  // reference count to the container content - guaranteed to be atomic
00476         BOOL deleteObjects;    // Used by PCollection but put here for efficiency
00477 #if PCONTAINER_USES_CRITSEC
00478         PCriticalSection critSec;
00479 #endif
00480       private:
00481         Reference & operator=(const Reference &) 
00482         { return *this; }
00483     } * reference;
00484 };
00485 
00486 
00487 
00535 #define PCONTAINERINFO(cls, par) \
00536     PCLASSINFO(cls, par) \
00537   public: \
00538     cls(const cls & c) : par(c) { CopyContents(c); } \
00539     cls & operator=(const cls & c) \
00540       { AssignContents(c); return *this; } \
00541     virtual ~cls() { Destruct(); } \
00542     virtual BOOL MakeUnique() \
00543       { if(par::MakeUnique())return TRUE; CloneContents(this);return FALSE; } \
00544   protected: \
00545     cls(int dummy, const cls * c) : par(dummy, c) { CloneContents(c); } \
00546     virtual void DestroyContents(); \
00547     void CloneContents(const cls * c); \
00548     void CopyContents(const cls & c); \
00549     virtual void AssignContents(const PContainer & c) \
00550       { par::AssignContents(c); CopyContents((const cls &)c); }
00551 
00552 
00554 // Abstract collection of objects class
00555 
00587 class PCollection : public PContainer
00588 {
00589   PCLASSINFO(PCollection, PContainer);
00590 
00591   public:
00596     PCollection(
00597       PINDEX initialSize = 0  
00598     );
00600 
00616     virtual void PrintOn(
00617       ostream &strm   
00618     ) const;
00620 
00632     virtual PINDEX Append(
00633       PObject * obj   
00634     ) = 0;
00635 
00652     virtual PINDEX Insert(
00653       const PObject & before,   
00654       PObject * obj             
00655     ) = 0;
00656 
00668     virtual PINDEX InsertAt(
00669       PINDEX index,   
00670       PObject * obj   
00671     ) = 0;
00672 
00682     virtual BOOL Remove(
00683       const PObject * obj   
00684     ) = 0;
00685 
00694     virtual PObject * RemoveAt(
00695       PINDEX index   
00696     ) = 0;
00697 
00704     virtual void RemoveAll();
00705 
00719     virtual BOOL SetAt(
00720       PINDEX index,   
00721       PObject * val   
00722     ) = 0;
00723 
00729     virtual PObject * GetAt(
00730       PINDEX index  
00731     ) const = 0;
00732 
00739     virtual PINDEX GetObjectsIndex(
00740       const PObject * obj  
00741     ) const = 0;
00742 
00751     virtual PINDEX GetValuesIndex(
00752       const PObject & obj  
00753     ) const = 0;
00754 
00768     PINLINE void AllowDeleteObjects(
00769       BOOL yes = TRUE   
00770     );
00771 
00775     void DisallowDeleteObjects();
00777 
00778   protected:
00789     PINLINE PCollection(
00790       int dummy,        
00791       const PCollection * coll  
00792     );
00793 };
00794 
00795 
00796 
00798 // The abstract array class
00799 
00800 #include <ptlib/array.h>
00801 
00803 // The abstract array class
00804 
00805 #include <ptlib/lists.h>
00806 
00808 // PString class (specialised version of PBASEARRAY(char))
00809 
00810 #include <ptlib/dict.h>
00811 
00812 
00814 // PString class
00815 
00816 #include <ptlib/pstring.h>
00817 
00818 
00819 
00821 // Fill in all the inline functions
00822 
00823 #if P_USE_INLINES
00824 #include <ptlib/contain.inl>
00825 #endif
00826 
00827 #endif // _CONTAIN_H
00828 
00829 
00830 // End Of File ///////////////////////////////////////////////////////////////

Generated on Fri Sep 21 14:40:11 2007 for PWLib by  doxygen 1.5.3