[apple/icu.git] / icuSources / common / unicode / uobject.h

/*
******************************************************************************
*
*   Copyright (C) 2002-2012, International Business Machines
*   Corporation and others.  All Rights Reserved.
*
******************************************************************************
*   file name:  uobject.h
*   encoding:   US-ASCII
*   tab size:   8 (not used)
*   indentation:4
*
*   created on: 2002jun26
*   created by: Markus W. Scherer
*/

#ifndef __UOBJECT_H__
#define __UOBJECT_H__

#include "unicode/utypes.h"

/**
 * \file
 * \brief C++ API: Common ICU base class UObject.
 */

/**
 * @{
 * \def U_NO_THROW
 *         Define this to define the throw() specification so
 *                 certain functions do not throw any exceptions
 *
 *         UMemory operator new methods should have the throw() specification 
 *         appended to them, so that the compiler adds the additional NULL check 
 *         before calling constructors. Without, if <code>operator new</code> returns NULL the 
 *         constructor is still called, and if the constructor references member 
 *         data, (which it typically does), the result is a segmentation violation.
 *
 * @stable ICU 4.2
 */
#ifndef U_NO_THROW
#define U_NO_THROW throw()
#endif

/** @} */

/*===========================================================================*/
/* UClassID-based RTTI */
/*===========================================================================*/

/**
 * UClassID is used to identify classes without using the compiler's RTTI.
 * This was used before C++ compilers consistently supported RTTI.
 * ICU 4.6 requires compiler RTTI to be turned on.
 *
 * Each class hierarchy which needs
 * to implement polymorphic clone() or operator==() defines two methods,
 * described in detail below.  UClassID values can be compared using
 * operator==(). Nothing else should be done with them.
 *
 * \par
 * In class hierarchies that implement "poor man's RTTI",
 * each concrete subclass implements getDynamicClassID() in the same way:
 *
 * \code
 *      class Derived {
 *      public:
 *          virtual UClassID getDynamicClassID() const
 *            { return Derived::getStaticClassID(); }
 *      }
 * \endcode
 *
 * Each concrete class implements getStaticClassID() as well, which allows
 * clients to test for a specific type.
 *
 * \code
 *      class Derived {
 *      public:
 *          static UClassID U_EXPORT2 getStaticClassID();
 *      private:
 *          static char fgClassID;
 *      }
 *
 *      // In Derived.cpp:
 *      UClassID Derived::getStaticClassID()
 *        { return (UClassID)&Derived::fgClassID; }
 *      char Derived::fgClassID = 0; // Value is irrelevant
 * \endcode
 * @stable ICU 2.0
 */
typedef void* UClassID;

U_NAMESPACE_BEGIN

/**
 * UMemory is the common ICU base class.
 * All other ICU C++ classes are derived from UMemory (starting with ICU 2.4).
 *
 * This is primarily to make it possible and simple to override the
 * C++ memory management by adding new/delete operators to this base class.
 *
 * To override ALL ICU memory management, including that from plain C code,
 * replace the allocation functions declared in cmemory.h
 *
 * UMemory does not contain any virtual functions.
 * Common "boilerplate" functions are defined in UObject.
 *
 * @stable ICU 2.4
 */
class U_COMMON_API UMemory {
public:

/* test versions for debugging shaper heap memory problems */
#ifdef SHAPER_MEMORY_DEBUG  
    static void * NewArray(int size, int count);
    static void * GrowArray(void * array, int newSize );
    static void   FreeArray(void * array );
#endif

#if U_OVERRIDE_CXX_ALLOCATION
    /**
     * Override for ICU4C C++ memory management.
     * simple, non-class types are allocated using the macros in common/cmemory.h
     * (uprv_malloc(), uprv_free(), uprv_realloc());
     * they or something else could be used here to implement C++ new/delete
     * for ICU4C C++ classes
     * @stable ICU 2.4
     */
    static void * U_EXPORT2 operator new(size_t size) U_NO_THROW;

    /**
     * Override for ICU4C C++ memory management.
     * See new().
     * @stable ICU 2.4
     */
    static void * U_EXPORT2 operator new[](size_t size) U_NO_THROW;

    /**
     * Override for ICU4C C++ memory management.
     * simple, non-class types are allocated using the macros in common/cmemory.h
     * (uprv_malloc(), uprv_free(), uprv_realloc());
     * they or something else could be used here to implement C++ new/delete
     * for ICU4C C++ classes
     * @stable ICU 2.4
     */
    static void U_EXPORT2 operator delete(void *p) U_NO_THROW;

    /**
     * Override for ICU4C C++ memory management.
     * See delete().
     * @stable ICU 2.4
     */
    static void U_EXPORT2 operator delete[](void *p) U_NO_THROW;

#if U_HAVE_PLACEMENT_NEW
    /**
     * Override for ICU4C C++ memory management for STL.
     * See new().
     * @stable ICU 2.6
     */
    static inline void * U_EXPORT2 operator new(size_t, void *ptr) U_NO_THROW { return ptr; }

    /**
     * Override for ICU4C C++ memory management for STL.
     * See delete().
     * @stable ICU 2.6
     */
    static inline void U_EXPORT2 operator delete(void *, void *) U_NO_THROW {}
#endif /* U_HAVE_PLACEMENT_NEW */
#if U_HAVE_DEBUG_LOCATION_NEW
    /**
      * This method overrides the MFC debug version of the operator new
      * 
      * @param size   The requested memory size
      * @param file   The file where the allocation was requested
      * @param line   The line where the allocation was requested 
      */ 
    static void * U_EXPORT2 operator new(size_t size, const char* file, int line) U_NO_THROW;
    /**
      * This method provides a matching delete for the MFC debug new
      * 
      * @param p      The pointer to the allocated memory
      * @param file   The file where the allocation was requested
      * @param line   The line where the allocation was requested 
      */ 
    static void U_EXPORT2 operator delete(void* p, const char* file, int line) U_NO_THROW;
#endif /* U_HAVE_DEBUG_LOCATION_NEW */
#endif /* U_OVERRIDE_CXX_ALLOCATION */

    /*
     * Assignment operator not declared. The compiler will provide one
     * which does nothing since this class does not contain any data members.
     * API/code coverage may show the assignment operator as present and
     * untested - ignore.
     * Subclasses need this assignment operator if they use compiler-provided
     * assignment operators of their own. An alternative to not declaring one
     * here would be to declare and empty-implement a protected or public one.
    UMemory &UMemory::operator=(const UMemory &);
     */
};

/**
 * UObject is the common ICU "boilerplate" class.
 * UObject inherits UMemory (starting with ICU 2.4),
 * and all other public ICU C++ classes
 * are derived from UObject (starting with ICU 2.2).
 *
 * UObject contains common virtual functions, in particular a virtual destructor.
 *
 * The clone() function is not available in UObject because it is not
 * implemented by all ICU classes.
 * Many ICU services provide a clone() function for their class trees,
 * defined on the service's C++ base class, and all subclasses within that
 * service class tree return a pointer to the service base class
 * (which itself is a subclass of UObject).
 * This is because some compilers do not support covariant (same-as-this)
 * return types; cast to the appropriate subclass if necessary.
 *
 * @stable ICU 2.2
 */
class U_COMMON_API UObject : public UMemory {
public:
    /**
     * Destructor.
     *
     * @stable ICU 2.2
     */
    virtual ~UObject();

    /**
     * ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.
     * The base class implementation returns a dummy value.
     *
     * Use compiler RTTI rather than ICU's "poor man's RTTI".
     * Since ICU 4.6, new ICU C++ class hierarchies do not implement "poor man's RTTI".
     *
     * @stable ICU 2.2
     */
    virtual UClassID getDynamicClassID() const;

protected:
    // the following functions are protected to prevent instantiation and
    // direct use of UObject itself

    // default constructor
    // inline UObject() {}

    // copy constructor
    // inline UObject(const UObject &other) {}

#if 0
    // TODO Sometime in the future. Implement operator==().
    // (This comment inserted in 2.2)
    // some or all of the following "boilerplate" functions may be made public
    // in a future ICU4C release when all subclasses implement them

    // assignment operator
    // (not virtual, see "Taligent's Guide to Designing Programs" pp.73..74)
    // commented out because the implementation is the same as a compiler's default
    // UObject &operator=(const UObject &other) { return *this; }

    // comparison operators
    virtual inline UBool operator==(const UObject &other) const { return this==&other; }
    inline UBool operator!=(const UObject &other) const { return !operator==(other); }

    // clone() commented out from the base class:
    // some compilers do not support co-variant return types
    // (i.e., subclasses would have to return UObject * as well, instead of SubClass *)
    // see also UObject class documentation.
    // virtual UObject *clone() const;
#endif

    /*
     * Assignment operator not declared. The compiler will provide one
     * which does nothing since this class does not contain any data members.
     * API/code coverage may show the assignment operator as present and
     * untested - ignore.
     * Subclasses need this assignment operator if they use compiler-provided
     * assignment operators of their own. An alternative to not declaring one
     * here would be to declare and empty-implement a protected or public one.
    UObject &UObject::operator=(const UObject &);
     */
};

#ifndef U_HIDE_INTERNAL_API
/**
 * This is a simple macro to add ICU RTTI to an ICU object implementation.
 * This does not go into the header. This should only be used in *.cpp files.
 *
 * @param myClass The name of the class that needs RTTI defined.
 * @internal
 */
#define UOBJECT_DEFINE_RTTI_IMPLEMENTATION(myClass) \
    UClassID U_EXPORT2 myClass::getStaticClassID() { \
        static char classID = 0; \
        return (UClassID)&classID; \
    } \
    UClassID myClass::getDynamicClassID() const \
    { return myClass::getStaticClassID(); }


/**
 * This macro adds ICU RTTI to an ICU abstract class implementation.
 * This macro should be invoked in *.cpp files.  The corresponding
 * header should declare getStaticClassID.
 *
 * @param myClass The name of the class that needs RTTI defined.
 * @internal
 */
#define UOBJECT_DEFINE_ABSTRACT_RTTI_IMPLEMENTATION(myClass) \
    UClassID U_EXPORT2 myClass::getStaticClassID() { \
        static char classID = 0; \
        return (UClassID)&classID; \
    }

#endif  /* U_HIDE_INTERNAL_API */

U_NAMESPACE_END

#endif
Commit	Line	Data
b75a7d8f A	1	/*
	2	******************************************************************************
	3	*
4388f060	4	* Copyright (C) 2002-2012, International Business Machines
b75a7d8f A	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
b75a7d8f A	22	/**
	23	* \file
	24	* \brief C++ API: Common ICU base class UObject.
	25	*/
	26
729e4ab9 A	27	/**
	28	* @{
	29	* \def U_NO_THROW
	30	* Define this to define the throw() specification so
	31	* certain functions do not throw any exceptions
	32	*
	33	* UMemory operator new methods should have the throw() specification
	34	* appended to them, so that the compiler adds the additional NULL check
	35	* before calling constructors. Without, if <code>operator new</code> returns NULL the
	36	* constructor is still called, and if the constructor references member
	37	* data, (which it typically does), the result is a segmentation violation.
	38	*
4388f060 A	39	* @stable ICU 4.2
4388f060 A	40	*/
729e4ab9 A	41	#ifndef U_NO_THROW
	42	#define U_NO_THROW throw()
	43	#endif
	44
	45	/** @} */
	46
4388f060 A	47	/===========================================================================/
	48	/* UClassID-based RTTI */
	49	/===========================================================================/
	50
	51	/**
	52	* UClassID is used to identify classes without using the compiler's RTTI.
	53	* This was used before C++ compilers consistently supported RTTI.
	54	* ICU 4.6 requires compiler RTTI to be turned on.
	55	*
	56	* Each class hierarchy which needs
	57	* to implement polymorphic clone() or operator==() defines two methods,
	58	* described in detail below. UClassID values can be compared using
	59	* operator==(). Nothing else should be done with them.
	60	*
	61	* \par
51004dcb A	62	* In class hierarchies that implement "poor man's RTTI",
51004dcb A	63	* each concrete subclass implements getDynamicClassID() in the same way:
4388f060 A	64	*
4388f060 A	65	* \code
4388f060 A	66	* class Derived {
	67	* public:
	68	* virtual UClassID getDynamicClassID() const
	69	* { return Derived::getStaticClassID(); }
	70	* }
	71	* \endcode
	72	*
	73	* Each concrete class implements getStaticClassID() as well, which allows
	74	* clients to test for a specific type.
	75	*
	76	* \code
	77	* class Derived {
	78	* public:
	79	* static UClassID U_EXPORT2 getStaticClassID();
	80	* private:
	81	* static char fgClassID;
	82	* }
	83	*
	84	* // In Derived.cpp:
	85	* UClassID Derived::getStaticClassID()
	86	* { return (UClassID)&Derived::fgClassID; }
	87	* char Derived::fgClassID = 0; // Value is irrelevant
	88	* \endcode
	89	* @stable ICU 2.0
	90	*/
	91	typedef void* UClassID;
	92
	93	U_NAMESPACE_BEGIN
	94
b75a7d8f A	95	/**
	96	* UMemory is the common ICU base class.
	97	* All other ICU C++ classes are derived from UMemory (starting with ICU 2.4).
	98	*
	99	* This is primarily to make it possible and simple to override the
	100	* C++ memory management by adding new/delete operators to this base class.
	101	*
	102	* To override ALL ICU memory management, including that from plain C code,
	103	* replace the allocation functions declared in cmemory.h
	104	*
	105	* UMemory does not contain any virtual functions.
	106	* Common "boilerplate" functions are defined in UObject.
	107	*
374ca955	108	* @stable ICU 2.4
b75a7d8f A	109	*/
	110	class U_COMMON_API UMemory {
	111	public:
	112
729e4ab9 A	113	/* test versions for debugging shaper heap memory problems */
	114	#ifdef SHAPER_MEMORY_DEBUG
	115	static void * NewArray(int size, int count);
	116	static void * GrowArray(void * array, int newSize );
	117	static void FreeArray(void * array );
	118	#endif
	119
b75a7d8f A	120	#if U_OVERRIDE_CXX_ALLOCATION
	121	/**
	122	* Override for ICU4C C++ memory management.
	123	* simple, non-class types are allocated using the macros in common/cmemory.h
	124	* (uprv_malloc(), uprv_free(), uprv_realloc());
	125	* they or something else could be used here to implement C++ new/delete
	126	* for ICU4C C++ classes
374ca955	127	* @stable ICU 2.4
b75a7d8f	128	*/
729e4ab9	129	static void * U_EXPORT2 operator new(size_t size) U_NO_THROW;
b75a7d8f A	130
	131	/**
	132	* Override for ICU4C C++ memory management.
	133	* See new().
374ca955	134	* @stable ICU 2.4
b75a7d8f	135	*/
729e4ab9	136	static void * U_EXPORT2 operator new[](size_t size) U_NO_THROW;
b75a7d8f A	137
	138	/**
	139	* Override for ICU4C C++ memory management.
	140	* simple, non-class types are allocated using the macros in common/cmemory.h
	141	* (uprv_malloc(), uprv_free(), uprv_realloc());
	142	* they or something else could be used here to implement C++ new/delete
	143	* for ICU4C C++ classes
374ca955	144	* @stable ICU 2.4
b75a7d8f	145	*/
729e4ab9	146	static void U_EXPORT2 operator delete(void *p) U_NO_THROW;
b75a7d8f A	147
	148	/**
	149	* Override for ICU4C C++ memory management.
	150	* See delete().
374ca955	151	* @stable ICU 2.4
b75a7d8f	152	*/
729e4ab9	153	static void U_EXPORT2 operator delete[](void *p) U_NO_THROW;
b75a7d8f A	154
	155	#if U_HAVE_PLACEMENT_NEW
	156	/**
	157	* Override for ICU4C C++ memory management for STL.
	158	* See new().
374ca955	159	* @stable ICU 2.6
b75a7d8f	160	*/
729e4ab9	161	static inline void * U_EXPORT2 operator new(size_t, void *ptr) U_NO_THROW { return ptr; }
b75a7d8f A	162
	163	/**
	164	* Override for ICU4C C++ memory management for STL.
	165	* See delete().
374ca955	166	* @stable ICU 2.6
b75a7d8f	167	*/
729e4ab9	168	static inline void U_EXPORT2 operator delete(void , void ) U_NO_THROW {}
b75a7d8f	169	#endif /* U_HAVE_PLACEMENT_NEW */
73c04bcf A	170	#if U_HAVE_DEBUG_LOCATION_NEW
	171	/**
	172	* This method overrides the MFC debug version of the operator new
	173	*
	174	* @param size The requested memory size
	175	* @param file The file where the allocation was requested
	176	* @param line The line where the allocation was requested
	177	*/
729e4ab9	178	static void * U_EXPORT2 operator new(size_t size, const char* file, int line) U_NO_THROW;
73c04bcf A	179	/**
	180	* This method provides a matching delete for the MFC debug new
	181	*
	182	* @param p The pointer to the allocated memory
	183	* @param file The file where the allocation was requested
	184	* @param line The line where the allocation was requested
	185	*/
729e4ab9	186	static void U_EXPORT2 operator delete(void* p, const char* file, int line) U_NO_THROW;
73c04bcf	187	#endif /* U_HAVE_DEBUG_LOCATION_NEW */
b75a7d8f A	188	#endif /* U_OVERRIDE_CXX_ALLOCATION */
	189
	190	/*
	191	* Assignment operator not declared. The compiler will provide one
	192	* which does nothing since this class does not contain any data members.
	193	* API/code coverage may show the assignment operator as present and
	194	* untested - ignore.
	195	* Subclasses need this assignment operator if they use compiler-provided
	196	* assignment operators of their own. An alternative to not declaring one
	197	* here would be to declare and empty-implement a protected or public one.
	198	UMemory &UMemory::operator=(const UMemory &);
	199	*/
	200	};
	201
	202	/**
	203	* UObject is the common ICU "boilerplate" class.
	204	* UObject inherits UMemory (starting with ICU 2.4),
	205	* and all other public ICU C++ classes
	206	* are derived from UObject (starting with ICU 2.2).
	207	*
51004dcb	208	* UObject contains common virtual functions, in particular a virtual destructor.
b75a7d8f A	209	*
	210	* The clone() function is not available in UObject because it is not
	211	* implemented by all ICU classes.
	212	* Many ICU services provide a clone() function for their class trees,
	213	* defined on the service's C++ base class, and all subclasses within that
	214	* service class tree return a pointer to the service base class
	215	* (which itself is a subclass of UObject).
	216	* This is because some compilers do not support covariant (same-as-this)
	217	* return types; cast to the appropriate subclass if necessary.
	218	*
374ca955	219	* @stable ICU 2.2
b75a7d8f A	220	*/
	221	class U_COMMON_API UObject : public UMemory {
	222	public:
	223	/**
	224	* Destructor.
	225	*
374ca955	226	* @stable ICU 2.2
b75a7d8f	227	*/
374ca955	228	virtual ~UObject();
b75a7d8f A	229
	230	/**
	231	* ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.
51004dcb A	232	* The base class implementation returns a dummy value.
	233	*
	234	* Use compiler RTTI rather than ICU's "poor man's RTTI".
	235	* Since ICU 4.6, new ICU C++ class hierarchies do not implement "poor man's RTTI".
b75a7d8f	236	*
374ca955	237	* @stable ICU 2.2
b75a7d8f	238	*/
51004dcb	239	virtual UClassID getDynamicClassID() const;
b75a7d8f A	240
	241	protected:
	242	// the following functions are protected to prevent instantiation and
	243	// direct use of UObject itself
	244
	245	// default constructor
b75a7d8f A	246	// inline UObject() {}
	247
	248	// copy constructor
b75a7d8f A	249	// inline UObject(const UObject &other) {}
b75a7d8f A	250
374ca955 A	251	#if 0
	252	// TODO Sometime in the future. Implement operator==().
	253	// (This comment inserted in 2.2)
b75a7d8f A	254	// some or all of the following "boilerplate" functions may be made public
	255	// in a future ICU4C release when all subclasses implement them
	256
	257	// assignment operator
	258	// (not virtual, see "Taligent's Guide to Designing Programs" pp.73..74)
	259	// commented out because the implementation is the same as a compiler's default
	260	// UObject &operator=(const UObject &other) { return *this; }
	261
	262	// comparison operators
	263	virtual inline UBool operator==(const UObject &other) const { return this==&other; }
	264	inline UBool operator!=(const UObject &other) const { return !operator==(other); }
	265
	266	// clone() commented out from the base class:
	267	// some compilers do not support co-variant return types
	268	// (i.e., subclasses would have to return UObject * as well, instead of SubClass *)
	269	// see also UObject class documentation.
	270	// virtual UObject *clone() const;
	271	#endif
	272
	273	/*
	274	* Assignment operator not declared. The compiler will provide one
	275	* which does nothing since this class does not contain any data members.
	276	* API/code coverage may show the assignment operator as present and
	277	* untested - ignore.
	278	* Subclasses need this assignment operator if they use compiler-provided
	279	* assignment operators of their own. An alternative to not declaring one
	280	* here would be to declare and empty-implement a protected or public one.
	281	UObject &UObject::operator=(const UObject &);
	282	*/
	283	};
	284
4388f060	285	#ifndef U_HIDE_INTERNAL_API
374ca955 A	286	/**
	287	* This is a simple macro to add ICU RTTI to an ICU object implementation.
	288	* This does not go into the header. This should only be used in *.cpp files.
	289	*
	290	* @param myClass The name of the class that needs RTTI defined.
	291	* @internal
	292	*/
	293	#define UOBJECT_DEFINE_RTTI_IMPLEMENTATION(myClass) \
	294	UClassID U_EXPORT2 myClass::getStaticClassID() { \
73c04bcf	295	static char classID = 0; \
374ca955 A	296	return (UClassID)&classID; \
	297	} \
	298	UClassID myClass::getDynamicClassID() const \
	299	{ return myClass::getStaticClassID(); }
	300
	301
	302	/**
	303	* This macro adds ICU RTTI to an ICU abstract class implementation.
	304	* This macro should be invoked in *.cpp files. The corresponding
	305	* header should declare getStaticClassID.
	306	*
	307	* @param myClass The name of the class that needs RTTI defined.
	308	* @internal
	309	*/
	310	#define UOBJECT_DEFINE_ABSTRACT_RTTI_IMPLEMENTATION(myClass) \
	311	UClassID U_EXPORT2 myClass::getStaticClassID() { \
73c04bcf	312	static char classID = 0; \
374ca955 A	313	return (UClassID)&classID; \
	314	}
	315
4388f060	316	#endif /* U_HIDE_INTERNAL_API */
374ca955	317
b75a7d8f A	318	U_NAMESPACE_END
	319
	320	#endif