michael@0: /* michael@0: ******************************************************************************* michael@0: * michael@0: * Copyright (C) 2009-2011, International Business Machines michael@0: * Corporation and others. All Rights Reserved. michael@0: * michael@0: ******************************************************************************* michael@0: * file name: errorcode.h michael@0: * encoding: US-ASCII michael@0: * tab size: 8 (not used) michael@0: * indentation:4 michael@0: * michael@0: * created on: 2009mar10 michael@0: * created by: Markus W. Scherer michael@0: */ michael@0: michael@0: #ifndef __ERRORCODE_H__ michael@0: #define __ERRORCODE_H__ michael@0: michael@0: /** michael@0: * \file michael@0: * \brief C++ API: ErrorCode class intended to make it easier to use michael@0: * ICU C and C++ APIs from C++ user code. michael@0: */ michael@0: michael@0: #include "unicode/utypes.h" michael@0: #include "unicode/uobject.h" michael@0: michael@0: U_NAMESPACE_BEGIN michael@0: michael@0: /** michael@0: * Wrapper class for UErrorCode, with conversion operators for direct use michael@0: * in ICU C and C++ APIs. michael@0: * Intended to be used as a base class, where a subclass overrides michael@0: * the handleFailure() function so that it throws an exception, michael@0: * does an assert(), logs an error, etc. michael@0: * This is not an abstract base class. This class can be used and instantiated michael@0: * by itself, although it will be more useful when subclassed. michael@0: * michael@0: * Features: michael@0: * - The constructor initializes the internal UErrorCode to U_ZERO_ERROR, michael@0: * removing one common source of errors. michael@0: * - Same use in C APIs taking a UErrorCode * (pointer) michael@0: * and C++ taking UErrorCode & (reference) via conversion operators. michael@0: * - Possible automatic checking for success when it goes out of scope. michael@0: * michael@0: * Note: For automatic checking for success in the destructor, a subclass michael@0: * must implement such logic in its own destructor because the base class michael@0: * destructor cannot call a subclass function (like handleFailure()). michael@0: * The ErrorCode base class destructor does nothing. michael@0: * michael@0: * Note also: While it is possible for a destructor to throw an exception, michael@0: * it is generally unsafe to do so. This means that in a subclass the destructor michael@0: * and the handleFailure() function may need to take different actions. michael@0: * michael@0: * Sample code: michael@0: * \code michael@0: * class IcuErrorCode: public icu::ErrorCode { michael@0: * public: michael@0: * virtual ~IcuErrorCode() { // should be defined in .cpp as "key function" michael@0: * // Safe because our handleFailure() does not throw exceptions. michael@0: * if(isFailure()) { handleFailure(); } michael@0: * } michael@0: * protected: michael@0: * virtual void handleFailure() const { michael@0: * log_failure(u_errorName(errorCode)); michael@0: * exit(errorCode); michael@0: * } michael@0: * }; michael@0: * IcuErrorCode error_code; michael@0: * UConverter *cnv = ucnv_open("Shift-JIS", error_code); michael@0: * length = ucnv_fromUChars(dest, capacity, src, length, error_code); michael@0: * ucnv_close(cnv); michael@0: * // IcuErrorCode destructor checks for success. michael@0: * \endcode michael@0: * michael@0: * @stable ICU 4.2 michael@0: */ michael@0: class U_COMMON_API ErrorCode: public UMemory { michael@0: public: michael@0: /** michael@0: * Default constructor. Initializes its UErrorCode to U_ZERO_ERROR. michael@0: * @stable ICU 4.2 michael@0: */ michael@0: ErrorCode() : errorCode(U_ZERO_ERROR) {} michael@0: /** Destructor, does nothing. See class documentation for details. @stable ICU 4.2 */ michael@0: virtual ~ErrorCode(); michael@0: /** Conversion operator, returns a reference. @stable ICU 4.2 */ michael@0: operator UErrorCode & () { return errorCode; } michael@0: /** Conversion operator, returns a pointer. @stable ICU 4.2 */ michael@0: operator UErrorCode * () { return &errorCode; } michael@0: /** Tests for U_SUCCESS(). @stable ICU 4.2 */ michael@0: UBool isSuccess() const { return U_SUCCESS(errorCode); } michael@0: /** Tests for U_FAILURE(). @stable ICU 4.2 */ michael@0: UBool isFailure() const { return U_FAILURE(errorCode); } michael@0: /** Returns the UErrorCode value. @stable ICU 4.2 */ michael@0: UErrorCode get() const { return errorCode; } michael@0: /** Sets the UErrorCode value. @stable ICU 4.2 */ michael@0: void set(UErrorCode value) { errorCode=value; } michael@0: /** Returns the UErrorCode value and resets it to U_ZERO_ERROR. @stable ICU 4.2 */ michael@0: UErrorCode reset(); michael@0: /** michael@0: * Asserts isSuccess(). michael@0: * In other words, this method checks for a failure code, michael@0: * and the base class handles it like this: michael@0: * \code michael@0: * if(isFailure()) { handleFailure(); } michael@0: * \endcode michael@0: * @stable ICU 4.4 michael@0: */ michael@0: void assertSuccess() const; michael@0: /** michael@0: * Return a string for the UErrorCode value. michael@0: * The string will be the same as the name of the error code constant michael@0: * in the UErrorCode enum. michael@0: * @stable ICU 4.4 michael@0: */ michael@0: const char* errorName() const; michael@0: michael@0: protected: michael@0: /** michael@0: * Internal UErrorCode, accessible to subclasses. michael@0: * @stable ICU 4.2 michael@0: */ michael@0: UErrorCode errorCode; michael@0: /** michael@0: * Called by assertSuccess() if isFailure() is true. michael@0: * A subclass should override this function to deal with a failure code: michael@0: * Throw an exception, log an error, terminate the program, or similar. michael@0: * @stable ICU 4.2 michael@0: */ michael@0: virtual void handleFailure() const {} michael@0: }; michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif // __ERRORCODE_H__