ICU 76.1: icu::ErrorCode Class Reference

ICU 76.1 76.1

Public Member Functions | Protected Member Functions | Protected Attributes
icu::ErrorCode Class Reference

Wrapper class for UErrorCode, with conversion operators for direct use in ICU C and C++ APIs. More...

`#include <errorcode.h>`

Inheritance diagram for icu::ErrorCode:

## Public Member Functions
| ErrorCode ()
| Default constructor.
virtual | ~ErrorCode ()
| Destructor, does nothing.
| operator UErrorCode & ()
| Conversion operator, returns a reference.
| operator UErrorCode * ()
| Conversion operator, returns a pointer.
UBool | isSuccess () const
| Tests for U_SUCCESS().
UBool | isFailure () const
| Tests for U_FAILURE().
UErrorCode | get () const
| Returns the UErrorCode value.
void | set (UErrorCode value)
| Sets the UErrorCode value.
UErrorCode | reset ()
| Returns the UErrorCode value and resets it to U_ZERO_ERROR.
void | assertSuccess () const
| Asserts isSuccess().
const char * | errorName () const
| Return a string for the UErrorCode value.

## Protected Member Functions
virtual void | handleFailure () const
| Called by assertSuccess() if isFailure() is true.

## Protected Attributes
UErrorCode | errorCode
| Internal UErrorCode, accessible to subclasses.

## Detailed Description

Wrapper class for UErrorCode, with conversion operators for direct use in ICU C and C++ APIs.

Intended to be used as a base class, where a subclass overrides the handleFailure() function so that it throws an exception, does an assert(), logs an error, etc. This is not an abstract base class. This class can be used and instantiated by itself, although it will be more useful when subclassed.

Features:

- The constructor initializes the internal UErrorCode to U_ZERO_ERROR, removing one common source of errors.
- Same use in C APIs taking a UErrorCode * (pointer) and C++ taking UErrorCode & (reference) via conversion operators.
- Possible automatic checking for success when it goes out of scope.

Note: For automatic checking for success in the destructor, a subclass must implement such logic in its own destructor because the base class destructor cannot call a subclass function (like handleFailure()). The ErrorCode base class destructor does nothing.

Note also: While it is possible for a destructor to throw an exception, it is generally unsafe to do so. This means that in a subclass the destructor and the handleFailure() function may need to take different actions.

Sample code:

class IcuErrorCode: public icu::ErrorCode {
public:
virtual ~IcuErrorCode() { // should be defined in .cpp as "key function"
// Safe because our handleFailure() does not throw exceptions.
if(isFailure()) { handleFailure(); }
}
protected:
virtual void handleFailure() const {
log_failure(u_errorName(errorCode));
exit(errorCode);
}
};
IcuErrorCode error_code;
UConverter *cnv = ucnv_open("Shift-JIS", error_code);
length = ucnv_fromUChars(dest, capacity, src, length, error_code);
ucnv_close(cnv);
// IcuErrorCode destructor checks for success.
icu::ErrorCode
Wrapper class for UErrorCode, with conversion operators for direct use in ICU C and C++ APIs.
Definition errorcode.h:84
icu::ErrorCode::isFailure
UBool isFailure() const
Tests for U_FAILURE().
Definition errorcode.h:100
icu::ErrorCode::handleFailure
virtual void handleFailure() const
Called by assertSuccess() if isFailure() is true.
Definition errorcode.h:137
icu::ErrorCode::errorCode
UErrorCode errorCode
Internal UErrorCode, accessible to subclasses.
Definition errorcode.h:130
ucnv_fromUChars
U_CAPI int32_t ucnv_fromUChars(UConverter *cnv, char *dest, int32_t destCapacity, const UChar *src, int32_t srcLength, UErrorCode *pErrorCode)
Convert the Unicode string into a codepage string using an existing UConverter.
ucnv_open
U_CAPI UConverter * ucnv_open(const char *converterName, UErrorCode *err)
Creates a UConverter object with the name of a coded character set specified as a C string.
ucnv_close
U_CAPI void ucnv_close(UConverter *converter)
Deletes the unicode converter and releases resources associated with just this instance.
UConverter
struct UConverter UConverter
Definition ucnv_err.h:96
u_errorName
U_CAPI const char * u_errorName(UErrorCode code)
Return a string for a UErrorCode value.

Stable
  ICU 4.2

Definition at line 84 of file errorcode.h.

## Constructor & Destructor Documentation

## ◆ ErrorCode()

icu::ErrorCode::ErrorCode | ( |  | ) |
| inline

Default constructor.

Initializes its UErrorCode to U_ZERO_ERROR.

Stable
  ICU 4.2

Definition at line 90 of file errorcode.h.

## ◆ ~ErrorCode()

virtual icu::ErrorCode::~ErrorCode | ( |  | ) |
| virtual

Destructor, does nothing.

See class documentation for details.

Stable
  ICU 4.2

## Member Function Documentation

## ◆ assertSuccess()

void icu::ErrorCode::assertSuccess | ( |  | ) | const

Asserts isSuccess().

In other words, this method checks for a failure code, and the base class handles it like this:

if(isFailure()) { handleFailure(); }

Stable
  ICU 4.4

## ◆ errorName()

const char * icu::ErrorCode::errorName | ( |  | ) | const

Return a string for the UErrorCode value.

The string will be the same as the name of the error code constant in the UErrorCode enum.

Stable
  ICU 4.4

## ◆ get()

UErrorCode icu::ErrorCode::get | ( |  | ) | const
| inline

Returns the UErrorCode value.

Stable
  ICU 4.2

Definition at line 102 of file errorcode.h.

## ◆ handleFailure()

virtual void icu::ErrorCode::handleFailure | ( |  | ) | const
| inlineprotectedvirtual

Called by assertSuccess() if isFailure() is true.

A subclass should override this function to deal with a failure code: Throw an exception, log an error, terminate the program, or similar.

Stable
  ICU 4.2

Definition at line 137 of file errorcode.h.

## ◆ isFailure()

UBool icu::ErrorCode::isFailure | ( |  | ) | const
| inline

Tests for U_FAILURE().

Stable
  ICU 4.2

Definition at line 100 of file errorcode.h.

References U_FAILURE.

## ◆ isSuccess()

UBool icu::ErrorCode::isSuccess | ( |  | ) | const
| inline

Tests for U_SUCCESS().

Stable
  ICU 4.2

Definition at line 98 of file errorcode.h.

References U_SUCCESS.

## ◆ operator UErrorCode &()

icu::ErrorCode::operator UErrorCode & | ( |  | ) |
| inline

Conversion operator, returns a reference.

Stable
  ICU 4.2

Definition at line 94 of file errorcode.h.

## ◆ operator UErrorCode *()

icu::ErrorCode::operator UErrorCode * | ( |  | ) |
| inline

Conversion operator, returns a pointer.

Stable
  ICU 4.2

Definition at line 96 of file errorcode.h.

## ◆ reset()

UErrorCode icu::ErrorCode::reset | ( |  | ) |

Returns the UErrorCode value and resets it to U_ZERO_ERROR.

Stable
  ICU 4.2

## ◆ set()

void icu::ErrorCode::set | ( | UErrorCode | value | ) |
| inline

Sets the UErrorCode value.

Stable
  ICU 4.2

Definition at line 104 of file errorcode.h.

## Field Documentation

## ◆ errorCode

UErrorCode icu::ErrorCode::errorCode
| protected

Internal UErrorCode, accessible to subclasses.

Stable
  ICU 4.2

Definition at line 130 of file errorcode.h.

The documentation for this class was generated from the following file:

- common/unicode/errorcode.h