organicmaps/icu
13
Fork 0
mirror of https://github.com/unicode-org/icu.git synced 2025-04-07 06:25:30 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions 1

ICU-21159 Document U_USING_DEFAULT_WARNING in .h

Browse source 
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.
This commit is contained in:
Frank Tang 2020-08-14 16:39:26 -07:00 • committed by Frank Yung-Fong Tang
parent 0da354bbca
commit e395e8abcd
3 changed files with 160 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

136
icu4c/source/common/unicode/uloc.h
View file

@ -553,16 +553,21 @@ uloc_getLCID(const char* localeID);
* 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 @@ uloc_getDisplayLanguage(const char* locale,
/**
* 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 @@ uloc_getDisplayScript(const char* locale,
/**
* 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 @@ uloc_getDisplayCountry(const char* locale,
/**
* 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 @@ uloc_getDisplayVariant(const char* locale,
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 @@ uloc_getDisplayVariant(const char* locale,
* 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 @@ uloc_getDisplayKeyword(const char* keyword,
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 @@ uloc_getDisplayKeyword(const char* keyword,
* 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

73
icu4c/source/test/cintltst/cloctst.c
View file

@ -56,6 +56,8 @@ static void TestBadLocaleIDs(void);
static void TestBug20370(void);
static void TestBug20321UnicodeLocaleKey(void);
static void TestUsingDefaultWarning(void);
void PrintDataTable();
/*---------------------------------------------------
@ -274,6 +276,7 @@ void addLocaleTest(TestNode** root)
TESTCASE(TestBadLocaleIDs);
TESTCASE(TestBug20370);
TESTCASE(TestBug20321UnicodeLocaleKey);
TESTCASE(TestUsingDefaultWarning);
}
@ -6741,3 +6744,73 @@ static void TestBug20149() {
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));
}
}

5
icu4c/source/test/cintltst/cloctst.h
View file

@ -137,6 +137,11 @@ static void TestToUnicodeLocaleType(void);
static void TestToLegacyType(void);
static void TestBug20149(void);
/**
* U_USING_DEFAULT_WARNING
*/
static void TestUsingDefaultWarning(void);
/**
* locale data
*/