/*

*******************************************************************************

* Copyright (c) 1996-2005, International Business Machines Corporation and others.

* All Rights Reserved.

*******************************************************************************

*/

#ifndef UCOL_H

#define UCOL_H

#include "unicode/utypes.h"

#if !UCONFIG_NO_COLLATION

#include "unicode/unorm.h"

#include "unicode/parseerr.h"

#include "unicode/uloc.h"

#include "unicode/uset.h"

/**

 * \file

 * \brief C API: Collator 

 *

 * <h2> Collator C API </h2>

 *

 * The C API for Collator performs locale-sensitive

 * string comparison. You use this service to build

 * searching and sorting routines for natural language text.

 * <em>Important: </em>The ICU collation service has been reimplemented 

 * in order to achieve better performance and UCA compliance. 

 * For details, see the 

 * <a href="http://icu.sourceforge.net/cvs/icu/~checkout~/icuhtml/design/collation/ICU_collation_design.htm">

 * collation design document</a>.

 * <p>

 * For more information about the collation service see 

 * <a href="http://icu.sourceforge.net/icu/userguide/Collate_Intro.html">the users guide</a>.

 * <p>

 * Collation service provides correct sorting orders for most locales supported in ICU. 

 * If specific data for a locale is not available, the orders eventually falls back

 * to the <a href="http://www.unicode.org/unicode/reports/tr10/">UCA sort order</a>. 

 * <p>

 * Sort ordering may be customized by providing your own set of rules. For more on

 * this subject see the 

 * <a href="http://icu.sourceforge.net/icu/userguide/Collate_Customization.html">

 * Collation customization</a> section of the users guide.

 * <p>

 * @see         UCollationResult

 * @see         UNormalizationMode

 * @see         UCollationStrength

 * @see         UCollationElements

 */

/** A collation element iterator.

*  For usage in C programs.

*/

struct collIterate;

/** structure representing collation element iterator instance 

 * @stable ICU 2.0

 */

typedef struct collIterate collIterate;

/** A collator.

*  For usage in C programs.

*/

struct UCollator;

/** structure representing a collator object instance 

 * @stable ICU 2.0

 */

typedef struct UCollator UCollator;

/**

 * UCOL_LESS is returned if source string is compared to be less than target

 * string in the u_strcoll() method.

 * UCOL_EQUAL is returned if source string is compared to be equal to target

 * string in the u_strcoll() method.

 * UCOL_GREATER is returned if source string is compared to be greater than

 * target string in the u_strcoll() method.

 * @see u_strcoll()

 * <p>

 * Possible values for a comparison result 

 * @stable ICU 2.0

 */

typedef enum {

  /** string a == string b */

  UCOL_EQUAL    = 0,

  /** string a > string b */

  UCOL_GREATER    = 1,

  /** string a < string b */

  UCOL_LESS    = -1

} UCollationResult ;

/** Enum containing attribute values for controling collation behavior.

 * Here are all the allowable values. Not every attribute can take every value. The only

 * universal value is UCOL_DEFAULT, which resets the attribute value to the predefined  

 * value for that locale 

 * @stable ICU 2.0

 */

typedef enum {

  /** accepted by most attributes */

  UCOL_DEFAULT = -1,

  /** Primary collation strength */

  UCOL_PRIMARY = 0,

  /** Secondary collation strength */

  UCOL_SECONDARY = 1,

  /** Tertiary collation strength */

  UCOL_TERTIARY = 2,

  /** Default collation strength */

  UCOL_DEFAULT_STRENGTH = UCOL_TERTIARY,

  UCOL_CE_STRENGTH_LIMIT,

  /** Quaternary collation strength */

  UCOL_QUATERNARY=3,

  /** Identical collation strength */

  UCOL_IDENTICAL=15,

  UCOL_STRENGTH_LIMIT,

  /** Turn the feature off - works for UCOL_FRENCH_COLLATION, 

      UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE

      & UCOL_DECOMPOSITION_MODE*/

  UCOL_OFF = 16,

  /** Turn the feature on - works for UCOL_FRENCH_COLLATION, 

      UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE

      & UCOL_DECOMPOSITION_MODE*/

  UCOL_ON = 17,

  /** Valid for UCOL_ALTERNATE_HANDLING. Alternate handling will be shifted */

  UCOL_SHIFTED = 20,

  /** Valid for UCOL_ALTERNATE_HANDLING. Alternate handling will be non ignorable */

  UCOL_NON_IGNORABLE = 21,

  /** Valid for UCOL_CASE_FIRST - 

      lower case sorts before upper case */

  UCOL_LOWER_FIRST = 24,

  /** upper case sorts before lower case */

  UCOL_UPPER_FIRST = 25,

  UCOL_ATTRIBUTE_VALUE_COUNT

} UColAttributeValue;

/**

 * Base letter represents a primary difference.  Set comparison

 * level to UCOL_PRIMARY to ignore secondary and tertiary differences.

 * Use this to set the strength of a Collator object.

 * Example of primary difference, "abc" < "abd"

 * 

 * Diacritical differences on the same base letter represent a secondary

 * difference.  Set comparison level to UCOL_SECONDARY to ignore tertiary

 * differences. Use this to set the strength of a Collator object.

 * Example of secondary difference, "ä" >> "a".

 *

 * Uppercase and lowercase versions of the same character represents a

 * tertiary difference.  Set comparison level to UCOL_TERTIARY to include

 * all comparison differences. Use this to set the strength of a Collator

 * object.

 * Example of tertiary difference, "abc" <<< "ABC".

 *

 * Two characters are considered "identical" when they have the same

 * unicode spellings.  UCOL_IDENTICAL.

 * For example, "ä" == "ä".

 *

 * UCollationStrength is also used to determine the strength of sort keys 

 * generated from UCollator objects

 * These values can be now found in the UColAttributeValue enum.

 * @stable ICU 2.0

 **/

typedef UColAttributeValue UCollationStrength;

/** Attributes that collation service understands. All the attributes can take UCOL_DEFAULT

 * value, as well as the values specific to each one. 

 * @stable ICU 2.0

 */

typedef enum {

     /** Attribute for direction of secondary weights - used in French.\ 

      * Acceptable values are UCOL_ON, which results in secondary weights

      * being considered backwards and UCOL_OFF which treats secondary

      * weights in the order they appear.*/

     UCOL_FRENCH_COLLATION, 

     /** Attribute for handling variable elements.\ 

      * Acceptable values are UCOL_NON_IGNORABLE (default)

      * which treats all the codepoints with non-ignorable 

      * primary weights in the same way,

      * and UCOL_SHIFTED which causes codepoints with primary 

      * weights that are equal or below the variable top value

      * to be ignored on primary level and moved to the quaternary 

      * level.*/

     UCOL_ALTERNATE_HANDLING, 

     /** Controls the ordering of upper and lower case letters.\ 

      * Acceptable values are UCOL_OFF (default), which orders

      * upper and lower case letters in accordance to their tertiary

      * weights, UCOL_UPPER_FIRST which forces upper case letters to 

      * sort before lower case letters, and UCOL_LOWER_FIRST which does 

      * the opposite. */

     UCOL_CASE_FIRST, 

     /** Controls whether an extra case level (positioned before the third

      * level) is generated or not.\ Acceptable values are UCOL_OFF (default), 

      * when case level is not generated, and UCOL_ON which causes the case

      * level to be generated.\ Contents of the case level are affected by

      * the value of UCOL_CASE_FIRST attribute.\ A simple way to ignore 

      * accent differences in a string is to set the strength to UCOL_PRIMARY

      * and enable case level. */

     UCOL_CASE_LEVEL,

     /** Controls whether the normalization check and necessary normalizations

      * are performed.\ When set to UCOL_OFF (default) no normalization check

      * is performed.\ The correctness of the result is guaranteed only if the 

      * input data is in so-called FCD form (see users manual for more info).\ 

      * When set to UCOL_ON, an incremental check is performed to see whether the input data

      * is in the FCD form.\ If the data is not in the FCD form, incremental 

      * NFD normalization is performed. */

     UCOL_NORMALIZATION_MODE, 

     /** An alias for UCOL_NORMALIZATION_MODE attribute */

     UCOL_DECOMPOSITION_MODE = UCOL_NORMALIZATION_MODE,

     /** The strength attribute.\ Can be either UCOL_PRIMARY, UCOL_SECONDARY,

      * UCOL_TERTIARY, UCOL_QUATERNARY or UCOL_IDENTICAL.\ The usual strength

      * for most locales (except Japanese) is tertiary.\ Quaternary strength 

      * is useful when combined with shifted setting for alternate handling

      * attribute and for JIS x 4061 collation, when it is used to distinguish

      * between Katakana  and Hiragana (this is achieved by setting the 

      * UCOL_HIRAGANA_QUATERNARY mode to on.\ Otherwise, quaternary level

      * is affected only by the number of non ignorable code points in

      * the string.\ Identical strength is rarely useful, as it amounts 

      * to codepoints of the NFD form of the string. */

     UCOL_STRENGTH,  

     /** when turned on, this attribute 

      * positions Hiragana before all  

      * non-ignorables on quaternary level

      * This is a sneaky way to produce JIS

      * sort order */     

     UCOL_HIRAGANA_QUATERNARY_MODE,

     /** when turned on, this attribute 

      * generates a collation key

      * for the numeric value of substrings

      * of digits. This is a way to get '100' 

      * to sort AFTER '2'.*/          

     UCOL_NUMERIC_COLLATION, 

     UCOL_ATTRIBUTE_COUNT

} UColAttribute;

/** Options for retrieving the rule string 

 *  @stable ICU 2.0

 */

typedef enum {

  /** Retrieve tailoring only */

  UCOL_TAILORING_ONLY, 

  /** Retrieve UCA rules and tailoring */

  UCOL_FULL_RULES 

} UColRuleOption ;

/**

 * Open a UCollator for comparing strings.

 * The UCollator pointer is used in all the calls to the Collation 

 * service. After finished, collator must be disposed of by calling

 * {@link #ucol_close }.

 * @param loc The locale containing the required collation rules. 

 *            Special values for locales can be passed in - 

 *            if NULL is passed for the locale, the default locale

 *            collation rules will be used. If empty string ("") or

 *            "root" are passed, UCA rules will be used.

 * @param status A pointer to an UErrorCode to receive any errors

 * @return A pointer to a UCollator, or 0 if an error occurred.

 * @see ucol_openRules

 * @see ucol_safeClone

 * @see ucol_close

 * @stable ICU 2.0

 */

U_STABLE UCollator* U_EXPORT2 

ucol_open(const char *loc, UErrorCode *status);

/**

 * Produce an UCollator instance according to the rules supplied.

 * The rules are used to change the default ordering, defined in the

 * UCA in a process called tailoring. The resulting UCollator pointer

 * can be used in the same way as the one obtained by {@link #ucol_strcoll }.

 * @param rules A string describing the collation rules. For the syntax

 *              of the rules please see users guide.

 * @param rulesLength The length of rules, or -1 if null-terminated.

 * @param normalizationMode The normalization mode: One of

 *             UCOL_OFF     (expect the text to not need normalization),

 *             UCOL_ON      (normalize), or

 *             UCOL_DEFAULT (set the mode according to the rules)

 * @param strength The default collation strength; one of UCOL_PRIMARY, UCOL_SECONDARY,

 * UCOL_TERTIARY, UCOL_IDENTICAL,UCOL_DEFAULT_STRENGTH - can be also set in the rules.

 * @param parseError  A pointer to UParseError to recieve information about errors

 *                    occurred during parsing. This argument can currently be set

 *                    to NULL, but at users own risk. Please provide a real structure.

 * @param status A pointer to an UErrorCode to receive any errors

 * @return A pointer to a UCollator.\ It is not guaranteed that NULL be returned in case

 *         of error - please use status argument to check for errors.

 * @see ucol_open

 * @see ucol_safeClone

 * @see ucol_close

 * @stable ICU 2.0

 */

U_STABLE UCollator* U_EXPORT2 

ucol_openRules( const UChar        *rules,

                int32_t            rulesLength,

                UColAttributeValue normalizationMode,

                UCollationStrength strength,

                UParseError        *parseError,

                UErrorCode         *status);

/** 

 * 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://icu.sourceforge.net/icu/userguide/Collate_Concepts.html#Naming_Collators

 * Attributes are overriden by the subsequent attributes. So, for "S2_S3", final

 * strength will be 3. 3066bis locale overrides individual locale parts.

 * 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 forceDefaults if FALSE, the settings that are the same as the collator 

 *                   default settings will not be applied (for example, setting

 *                   French secondary on a French collator would not be executed). 

 *                   If TRUE, all the settings will be applied regardless of the 

 *                   collator default value. If the definition

 *                   strings are to be cached, should be set to FALSE.

 * @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,

                          UBool forceDefaults,

                          UParseError *parseError,

                          UErrorCode *status);

/**

 * Get a set containing the contractions defined by the collator. The set includes

 * both the UCA contractions and the contractions defined by the collator. This set

 * will contain only strings. If a tailoring explicitly suppresses contractions from 

 * the UCA (like Russian), removed contractions will not be in the resulting set.

 * @param coll collator 

 * @param conts the set to hold the result. It gets emptied before

 *              contractions are added. 

 * @param status to hold the error code

 * @return the size of the contraction set

 *

 * @draft ICU 3.0

 */

U_CAPI int32_t U_EXPORT2

ucol_getContractions( const UCollator *coll,

                  USet *conts,

                  UErrorCode *status);

/** 

 * Close a UCollator.

 * Once closed, a UCollator should not be used.\ Every open collator should

 * be closed.\ Otherwise, a memory leak will result.

 * @param coll The UCollator to close.

 * @see ucol_open

 * @see ucol_openRules

 * @see ucol_safeClone

 * @stable ICU 2.0

 */

U_STABLE void U_EXPORT2 

ucol_close(UCollator *coll);

/**

 * Compare two strings.

 * The strings will be compared using the options already specified.

 * @param coll The UCollator containing the comparison rules.

 * @param source The source string.

 * @param sourceLength The length of source, or -1 if null-terminated.

 * @param target The target string.

 * @param targetLength The length of target, or -1 if null-terminated.

 * @return The result of comparing the strings; one of UCOL_EQUAL,

 * UCOL_GREATER, UCOL_LESS

 * @see ucol_greater

 * @see ucol_greaterOrEqual

 * @see ucol_equal

 * @stable ICU 2.0

 */

U_STABLE UCollationResult U_EXPORT2 

ucol_strcoll(    const    UCollator    *coll,

        const    UChar        *source,

        int32_t            sourceLength,

        const    UChar        *target,

        int32_t            targetLength);

/**

 * Determine if one string is greater than another.

 * This function is equivalent to {@link #ucol_strcoll } == UCOL_GREATER

 * @param coll The UCollator containing the comparison rules.

 * @param source The source string.

 * @param sourceLength The length of source, or -1 if null-terminated.

 * @param target The target string.

 * @param targetLength The length of target, or -1 if null-terminated.

 * @return TRUE if source is greater than target, FALSE otherwise.

 * @see ucol_strcoll

 * @see ucol_greaterOrEqual

 * @see ucol_equal

 * @stable ICU 2.0

 */

U_STABLE UBool U_EXPORT2 

ucol_greater(const UCollator *coll,

             const UChar     *source, int32_t sourceLength,

             const UChar     *target, int32_t targetLength);

/**

 * Determine if one string is greater than or equal to another.

 * This function is equivalent to {@link #ucol_strcoll } != UCOL_LESS

 * @param coll The UCollator containing the comparison rules.

 * @param source The source string.

 * @param sourceLength The length of source, or -1 if null-terminated.

 * @param target The target string.

 * @param targetLength The length of target, or -1 if null-terminated.

 * @return TRUE if source is greater than or equal to target, FALSE otherwise.

 * @see ucol_strcoll

 * @see ucol_greater

 * @see ucol_equal

 * @stable ICU 2.0

 */

U_STABLE UBool U_EXPORT2 

ucol_greaterOrEqual(const UCollator *coll,

                    const UChar     *source, int32_t sourceLength,

                    const UChar     *target, int32_t targetLength);

/**

 * Compare two strings for equality.

 * This function is equivalent to {@link #ucol_strcoll } == UCOL_EQUAL

 * @param coll The UCollator containing the comparison rules.

 * @param source The source string.

 * @param sourceLength The length of source, or -1 if null-terminated.

 * @param target The target string.

 * @param targetLength The length of target, or -1 if null-terminated.

 * @return TRUE if source is equal to target, FALSE otherwise

 * @see ucol_strcoll

 * @see ucol_greater

 * @see ucol_greaterOrEqual

 * @stable ICU 2.0

 */

U_STABLE UBool U_EXPORT2 

ucol_equal(const UCollator *coll,

           const UChar     *source, int32_t sourceLength,

           const UChar     *target, int32_t targetLength);

/**

 * Compare two UTF-8 encoded trings.

 * The strings will be compared using the options already specified.

 * @param coll The UCollator containing the comparison rules.

 * @param sIter The source string iterator.

 * @param tIter The target string iterator.

 * @return The result of comparing the strings; one of UCOL_EQUAL,

 * UCOL_GREATER, UCOL_LESS

 * @param status A pointer to an UErrorCode to receive any errors

 * @see ucol_strcoll

 * @stable ICU 2.6

 */

U_STABLE UCollationResult U_EXPORT2 

ucol_strcollIter(  const    UCollator    *coll,

                  UCharIterator *sIter,

                  UCharIterator *tIter,

                  UErrorCode *status);

/**

 * Get the collation strength used in a UCollator.

 * The strength influences how strings are compared.

 * @param coll The UCollator to query.

 * @return The collation strength; one of UCOL_PRIMARY, UCOL_SECONDARY,

 * UCOL_TERTIARY, UCOL_QUATERNARY, UCOL_IDENTICAL

 * @see ucol_setStrength

 * @stable ICU 2.0

 */

U_STABLE UCollationStrength U_EXPORT2 

ucol_getStrength(const UCollator *coll);

/**

 * Set the collation strength used in a UCollator.

 * The strength influences how strings are compared.

 * @param coll The UCollator to set.

 * @param strength The desired collation strength; one of UCOL_PRIMARY, 

 * UCOL_SECONDARY, UCOL_TERTIARY, UCOL_QUATERNARY, UCOL_IDENTICAL, UCOL_DEFAULT

 * @see ucol_getStrength

 * @stable ICU 2.0

 */

U_STABLE void U_EXPORT2 

ucol_setStrength(UCollator *coll,

                 UCollationStrength strength);

/**

 * Get the display name for a UCollator.

 * The display name is suitable for presentation to a user.

 * @param objLoc The locale of the collator in question.

 * @param dispLoc The locale for display.

 * @param result A pointer to a buffer to receive the attribute.

 * @param resultLength The maximum size of result.

 * @param status A pointer to an UErrorCode to receive any errors

 * @return The total buffer size needed; if greater than resultLength,

 * the output was truncated.

 * @stable ICU 2.0

 */

U_STABLE int32_t U_EXPORT2 

ucol_getDisplayName(    const    char        *objLoc,

            const    char        *dispLoc,

            UChar             *result,

            int32_t         resultLength,

            UErrorCode        *status);

/**

 * Get a locale for which collation rules are available.

 * A UCollator in a locale returned by this function will perform the correct

 * collation for the locale.

 * @param index The index of the desired locale.

 * @return A locale for which collation rules are available, or 0 if none.

 * @see ucol_countAvailable

 * @stable ICU 2.0

 */

U_STABLE const char* U_EXPORT2 

ucol_getAvailable(int32_t index);