Proposal: New collation "available" API (revised)

[Revised 5/3/04: The "keyword" parameter was added to 
getFuntionalEquivalent.]

This proposal is to add several new API to the collation service in ICU4C.

See: http://www.jtcsv.com/cgibin/icu-bugs?findid=3549

ucol.h

/**
 * Create a string enumerator of all locales for which a collator may
 * be opened.
 * @param status input-output error code
 * @return a string enumeration over locale strings. The caller is
 * responsible for closing the result.
 * @draft ICU 3.0
 */
U_DRAFT UEnumeration* U_EXPORT2
ucol_openAvailableLocales(UErrorCode *status);

/**
 * Create a string enumerator of all keywords that are relevant to
 * collation. At this point, the only recognized keyword for this
 * service is "collation".
 * @param status input-output error code
 * @return a string enumeration over locale strings. The caller is
 * responsible for closing the result.
 * @draft ICU 3.0
 */
U_DRAFT UEnumeration* U_EXPORT2
ucol_getKeywords(UErrorCode *status);

/**
 * Given a keyword, create a string enumeration of all possible values
 * for that keyword.
 * @param keyword a particular keyword as enumerated by
 * ucol_getKeywords. If any other keyword is passed in, *status is set
 * to U_ILLEGAL_ARGUMENT_ERROR.
 * @param status input-output error code
 * @return a string enumeration over collation keyword values, or NULL
 * upon error. The caller is responsible for closing the result.
 * @draft ICU 3.0
 */
U_DRAFT UEnumeration* U_EXPORT2
ucol_getKeywordValues(const char *keyword, UErrorCode *status);

/**
 * Return a functionally equivalent collation locale for the given
 * requested locale.
 * @param result fillin for the functionally equivalent locale
 * @param resultCapacity capacity of the fillin buffer
 * @param keyword a particular keyword as enumerated by
 * ucol_getKeywords.
 * @param locale the requested locale
 * @param isAvailable if non-NULL, pointer to a fillin parameter that
 * indicates whether the requested locale was 'available' to the
 * collation service. A locale is defined as 'available' if it
 * physically exists within the collation locale data.
 * @param status pointer to input-output error code
 * @return the actual buffer size needed for the locale.  If greater
 * than resultCapacity, the returned full name will be truncated and
 * an error code will be returned.
 * @draft ICU 3.0
 */
U_DRAFT int32_t U_EXPORT2
ucol_getFunctionalEquivalent(char* result, int32_t resultCapacity,
                             const char* keyword,
                             const char* locale, UBool* isAvailable,
                             UErrorCode* status);

coll.h:

    /**
     * Create a string enumerator of all keywords that are relevant to
     * collation. At this point, the only recognized keyword for this
     * service is "collation".
     * @param status input-output error code
     * @return a string enumeration over locale strings. The caller is
     * responsible for closing the result.
     * @draft ICU 3.0
     */
    static StringEnumeration* getKeywords(UErrorCode& status);

    /**
     * Given a keyword, create a string enumeration of all possible values
     * for that keyword.
     * @param keyword a particular keyword as enumerated by
     * ucol_getKeywords. If any other keyword is passed in, status is set
     * to U_ILLEGAL_ARGUMENT_ERROR.
     * @param status input-output error code
     * @return a string enumeration over collation keyword values, or NULL
     * upon error. The caller is responsible for deleting the result.
     * @draft ICU 3.0
     */
    static StringEnumeration* getKeywordValues(const char *keyword,
                                               UErrorCode& status);
 
    /**
     * Return a functionally equivalent collation locale for the given
     * requested locale.
     * @param keyword a particular keyword as enumerated by
     * ucol_getKeywords.
     * @param locale the requested locale
     * @param isAvailable reference to a fillin parameter that
     * indicates whether the requested locale was 'available' to the
     * collation service. A locale is defined as 'available' if it
     * physically exists within the collation locale data.
     * @param status reference to input-output error code
     * @return the functionally equivalent collation locale, or the root
     * locale upon error.
     * @draft ICU 3.0
     */
    static Locale getFunctionalEquivalent(const char* keyword,
                                          const Locale& locale,
                                          UBool& isAvailable,
                                          UErrorCode& status);

[Alan S Liu/San Jose/IBM@IBMUS; [email protected];; IBM Globalization; 
5600 Cottle Road; San Jose, CA 95193;; (408) 256-3155]