|
From: Frank T. (譚. <ft...@go...> - 2023-07-21 01:23:14
|
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 |