API addition proposal: uloc_getKeywords, uloc_getKeywordValue

Expiration 10/17/2003

ICU services will be extended to use keyword variants, such as 
"de_DE@collation=phonebook".

In order to support this, two new APIs will be added to locale framework:
/**
  * Gets the list of keywords for the specified locale. Keywords are terminated
  * with a NUL character and the list is terminated with an additional NUL.
  * For example "calendar\0collation\0currency\0\0"
  *
  * @param localeID the locale to get the variant code with
  * @param keywords the keywords in this localeID
  * @param keywordsCapacity the size of the buffer to store the
  * keywords in
  * @param err error information if retrieving the keywords failed
  * @return the actual buffer size needed to store the keywords.
  * @draft ICU 2.8
  */
U_CAPI int32_t  U_EXPORT2
uloc_getKeywords(const char* localeID,
                         char* keywords,
                         int32_t keywordsCapacity,
                         UErrorCode* status);

/**
  * Get the value for a keyword. Locale name does not need to be normalized.
  *
  * @param localeID locale name containing the keyword 
("de_DE@currency=EURO;collation=PHONEBOOK")
  * @param keywordName name of the keyword for which we want the value. Case 
insensitive.
  * @param buffer receiving buffer
  * @param bufferCapacity capacity of receiving buffer
  * @param status containing error code - buffer not big enough.
  *
  * @draft ICU 2.8
  */
U_CAPI int32_t U_EXPORT2
uloc_getKeywordValue(const char* localeID,
                      const char* keywordName,
                      char* buffer, int32_t bufferCapacity,
                      UErrorCode* status);


Also, uloc_getName API will be modified and will recognize a list of 
keyword/value pairs after a '@'.

Analogous APIs will be provided for C++:
/**
  * Gets the list of keywords for the specified locale. Keywords are terminated
  * with a NUL character and the list is terminated with an additional NUL.
  * For example "calendar\0collation\0currency\0\0"
  *
  * @param keywordsLen length of the keywords array
  * @return pointer to keywords owned by the Locale object or NULL if there are
  *         no keywords.
  * @draft ICU 2.8
  */
const char * getKeywords(int32_t& keywordsLen) const;

/**
  * Get the value for a keyword.
  *
  * @param keywordName name of the keyword for which we want the value.
  *                    Case insensitive.
  * @return pointer to the keyword value owned by the Locale object or NULL if
  *                    there is no such a keyword.
  *
  * @draft ICU 2.8
  */
  const char * getKeywordValue(const char* keywordName) const;

Furthermore, constructor will be extended so that it can take another optional 
argument containing keywords and values.

ICU4J will also need to support keywords somehow. This is still under 
consideration, as we use JDK's Locale class.

Thank you.

Regards,
v.

-- 
Vladimir Weinstein, IBM GCoC-Unicode/ICU  San Jose, CA [email protected]