icuSources/common/unicode/errorcode.h

   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 #if U_SHOW_CPLUSPLUS_API
  32 U_NAMESPACE_BEGIN
  33
  34 /**
  35  * Wrapper class for UErrorCode, with conversion operators for direct use
  36  * in ICU C and C++ APIs.
  37  * Intended to be used as a base class, where a subclass overrides
  38  * the handleFailure() function so that it throws an exception,
  39  * does an assert(), logs an error, etc.
  40  * This is not an abstract base class. This class can be used and instantiated
  41  * by itself, although it will be more useful when subclassed.
  42  *
  43  * Features:
  44  * - The constructor initializes the internal UErrorCode to U_ZERO_ERROR,
  45  *   removing one common source of errors.
  46  * - Same use in C APIs taking a UErrorCode * (pointer)
  47  *   and C++ taking UErrorCode & (reference) via conversion operators.
  48  * - Possible automatic checking for success when it goes out of scope.
  49  *
  50  * Note: For automatic checking for success in the destructor, a subclass
  51  * must implement such logic in its own destructor because the base class
  52  * destructor cannot call a subclass function (like handleFailure()).
  53  * The ErrorCode base class destructor does nothing.
  54  *
  55  * Note also: While it is possible for a destructor to throw an exception,
  56  * it is generally unsafe to do so. This means that in a subclass the destructor
  57  * and the handleFailure() function may need to take different actions.
  58  *
  59  * Sample code:
  60  * \code
  61  *   class IcuErrorCode: public icu::ErrorCode {
  62  *   public:
  63  *     virtual ~IcuErrorCode() {  // should be defined in .cpp as "key function"
  64  *       // Safe because our handleFailure() does not throw exceptions.
  65  *       if(isFailure()) { handleFailure(); }
  66  *     }
  67  *   protected:
  68  *     virtual void handleFailure() const {
  69  *       log_failure(u_errorName(errorCode));
  70  *       exit(errorCode);
  71  *     }
  72  *   };
  73  *   IcuErrorCode error_code;
  74  *   UConverter *cnv = ucnv_open("Shift-JIS", error_code);
  75  *   length = ucnv_fromUChars(dest, capacity, src, length, error_code);
  76  *   ucnv_close(cnv);
  77  *   // IcuErrorCode destructor checks for success.
  78  * \endcode
  79  *
  80  * @stable ICU 4.2
  81  */
  82 class U_COMMON_API ErrorCode: public UMemory {
  83 public:
  84     /**
  85      * Default constructor. Initializes its UErrorCode to U_ZERO_ERROR.
  86      * @stable ICU 4.2
  87      */
  88     ErrorCode() : errorCode(U_ZERO_ERROR) {}
  89     /** Destructor, does nothing. See class documentation for details. @stable ICU 4.2 */
  90     virtual ~ErrorCode();
  91     /** Conversion operator, returns a reference. @stable ICU 4.2 */
  92     operator UErrorCode & () { return errorCode; }
  93     /** Conversion operator, returns a pointer. @stable ICU 4.2 */
  94     operator UErrorCode * () { return &errorCode; }
  95     /** Tests for U_SUCCESS(). @stable ICU 4.2 */
  96     UBool isSuccess() const { return U_SUCCESS(errorCode); }
  97     /** Tests for U_FAILURE(). @stable ICU 4.2 */
  98     UBool isFailure() const { return U_FAILURE(errorCode); }
  99     /** Returns the UErrorCode value. @stable ICU 4.2 */
 100     UErrorCode get() const { return errorCode; }
 101     /** Sets the UErrorCode value. @stable ICU 4.2 */
 102     void set(UErrorCode value) { errorCode=value; }
 103     /** Returns the UErrorCode value and resets it to U_ZERO_ERROR. @stable ICU 4.2 */
 104     UErrorCode reset();
 105     /**
 106      * Asserts isSuccess().
 107      * In other words, this method checks for a failure code,
 108      * and the base class handles it like this:
 109      * \code
 110      *   if(isFailure()) { handleFailure(); }
 111      * \endcode
 112      * @stable ICU 4.4
 113      */
 114     void assertSuccess() const;
 115     /**
 116      * Return a string for the UErrorCode value.
 117      * The string will be the same as the name of the error code constant
 118      * in the UErrorCode enum.
 119      * @stable ICU 4.4
 120      */
 121     const char* errorName() const;
 122
 123 protected:
 124     /**
 125      * Internal UErrorCode, accessible to subclasses.
 126      * @stable ICU 4.2
 127      */
 128     UErrorCode errorCode;
 129     /**
 130      * Called by assertSuccess() if isFailure() is true.
 131      * A subclass should override this function to deal with a failure code:
 132      * Throw an exception, log an error, terminate the program, or similar.
 133      * @stable ICU 4.2
 134      */
 135     virtual void handleFailure() const {}
 136 };
 137
 138 U_NAMESPACE_END
 139 #endif // U_SHOW_CPLUSPLUS_API
 140
 141 #endif  // __ERRORCODE_H__