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
31U_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 */
81class U_COMMON_API ErrorCode: public UMemory {
82public:
83    /**
84     * Default constructor. Initializes its UErrorCode to U_ZERO_ERROR.
85     * @stable ICU 4.2
86     */
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 */
95    UBool isSuccess() const { return U_SUCCESS(errorCode); }
96    /** Tests for U_FAILURE(). @stable ICU 4.2 */
97    UBool isFailure() const { return U_FAILURE(errorCode); }
98    /** Returns the UErrorCode value. @stable ICU 4.2 */
99    UErrorCode get() const { return errorCode; }
100    /** Sets the UErrorCode value. @stable ICU 4.2 */
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
122protected:
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     */
134    virtual void handleFailure() const {}
135};
136
137U_NAMESPACE_END
138
139#endif  // __ERRORCODE_H__
140