icuSources/common/unicode/uobject.h

   1 /*
   2 ******************************************************************************
   3 *
   4 *   Copyright (C) 2002-2003, International Business Machines
   5 *   Corporation and others.  All Rights Reserved.
   6 *
   7 ******************************************************************************
   8 *   file name:  uobject.h
   9 *   encoding:   US-ASCII
  10 *   tab size:   8 (not used)
  11 *   indentation:4
  12 *
  13 *   created on: 2002jun26
  14 *   created by: Markus W. Scherer
  15 */
  16
  17 #ifndef __UOBJECT_H__
  18 #define __UOBJECT_H__
  19
  20 #include "unicode/utypes.h"
  21
  22 U_NAMESPACE_BEGIN
  23
  24 /**
  25  * \file
  26  * \brief C++ API: Common ICU base class UObject.
  27  */
  28
  29 /**  U_OVERRIDE_CXX_ALLOCATION - Define this to override operator new and
  30  *                               delete in UMemory. Enabled by default for ICU.
  31  *
  32  *         Enabling forces all allocation of ICU object types to use ICU's
  33  *         memory allocation. On Windows, this allows the ICU DLL to be used by
  34  *         applications that statically link the C Runtime library, meaning that
  35  *         the app and ICU will be using different heaps.
  36  *
  37  * @draft ICU 2.2
  38  */
  39 #ifndef U_OVERRIDE_CXX_ALLOCATION
  40 #define U_OVERRIDE_CXX_ALLOCATION 1
  41 #endif
  42
  43 /**  U_HAVE_PLACEMENT_NEW - Define this to define the placement new and
  44  *                          delete in UMemory for STL.
  45  *
  46  * @draft ICU 2.6
  47  */
  48 #ifndef U_HAVE_PLACEMENT_NEW
  49 #define U_HAVE_PLACEMENT_NEW 1
  50 #endif
  51
  52 /**
  53  * UMemory is the common ICU base class.
  54  * All other ICU C++ classes are derived from UMemory (starting with ICU 2.4).
  55  *
  56  * This is primarily to make it possible and simple to override the
  57  * C++ memory management by adding new/delete operators to this base class.
  58  *
  59  * To override ALL ICU memory management, including that from plain C code,
  60  * replace the allocation functions declared in cmemory.h
  61  *
  62  * UMemory does not contain any virtual functions.
  63  * Common "boilerplate" functions are defined in UObject.
  64  *
  65  * @draft ICU 2.4
  66  */
  67 class U_COMMON_API UMemory {
  68 public:
  69
  70 #if U_OVERRIDE_CXX_ALLOCATION
  71     /**
  72      * Override for ICU4C C++ memory management.
  73      * simple, non-class types are allocated using the macros in common/cmemory.h
  74      * (uprv_malloc(), uprv_free(), uprv_realloc());
  75      * they or something else could be used here to implement C++ new/delete
  76      * for ICU4C C++ classes
  77      * @draft ICU 2.4
  78      */
  79     static void *operator new(size_t size);
  80
  81     /**
  82      * Override for ICU4C C++ memory management.
  83      * See new().
  84      * @draft ICU 2.4
  85      */
  86     static void *operator new[](size_t size);
  87
  88     /**
  89      * Override for ICU4C C++ memory management.
  90      * simple, non-class types are allocated using the macros in common/cmemory.h
  91      * (uprv_malloc(), uprv_free(), uprv_realloc());
  92      * they or something else could be used here to implement C++ new/delete
  93      * for ICU4C C++ classes
  94      * @draft ICU 2.4
  95      */
  96     static void operator delete(void *p);
  97
  98     /**
  99      * Override for ICU4C C++ memory management.
 100      * See delete().
 101      * @draft ICU 2.4
 102      */
 103     static void operator delete[](void *p);
 104
 105 #if U_HAVE_PLACEMENT_NEW
 106     /**
 107      * Override for ICU4C C++ memory management for STL.
 108      * See new().
 109      * @draft ICU 2.6
 110      */
 111     static inline void * operator new(size_t, void *ptr) { return ptr; }
 112
 113     /**
 114      * Override for ICU4C C++ memory management for STL.
 115      * See delete().
 116      * @draft ICU 2.6
 117      */
 118     static inline void operator delete(void *, void *) {}
 119 #endif /* U_HAVE_PLACEMENT_NEW */
 120 #endif /* U_OVERRIDE_CXX_ALLOCATION */
 121
 122     /*
 123      * Assignment operator not declared. The compiler will provide one
 124      * which does nothing since this class does not contain any data members.
 125      * API/code coverage may show the assignment operator as present and
 126      * untested - ignore.
 127      * Subclasses need this assignment operator if they use compiler-provided
 128      * assignment operators of their own. An alternative to not declaring one
 129      * here would be to declare and empty-implement a protected or public one.
 130     UMemory &UMemory::operator=(const UMemory &);
 131      */
 132 };
 133
 134 /**
 135  * UObject is the common ICU "boilerplate" class.
 136  * UObject inherits UMemory (starting with ICU 2.4),
 137  * and all other public ICU C++ classes
 138  * are derived from UObject (starting with ICU 2.2).
 139  *
 140  * UObject contains common virtual functions like for ICU's "poor man's RTTI".
 141  * It does not contain default implementations of virtual methods
 142  * like getDynamicClassID to allow derived classes such as Format
 143  * to declare these as pure virtual.
 144  *
 145  * The clone() function is not available in UObject because it is not
 146  * implemented by all ICU classes.
 147  * Many ICU services provide a clone() function for their class trees,
 148  * defined on the service's C++ base class, and all subclasses within that
 149  * service class tree return a pointer to the service base class
 150  * (which itself is a subclass of UObject).
 151  * This is because some compilers do not support covariant (same-as-this)
 152  * return types; cast to the appropriate subclass if necessary.
 153  *
 154  * @draft ICU 2.2
 155  */
 156 class U_COMMON_API UObject : public UMemory {
 157 public:
 158     /**
 159      * Destructor.
 160      *
 161      * @draft ICU 2.2
 162      */
 163     virtual inline ~UObject() {}
 164
 165     /**
 166      * ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.
 167      *
 168      * @draft ICU 2.2
 169      */
 170     virtual inline UClassID getDynamicClassID() const = 0;
 171
 172 protected:
 173     // the following functions are protected to prevent instantiation and
 174     // direct use of UObject itself
 175
 176     // default constructor
 177     // commented out because UObject is abstract (see getDynamicClassID)
 178     // inline UObject() {}
 179
 180     // copy constructor
 181     // commented out because UObject is abstract (see getDynamicClassID)
 182     // inline UObject(const UObject &other) {}
 183
 184 #if U_ICU_VERSION_MAJOR_NUM>2 || (U_ICU_VERSION_MAJOR_NUM==2 && U_ICU_VERSION_MINOR_NUM>6)
 185     // TODO post ICU 2.4  (This comment inserted in 2.2)
 186     // some or all of the following "boilerplate" functions may be made public
 187     // in a future ICU4C release when all subclasses implement them
 188
 189     // assignment operator
 190     // (not virtual, see "Taligent's Guide to Designing Programs" pp.73..74)
 191     // commented out because the implementation is the same as a compiler's default
 192     // UObject &operator=(const UObject &other) { return *this; }
 193
 194     // comparison operators
 195     virtual inline UBool operator==(const UObject &other) const { return this==&other; }
 196     inline UBool operator!=(const UObject &other) const { return !operator==(other); }
 197
 198     // clone() commented out from the base class:
 199     // some compilers do not support co-variant return types
 200     // (i.e., subclasses would have to return UObject * as well, instead of SubClass *)
 201     // see also UObject class documentation.
 202     // virtual UObject *clone() const;
 203 #endif
 204
 205     /*
 206      * Assignment operator not declared. The compiler will provide one
 207      * which does nothing since this class does not contain any data members.
 208      * API/code coverage may show the assignment operator as present and
 209      * untested - ignore.
 210      * Subclasses need this assignment operator if they use compiler-provided
 211      * assignment operators of their own. An alternative to not declaring one
 212      * here would be to declare and empty-implement a protected or public one.
 213     UObject &UObject::operator=(const UObject &);
 214      */
 215 };
 216
 217 U_NAMESPACE_END
 218
 219 #endif