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