ICU-22435 Add C API for Locale

See #2531

icu4c/source/common/BUILD.bazel

@@ -609,6 +609,7 @@ cc_library(
         "uloc.cpp",
         "uloc_tag.cpp",
         "uloc_keytype.cpp",
+        "ulocale.cpp",
         "ulocbuilder.cpp",
         "uresbund.cpp",
         "uresdata.cpp",

icu4c/source/common/common.vcxproj

@@ -186,6 +186,7 @@
     <ClCompile Include="ucat.cpp" />
     <ClCompile Include="uloc.cpp" />
     <ClCompile Include="uloc_tag.cpp" />
+    <ClCompile Include="ulocale.cpp" />
     <ClCompile Include="ures_cnv.cpp" />
     <ClCompile Include="uresbund.cpp" />
     <ClCompile Include="uresdata.cpp" />

icu4c/source/common/common.vcxproj.filters

@@ -376,6 +376,9 @@
     <ClCompile Include="uloc_tag.cpp">
       <Filter>locales &amp; resources</Filter>
     </ClCompile>
+    <ClCompile Include="ulocale.cpp">
+      <Filter>locales &amp; resources</Filter>
+    </ClCompile>
     <ClCompile Include="ures_cnv.cpp">
       <Filter>locales &amp; resources</Filter>
     </ClCompile>
@@ -1153,6 +1156,9 @@
     <CustomBuild Include="unicode\uloc.h">
       <Filter>locales &amp; resources</Filter>
     </CustomBuild>
+    <CustomBuild Include="unicode\ulocale.h">
+      <Filter>locales &amp; resources</Filter>
+    </CustomBuild>
     <CustomBuild Include="unicode\ures.h">
       <Filter>locales &amp; resources</Filter>
     </CustomBuild>

icu4c/source/common/common_uwp.vcxproj

@@ -320,6 +320,7 @@
     <ClCompile Include="ucat.cpp" />
     <ClCompile Include="uloc.cpp" />
     <ClCompile Include="uloc_tag.cpp" />
+    <ClCompile Include="ulocale.cpp" />
     <ClCompile Include="ures_cnv.cpp" />
     <ClCompile Include="uresbund.cpp" />
     <ClCompile Include="uresdata.cpp" />

icu4c/source/common/sources.txt

@@ -139,6 +139,7 @@ ulist.cpp
 uloc.cpp
 uloc_keytype.cpp
 uloc_tag.cpp
+ulocale.cpp
 ulocbuilder.cpp
 umapfile.cpp
 umath.cpp

icu4c/source/common/ulocale.cpp

@@ -0,0 +1,96 @@
+// © 2023 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
+//
+#include "unicode/errorcode.h"
+#include "unicode/stringpiece.h"
+#include "unicode/utypes.h"
+#include "unicode/ustring.h"
+#include "unicode/ulocale.h"
+#include "unicode/locid.h"
+
+#include "charstr.h"
+#include "cmemory.h"
+
+U_NAMESPACE_USE
+#define EXTERNAL(i) (reinterpret_cast<ULocale*>(i))
+#define CONST_INTERNAL(e) (reinterpret_cast<const icu::Locale*>(e))
+#define INTERNAL(e) (reinterpret_cast<icu::Locale*>(e))
+
+ULocale*
+ulocale_openForLocaleID(const char* localeID, int32_t length, UErrorCode* err) {
+    CharString str(length < 0 ? StringPiece(localeID) : StringPiece(localeID, length), *err);
+    if (U_FAILURE(*err)) return nullptr;
+    return EXTERNAL(icu::Locale::createFromName(str.data()).clone());
+}
+
+ULocale*
+ulocale_openForLanguageTag(const char* tag, int32_t length, UErrorCode* err) {
+  Locale l = icu::Locale::forLanguageTag(length < 0 ? StringPiece(tag) : StringPiece(tag, length), *err);
+  if (U_FAILURE(*err)) return nullptr;
+  return EXTERNAL(l.clone());
+}
+
+void
+ulocale_close(ULocale* locale) {
+    delete INTERNAL(locale);
+}
+
+#define IMPL_ULOCALE_STRING_GETTER(N1, N2) \
+const char* ulocale_get ## N1(const ULocale* locale) { \
+    if (locale == nullptr) return nullptr; \
+    return CONST_INTERNAL(locale)->get ## N2(); \
+}
+
+#define IMPL_ULOCALE_STRING_IDENTICAL_GETTER(N) IMPL_ULOCALE_STRING_GETTER(N, N)
+
+#define IMPL_ULOCALE_GET_KEYWORD_VALUE(N) \
+int32_t ulocale_get ##N ( \
+    const ULocale* locale, const char* keyword, int32_t keywordLength, \
+    char* valueBuffer, int32_t bufferCapacity, UErrorCode *err) { \
+    if (U_FAILURE(*err)) return 0; \
+    if (locale == nullptr) { \
+        *err = U_ILLEGAL_ARGUMENT_ERROR; \
+        return 0; \
+    } \
+    CheckedArrayByteSink sink(valueBuffer, bufferCapacity); \
+    CONST_INTERNAL(locale)->get ## N( \
+        keywordLength < 0 ? StringPiece(keyword) : StringPiece(keyword, keywordLength), \
+        sink, *err); \
+    if (U_FAILURE(*err)) return 0; \
+    if (sink.Overflowed()) { \
+       *err = U_BUFFER_OVERFLOW_ERROR; \
+       return sink.NumberOfBytesAppended()+1; \
+    } \
+    int32_t len = sink.NumberOfBytesWritten(); \
+    if (len < bufferCapacity) valueBuffer[len] = '\0'; \
+    return len; \
+}
+
+#define IMPL_ULOCALE_GET_KEYWORDS(N) \
+UEnumeration* ulocale_get ## N(const ULocale* locale, UErrorCode *err) { \
+    if (U_FAILURE(*err)) return nullptr; \
+    if (locale == nullptr) { \
+        *err = U_ILLEGAL_ARGUMENT_ERROR; \
+        return nullptr; \
+    } \
+    return uenum_openFromStringEnumeration( \
+        CONST_INTERNAL(locale)->create ## N(*err), err); \
+}
+
+IMPL_ULOCALE_STRING_IDENTICAL_GETTER(Language)
+IMPL_ULOCALE_STRING_IDENTICAL_GETTER(Script)
+IMPL_ULOCALE_STRING_GETTER(Region, Country)
+IMPL_ULOCALE_STRING_IDENTICAL_GETTER(Variant)
+IMPL_ULOCALE_STRING_GETTER(LocaleID, Name)
+IMPL_ULOCALE_STRING_IDENTICAL_GETTER(BaseName)
+IMPL_ULOCALE_GET_KEYWORD_VALUE(KeywordValue)
+IMPL_ULOCALE_GET_KEYWORD_VALUE(UnicodeKeywordValue)
+IMPL_ULOCALE_GET_KEYWORDS(Keywords)
+IMPL_ULOCALE_GET_KEYWORDS(UnicodeKeywords)
+
+bool ulocale_isBogus(const ULocale* locale) {
+    if (locale == nullptr) return false;
+    return CONST_INTERNAL(locale)->isBogus();
+}
+
+/*eof*/

icu4c/source/common/ulocbuilder.cpp

@@ -14,8 +14,9 @@
 using icu::CheckedArrayByteSink;
 using icu::StringPiece;
 
-#define EXTERNAL(i) ((ULocaleBuilder*)(i))
-#define INTERNAL(e) ((icu::LocaleBuilder*)(e))
+#define EXTERNAL(i) (reinterpret_cast<ULocaleBuilder*>(i))
+#define INTERNAL(e) (reinterpret_cast<icu::LocaleBuilder*>(e))
+#define CONST_INTERNAL(e) (reinterpret_cast<const icu::LocaleBuilder*>(e))
 
 ULocaleBuilder* ulocbld_open() {
     return EXTERNAL(new icu::LocaleBuilder());
@@ -141,5 +142,5 @@ UBool ulocbld_copyErrorTo(const ULocaleBuilder* builder, UErrorCode *outErrorCod
         *outErrorCode = U_ILLEGAL_ARGUMENT_ERROR;
         return true;
     }
-    return INTERNAL(builder)->copyErrorTo(*outErrorCode);
+    return CONST_INTERNAL(builder)->copyErrorTo(*outErrorCode);
 }

icu4c/source/common/unicode/ulocale.h

@@ -0,0 +1,229 @@
+// © 2023 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
+
+#ifndef ULOCALE_H
+#define ULOCALE_H
+
+#include "unicode/localpointer.h"
+#include "unicode/uenum.h"
+#include "unicode/utypes.h"
+
+/**
+ * \file
+ * \brief C API: Locale ID functionality similar to C++ class Locale
+ */
+
+#ifndef U_HIDE_DRAFT_API
+/**
+ * Opaque C service object type for the locale API
+ * @draft ICU 74
+ */
+struct ULocale;
+
+/**
+ * C typedef for struct ULocale.
+ * @draft ICU 74
+ */
+typedef struct ULocale ULocale;
+
+/**
+ * Constructs an ULocale from the locale ID.
+ * The created ULocale should be destroyed by calling
+ * ulocale_close();
+ * @param localeID the locale, a const char * pointer (need not be terminated when
+ *               the length is non-negative)
+ * @param length the length of the locale; if negative, then the locale need to be
+ *               null terminated.
+ * @param err the error code
+ * @return the locale.
+ *
+ * @draft ICU 74
+ */
+U_CAPI ULocale* U_EXPORT2
+ulocale_openForLocaleID(const char* localeID, int32_t length, UErrorCode* err);
+
+/**
+ * Constructs an ULocale from the provided IETF BCP 47 language tag.
+ * The created ULocale should be destroyed by calling
+ * ulocale_close();
+ * @param tag the language tag, defined as IETF BCP 47 language tag, const
+ *            char* pointer (need not be terminated when the length is non-negative)
+ * @param length the length of the tag; if negative, then the tag need to be
+ *               null terminated.
+ * @param err the error code
+ * @return the locale.
+ *
+ * @draft ICU 74
+ */
+U_CAPI ULocale* U_EXPORT2
+ulocale_openForLanguageTag(const char* tag, int32_t length, UErrorCode* err);
+
+/**
+ * Close the locale and destroy it's internal states.
+ *
+ * @param locale the locale
+ * @draft ICU 74
+ */
+U_CAPI void U_EXPORT2
+ulocale_close(ULocale* locale);
+
+/**
+ * Returns the locale's ISO-639 language code.
+ *
+ * @param locale the locale
+ * @return      the language code of the locale.
+ * @draft ICU 74
+ */
+U_CAPI const char* U_EXPORT2
+ulocale_getLanguage(const ULocale* locale);
+
+/**
+ * Returns the locale's ISO-15924 abbreviation script code.
+ *
+ * @param locale the locale
+ * @return      A pointer to the script.
+ * @draft ICU 74
+ */
+U_CAPI const char* U_EXPORT2
+ulocale_getScript(const ULocale* locale);
+
+/**
+ * Returns the locale's ISO-3166 region code.
+ *
+ * @param locale the locale
+ * @return      A pointer to the region.
+ * @draft ICU 74
+ */
+U_CAPI const char* U_EXPORT2
+ulocale_getRegion(const ULocale* locale);
+
+/**
+ * Returns the locale's variant code.
+ *
+ * @param locale the locale
+ * @return      A pointer to the variant.
+ * @draft ICU 74
+ */
+U_CAPI const char* U_EXPORT2
+ulocale_getVariant(const ULocale* locale);
+
+/**
+ * Returns the programmatic name of the entire locale, with the language,
+ * country and variant separated by underbars. If a field is missing, up
+ * to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN",
+ * "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO"
+ *
+ * @param locale the locale
+ * @return      A pointer to "name".
+ * @draft ICU 74
+ */
+U_CAPI const char* U_EXPORT2
+ulocale_getLocaleID(const ULocale* locale);
+
+/**
+ * Returns the programmatic name of the entire locale as ulocale_getLocaleID()
+ * would return, but without keywords.
+ *
+ * @param locale the locale
+ * @return      A pointer to "base name".
+ * @draft ICU 74
+ */
+U_CAPI const char* U_EXPORT2
+ulocale_getBaseName(const ULocale* locale);
+
+/**
+ * Gets the bogus state. Locale object can be bogus if it doesn't exist
+ *
+ * @param locale the locale
+ * @return false if it is a real locale, true if it is a bogus locale
+ * @draft ICU 74
+ */
+U_CAPI bool U_EXPORT2
+ulocale_isBogus(const ULocale* locale);
+
+/**
+ * Gets the list of keywords for the specified locale.
+ *
+ * @param locale the locale
+ * @param err the error code
+ * @return pointer to UEnumeration, or nullptr if there are no keywords.
+ * Client must call uenum_close() to dispose the returned value.
+ * @draft ICU 74
+ */
+U_CAPI UEnumeration* U_EXPORT2
+ulocale_getKeywords(const ULocale* locale, UErrorCode *err);
+
+/**
+ * Gets the list of unicode keywords for the specified locale.
+ *
+ * @param locale the locale
+ * @param err the error code
+ * @return pointer to UEnumeration, or nullptr if there are no keywords.
+ * Client must call uenum_close() to dispose the returned value.
+ * @draft ICU 74
+ */
+U_CAPI UEnumeration* U_EXPORT2
+ulocale_getUnicodeKeywords(const ULocale* locale, UErrorCode *err);
+
+/**
+ * Gets the value for a keyword.
+ *
+ * This uses legacy keyword=value pairs, like "collation=phonebook".
+ *
+ * @param locale the locale
+ * @param keyword the keyword, a const char * pointer (need not be
+ *                terminated when the length is non-negative)
+ * @param keywordLength the length of the keyword; if negative, then the
+ *                      keyword need to be null terminated.
+ * @param valueBuffer The buffer to receive the value.
+ * @param valueBufferCapacity The capacity of receiving valueBuffer.
+ * @param err the error code
+ * @draft ICU 74
+ */
+U_CAPI int32_t U_EXPORT2
+ulocale_getKeywordValue(
+    const ULocale* locale, const char* keyword, int32_t keywordLength,
+    char* valueBuffer, int32_t valueBufferCapacity, UErrorCode *err);
+
+/**
+ * Gets the Unicode value for a Unicode keyword.
+ *
+ * This uses Unicode key-value pairs, like "co-phonebk".
+ *
+ * @param locale the locale
+ * @param keyword the Unicode keyword, a const char * pointer (need not be
+ *                terminated when the length is non-negative)
+ * @param keywordLength the length of the Unicode keyword; if negative,
+ *                      then the keyword need to be null terminated.
+ * @param valueBuffer The buffer to receive the Unicode value.
+ * @param valueBufferCapacity The capacity of receiving valueBuffer.
+ * @param err the error code
+ * @draft ICU 74
+ */
+U_CAPI int32_t U_EXPORT2
+ulocale_getUnicodeKeywordValue(
+    const ULocale* locale, const char* keyword, int32_t keywordLength,
+    char* valueBuffer, int32_t valueBufferCapacity, UErrorCode *err);
+
+#if U_SHOW_CPLUSPLUS_API
+
+U_NAMESPACE_BEGIN
+
+/**
+ * \class LocalULocalePointer
+ * "Smart pointer" class, closes a ULocale via ulocale_close().
+ * For most methods see the LocalPointerBase base class.
+ *
+ * @see LocalPointerBase
+ * @see LocalPointer
+ * @draft ICU 74
+ */
+U_DEFINE_LOCAL_OPEN_POINTER(LocalULocalePointer, ULocale, ulocale_close);
+
+U_NAMESPACE_END
+
+#endif  /* U_SHOW_CPLUSPLUS_API */
+
+#endif /* U_HIDE_DRAFT_API */
+
+#endif /*_ULOCALE */