From 60f61805e45d5e82f8045e694df92f1986182767 Mon Sep 17 00:00:00 2001 From: Markus Scherer Date: Mon, 10 Jun 2013 22:37:40 +0000 Subject: [PATCH] ICU-8134 improve API docs for getBaseName() & setKeywordValue() X-SVN-Rev: 33814 --- icu4c/source/common/unicode/locid.h | 7 +++++-- icu4c/source/common/unicode/uloc.h | 12 +++++++++--- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/icu4c/source/common/unicode/locid.h b/icu4c/source/common/unicode/locid.h index c406183b105..904599ab795 100644 --- a/icu4c/source/common/unicode/locid.h +++ b/icu4c/source/common/unicode/locid.h @@ -421,7 +421,7 @@ public: inline const char * getName() const; /** - * Returns the programmatic name of the entire locale as getName would return, + * Returns the programmatic name of the entire locale as getName() would return, * but without keywords. * @return A pointer to "name". * @see getName @@ -454,7 +454,10 @@ public: int32_t getKeywordValue(const char* keywordName, char *buffer, int32_t bufferCapacity, UErrorCode &status) const; /** - * Sets the value for a keyword. + * Sets or removes the value for a keyword. + * + * For removing all keywords, use getBaseName(), + * and construct a new Locale if it differs from getName(). * * @param keywordName name of the keyword to be set. Case insensitive. * @param keywordValue value of the keyword to be set. If 0-length or diff --git a/icu4c/source/common/unicode/uloc.h b/icu4c/source/common/unicode/uloc.h index a8b59fb6d42..28ab902b522 100644 --- a/icu4c/source/common/unicode/uloc.h +++ b/icu4c/source/common/unicode/uloc.h @@ -800,12 +800,15 @@ uloc_getParent(const char* localeID, /** - * Gets the full name for the specified locale. + * Gets the full name for the specified locale, like uloc_getName(), + * but without keywords. + * * Note: This has the effect of 'canonicalizing' the string to * a certain extent. Upper and lower case are set as needed, * and if the components were in 'POSIX' format they are changed to * ICU format. It does NOT map aliased names in any way. * See the top of this header file. + * * This API strips off the keyword part, so "de_DE\@collation=phonebook" * will become "de_DE". * This API supports preflighting. @@ -856,13 +859,16 @@ uloc_getKeywordValue(const char* localeID, /** - * Set the value of the specified keyword. + * Sets or removes the value of the specified keyword. + * + * For removing all keywords, use uloc_getBaseName(). + * * NOTE: Unlike almost every other ICU function which takes a * buffer, this function will NOT truncate the output text. If a * BUFFER_OVERFLOW_ERROR is received, it means that the original * buffer is untouched. This is done to prevent incorrect or possibly * even malformed locales from being generated and used. - * + * * @param keywordName name of the keyword to be set. Case insensitive. * @param keywordValue value of the keyword to be set. If 0-length or * NULL, will result in the keyword being removed. No error is given if -- 2.40.0