1/*
2*******************************************************************************
3*
4*   Copyright (C) 2009-2011, International Business Machines
5*   Corporation and others.  All Rights Reserved.
6*
7*******************************************************************************
8*   file name:  errorcode.h
9*   encoding:   US-ASCII
10*   tab size:   8 (not used)
11*   indentation:4
12*
13*   created on: 2009mar10
14*   created by: Markus W. Scherer
15*/
16
17#ifndef __ERRORCODE_H__
18#define __ERRORCODE_H__
19
20/**
21 * \file
22 * \brief C++ API: ErrorCode class intended to make it easier to use
23 *                 ICU C and C++ APIs from C++ user code.
24 */
25
26#include "unicode/utypes.h"
27#include "unicode/uobject.h"
28
29U_NAMESPACE_BEGIN
30
31/**
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.
39 *
40 * Features:
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.
46 *
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.
51 *
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.
55 *
56 * Sample code:
57 * \code
58 *   class IcuErrorCode: public icu::ErrorCode {
59 *   public:
60 *     virtual ~IcuErrorCode() {  // should be defined in .cpp as "key function"
61 *       // Safe because our handleFailure() does not throw exceptions.
62 *       if(isFailure()) { handleFailure(); }
63 *     }
64 *   protected:
65 *     virtual void handleFailure() const {
66 *       log_failure(u_errorName(errorCode));
67 *       exit(errorCode);
68 *     }
69 *   };
70 *   IcuErrorCode error_code;
71 *   UConverter *cnv = ucnv_open("Shift-JIS", error_code);
72 *   length = ucnv_fromUChars(dest, capacity, src, length, error_code);
73 *   ucnv_close(cnv);
74 *   // IcuErrorCode destructor checks for success.
75 * \endcode
76 *
77 * @stable ICU 4.2
78 */
79class U_COMMON_API ErrorCode: public UMemory {
80public:
81    /**
82     * Default constructor. Initializes its UErrorCode to U_ZERO_ERROR.
83     * @stable ICU 4.2
84     */
85    ErrorCode() : errorCode(U_ZERO_ERROR) {}
86    /** Destructor, does nothing. See class documentation for details. @stable ICU 4.2 */
87    virtual ~ErrorCode();
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 */
101    UErrorCode reset();
102    /**
103     * Asserts isSuccess().
104     * In other words, this method checks for a failure code,
105     * and the base class handles it like this:
106     * \code
107     *   if(isFailure()) { handleFailure(); }
108     * \endcode
109     * @stable ICU 4.4
110     */
111    void assertSuccess() const;
112    /**
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.
116     * @stable ICU 4.4
117     */
118    const char* errorName() const;
119
120protected:
121    /**
122     * Internal UErrorCode, accessible to subclasses.
123     * @stable ICU 4.2
124     */
125    UErrorCode errorCode;
126    /**
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.
130     * @stable ICU 4.2
131     */
132    virtual void handleFailure() const {}
133};
134
135U_NAMESPACE_END
136
137#endif  // __ERRORCODE_H__
138