1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/uobject.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,320 @@
1.4 +/*
1.5 +******************************************************************************
1.6 +*
1.7 +* Copyright (C) 2002-2012, International Business Machines
1.8 +* Corporation and others. All Rights Reserved.
1.9 +*
1.10 +******************************************************************************
1.11 +* file name: uobject.h
1.12 +* encoding: US-ASCII
1.13 +* tab size: 8 (not used)
1.14 +* indentation:4
1.15 +*
1.16 +* created on: 2002jun26
1.17 +* created by: Markus W. Scherer
1.18 +*/
1.19 +
1.20 +#ifndef __UOBJECT_H__
1.21 +#define __UOBJECT_H__
1.22 +
1.23 +#include "unicode/utypes.h"
1.24 +
1.25 +/**
1.26 + * \file
1.27 + * \brief C++ API: Common ICU base class UObject.
1.28 + */
1.29 +
1.30 +/**
1.31 + * @{
1.32 + * \def U_NO_THROW
1.33 + * Define this to define the throw() specification so
1.34 + * certain functions do not throw any exceptions
1.35 + *
1.36 + * UMemory operator new methods should have the throw() specification
1.37 + * appended to them, so that the compiler adds the additional NULL check
1.38 + * before calling constructors. Without, if <code>operator new</code> returns NULL the
1.39 + * constructor is still called, and if the constructor references member
1.40 + * data, (which it typically does), the result is a segmentation violation.
1.41 + *
1.42 + * @stable ICU 4.2
1.43 + */
1.44 +#ifndef U_NO_THROW
1.45 +#define U_NO_THROW throw()
1.46 +#endif
1.47 +
1.48 +/** @} */
1.49 +
1.50 +/*===========================================================================*/
1.51 +/* UClassID-based RTTI */
1.52 +/*===========================================================================*/
1.53 +
1.54 +/**
1.55 + * UClassID is used to identify classes without using the compiler's RTTI.
1.56 + * This was used before C++ compilers consistently supported RTTI.
1.57 + * ICU 4.6 requires compiler RTTI to be turned on.
1.58 + *
1.59 + * Each class hierarchy which needs
1.60 + * to implement polymorphic clone() or operator==() defines two methods,
1.61 + * described in detail below. UClassID values can be compared using
1.62 + * operator==(). Nothing else should be done with them.
1.63 + *
1.64 + * \par
1.65 + * In class hierarchies that implement "poor man's RTTI",
1.66 + * each concrete subclass implements getDynamicClassID() in the same way:
1.67 + *
1.68 + * \code
1.69 + * class Derived {
1.70 + * public:
1.71 + * virtual UClassID getDynamicClassID() const
1.72 + * { return Derived::getStaticClassID(); }
1.73 + * }
1.74 + * \endcode
1.75 + *
1.76 + * Each concrete class implements getStaticClassID() as well, which allows
1.77 + * clients to test for a specific type.
1.78 + *
1.79 + * \code
1.80 + * class Derived {
1.81 + * public:
1.82 + * static UClassID U_EXPORT2 getStaticClassID();
1.83 + * private:
1.84 + * static char fgClassID;
1.85 + * }
1.86 + *
1.87 + * // In Derived.cpp:
1.88 + * UClassID Derived::getStaticClassID()
1.89 + * { return (UClassID)&Derived::fgClassID; }
1.90 + * char Derived::fgClassID = 0; // Value is irrelevant
1.91 + * \endcode
1.92 + * @stable ICU 2.0
1.93 + */
1.94 +typedef void* UClassID;
1.95 +
1.96 +U_NAMESPACE_BEGIN
1.97 +
1.98 +/**
1.99 + * UMemory is the common ICU base class.
1.100 + * All other ICU C++ classes are derived from UMemory (starting with ICU 2.4).
1.101 + *
1.102 + * This is primarily to make it possible and simple to override the
1.103 + * C++ memory management by adding new/delete operators to this base class.
1.104 + *
1.105 + * To override ALL ICU memory management, including that from plain C code,
1.106 + * replace the allocation functions declared in cmemory.h
1.107 + *
1.108 + * UMemory does not contain any virtual functions.
1.109 + * Common "boilerplate" functions are defined in UObject.
1.110 + *
1.111 + * @stable ICU 2.4
1.112 + */
1.113 +class U_COMMON_API UMemory {
1.114 +public:
1.115 +
1.116 +/* test versions for debugging shaper heap memory problems */
1.117 +#ifdef SHAPER_MEMORY_DEBUG
1.118 + static void * NewArray(int size, int count);
1.119 + static void * GrowArray(void * array, int newSize );
1.120 + static void FreeArray(void * array );
1.121 +#endif
1.122 +
1.123 +#if U_OVERRIDE_CXX_ALLOCATION
1.124 + /**
1.125 + * Override for ICU4C C++ memory management.
1.126 + * simple, non-class types are allocated using the macros in common/cmemory.h
1.127 + * (uprv_malloc(), uprv_free(), uprv_realloc());
1.128 + * they or something else could be used here to implement C++ new/delete
1.129 + * for ICU4C C++ classes
1.130 + * @stable ICU 2.4
1.131 + */
1.132 + static void * U_EXPORT2 operator new(size_t size) U_NO_THROW;
1.133 +
1.134 + /**
1.135 + * Override for ICU4C C++ memory management.
1.136 + * See new().
1.137 + * @stable ICU 2.4
1.138 + */
1.139 + static void * U_EXPORT2 operator new[](size_t size) U_NO_THROW;
1.140 +
1.141 + /**
1.142 + * Override for ICU4C C++ memory management.
1.143 + * simple, non-class types are allocated using the macros in common/cmemory.h
1.144 + * (uprv_malloc(), uprv_free(), uprv_realloc());
1.145 + * they or something else could be used here to implement C++ new/delete
1.146 + * for ICU4C C++ classes
1.147 + * @stable ICU 2.4
1.148 + */
1.149 + static void U_EXPORT2 operator delete(void *p) U_NO_THROW;
1.150 +
1.151 + /**
1.152 + * Override for ICU4C C++ memory management.
1.153 + * See delete().
1.154 + * @stable ICU 2.4
1.155 + */
1.156 + static void U_EXPORT2 operator delete[](void *p) U_NO_THROW;
1.157 +
1.158 +#if U_HAVE_PLACEMENT_NEW
1.159 + /**
1.160 + * Override for ICU4C C++ memory management for STL.
1.161 + * See new().
1.162 + * @stable ICU 2.6
1.163 + */
1.164 + static inline void * U_EXPORT2 operator new(size_t, void *ptr) U_NO_THROW { return ptr; }
1.165 +
1.166 + /**
1.167 + * Override for ICU4C C++ memory management for STL.
1.168 + * See delete().
1.169 + * @stable ICU 2.6
1.170 + */
1.171 + static inline void U_EXPORT2 operator delete(void *, void *) U_NO_THROW {}
1.172 +#endif /* U_HAVE_PLACEMENT_NEW */
1.173 +#if U_HAVE_DEBUG_LOCATION_NEW
1.174 + /**
1.175 + * This method overrides the MFC debug version of the operator new
1.176 + *
1.177 + * @param size The requested memory size
1.178 + * @param file The file where the allocation was requested
1.179 + * @param line The line where the allocation was requested
1.180 + */
1.181 + static void * U_EXPORT2 operator new(size_t size, const char* file, int line) U_NO_THROW;
1.182 + /**
1.183 + * This method provides a matching delete for the MFC debug new
1.184 + *
1.185 + * @param p The pointer to the allocated memory
1.186 + * @param file The file where the allocation was requested
1.187 + * @param line The line where the allocation was requested
1.188 + */
1.189 + static void U_EXPORT2 operator delete(void* p, const char* file, int line) U_NO_THROW;
1.190 +#endif /* U_HAVE_DEBUG_LOCATION_NEW */
1.191 +#endif /* U_OVERRIDE_CXX_ALLOCATION */
1.192 +
1.193 + /*
1.194 + * Assignment operator not declared. The compiler will provide one
1.195 + * which does nothing since this class does not contain any data members.
1.196 + * API/code coverage may show the assignment operator as present and
1.197 + * untested - ignore.
1.198 + * Subclasses need this assignment operator if they use compiler-provided
1.199 + * assignment operators of their own. An alternative to not declaring one
1.200 + * here would be to declare and empty-implement a protected or public one.
1.201 + UMemory &UMemory::operator=(const UMemory &);
1.202 + */
1.203 +};
1.204 +
1.205 +/**
1.206 + * UObject is the common ICU "boilerplate" class.
1.207 + * UObject inherits UMemory (starting with ICU 2.4),
1.208 + * and all other public ICU C++ classes
1.209 + * are derived from UObject (starting with ICU 2.2).
1.210 + *
1.211 + * UObject contains common virtual functions, in particular a virtual destructor.
1.212 + *
1.213 + * The clone() function is not available in UObject because it is not
1.214 + * implemented by all ICU classes.
1.215 + * Many ICU services provide a clone() function for their class trees,
1.216 + * defined on the service's C++ base class, and all subclasses within that
1.217 + * service class tree return a pointer to the service base class
1.218 + * (which itself is a subclass of UObject).
1.219 + * This is because some compilers do not support covariant (same-as-this)
1.220 + * return types; cast to the appropriate subclass if necessary.
1.221 + *
1.222 + * @stable ICU 2.2
1.223 + */
1.224 +class U_COMMON_API UObject : public UMemory {
1.225 +public:
1.226 + /**
1.227 + * Destructor.
1.228 + *
1.229 + * @stable ICU 2.2
1.230 + */
1.231 + virtual ~UObject();
1.232 +
1.233 + /**
1.234 + * ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.
1.235 + * The base class implementation returns a dummy value.
1.236 + *
1.237 + * Use compiler RTTI rather than ICU's "poor man's RTTI".
1.238 + * Since ICU 4.6, new ICU C++ class hierarchies do not implement "poor man's RTTI".
1.239 + *
1.240 + * @stable ICU 2.2
1.241 + */
1.242 + virtual UClassID getDynamicClassID() const;
1.243 +
1.244 +protected:
1.245 + // the following functions are protected to prevent instantiation and
1.246 + // direct use of UObject itself
1.247 +
1.248 + // default constructor
1.249 + // inline UObject() {}
1.250 +
1.251 + // copy constructor
1.252 + // inline UObject(const UObject &other) {}
1.253 +
1.254 +#if 0
1.255 + // TODO Sometime in the future. Implement operator==().
1.256 + // (This comment inserted in 2.2)
1.257 + // some or all of the following "boilerplate" functions may be made public
1.258 + // in a future ICU4C release when all subclasses implement them
1.259 +
1.260 + // assignment operator
1.261 + // (not virtual, see "Taligent's Guide to Designing Programs" pp.73..74)
1.262 + // commented out because the implementation is the same as a compiler's default
1.263 + // UObject &operator=(const UObject &other) { return *this; }
1.264 +
1.265 + // comparison operators
1.266 + virtual inline UBool operator==(const UObject &other) const { return this==&other; }
1.267 + inline UBool operator!=(const UObject &other) const { return !operator==(other); }
1.268 +
1.269 + // clone() commented out from the base class:
1.270 + // some compilers do not support co-variant return types
1.271 + // (i.e., subclasses would have to return UObject * as well, instead of SubClass *)
1.272 + // see also UObject class documentation.
1.273 + // virtual UObject *clone() const;
1.274 +#endif
1.275 +
1.276 + /*
1.277 + * Assignment operator not declared. The compiler will provide one
1.278 + * which does nothing since this class does not contain any data members.
1.279 + * API/code coverage may show the assignment operator as present and
1.280 + * untested - ignore.
1.281 + * Subclasses need this assignment operator if they use compiler-provided
1.282 + * assignment operators of their own. An alternative to not declaring one
1.283 + * here would be to declare and empty-implement a protected or public one.
1.284 + UObject &UObject::operator=(const UObject &);
1.285 + */
1.286 +};
1.287 +
1.288 +#ifndef U_HIDE_INTERNAL_API
1.289 +/**
1.290 + * This is a simple macro to add ICU RTTI to an ICU object implementation.
1.291 + * This does not go into the header. This should only be used in *.cpp files.
1.292 + *
1.293 + * @param myClass The name of the class that needs RTTI defined.
1.294 + * @internal
1.295 + */
1.296 +#define UOBJECT_DEFINE_RTTI_IMPLEMENTATION(myClass) \
1.297 + UClassID U_EXPORT2 myClass::getStaticClassID() { \
1.298 + static char classID = 0; \
1.299 + return (UClassID)&classID; \
1.300 + } \
1.301 + UClassID myClass::getDynamicClassID() const \
1.302 + { return myClass::getStaticClassID(); }
1.303 +
1.304 +
1.305 +/**
1.306 + * This macro adds ICU RTTI to an ICU abstract class implementation.
1.307 + * This macro should be invoked in *.cpp files. The corresponding
1.308 + * header should declare getStaticClassID.
1.309 + *
1.310 + * @param myClass The name of the class that needs RTTI defined.
1.311 + * @internal
1.312 + */
1.313 +#define UOBJECT_DEFINE_ABSTRACT_RTTI_IMPLEMENTATION(myClass) \
1.314 + UClassID U_EXPORT2 myClass::getStaticClassID() { \
1.315 + static char classID = 0; \
1.316 + return (UClassID)&classID; \
1.317 + }
1.318 +
1.319 +#endif /* U_HIDE_INTERNAL_API */
1.320 +
1.321 +U_NAMESPACE_END
1.322 +
1.323 +#endif
