ICU4C and Binary Compatibility

The C++ language does not have a stable ABI. This means that there is no guarantee of binary compatibility between compilers, or even between the same compiler but with different build options or configurations.

Due to this the version of ICU4C that is part of the Windows operating system only exposes the C APIs. It does not expose any of the C++ APIs.

However, beyond the C versus C++ API and ABI issues, the ICU4C project also has the notion of "public" and "non-public" API, as well as "internal" and "draft" APIs.

The non-public (or internal) APIs are never intended to be used by external applications and should be completely avoided.

The "draft" APIs are part of the ICU API design process: New APIs are initially created as "draft", and after a period of time (minimum of one public release), the new API could be promoted to "stable" status.

However, not all "draft" APIs will become stable, and some may even be removed or changed entirely. Due to this applications should avoid using any "draft" APIs wherever possible.

Quoting from the ICU Design Docs:

A draft API is not guaranteed to be stable! Although we will not make gratuitous changes, sometimes the draft APIs turns out to be unsatisfactory in actual practice and may need to be changed or even removed.

The Windows SDK requires binary compatibility between versions, so all draft APIs are completely excluded from being exposed.

For applications that use the public version of ICU, or use the public header files, and wish to avoid potential breakage when updating to newer versions, it is recommended to set the following flags/defines before including any ICU4C headers.

// Set the following defines before including any ICU headers.

#define U_SHOW_CPLUSPLUS_API 0
#define U_DEFAULT_SHOW_DRAFT 0
#define U_HIDE_DRAFT_API 1
#define U_HIDE_DEPRECATED_API 1
#define U_HIDE_OBSOLETE_API 1
#define U_HIDE_INTERNAL_API 1


// Now include the ICU headers.
// For example: 
#include "unicode/uloc.h"