include/unicode/errorcode.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 *******************************************************************************
0005 *
0006 *   Copyright (C) 2009-2011, International Business Machines
0007 *   Corporation and others.  All Rights Reserved.
0008 *
0009 *******************************************************************************
0010 *   file name:  errorcode.h
0011 *   encoding:   UTF-8
0012 *   tab size:   8 (not used)
0013 *   indentation:4
0014 *
0015 *   created on: 2009mar10
0016 *   created by: Markus W. Scherer
0017 */
0018
0019 #ifndef __ERRORCODE_H__
0020 #define __ERRORCODE_H__
0021
0022 /**
0023  * \file
0024  * \brief C++ API: ErrorCode class intended to make it easier to use
0025  *                 ICU C and C++ APIs from C++ user code.
0026  */
0027
0028 #include "unicode/utypes.h"
0029
0030 #if U_SHOW_CPLUSPLUS_API
0031
0032 #include "unicode/uobject.h"
0033
0034 U_NAMESPACE_BEGIN
0035
0036 /**
0037  * Wrapper class for UErrorCode, with conversion operators for direct use
0038  * in ICU C and C++ APIs.
0039  * Intended to be used as a base class, where a subclass overrides
0040  * the handleFailure() function so that it throws an exception,
0041  * does an assert(), logs an error, etc.
0042  * This is not an abstract base class. This class can be used and instantiated
0043  * by itself, although it will be more useful when subclassed.
0044  *
0045  * Features:
0046  * - The constructor initializes the internal UErrorCode to U_ZERO_ERROR,
0047  *   removing one common source of errors.
0048  * - Same use in C APIs taking a UErrorCode * (pointer)
0049  *   and C++ taking UErrorCode & (reference) via conversion operators.
0050  * - Possible automatic checking for success when it goes out of scope.
0051  *
0052  * Note: For automatic checking for success in the destructor, a subclass
0053  * must implement such logic in its own destructor because the base class
0054  * destructor cannot call a subclass function (like handleFailure()).
0055  * The ErrorCode base class destructor does nothing.
0056  *
0057  * Note also: While it is possible for a destructor to throw an exception,
0058  * it is generally unsafe to do so. This means that in a subclass the destructor
0059  * and the handleFailure() function may need to take different actions.
0060  *
0061  * Sample code:
0062  * \code
0063  *   class IcuErrorCode: public icu::ErrorCode {
0064  *   public:
0065  *     virtual ~IcuErrorCode() {  // should be defined in .cpp as "key function"
0066  *       // Safe because our handleFailure() does not throw exceptions.
0067  *       if(isFailure()) { handleFailure(); }
0068  *     }
0069  *   protected:
0070  *     virtual void handleFailure() const {
0071  *       log_failure(u_errorName(errorCode));
0072  *       exit(errorCode);
0073  *     }
0074  *   };
0075  *   IcuErrorCode error_code;
0076  *   UConverter *cnv = ucnv_open("Shift-JIS", error_code);
0077  *   length = ucnv_fromUChars(dest, capacity, src, length, error_code);
0078  *   ucnv_close(cnv);
0079  *   // IcuErrorCode destructor checks for success.
0080  * \endcode
0081  *
0082  * @stable ICU 4.2
0083  */
0084 class U_COMMON_API ErrorCode: public UMemory {
0085 public:
0086     /**
0087      * Default constructor. Initializes its UErrorCode to U_ZERO_ERROR.
0088      * @stable ICU 4.2
0089      */
0090     ErrorCode() : errorCode(U_ZERO_ERROR) {}
0091     /** Destructor, does nothing. See class documentation for details. @stable ICU 4.2 */
0092     virtual ~ErrorCode();
0093     /** Conversion operator, returns a reference. @stable ICU 4.2 */
0094     operator UErrorCode & () { return errorCode; }
0095     /** Conversion operator, returns a pointer. @stable ICU 4.2 */
0096     operator UErrorCode * () { return &errorCode; }
0097     /** Tests for U_SUCCESS(). @stable ICU 4.2 */
0098     UBool isSuccess() const { return U_SUCCESS(errorCode); }
0099     /** Tests for U_FAILURE(). @stable ICU 4.2 */
0100     UBool isFailure() const { return U_FAILURE(errorCode); }
0101     /** Returns the UErrorCode value. @stable ICU 4.2 */
0102     UErrorCode get() const { return errorCode; }
0103     /** Sets the UErrorCode value. @stable ICU 4.2 */
0104     void set(UErrorCode value) { errorCode=value; }
0105     /** Returns the UErrorCode value and resets it to U_ZERO_ERROR. @stable ICU 4.2 */
0106     UErrorCode reset();
0107     /**
0108      * Asserts isSuccess().
0109      * In other words, this method checks for a failure code,
0110      * and the base class handles it like this:
0111      * \code
0112      *   if(isFailure()) { handleFailure(); }
0113      * \endcode
0114      * @stable ICU 4.4
0115      */
0116     void assertSuccess() const;
0117     /**
0118      * Return a string for the UErrorCode value.
0119      * The string will be the same as the name of the error code constant
0120      * in the UErrorCode enum.
0121      * @stable ICU 4.4
0122      */
0123     const char* errorName() const;
0124
0125 protected:
0126     /**
0127      * Internal UErrorCode, accessible to subclasses.
0128      * @stable ICU 4.2
0129      */
0130     UErrorCode errorCode;
0131     /**
0132      * Called by assertSuccess() if isFailure() is true.
0133      * A subclass should override this function to deal with a failure code:
0134      * Throw an exception, log an error, terminate the program, or similar.
0135      * @stable ICU 4.2
0136      */
0137     virtual void handleFailure() const {}
0138 };
0139
0140 U_NAMESPACE_END
0141
0142 #endif /* U_SHOW_CPLUSPLUS_API */
0143
0144 #endif  // __ERRORCODE_H__