• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 *******************************************************************************
5 *
6 *   Copyright (C) 2009-2011, International Business Machines
7 *   Corporation and others.  All Rights Reserved.
8 *
9 *******************************************************************************
10 *   file name:  errorcode.h
11 *   encoding:   UTF-8
12 *   tab size:   8 (not used)
13 *   indentation:4
14 *
15 *   created on: 2009mar10
16 *   created by: Markus W. Scherer
17 */
18 
19 #ifndef __ERRORCODE_H__
20 #define __ERRORCODE_H__
21 
22 /**
23  * \file
24  * \brief C++ API: ErrorCode class intended to make it easier to use
25  *                 ICU C and C++ APIs from C++ user code.
26  */
27 
28 #include "unicode/utypes.h"
29 #include "unicode/uobject.h"
30 
31 U_NAMESPACE_BEGIN
32 
33 /**
34  * Wrapper class for UErrorCode, with conversion operators for direct use
35  * in ICU C and C++ APIs.
36  * Intended to be used as a base class, where a subclass overrides
37  * the handleFailure() function so that it throws an exception,
38  * does an assert(), logs an error, etc.
39  * This is not an abstract base class. This class can be used and instantiated
40  * by itself, although it will be more useful when subclassed.
41  *
42  * Features:
43  * - The constructor initializes the internal UErrorCode to U_ZERO_ERROR,
44  *   removing one common source of errors.
45  * - Same use in C APIs taking a UErrorCode * (pointer)
46  *   and C++ taking UErrorCode & (reference) via conversion operators.
47  * - Possible automatic checking for success when it goes out of scope.
48  *
49  * Note: For automatic checking for success in the destructor, a subclass
50  * must implement such logic in its own destructor because the base class
51  * destructor cannot call a subclass function (like handleFailure()).
52  * The ErrorCode base class destructor does nothing.
53  *
54  * Note also: While it is possible for a destructor to throw an exception,
55  * it is generally unsafe to do so. This means that in a subclass the destructor
56  * and the handleFailure() function may need to take different actions.
57  *
58  * Sample code:
59  * \code
60  *   class IcuErrorCode: public icu::ErrorCode {
61  *   public:
62  *     virtual ~IcuErrorCode() {  // should be defined in .cpp as "key function"
63  *       // Safe because our handleFailure() does not throw exceptions.
64  *       if(isFailure()) { handleFailure(); }
65  *     }
66  *   protected:
67  *     virtual void handleFailure() const {
68  *       log_failure(u_errorName(errorCode));
69  *       exit(errorCode);
70  *     }
71  *   };
72  *   IcuErrorCode error_code;
73  *   UConverter *cnv = ucnv_open("Shift-JIS", error_code);
74  *   length = ucnv_fromUChars(dest, capacity, src, length, error_code);
75  *   ucnv_close(cnv);
76  *   // IcuErrorCode destructor checks for success.
77  * \endcode
78  *
79  * @stable ICU 4.2
80  */
81 class U_COMMON_API ErrorCode: public UMemory {
82 public:
83     /**
84      * Default constructor. Initializes its UErrorCode to U_ZERO_ERROR.
85      * @stable ICU 4.2
86      */
ErrorCode()87     ErrorCode() : errorCode(U_ZERO_ERROR) {}
88     /** Destructor, does nothing. See class documentation for details. @stable ICU 4.2 */
89     virtual ~ErrorCode();
90     /** Conversion operator, returns a reference. @stable ICU 4.2 */
91     operator UErrorCode & () { return errorCode; }
92     /** Conversion operator, returns a pointer. @stable ICU 4.2 */
93     operator UErrorCode * () { return &errorCode; }
94     /** Tests for U_SUCCESS(). @stable ICU 4.2 */
isSuccess()95     UBool isSuccess() const { return U_SUCCESS(errorCode); }
96     /** Tests for U_FAILURE(). @stable ICU 4.2 */
isFailure()97     UBool isFailure() const { return U_FAILURE(errorCode); }
98     /** Returns the UErrorCode value. @stable ICU 4.2 */
get()99     UErrorCode get() const { return errorCode; }
100     /** Sets the UErrorCode value. @stable ICU 4.2 */
set(UErrorCode value)101     void set(UErrorCode value) { errorCode=value; }
102     /** Returns the UErrorCode value and resets it to U_ZERO_ERROR. @stable ICU 4.2 */
103     UErrorCode reset();
104     /**
105      * Asserts isSuccess().
106      * In other words, this method checks for a failure code,
107      * and the base class handles it like this:
108      * \code
109      *   if(isFailure()) { handleFailure(); }
110      * \endcode
111      * @stable ICU 4.4
112      */
113     void assertSuccess() const;
114     /**
115      * Return a string for the UErrorCode value.
116      * The string will be the same as the name of the error code constant
117      * in the UErrorCode enum.
118      * @stable ICU 4.4
119      */
120     const char* errorName() const;
121 
122 protected:
123     /**
124      * Internal UErrorCode, accessible to subclasses.
125      * @stable ICU 4.2
126      */
127     UErrorCode errorCode;
128     /**
129      * Called by assertSuccess() if isFailure() is true.
130      * A subclass should override this function to deal with a failure code:
131      * Throw an exception, log an error, terminate the program, or similar.
132      * @stable ICU 4.2
133      */
handleFailure()134     virtual void handleFailure() const {}
135 };
136 
137 U_NAMESPACE_END
138 
139 #endif  // __ERRORCODE_H__
140