[icu-design] C API for ULocale

[Frank T. (譚. <ft...@go...>]

Dear ICU team & users,


I would like to propose the following for: ICU 74

Please provide feedback by: Next Wednesday, July 26, or any time
sufficiently in advance of the feature freeze

Designated API review: Rich Gillam

Issue: https://unicode-org.atlassian.net/browse/ICU-22435
A draft PR and implementation (not including test yet) could be found at
https://github.com/unicode-org/icu/pull/2531 )

This is to follow up the C API for ULocaleBuilder

Issue to be discussed
1. Do we need methods for canonicalize/addLikelySubtag/minimizeSubtags
2. If the answer for #1 is YES, should we make them as producer  which to
produce and return a different ULocale and keep ULocale as an immutable
object. (as proposed below)
3. Do we need methods unrelated of parsing:

ulocale_isRightToLeft

ulocale_getISO3Country

ulocale_getISO3Language




diff --git a/icu4c/source/common/unicode/uloc.h
b/icu4c/source/common/unicode/uloc.h
index 21179c1b628..4b0b419ec4b 100644
--- a/icu4c/source/common/unicode/uloc.h
+++ b/icu4c/source/common/unicode/uloc.h
@@ -1390,4 +1390,279 @@ uloc_toLegacyKey(const char* keyword);
 U_CAPI const char* U_EXPORT2
 uloc_toLegacyType(const char* keyword, const char* value);

+#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 locale 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.
+ * @return the locale.
+ *
+ * @draft ICU 74
+ */
+U_CAPI ULocale* U_EXPORT2
+ulocale_openForLanguageTag(const char* tag, int32_t length);
+
+/**
+ * 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);
+
+/**
+ * Constructs another ULocale by canonicalize the provided locale.
+ * The created ULocale should be destoried by calling
+ * ulocale_close();
+ *
+ * @param locale the locale
+ * @param err the error code
+ * @return the canonicalized locale.
+ * @draft ICU 74
+ */
+U_CAPI ULocale* U_EXPORT2
+ulocale_canonicalize(const ULocale* locale, UErrorCode *err);
+
+/**
+ * Constructs another ULocale by maximize from the the subtags of the provided
+ * Locale, per the algorithm described in the following CLDR technical report:
+ * http://www.unicode.org/reports/tr35/#Likely_Subtags
+ * The created ULocale should be destoried by calling
+ * ulocale_close();
+ *
+ * @param locale the locale
+ * @param err the error code
+ * @return the maximized locale.
+ * @draft ICU 74
+ */
+U_CAPI ULocale* U_EXPORT2
+ulocale_addLikelySubtags(const ULocale* locale, UErrorCode *err);
+
+/**
+ * Constructs another ULocale by minimize from the the subtags of the provided
+ * Locale, per the algorithm described in the following CLDR technical report:
+ * http://www.unicode.org/reports/tr35/#Likely_Subtags
+ * The created ULocale should be destoried by calling
+ * ulocale_close();
+ *
+ * @param locale the locale
+ * @param err the error code
+ * @return the minimized locale.
+ * @draft ICU 74
+ */
+U_CAPI ULocale* U_EXPORT2
+ulocale_minimizeSubtags(const ULocale* locale, UErrorCode *err);
+
+/**
+ * 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);
+
+/**
+ * Returns the locale's three-letter language code, as specified
+ * in ISO draft standard ISO-639-2.
+ *
+ * @param locale the locale
+ * @return      the locale's three-letter language code of the locale,
+ *              or an empty string..
+ * @draft ICU 74
+ */
+U_CAPI const char* U_EXPORT2
+ulocale_getISO3Language(const ULocale* locale);
+
+/**
+ * Returns the locale's three-letter ISO-3166 country code.
+ *
+ * @param locale the locale
+ * @return      the locale's three-letter ISO-3166 country code of the locale,
+ *              or an empty string..
+ * @draft ICU 74
+ */
+U_CAPI const char* U_EXPORT2
+ulocale_getISO3Country(const ULocale* locale);
+
+/**
+ * Returns whether this locale's script is written right-to-left.
+ * If there is no script subtag, then the likely script is used, see
uloc_addLikelySubtags().
+ * If no likely script is known, then false is returned.
+ *
+ * A script is right-to-left according to the CLDR script metadata
+ * which corresponds to whether the script's letters have Bidi_Class=R or AL.
+ *
+ * Returns true for "ar" and "en-Hebr", false for "zh" and "fa-Cyrl".
+ *
+ * @param locale the locale
+ * @return true if the locale's script is written right-to-left
+ * @draft ICU 74
+ */
+U_CAPI bool U_EXPORT2
+ulocale_isRightToLeft(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 bufferCapacity, UErrorCode *err);
+
+#endif /* U_HIDE_DRAFT_API */
+
 #endif /*_ULOC*/

-- 
Frank Yung-Fong Tang
譚永鋒 / 🌭🍊
Sr. Software Engineer