International Components for Unicode

Expiration: Thu, 2004-apr-22

This proposal seeks to add support for instantiation of collators by using a short string definition, as defined in 
http://oss.software.ibm.com/icu/userguide/Collate_Concepts.html#Naming_Collators



/**
  * Open a collator defined by a short form string.
  * The structure and the syntax of the string is defined in the "Naming collators"
  * section of the users guide:
  * http://oss.software.ibm.com/icu/userguide/Collate_Concepts.html#Naming_Collators
  * The call to this function is equivalent to a call to ucol_open, followed by a
  * series of calls to ucol_setAttribute and ucol_setVariableTop.
  * @param definition A short string containing a locale and a set of attributes.
  *                   Attributes not explicitly mentioned are left at the default
  *                   state for a locale.
  * @param parseError if not NULL, structure that will get filled with error's pre
  *                   and post context in case of error.
  * @param status     Error code. Apart from regular error conditions connected to
  *                   instantiating collators (like out of memory or similar), this
  *                   API will return an error if an invalid attribute or attribute/value
  *                   combination is specified.
  * @return           A pointer to a UCollator or 0 if an error occured (including an
  *                   invalid attribute).
  * @see ucol_open
  * @see ucol_setAttribute
  * @see ucol_setVariableTop
  * @see ucol_getShortDefinitionString
  * @see ucol_normalizeShortDefinitionString
  * @draft ICU 3.0
  *
  */
U_CAPI UCollator* U_EXPORT2
ucol_openFromShortString( const char *definition,
                           UParseError *parseError,
                           UErrorCode *status);



/** Get the short definition string for a collator. This API harvests the collator's
  *  locale and the attribute set and produces a string that can be used for opening
  *  a collator with the same properties using the ucol_openFromShortString API.
  *  This string will be normalized.
  *  The structure and the syntax of the string is defined in the "Naming collators"
  *  section of the users guide:
  *  http://oss.software.ibm.com/icu/userguide/Collate_Concepts.html#Naming_Collators
  *  This API supports preflighting.
  *  @param coll a collator
  *  @param locale locale for the collator. If NULL, collator's real locale will be used
  *  @param buffer space to hold the resulting string
  *  @param capacity capacity of the buffer
  *  @status for returning errors. All the preflighting errors are featured
  *  @return length of the resulting string
  *  @see ucol_openFromShortString
  *  @see ucol_normalizeShortDefinitionString
  *  @draft ICU 3.0
  */
U_CAPI int32_t U_EXPORT2
ucol_getShortDefinitionString(const UCollator *coll,
                               const char *locale,
                               char *buffer,
                               int32_t capacity,
                               UErrorCode *status);

/** Verifies and normalizes short definition string.
  *  Normalized short definition string has all the option sorted by the argument name,
  *  so that equivalent definition strings are the same.
  *  This API supports preflighting.
  *  @param source definition string
  *  @param destination space to hold the resulting string
  *  @param capacity capacity of the buffer
  *  @param parseError if not NULL, structure that will get filled with error's pre
  *                   and post context in case of error.
  *  @param status     Error code. This API will return an error if an invalid attribute
  *                    or attribute/value combination is specified. All the preflighting
  *                    errors are also featured
  *
  *  @see ucol_openFromShortString
  *  @see ucol_getShortDefinitionString
  *
  *  @draft ICU 3.0
  */

U_CAPI int32_t U_EXPORT2
ucol_normalizeShortDefinitionString(const char *source,
                                     char *destination,
                                     int32_t capacity,
                                     UParseError *parseError,
                                     UErrorCode *status);


Regards,
v.