ICU-21159 Document U_USING_DEFAULT_WARNING in .h
Document the fact
uloc_getDisplay(Language|Script|Country|Variant|Keyword|KeywordValue)
would fallback with the code, case canonicalied in same cases, and
set the status to U_USING_DEFAULT_WARNING.
No change to the implementation behavior. Only complete the missing
comments and tweak line wrap, remove double spaces and add test to
validate this pre-existing behavior that I added the documents now.
diff --git a/icu4c/source/common/unicode/uloc.h b/icu4c/source/common/unicode/uloc.h
index d877ce4..d3de89f 100644
--- a/icu4c/source/common/unicode/uloc.h
+++ b/icu4c/source/common/unicode/uloc.h
@@ -553,16 +553,21 @@
* Gets the language name suitable for display for the specified locale.
*
* @param locale the locale to get the ISO language code with
- * @param displayLocale Specifies the locale to be used to display the name. In other words,
- * if the locale's language code is "en", passing Locale::getFrench() for
- * inLocale would result in "Anglais", while passing Locale::getGerman()
- * for inLocale would result in "Englisch".
+ * @param displayLocale Specifies the locale to be used to display the name. In
+ * other words, if the locale's language code is "en", passing
+ * Locale::getFrench() for inLocale would result in "Anglais",
+ * while passing Locale::getGerman() for inLocale would result
+ * in "Englisch".
* @param language the displayable language code for localeID
- * @param languageCapacity the size of the language buffer to store the
- * displayable language code with
- * @param status error information if retrieving the displayable language code failed
- * @return the actual buffer size needed for the displayable language code. If it's greater
- * than languageCapacity, the returned language code will be truncated.
+ * @param languageCapacity the size of the language buffer to store the
+ * displayable language code with.
+ * @param status error information if retrieving the displayable language code
+ * failed. U_USING_DEFAULT_WARNING indicates that no data was
+ * found from the locale resources and a case canonicalized
+ * language code is placed into language as fallback.
+ * @return the actual buffer size needed for the displayable language code. If
+ * it's greater than languageCapacity, the returned language
+ * code will be truncated.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
@@ -575,17 +580,23 @@
/**
* Gets the script name suitable for display for the specified locale.
*
- * @param locale the locale to get the displayable script code with. NULL may be used to specify the default.
- * @param displayLocale Specifies the locale to be used to display the name. In other words,
- * if the locale's language code is "en", passing Locale::getFrench() for
- * inLocale would result in "", while passing Locale::getGerman()
- * for inLocale would result in "". NULL may be used to specify the default.
- * @param script the displayable script for the localeID
- * @param scriptCapacity the size of the script buffer to store the
- * displayable script code with
- * @param status error information if retrieving the displayable script code failed
- * @return the actual buffer size needed for the displayable script code. If it's greater
- * than scriptCapacity, the returned displayable script code will be truncated.
+ * @param locale the locale to get the displayable script code with. NULL may be
+ * used to specify the default.
+ * @param displayLocale Specifies the locale to be used to display the name. In
+ * other words, if the locale's language code is "en", passing
+ * Locale::getFrench() for inLocale would result in "", while
+ * passing Locale::getGerman() for inLocale would result in "".
+ * NULL may be used to specify the default.
+ * @param script the displayable script for the localeID.
+ * @param scriptCapacity the size of the script buffer to store the displayable
+ * script code with.
+ * @param status error information if retrieving the displayable script code
+ * failed. U_USING_DEFAULT_WARNING indicates that no data was
+ * found from the locale resources and a case canonicalized
+ * script code is placed into script as fallback.
+ * @return the actual buffer size needed for the displayable script code. If
+ * it's greater than scriptCapacity, the returned displayable
+ * script code will be truncated.
* @stable ICU 2.8
*/
U_STABLE int32_t U_EXPORT2
@@ -597,20 +608,27 @@
/**
* Gets the country name suitable for display for the specified locale.
- * Warning: this is for the region part of a valid locale ID; it cannot just be the region code (like "FR").
- * To get the display name for a region alone, or for other options, use ULocaleDisplayNames instead.
+ * Warning: this is for the region part of a valid locale ID; it cannot just be
+ * the region code (like "FR"). To get the display name for a region alone, or
+ * for other options, use ULocaleDisplayNames instead.
*
- * @param locale the locale to get the displayable country code with. NULL may be used to specify the default.
- * @param displayLocale Specifies the locale to be used to display the name. In other words,
- * if the locale's language code is "en", passing Locale::getFrench() for
- * inLocale would result in "Anglais", while passing Locale::getGerman()
- * for inLocale would result in "Englisch". NULL may be used to specify the default.
- * @param country the displayable country code for localeID
- * @param countryCapacity the size of the country buffer to store the
- * displayable country code with
- * @param status error information if retrieving the displayable country code failed
- * @return the actual buffer size needed for the displayable country code. If it's greater
- * than countryCapacity, the returned displayable country code will be truncated.
+ * @param locale the locale to get the displayable country code with. NULL may
+ * be used to specify the default.
+ * @param displayLocale Specifies the locale to be used to display the name. In
+ * other words, if the locale's language code is "en", passing
+ * Locale::getFrench() for inLocale would result in "Anglais",
+ * while passing Locale::getGerman() for inLocale would result
+ * in "Englisch". NULL may be used to specify the default.
+ * @param country the displayable country code for localeID.
+ * @param countryCapacity the size of the country buffer to store the
+ * displayable country code with.
+ * @param status error information if retrieving the displayable country code
+ * failed. U_USING_DEFAULT_WARNING indicates that no data was
+ * found from the locale resources and a case canonicalized
+ * country code is placed into country as fallback.
+ * @return the actual buffer size needed for the displayable country code. If
+ * it's greater than countryCapacity, the returned displayable
+ * country code will be truncated.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
@@ -624,17 +642,23 @@
/**
* Gets the variant name suitable for display for the specified locale.
*
- * @param locale the locale to get the displayable variant code with. NULL may be used to specify the default.
- * @param displayLocale Specifies the locale to be used to display the name. In other words,
- * if the locale's language code is "en", passing Locale::getFrench() for
- * inLocale would result in "Anglais", while passing Locale::getGerman()
- * for inLocale would result in "Englisch". NULL may be used to specify the default.
- * @param variant the displayable variant code for localeID
- * @param variantCapacity the size of the variant buffer to store the
- * displayable variant code with
- * @param status error information if retrieving the displayable variant code failed
- * @return the actual buffer size needed for the displayable variant code. If it's greater
- * than variantCapacity, the returned displayable variant code will be truncated.
+ * @param locale the locale to get the displayable variant code with. NULL may
+ * be used to specify the default.
+ * @param displayLocale Specifies the locale to be used to display the name. In
+ * other words, if the locale's language code is "en", passing
+ * Locale::getFrench() for inLocale would result in "Anglais",
+ * while passing Locale::getGerman() for inLocale would result
+ * in "Englisch". NULL may be used to specify the default.
+ * @param variant the displayable variant code for localeID.
+ * @param variantCapacity the size of the variant buffer to store the
+ * displayable variant code with.
+ * @param status error information if retrieving the displayable variant code
+ * failed. U_USING_DEFAULT_WARNING indicates that no data was
+ * found from the locale resources and a case canonicalized
+ * variant code is placed into variant as fallback.
+ * @return the actual buffer size needed for the displayable variant code. If
+ * it's greater than variantCapacity, the returned displayable
+ * variant code will be truncated.
* @stable ICU 2.0
*/
U_STABLE int32_t U_EXPORT2
@@ -645,9 +669,9 @@
UErrorCode* status);
/**
- * Gets the keyword name suitable for display for the specified locale.
- * E.g: for the locale string de_DE\@collation=PHONEBOOK, this API gets the display
- * string for the keyword collation.
+ * Gets the keyword name suitable for display for the specified locale. E.g:
+ * for the locale string de_DE\@collation=PHONEBOOK, this API gets the display
+ * string for the keyword collation.
* Usage:
* <code>
* UErrorCode status = U_ZERO_ERROR;
@@ -676,11 +700,13 @@
* for inLocale would result in "Englisch". NULL may be used to specify the default.
* @param dest the buffer to which the displayable keyword should be written.
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
- * dest may be NULL and the function will only return the length of the
+ * dest may be NULL and the function will only return the length of the
* result without writing any of the result string (pre-flighting).
- * @param status error information if retrieving the displayable string failed.
+ * @param status error information if retrieving the displayable string failed.
* Should not be NULL and should not indicate failure on entry.
- * @return the actual buffer size needed for the displayable variant code.
+ * U_USING_DEFAULT_WARNING indicates that no data was found from the locale
+ * resources and the keyword is placed into dest as fallback.
+ * @return the actual buffer size needed for the displayable variant code.
* @see #uloc_openKeywords
* @stable ICU 2.8
*/
@@ -692,7 +718,7 @@
UErrorCode* status);
/**
* Gets the value of the keyword suitable for display for the specified locale.
- * E.g: for the locale string de_DE\@collation=PHONEBOOK, this API gets the display
+ * E.g: for the locale string de_DE\@collation=PHONEBOOK, this API gets the display
* string for PHONEBOOK, in the display locale, when "collation" is specified as the keyword.
*
* @param locale The locale to get the displayable variant code with. NULL may be used to specify the default.
@@ -703,11 +729,13 @@
* for inLocale would result in "Englisch". NULL may be used to specify the default.
* @param dest the buffer to which the displayable keyword should be written.
* @param destCapacity The size of the buffer (number of UChars). If it is 0, then
- * dest may be NULL and the function will only return the length of the
+ * dest may be NULL and the function will only return the length of the
* result without writing any of the result string (pre-flighting).
- * @param status error information if retrieving the displayable string failed.
+ * @param status error information if retrieving the displayable string failed.
* Should not be NULL and must not indicate failure on entry.
- * @return the actual buffer size needed for the displayable variant code.
+ * U_USING_DEFAULT_WARNING indicates that no data was found from the locale
+ * resources and the value of the keyword is placed into dest as fallback.
+ * @return the actual buffer size needed for the displayable variant code.
* @stable ICU 2.8
*/
U_STABLE int32_t U_EXPORT2
diff --git a/icu4c/source/test/cintltst/cloctst.c b/icu4c/source/test/cintltst/cloctst.c
index bc87be0..e3385b3 100644
--- a/icu4c/source/test/cintltst/cloctst.c
+++ b/icu4c/source/test/cintltst/cloctst.c
@@ -56,6 +56,8 @@
static void TestBug20370(void);
static void TestBug20321UnicodeLocaleKey(void);
+static void TestUsingDefaultWarning(void);
+
void PrintDataTable();
/*---------------------------------------------------
@@ -274,6 +276,7 @@
TESTCASE(TestBadLocaleIDs);
TESTCASE(TestBug20370);
TESTCASE(TestBug20321UnicodeLocaleKey);
+ TESTCASE(TestUsingDefaultWarning);
}
@@ -6741,3 +6744,73 @@
log_err("ERROR: in uloc_forLanguageTag %s return %s\n", myErrorName(status), locale);
}
}
+
+static void TestUsingDefaultWarning() {
+ UChar buff[256];
+ char cbuff[256];
+ UErrorCode status = U_ZERO_ERROR;
+ const char* language = "jJj";
+ int32_t length = uloc_getDisplayLanguage(language, "de", buff, 256, &status);
+ if (status != U_USING_DEFAULT_WARNING ||
+ u_strcmp(buff, CharsToUChars("jjj")) != 0 ||
+ length != 3) {
+ u_UCharsToChars(buff, cbuff, length+1);
+ log_err("ERROR: in uloc_getDisplayLanguage %s return len:%d %s with status %d %s\n",
+ language, length, cbuff, status, myErrorName(status));
+ }
+
+ status = U_ZERO_ERROR;
+ const char* script = "und-lALA";
+ length = uloc_getDisplayScript(script, "de", buff, 256, &status);
+ if (status != U_USING_DEFAULT_WARNING ||
+ u_strcmp(buff, CharsToUChars("Lala")) != 0 ||
+ length != 4) {
+ u_UCharsToChars(buff, cbuff, length+1);
+ log_err("ERROR: in uloc_getDisplayScript %s return len:%d %s with status %d %s\n",
+ script, length, cbuff, status, myErrorName(status));
+ }
+
+ status = U_ZERO_ERROR;
+ const char* region = "und-wt";
+ length = uloc_getDisplayCountry(region, "de", buff, 256, &status);
+ if (status != U_USING_DEFAULT_WARNING ||
+ u_strcmp(buff, CharsToUChars("WT")) != 0 ||
+ length != 2) {
+ u_UCharsToChars(buff, cbuff, length+1);
+ log_err("ERROR: in uloc_getDisplayCountry %s return len:%d %s with status %d %s\n",
+ region, length, cbuff, status, myErrorName(status));
+ }
+
+ status = U_ZERO_ERROR;
+ const char* variant = "und-abcde";
+ length = uloc_getDisplayVariant(variant, "de", buff, 256, &status);
+ if (status != U_USING_DEFAULT_WARNING ||
+ u_strcmp(buff, CharsToUChars("ABCDE")) != 0 ||
+ length != 5) {
+ u_UCharsToChars(buff, cbuff, length+1);
+ log_err("ERROR: in uloc_getDisplayVariant %s return len:%d %s with status %d %s\n",
+ variant, length, cbuff, status, myErrorName(status));
+ }
+
+ status = U_ZERO_ERROR;
+ const char* keyword = "postCODE";
+ length = uloc_getDisplayKeyword(keyword, "de", buff, 256, &status);
+ if (status != U_USING_DEFAULT_WARNING ||
+ u_strcmp(buff, CharsToUChars("postCODE")) != 0 ||
+ length != 8) {
+ u_UCharsToChars(buff, cbuff, length+1);
+ log_err("ERROR: in uloc_getDisplayKeyword %s return len:%d %s with status %d %s\n",
+ keyword, length, cbuff, status, myErrorName(status));
+ }
+
+ status = U_ZERO_ERROR;
+ const char* keyword_value = "de_DE@postCode=fOObAR";
+ length = uloc_getDisplayKeywordValue(keyword_value, keyword, "de", buff, 256, &status);
+ if (status != U_USING_DEFAULT_WARNING ||
+ u_strcmp(buff, CharsToUChars("fOObAR")) != 0 ||
+ length != 6) {
+ u_UCharsToChars(buff, cbuff, length+1);
+ log_err("ERROR: in uloc_getDisplayKeywordValue %s %s return len:%d %s with status %d %s\n",
+ keyword_value, keyword, length, cbuff, status, myErrorName(status));
+ }
+}
diff --git a/icu4c/source/test/cintltst/cloctst.h b/icu4c/source/test/cintltst/cloctst.h
index 3aaba10..6f03ce6 100644
--- a/icu4c/source/test/cintltst/cloctst.h
+++ b/icu4c/source/test/cintltst/cloctst.h
@@ -138,6 +138,11 @@
static void TestBug20149(void);
/**
+ * U_USING_DEFAULT_WARNING
+ */
+static void TestUsingDefaultWarning(void);
+
+/**
* locale data
*/
static void TestEnglishExemplarCharacters(void);
