ICU-22435 Add C API for Locale

Add implementation

Add pointer

Use Macro

ICU-22435 fix param

ICU-22435 split file

ICU-22435 Fix doc

ICU-22435 Fix dependencies

ICU-22435 Add tests

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,107 @@
+// © 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 "cmemory.h"
+
+U_NAMESPACE_USE
+#define EXTERNAL(i) ((ULocale*)(i))
+#define CONST_INTERNAL(e) ((const icu::Locale*)(e))
+#define INTERNAL(e) ((icu::Locale*)(e))
+
+ULocale*
+ulocale_openLocaleID(const char* localeID, int32_t length) {
+    if (length < 0 || localeID[length] == '\0') {
+        return EXTERNAL(new icu::Locale(localeID));
+    } else {
+        if (length < ULOC_FULLNAME_CAPACITY-1) {
+            char buf[ULOC_FULLNAME_CAPACITY];
+            uprv_memcpy(buf, localeID, length);
+            buf[length] = '\0';
+            return EXTERNAL(new icu::Locale(buf));
+        }
+        // return a bogus one
+        Locale bogus;
+        bogus.setToBogus();
+        return EXTERNAL(bogus.clone());
+    }
+}
+
+ULocale*
+ulocale_openForLanguageTag(const char* tag, int32_t length, UErrorCode* err) {
+  if (U_FAILURE(*err)) return nullptr;
+  return EXTERNAL(icu::Locale::forLanguageTag(
+      length < 0 ? StringPiece(tag) : StringPiece(tag, length), *err).clone());
+}
+
+void
+ulocale_close(ULocale* locale) {
+    if (locale == nullptr) return;
+    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_BOOL_IDENTICAL_GETTER(N) \
+bool ulocale_is ## N(const ULocale* locale) { \
+    if (locale == nullptr) return false; \
+    return CONST_INTERNAL(locale)->is ## 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; \
+    } \
+    return sink.NumberOfBytesWritten(); \
+}
+
+#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_BOOL_IDENTICAL_GETTER(Bogus)
+IMPL_ULOCALE_GET_KEYWORD_VALUE(KeywordValue)
+IMPL_ULOCALE_GET_KEYWORD_VALUE(UnicodeKeywordValue)
+IMPL_ULOCALE_GET_KEYWORDS(Keywords)
+IMPL_ULOCALE_GET_KEYWORDS(UnicodeKeywords)
+
+/*eof*/

icu4c/source/common/unicode/ulocale.h

@@ -0,0 +1,228 @@
+// © 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 destoried 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.
+ * @return the locale.
+ *
+ * @draft ICU 74
+ */
+U_CAPI ULocale* U_EXPORT2
+ulocale_openLocaleID(const char* localeID, int32_t length);
+
+/**
+ * Constructs an ULocale from the provided IETF BCP 47 language tag.
+ * The created ULocale should be destoried 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 */

icu4c/source/test/cintltst/Makefile.in

@@ -42,7 +42,8 @@ LIBS = $(LIBCTESTFW) $(LIBICUI18N) $(LIBICUTOOLUTIL) $(LIBICUUC) $(DEFAULT_LIBS)
 OBJECTS = callcoll.o calltest.o capitst.o cbiapts.o cbkittst.o \
 ccaltst.o ucnvseltst.o cctest.o ccapitst.o ccolltst.o encoll.o cconvtst.o ccurrtst.o \
 cdateintervalformattest.o cdattst.o cdetst.o cdtdptst.o cdtrgtst.o cestst.o cfintst.o \
-cformtst.o cfrtst.o cg7coll.o chashtst.o cintltst.o citertst.o cjaptst.o cloctst.o ulocbuildertst.o \
+cformtst.o cfrtst.o cg7coll.o chashtst.o cintltst.o citertst.o cjaptst.o cloctst.o \
+ulocaletst.o ulocbuildertst.o \
 cmsccoll.o cmsgtst.o cpluralrulestest.o cposxtst.o cldrtest.o \
 cnmdptst.o cnormtst.o cnumtst.o crelativedateformattest.o crestst.o creststn.o cturtst.o \
 cucdapi.o cucdtst.o custrtst.o cstrcase.o cutiltst.o nucnvtst.o nccbtst.o bocu1tst.o \