Home | History | Annotate | Download | only in unicode 
      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 
     29 U_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  * Inside Google, this class is modified to use Google error logging.
     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      */
     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 
    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      */
    134 
    135     virtual void handleFailure() const {}
    136 };
    137 
    138 U_NAMESPACE_END
    139 
    140 #endif  // __ERRORCODE_H__
    141