1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/errorcode.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,137 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +*
1.7 +* Copyright (C) 2009-2011, International Business Machines
1.8 +* Corporation and others. All Rights Reserved.
1.9 +*
1.10 +*******************************************************************************
1.11 +* file name: errorcode.h
1.12 +* encoding: US-ASCII
1.13 +* tab size: 8 (not used)
1.14 +* indentation:4
1.15 +*
1.16 +* created on: 2009mar10
1.17 +* created by: Markus W. Scherer
1.18 +*/
1.19 +
1.20 +#ifndef __ERRORCODE_H__
1.21 +#define __ERRORCODE_H__
1.22 +
1.23 +/**
1.24 + * \file
1.25 + * \brief C++ API: ErrorCode class intended to make it easier to use
1.26 + * ICU C and C++ APIs from C++ user code.
1.27 + */
1.28 +
1.29 +#include "unicode/utypes.h"
1.30 +#include "unicode/uobject.h"
1.31 +
1.32 +U_NAMESPACE_BEGIN
1.33 +
1.34 +/**
1.35 + * Wrapper class for UErrorCode, with conversion operators for direct use
1.36 + * in ICU C and C++ APIs.
1.37 + * Intended to be used as a base class, where a subclass overrides
1.38 + * the handleFailure() function so that it throws an exception,
1.39 + * does an assert(), logs an error, etc.
1.40 + * This is not an abstract base class. This class can be used and instantiated
1.41 + * by itself, although it will be more useful when subclassed.
1.42 + *
1.43 + * Features:
1.44 + * - The constructor initializes the internal UErrorCode to U_ZERO_ERROR,
1.45 + * removing one common source of errors.
1.46 + * - Same use in C APIs taking a UErrorCode * (pointer)
1.47 + * and C++ taking UErrorCode & (reference) via conversion operators.
1.48 + * - Possible automatic checking for success when it goes out of scope.
1.49 + *
1.50 + * Note: For automatic checking for success in the destructor, a subclass
1.51 + * must implement such logic in its own destructor because the base class
1.52 + * destructor cannot call a subclass function (like handleFailure()).
1.53 + * The ErrorCode base class destructor does nothing.
1.54 + *
1.55 + * Note also: While it is possible for a destructor to throw an exception,
1.56 + * it is generally unsafe to do so. This means that in a subclass the destructor
1.57 + * and the handleFailure() function may need to take different actions.
1.58 + *
1.59 + * Sample code:
1.60 + * \code
1.61 + * class IcuErrorCode: public icu::ErrorCode {
1.62 + * public:
1.63 + * virtual ~IcuErrorCode() { // should be defined in .cpp as "key function"
1.64 + * // Safe because our handleFailure() does not throw exceptions.
1.65 + * if(isFailure()) { handleFailure(); }
1.66 + * }
1.67 + * protected:
1.68 + * virtual void handleFailure() const {
1.69 + * log_failure(u_errorName(errorCode));
1.70 + * exit(errorCode);
1.71 + * }
1.72 + * };
1.73 + * IcuErrorCode error_code;
1.74 + * UConverter *cnv = ucnv_open("Shift-JIS", error_code);
1.75 + * length = ucnv_fromUChars(dest, capacity, src, length, error_code);
1.76 + * ucnv_close(cnv);
1.77 + * // IcuErrorCode destructor checks for success.
1.78 + * \endcode
1.79 + *
1.80 + * @stable ICU 4.2
1.81 + */
1.82 +class U_COMMON_API ErrorCode: public UMemory {
1.83 +public:
1.84 + /**
1.85 + * Default constructor. Initializes its UErrorCode to U_ZERO_ERROR.
1.86 + * @stable ICU 4.2
1.87 + */
1.88 + ErrorCode() : errorCode(U_ZERO_ERROR) {}
1.89 + /** Destructor, does nothing. See class documentation for details. @stable ICU 4.2 */
1.90 + virtual ~ErrorCode();
1.91 + /** Conversion operator, returns a reference. @stable ICU 4.2 */
1.92 + operator UErrorCode & () { return errorCode; }
1.93 + /** Conversion operator, returns a pointer. @stable ICU 4.2 */
1.94 + operator UErrorCode * () { return &errorCode; }
1.95 + /** Tests for U_SUCCESS(). @stable ICU 4.2 */
1.96 + UBool isSuccess() const { return U_SUCCESS(errorCode); }
1.97 + /** Tests for U_FAILURE(). @stable ICU 4.2 */
1.98 + UBool isFailure() const { return U_FAILURE(errorCode); }
1.99 + /** Returns the UErrorCode value. @stable ICU 4.2 */
1.100 + UErrorCode get() const { return errorCode; }
1.101 + /** Sets the UErrorCode value. @stable ICU 4.2 */
1.102 + void set(UErrorCode value) { errorCode=value; }
1.103 + /** Returns the UErrorCode value and resets it to U_ZERO_ERROR. @stable ICU 4.2 */
1.104 + UErrorCode reset();
1.105 + /**
1.106 + * Asserts isSuccess().
1.107 + * In other words, this method checks for a failure code,
1.108 + * and the base class handles it like this:
1.109 + * \code
1.110 + * if(isFailure()) { handleFailure(); }
1.111 + * \endcode
1.112 + * @stable ICU 4.4
1.113 + */
1.114 + void assertSuccess() const;
1.115 + /**
1.116 + * Return a string for the UErrorCode value.
1.117 + * The string will be the same as the name of the error code constant
1.118 + * in the UErrorCode enum.
1.119 + * @stable ICU 4.4
1.120 + */
1.121 + const char* errorName() const;
1.122 +
1.123 +protected:
1.124 + /**
1.125 + * Internal UErrorCode, accessible to subclasses.
1.126 + * @stable ICU 4.2
1.127 + */
1.128 + UErrorCode errorCode;
1.129 + /**
1.130 + * Called by assertSuccess() if isFailure() is true.
1.131 + * A subclass should override this function to deal with a failure code:
1.132 + * Throw an exception, log an error, terminate the program, or similar.
1.133 + * @stable ICU 4.2
1.134 + */
1.135 + virtual void handleFailure() const {}
1.136 +};
1.137 +
1.138 +U_NAMESPACE_END
1.139 +
1.140 +#endif // __ERRORCODE_H__
