]>
git.saurik.com Git - apple/icu.git/blob - icuSources/common/unicode/errorcode.h
2 *******************************************************************************
4 * Copyright (C) 2009-2011, International Business Machines
5 * Corporation and others. All Rights Reserved.
7 *******************************************************************************
8 * file name: errorcode.h
10 * tab size: 8 (not used)
13 * created on: 2009mar10
14 * created by: Markus W. Scherer
17 #ifndef __ERRORCODE_H__
18 #define __ERRORCODE_H__
22 * \brief C++ API: ErrorCode class intended to make it easier to use
23 * ICU C and C++ APIs from C++ user code.
26 #include "unicode/utypes.h"
27 #include "unicode/uobject.h"
32 * Wrapper class for UErrorCode, with conversion operators for direct use
33 * in ICU C and C++ APIs.
34 * Intended to be used as a base class, where a subclass overrides
35 * the handleFailure() function so that it throws an exception,
36 * does an assert(), logs an error, etc.
37 * This is not an abstract base class. This class can be used and instantiated
38 * by itself, although it will be more useful when subclassed.
41 * - The constructor initializes the internal UErrorCode to U_ZERO_ERROR,
42 * removing one common source of errors.
43 * - Same use in C APIs taking a UErrorCode * (pointer)
44 * and C++ taking UErrorCode & (reference) via conversion operators.
45 * - Possible automatic checking for success when it goes out of scope.
47 * Note: For automatic checking for success in the destructor, a subclass
48 * must implement such logic in its own destructor because the base class
49 * destructor cannot call a subclass function (like handleFailure()).
50 * The ErrorCode base class destructor does nothing.
52 * Note also: While it is possible for a destructor to throw an exception,
53 * it is generally unsafe to do so. This means that in a subclass the destructor
54 * and the handleFailure() function may need to take different actions.
58 * class IcuErrorCode: public icu::ErrorCode {
60 * virtual ~IcuErrorCode() { // should be defined in .cpp as "key function"
61 * // Safe because our handleFailure() does not throw exceptions.
62 * if(isFailure()) { handleFailure(); }
65 * virtual void handleFailure() const {
66 * log_failure(u_errorName(errorCode));
70 * IcuErrorCode error_code;
71 * UConverter *cnv = ucnv_open("Shift-JIS", error_code);
72 * length = ucnv_fromUChars(dest, capacity, src, length, error_code);
74 * // IcuErrorCode destructor checks for success.
79 class U_COMMON_API ErrorCode
: public UMemory
{
82 * Default constructor. Initializes its UErrorCode to U_ZERO_ERROR.
85 ErrorCode() : errorCode(U_ZERO_ERROR
) {}
86 /** Destructor, does nothing. See class documentation for details. @stable ICU 4.2 */
88 /** Conversion operator, returns a reference. @stable ICU 4.2 */
89 operator UErrorCode
& () { return errorCode
; }
90 /** Conversion operator, returns a pointer. @stable ICU 4.2 */
91 operator UErrorCode
* () { return &errorCode
; }
92 /** Tests for U_SUCCESS(). @stable ICU 4.2 */
93 UBool
isSuccess() const { return U_SUCCESS(errorCode
); }
94 /** Tests for U_FAILURE(). @stable ICU 4.2 */
95 UBool
isFailure() const { return U_FAILURE(errorCode
); }
96 /** Returns the UErrorCode value. @stable ICU 4.2 */
97 UErrorCode
get() const { return errorCode
; }
98 /** Sets the UErrorCode value. @stable ICU 4.2 */
99 void set(UErrorCode value
) { errorCode
=value
; }
100 /** Returns the UErrorCode value and resets it to U_ZERO_ERROR. @stable ICU 4.2 */
103 * Asserts isSuccess().
104 * In other words, this method checks for a failure code,
105 * and the base class handles it like this:
107 * if(isFailure()) { handleFailure(); }
111 void assertSuccess() const;
113 * Return a string for the UErrorCode value.
114 * The string will be the same as the name of the error code constant
115 * in the UErrorCode enum.
118 const char* errorName() const;
122 * Internal UErrorCode, accessible to subclasses.
125 UErrorCode errorCode
;
127 * Called by assertSuccess() if isFailure() is true.
128 * A subclass should override this function to deal with a failure code:
129 * Throw an exception, log an error, terminate the program, or similar.
132 virtual void handleFailure() const {}
137 #endif // __ERRORCODE_H__