home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 6 / AACD06.ISO / AACD / Programming / ICU / include / ucol.h < prev    next >
C/C++ Source or Header  |  1999-11-12  |  28KB  |  715 lines
  1. /*
  2. *******************************************************************************
  3. *                                                                             *
  4. * COPYRIGHT:                                                                  *
  5. *   (C) Copyright Taligent, Inc.,  1996                                       *
  6. *   (C) Copyright International Business Machines Corporation,  1998-1999     *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.        *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure   *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                    *
  10. *                                                                             *
  11. *******************************************************************************
  12. */
  13.  
  14. #ifndef UCOL_H
  15. #define UCOL_H
  16.  
  17. #include "utypes.h"
  18. /**
  19.  * The C API for Collator performs locale-sensitive
  20.  * <code>String</code> comparison. You use this class to build
  21.  * searching and sorting routines for natural language text.
  22.  *
  23.  *  
  24.  * <p>
  25.  * Like other locale-sensitive classes, you can use the function
  26.  * <code>ucol_open()</code>, to obtain the appropriate pointer to 
  27.  * <code>UCollator</code> object for a given locale. If you need
  28.  * to understand the details of a particular collation strategy or
  29.  * if you need to modify that strategy.
  30.  *
  31.  * <p>
  32.  * The following example shows how to compare two strings using
  33.  * the <code>UCollator</code> for the default locale.
  34.  * <blockquote>
  35.  * <pre>
  36.  * // Compare two strings in the default locale
  37.  * UErrorCode success = U_ZERO_ERROR;
  38.  * UCollator* myCollator = ucol_open(NULL, &success);
  39.  * UChar source[4], target[4];
  40.  * u_uastrcpy(source, "abc");
  41.  * u_uastrcpy(target, "ABC");
  42.  * if( u_strcoll(myCollator, source, u_strlen(source), target, u_strlen(target)) == UCOL_LESS) {
  43.  *     printf("abc is less than ABC\n");
  44.  * }else{
  45.  *     printf("abc is greater than or equal to ABC\n");
  46.  * }
  47.  * </pre>
  48.  * </blockquote>
  49.  *
  50.  * <p>
  51.  * You can set a <code>Collator</code>'s <em>strength</em> property
  52.  * to determine the level of difference considered significant in
  53.  * comparisons. Four strengths are provided: <code>UCOL_PRIMARY</code>,
  54.  * <code>UCOL_SECONDARY</code>, <code>UCOL_TERTIARY</code>, and 
  55.  * <code>UCOL_IDENTICAL</code>. The exact assignment of strengths to 
  56.  * language features is locale dependant.  For example, in Czech, 
  57.  * "e" and "f" are considered primary differences, while "e" and "\u00EA"
  58.  * are secondary differences, "e" and "E" are tertiary differences and 
  59.  * "e" and "e" are identical.
  60.  * The following shows how both case and accents could be ignored for
  61.  * US English.
  62.  * <blockquote>
  63.  * <pre>
  64.  * //Get the Collator for US English and set its strength to UCOL_PRIMARY
  65.  * UErrorCode success = U_ZERO_ERROR;
  66.  * UCollator* usCollator = ucol_open("en_US", &success);
  67.  * ucol_setStrength(usCollator, UCOL_PRIMARY);
  68.  * UChar source[4], target[4];
  69.  * u_uastrcpy(source, "abc");
  70.  * u_uastrcpy(target, "ABC");
  71.  * if( u_strcoll(myCollator, source, u_strlen(source), target, u_strlen(target)) == UCOL_EQUAL) {
  72.  *     printf("'abc' and 'ABC' strings are equivalent with strength UCOL_PRIMARY\n");
  73.  * }
  74.  * </pre>
  75.  * </blockquote>
  76.  * <p>
  77.  * For comparing <code>String</code>s exactly once, the <code>u_strcoll</code>
  78.  * method provides the best performance. When sorting a list of
  79.  * <code>String</code>s however, it is generally necessary to compare each
  80.  * <code>String</code> multiple times. In this case, <code>sortKey</code>s
  81.  * provide better performance. The <code>ucol_getsortKey</code> method converts
  82.  * a <code>String</code> to a series of bits that can be compared bitwise
  83.  * against other <code>sortKey</code>s using <code>memcmp()</code> 
  84.  * <p>
  85.  * <strong>Note:</strong> <code>UCollator</code>s with different Locale,
  86.  * Collation Strength and Decomposition Mode settings will return different
  87.  * sort orders for the same set of strings. Locales have specific 
  88.  * collation rules, and the way in which secondary and tertiary differences 
  89.  * are taken into account, for example, will result in a different sorting order
  90.  * for same strings.
  91.  * <p>
  92.  * @see         UCollationResult
  93.  * @see         UNormalizationMode
  94.  * @see            UCollationStrength
  95.  * @see         UCollationElements
  96.  */
  97. /** A collator */
  98. typedef void* UCollator;
  99.  
  100.     /**
  101.      * UCOL_LESS is returned if source string is compared to be less than target
  102.      * string in the u_strcoll() method.
  103.      * UCOL_EQUAL is returned if source string is compared to be equal to target
  104.      * string in the u_strcoll() method.
  105.      * UCOL_GREATER is returned if source string is compared to be greater than
  106.      * target string in the u_strcoll() method.
  107.      * @see u_strcoll()
  108.      **/
  109. /** Possible values for a comparison result */
  110. enum UCollationResult {
  111.   /** string a == string b */
  112.   UCOL_EQUAL    = 0,
  113.   /** string a > string b */
  114.   UCOL_GREATER    = 1,
  115.   /** string a < string b */
  116.   UCOL_LESS    = -1
  117. };
  118. typedef enum UCollationResult UCollationResult;
  119.   /**
  120.     * UCOL_NO_NORMALIZATION : Accented characters will not be decomposed for sorting.  
  121.     * UCOL_DECOM_CAN          : Characters that are canonical variants according 
  122.     * to Unicode 2.0 will be decomposed for sorting. 
  123.     * UCOL_DECOMP_COMPAT    : Characters that are compatibility variants will be
  124.     * decomposed for sorting. This is the default normalization mode used.
  125.     * UCOL_DECOMP_CAN_COMP_COMPAT : Canonical decomposition followed by canonical composition 
  126.     * UCOL_DECOMP_COMPAT_COMP_CAN : Compatibility decomposition followed by canonical composition
  127.     *
  128.     **/
  129. /** Possible collation normalization modes */
  130. enum UNormalizationMode {
  131.   /** No decomposition/composition */
  132.   UCOL_NO_NORMALIZATION,
  133.   /** Canonical decomposition */
  134.   UCOL_DECOMP_CAN,
  135.   /** Compatibility decomposition */
  136.   UCOL_DECOMP_COMPAT,
  137.   /** Canonical decomposition followed by canonical composition */
  138.   UCOL_DECOMP_CAN_COMP_COMPAT,
  139.   /** Compatibility decomposition followed by canonical composition */
  140.   UCOL_DECOMP_COMPAT_COMP_CAN,
  141.   /** Default normalization */
  142.   UCOL_DEFAULT_NORMALIZATION = UCOL_DECOMP_COMPAT
  143. };
  144. typedef enum UNormalizationMode UNormalizationMode;
  145.  
  146. /** Possible normalization options */
  147. enum UNormalizationOption {
  148.   /** Do not normalize Hangul */
  149.   UCOL_IGNORE_HANGUL    = 1
  150. };
  151. typedef enum UNormalizationOption UNormalizationOption;
  152.     /**
  153.      * Base letter represents a primary difference.  Set comparison
  154.      * level to UCOL_PRIMARY to ignore secondary and tertiary differences.
  155.      * Use this to set the strength of a Collator object.
  156.      * Example of primary difference, "abc" < "abd"
  157.      * 
  158.      * Diacritical differences on the same base letter represent a secondary
  159.      * difference.  Set comparison level to UCOL_SECONDARY to ignore tertiary
  160.      * differences. Use this to set the strength of a Collator object.
  161.      * Example of secondary difference, "ä" >> "a".
  162.      *
  163.      * Uppercase and lowercase versions of the same character represents a
  164.      * tertiary difference.  Set comparison level to UCOL_TERTIARY to include
  165.      * all comparison differences. Use this to set the strength of a Collator
  166.      * object.
  167.      * Example of tertiary difference, "abc" <<< "ABC".
  168.      *
  169.      * Two characters are considered "identical" when they have the same
  170.      * unicode spellings.  UCOL_IDENTICAL.
  171.      * For example, "ä" == "ä".
  172.      *
  173.      * UCollationStrength is also used to determine the strength of sort keys 
  174.      * generated from UCollator objects
  175.      **/
  176. /** Possible collation strengths */
  177. enum UCollationStrength {
  178.   /** Primary collation strength */
  179.   UCOL_PRIMARY = 0,
  180.   /** Secondary collation strength */
  181.   UCOL_SECONDARY = 1,
  182.   /** Tertiary collation strength */
  183.   UCOL_TERTIARY = 2,
  184.   /** Identical collation strength */
  185.   UCOL_IDENTICAL = 3,
  186.   /** Default collation strength */
  187.   UCOL_DEFAULT_STRENGTH = UCOL_TERTIARY
  188. } ;
  189. typedef enum UCollationStrength UCollationStrength;
  190.  
  191. /*===============================================
  192. =================================================
  193.     ---> MOVE SOMEWHERE ELSE !!! <---
  194. =================================================
  195. ===============================================*/
  196. /**
  197.  * <tt>u_normalize</tt> transforms Unicode text into an equivalent composed or
  198.  * decomposed form, allowing for easier sorting and searching of text.
  199.  * <tt>u_normalize</tt> supports the standard normalization forms described in
  200.  * <a href="http://www.unicode.org/unicode/reports/tr15/" target="unicode">
  201.  * Unicode Technical Report #15</a>.
  202.  * <p>
  203.  * Characters with accents or other adornments can be encoded in
  204.  * several different ways in Unicode.  For example, take the character "Á"
  205.  * (A-acute).   In Unicode, this can be encoded as a single character (the
  206.  * "composed" form):
  207.  * <pre>
  208.  *      00C1    LATIN CAPITAL LETTER A WITH ACUTE</pre>
  209.  * or as two separate characters (the "decomposed" form):
  210.  * <pre>
  211.  *      0041    LATIN CAPITAL LETTER A
  212.  *      0301    COMBINING ACUTE ACCENT</pre>
  213.  * <p>
  214.  * To a user of your program, however, both of these sequences should be
  215.  * treated as the same "user-level" character "Á".  When you are searching or
  216.  * comparing text, you must ensure that these two sequences are treated 
  217.  * equivalently.  In addition, you must handle characters with more than one
  218.  * accent.  Sometimes the order of a character's combining accents is
  219.  * significant, while in other cases accent sequences in different orders are
  220.  * really equivalent.
  221.  * <p>
  222.  * Similarly, the string "ffi" can be encoded as three separate letters:
  223.  * <pre>
  224.  *      0066    LATIN SMALL LETTER F
  225.  *      0066    LATIN SMALL LETTER F
  226.  *      0069    LATIN SMALL LETTER I</pre>
  227.  * or as the single character
  228.  * <pre>
  229.  *      FB03    LATIN SMALL LIGATURE FFI</pre>
  230.  * <p>
  231.  * The ffi ligature is not a distinct semantic character, and strictly speaking
  232.  * it shouldn't be in Unicode at all, but it was included for compatibility
  233.  * with existing character sets that already provided it.  The Unicode standard
  234.  * identifies such characters by giving them "compatibility" decompositions
  235.  * into the corresponding semantic characters.  When sorting and searching, you
  236.  * will often want to use these mappings.
  237.  * <p>
  238.  * <tt>u_normalize</tt> helps solve these problems by transforming text into the
  239.  * canonical composed and decomposed forms as shown in the first example above.  
  240.  * In addition, you can have it perform compatibility decompositions so that 
  241.  * you can treat compatibility characters the same as their equivalents.
  242.  * Finally, <tt>u_normalize</tt> rearranges accents into the proper canonical
  243.  * order, so that you do not have to worry about accent rearrangement on your
  244.  * own.
  245.  * <p>
  246.  * <tt>u_normalize</tt> adds one optional behavior, {@link #UCOL_IGNORE_HANGUL},
  247.  * that differs from
  248.  * the standard Unicode Normalization Forms. 
  249.  **/
  250.  
  251.  
  252. /**
  253.  * Normalize a string.
  254.  * The string will be normalized according the the specified normalization mode
  255.  * and options.
  256.  * @param source The string to normalize.
  257.  * @param sourceLength The length of source, or -1 if null-terminated.
  258.  * @param mode The normalization mode; one of UCOL_NO_NORMALIZATION, 
  259.  * UCOL_CAN_DECOMP, UCOL_COMPAT_DECOMP, UCOL_CAN_DECOMP_COMPAT_COMP, 
  260.  * UCOL_COMPAT_DECOMP_CAN_COMP, UCOL_DEFAULT_NORMALIZATION
  261.  * @param options The normalization options, ORed together; possible values
  262.  * are UCOL_IGNORE_HANGUL
  263.  * @param result A pointer to a buffer to receive the attribute.
  264.  * @param resultLength The maximum size of result.
  265.  * @param status A pointer to an UErrorCode to receive any errors
  266.  * @return The total buffer size needed; if greater than resultLength,
  267.  * the output was truncated.
  268.  */
  269. U_CAPI int32_t
  270. u_normalize(const UChar*           source,
  271.         int32_t                 sourceLength, 
  272.         UNormalizationMode      mode, 
  273.         int32_t            options,
  274.         UChar*                  result,
  275.         int32_t                 resultLength,
  276.         UErrorCode*             status);    
  277.  
  278. /**
  279.  * Open a UCollator for comparing strings.
  280.  * The UCollator may be used in calls to \Ref{ucol_strcoll}.
  281.  * @param loc The locale containing the comparison conventions.
  282.  * @param status A pointer to an UErrorCode to receive any errors
  283.  * @return A pointer to a UCollator, or 0 if an error occurred.
  284.  * @see ucol_openRules
  285.  */
  286. U_CAPI UCollator*
  287. ucol_open(    const    char         *loc,
  288.         UErrorCode      *status);
  289.  
  290. /**
  291.  * Open a UCollator for comparing strings.
  292.  * The UCollator may be used in calls to \Ref{ucol_strcoll}.
  293.  * @param rules A string describing the collation rules.
  294.  * @param rulesLength The length of rules, or -1 if null-terminated.
  295.  * @param mode The normalization mode; one of UCOL_NO_NORMALIZATION,
  296.  * UCOL_CAN_DECOMP, UCOL_COMPAT_DECOMP, UCOL_CAN_DECOMP_COMPAT_COMP,
  297.  * UCOL_COMPAT_DECOMP_CAN_COMP, UCOL_DEFAULT_NORMALIZATION
  298.  * @param strength The collation strength; one of UCOL_PRIMARY, UCOL_SECONDARY,
  299.  * UCOL_TERTIARY, UCOL_IDENTICAL,UCOL_DEFAULT_STRENGTH
  300.  * @param status A pointer to an UErrorCode to receive any errors
  301.  * @return A pointer to a UCollator, or 0 if an error occurred.
  302.  * @see ucol_open
  303.  */
  304. U_CAPI UCollator*
  305. ucol_openRules(    const    UChar        *rules,
  306.         int32_t                 rulesLength,
  307.         UNormalizationMode      mode,
  308.         UCollationStrength      strength,
  309.         UErrorCode              *status);
  310.  
  311. /** 
  312.  * Close a UCollator.
  313.  * Once closed, a UCollator should not be used.
  314.  * @param coll The UCollator to close.
  315.  */
  316. U_CAPI void
  317. ucol_close(UCollator *coll);
  318.  
  319. /**
  320.  * Compare two strings.
  321.  * The strings will be compared using the normalization mode and options
  322.  * specified in \Ref{ucol_open} or \Ref{ucol_openRules}
  323.  * @param coll The UCollator containing the comparison rules.
  324.  * @param source The source string.
  325.  * @param sourceLength The length of source, or -1 if null-terminated.
  326.  * @param target The target string.
  327.  * @param targetLength The length of target, or -1 if null-terminated.
  328.  * @return The result of comparing the strings; one of UCOL_EQUAL,
  329.  * UCOL_GREATER, UCOL_LESS
  330.  * @see ucol_greater
  331.  * @see ucol_greaterOrEqual
  332.  * @see ucol_equal
  333.  */
  334. U_CAPI UCollationResult
  335. ucol_strcoll(    const    UCollator    *coll,
  336.         const    UChar        *source,
  337.         int32_t            sourceLength,
  338.         const    UChar        *target,
  339.         int32_t            targetLength);
  340.  
  341. /**
  342.  * Determine if one string is greater than another.
  343.  * This function is equivalent to \Ref{ucol_strcoll} == UCOL_GREATER
  344.  * @param coll The UCollator containing the comparison rules.
  345.  * @param source The source string.
  346.  * @param sourceLength The length of source, or -1 if null-terminated.
  347.  * @param target The target string.
  348.  * @param targetLength The length of target, or -1 if null-terminated.
  349.  * @return TRUE if source is greater than target, FALSE otherwise.
  350.  * @see ucol_strcoll
  351.  * @see ucol_greaterOrEqual
  352.  * @see ucol_equal
  353.  */
  354. U_CAPI bool_t
  355. ucol_greater(    const    UCollator    *coll,
  356.         const    UChar        *source,
  357.         int32_t            sourceLength,
  358.         const    UChar        *target,
  359.         int32_t            targetLength);
  360.  
  361. /**
  362.  * Determine if one string is greater than or equal to another.
  363.  * This function is equivalent to \Ref{ucol_strcoll} != UCOL_LESS
  364.  * @param coll The UCollator containing the comparison rules.
  365.  * @param source The source string.
  366.  * @param sourceLength The length of source, or -1 if null-terminated.
  367.  * @param target The target string.
  368.  * @param targetLength The length of target, or -1 if null-terminated.
  369.  * @return TRUE if source is greater than or equal to target, FALSE otherwise.
  370.  * @see ucol_strcoll
  371.  * @see ucol_greater
  372.  * @see ucol_equal
  373.  */
  374. U_CAPI bool_t
  375. ucol_greaterOrEqual(    const    UCollator    *coll,
  376.             const    UChar        *source,
  377.             int32_t            sourceLength,
  378.             const    UChar        *target,
  379.             int32_t            targetLength);
  380.  
  381. /**
  382.  * Compare two strings for equality.
  383.  * This function is equivalent to \Ref{ucol_strcoll} == UCOL_EQUAL
  384.  * @param coll The UCollator containing the comparison rules.
  385.  * @param source The source string.
  386.  * @param sourceLength The length of source, or -1 if null-terminated.
  387.  * @param target The target string.
  388.  * @param targetLength The length of target, or -1 if null-terminated.
  389.  * @return TRUE if source is equal to target, FALSE otherwise
  390.  * @see ucol_strcoll
  391.  * @see ucol_greater
  392.  * @see ucol_greaterOrEqual
  393.  */
  394. U_CAPI bool_t
  395. ucol_equal(    const    UCollator    *coll,
  396.         const    UChar        *source,
  397.         int32_t            sourceLength,
  398.         const    UChar        *target,
  399.         int32_t            targetLength);
  400.  
  401. /**
  402.  * Get the collation strength used in a UCollator.
  403.  * The strength influences how strings are compared.
  404.  * @param coll The UCollator to query.
  405.  * @return The collation strength; one of UCOL_PRIMARY, UCOL_SECONDARY,
  406.  * UCOL_TERTIARY, UCOL_IDENTICAL, UCOL_DEFAULT_STRENGTH
  407.  * @see ucol_setStrength
  408.  */
  409. U_CAPI UCollationStrength
  410. ucol_getStrength(const UCollator *coll);
  411.  
  412. /**
  413.  * Set the collation strength used in a UCollator.
  414.  * The strength influences how strings are compared.
  415.  * <p>Example of use:
  416.  * <pre>
  417.  * .       UCollationResult result;
  418.  * .       UChar *source, *target;
  419.  * .       UErrorCode status = U_ZERO_ERROR;
  420.  * .       UCollator *myCollation = ucol_open("en_US", status);
  421.  * .       if (U_FAILURE(&status)) return;
  422.  * .       ucol_setStrength(myCollation, UCOL_PRIMARY);
  423.  * .       u_uastrcpy(source, "abc");
  424.  * .       u_uastrcpy(target, "ABC");
  425.  * .       // result will be "abc" == "ABC"
  426.  * .       // tertiary differences will be ignored
  427.  * .       result = ucol_strcoll(myCollation, source, u_strlen(source), target, u_strlen(target));
  428.  * </pre>
  429.  * @param coll The UCollator to set.
  430.  * @param strength The desired collation strength; one of UCOL_PRIMARY, 
  431.  * UCOL_SECONDARY, UCOL_TERTIARY, UCOL_IDENTICAL, UCOL_DEFAULT_STRENGTH
  432.  * @see ucol_getStrength
  433.  */
  434. U_CAPI void
  435. ucol_setStrength(    UCollator            *coll,
  436.             UCollationStrength        strength);
  437.  
  438. /**
  439.  * Get the normalization mode used in a UCollator.
  440.  * The normalization mode influences how strings are compared.
  441.  * @param coll The UCollator to query.
  442.  * @return The normalization mode; one of UCOL_NO_NORMALIZATION, 
  443.  * UCOL_CAN_DECOMP, UCOL_COMPAT_DECOMP, UCOL_CAN_DECOMP_COMPAT_COMP,
  444.  * UCOL_COMPAT_DECOMP_CAN_COMP, UCOL_DEFAULT_NORMALIZATION
  445.  * @see ucol_setNormalization
  446.  */
  447. U_CAPI UNormalizationMode
  448. ucol_getNormalization(const UCollator* coll);
  449.  
  450. /**
  451.  * Set the normalization mode used in a UCollator.
  452.  * The normalization mode influences how strings are compared.
  453.  * @param coll The UCollator to set.
  454.  * @param mode The desired normalization mode; one of UCOL_NO_NORMALIZATION,
  455.  * UCOL_CAN_DECOMP, UCOL_COMPAT_DECOMP, UCOL_CAN_DECOMP_COMPAT_COMP, 
  456.  * UCOL_COMPAT_DECOMP_CAN_COMP, UCOL_DEFAULT_NORMALIZATION
  457.  * @see ucol_getNormalization
  458.  */
  459. U_CAPI void
  460. ucol_setNormalization(  UCollator        *coll,
  461.             UNormalizationMode    mode);
  462.  
  463. /**
  464.  * Get the display name for a UCollator.
  465.  * The display name is suitable for presentation to a user.
  466.  * @param objLoc The locale of the collator in question.
  467.  * @param dispLoc The locale for display.
  468.  * @param result A pointer to a buffer to receive the attribute.
  469.  * @param resultLength The maximum size of result.
  470.  * @param status A pointer to an UErrorCode to receive any errors
  471.  * @return The total buffer size needed; if greater than resultLength,
  472.  * the output was truncated.
  473.  */
  474. U_CAPI int32_t
  475. ucol_getDisplayName(    const    char        *objLoc,
  476.             const    char        *dispLoc,
  477.             UChar             *result,
  478.             int32_t         resultLength,
  479.             UErrorCode        *status);
  480.  
  481. /**
  482.  * Get a locale for which collation rules are available.
  483.  * A UCollator in a locale returned by this function will perform the correct
  484.  * collation for the locale.
  485.  * @param index The index of the desired locale.
  486.  * @return A locale for which collation rules are available, or 0 if none.
  487.  * @see ucol_countAvailable
  488.  */
  489. U_CAPI const char*
  490. ucol_getAvailable(int32_t index);
  491.  
  492. /**
  493.  * Determine how many locales have collation rules available.
  494.  * This function is most useful as determining the loop ending condition for
  495.  * calls to \Ref{ucol_getAvailable}.
  496.  * @return The number of locales for which collation rules are available.
  497.  * @see ucol_getAvailable
  498.  */
  499. U_CAPI int32_t
  500. ucol_countAvailable(void);
  501.  
  502. /**
  503.  * Get the collation rules from a UCollator.
  504.  * The rules will follow the rule syntax.
  505.  * @param coll The UCollator to query.
  506.  * @param length 
  507.  * @return The collation rules.
  508.  */
  509. U_CAPI const UChar*
  510. ucol_getRules(    const    UCollator    *coll, 
  511.         int32_t            *length);
  512.  
  513. /**
  514.  * Get a sort key for a string from a UCollator.
  515.  * Sort keys may be compared using <TT>memcmp</TT>.
  516.  * @param coll The UCollator containing the collation rules.
  517.  * @param source The string to transform.
  518.  * @param sourecLength The length of source, or -1 if null-terminated.
  519.  * @param result A pointer to a buffer to receive the attribute.
  520.  * @param resultLength The maximum size of result.
  521.  * @return The size needed to fully store the sort key..
  522.  * @see ucol_keyHashCode
  523.  */
  524. U_CAPI int32_t
  525. ucol_getSortKey(const    UCollator    *coll,
  526.         const    UChar        *source,
  527.         int32_t            sourceLength,
  528.         uint8_t            *result,
  529.         int32_t            resultLength);
  530.  
  531. /**
  532.  * Generate a hash code for a collation key.
  533.  * A hash code is a 32-bit value suitable for use as a key in a hashtable.
  534.  * @param key The collation key.
  535.  * @param keyLength The length of key.
  536.  * @return A hash code for key.
  537.  * @see ucol_getSortKey
  538.  */
  539. U_CAPI int32_t
  540. ucol_keyHashCode(    const    uint8_t*    key, 
  541.             int32_t        length);
  542.  
  543.  
  544. /** The UCollationElements struct */
  545. struct UCollationElements;
  546. typedef struct UCollationElements UCollationElements;
  547. /**
  548.  * The UCollationElements  is used as an iterator to walk through
  549.  * each character of an international string. Use the iterator to return the
  550.  * ordering priority of the positioned character. The ordering priority of
  551.  * a character, which we refer to as a key, defines how a character is
  552.  * collated in the given collation object.
  553.  * For example, consider the following in Spanish:
  554.  * <pre>
  555.  * .       "ca" -> the first key is key('c') and second key is key('a').
  556.  * .       "cha" -> the first key is key('ch') and second key is key('a').
  557.  * </pre>
  558.  * And in German,
  559.  * <pre>
  560.  * .       "æb"-> the first key is key('a'), the second key is key('e'), and
  561.  * .       the third key is key('b').
  562.  * </pre>
  563.  * The key of a character, is an const UCOL_PRIMARYMASK, UCOL_SECONDARY_MASK,
  564.  * UCOL_TERTIARYMASK.    
  565.  * <p>Example of the iterator usage: (without error checking)
  566.  * <pre>
  567.  * .  void CollationElementIterator_Example()
  568.  * .  {
  569.  * .      UChar *s;
  570.  * .      t_int32 order, primaryOrder;
  571.  * .      UCollationElements *c;
  572.  * .      UCollator *coll;
  573.  * .      UErrorCode success = U_ZERO_ERROR;
  574.  * .      s=(UChar*)malloc(sizeof(UChar) * (strlen("This is a test")+1) );
  575.  * .      u_uastrcpy(s, "This is a test");
  576.  * .      coll = ucol_open(NULL, &success);
  577.  * .      c = ucol_openElements(coll, str, u_strlen(str), &status);
  578.  * .      order = ucol_next(c, &success);
  579.  * .      primaryOrder = order & UCOL_PRIMARYMASK;
  580.  * .      free(s);
  581.  * .      ucol_close(coll);
  582.  * .      ucol_closeElements(c);
  583.  * .  }
  584.  * </pre>
  585.  * <p>
  586.  * ucol_next() returns the collation order of the next
  587.  * character based on the comparison level of the collator.  A collation order 
  588.  * consists of primary order, secondary order and tertiary order.  The data 
  589.  * type of the collation order is <strong>t_int32</strong>.  The first 16 bits of 
  590.  * a collation order is its primary order; the next 8 bits is the secondary 
  591.  * order and the last 8 bits is the tertiary order.
  592.  *
  593.  * @see                Collator
  594.  */
  595. /**
  596.  * Open the collation elements for a string.
  597.  * @param coll The collator containing the desired collation rules.
  598.  * @param text The text to iterate over.
  599.  * @param textLength The number of characters in text, or -1 if null-terminated
  600.  * @param status A pointer to an UErrorCode to receive any errors.
  601.  */
  602. U_CAPI UCollationElements*
  603. ucol_openElements(    const    UCollator       *coll,
  604.             const    UChar           *text,
  605.             int32_t                  textLength,
  606.             UErrorCode         *status);
  607.  
  608. /** Bit mask for primary collation strength */
  609. #define UCOL_PRIMARYMASK    0xFFFF0000
  610.  
  611. /** Bit mask for secondary collation strength */
  612. #define UCOL_SECONDARYMASK  0x0000FF00
  613.  
  614. /** Bit mask for tertiary collation strength */
  615. #define UCOL_TERTIARYMASK   0x000000FF
  616.  
  617. /** This indicates the last element in a UCollationElements has been consumed. */
  618. #define UCOL_NULLORDER        0xFFFFFFFF
  619.  
  620. /**
  621.  * Close a UCollationElements.
  622.  * Once closed, a UCollationElements may no longer be used.
  623.  * @param elems The UCollationElements to close.
  624.  */
  625. U_CAPI void
  626. ucol_closeElements(UCollationElements *elems);
  627.  
  628. /**
  629.  * Reset the collation elements to their initial state.
  630.  * This will move the 'cursor' to the beginning of the text.
  631.  * @param elems The UCollationElements to reset.
  632.  * @see ucol_next
  633.  * @see ucol_previous
  634.  */
  635. U_CAPI void
  636. ucol_reset(UCollationElements *elems);
  637.  
  638. /**
  639.  * Get the ordering priority of the next collation element in the text.
  640.  * A single character may contain more than one collation element.
  641.  * @param elems The UCollationElements containing the text.
  642.  * @param status A pointer to an UErrorCode to receive any errors.
  643.  * @return The next collation elements ordering, or \Ref{UCOL_NULLORDER} if the
  644.  * end of the text is reached.
  645.  */
  646. U_CAPI int32_t
  647. ucol_next(    UCollationElements    *elems,
  648.         UErrorCode        *status);
  649.  
  650. /**
  651.  * Get the ordering priority of the previous collation element in the text.
  652.  * A single character may contain more than one collation element.
  653.  * @param elems The UCollationElements containing the text.
  654.  * @param status A pointer to an UErrorCode to receive any errors.
  655.  * @return The previous collation elements ordering, or \Ref{UCOL_NULLORDER}
  656.  * if the end of the text is reached.
  657.  */
  658. U_CAPI int32_t
  659. ucol_previous(    UCollationElements    *elems,
  660.         UErrorCode        *status);
  661.  
  662. /**
  663.  * Get the maximum length of any expansion sequences that end with the 
  664.  * specified comparison order.
  665.  * This is useful for .... ?
  666.  * @param elems The UCollationElements containing the text.
  667.  * @param order A collation order returned by previous or next.
  668.  * @return The maximum length of any expansion sequences ending with the 
  669.  * specified order.
  670.  */
  671. U_CAPI int32_t
  672. ucol_getMaxExpansion(    const    UCollationElements    *elems,
  673.             int32_t                order);
  674.  
  675. /**
  676.  * Set the text containing the collation elements.
  677.  * This 
  678.  * @param elems The UCollationElements to set.
  679.  * @param text The source text containing the collation elements.
  680.  * @param textLength The length of text, or -1 if null-terminated.
  681.  * @param status A pointer to an UErrorCode to receive any errors.
  682.  * @see ucol_getText
  683.  */
  684. U_CAPI void
  685. ucol_setText(    UCollationElements    *elems,
  686.         const    UChar        *text,
  687.         int32_t            textLength,
  688.         UErrorCode        *status);
  689.  
  690. /**
  691.  * Get the offset of the current source character.
  692.  * This is an offset into the text of the character containing the current
  693.  * collation elements.
  694.  * @param elems The UCollationElements to query.
  695.  * @return The offset of the current source character.
  696.  * @see ucol_setOffset
  697.  */
  698. U_CAPI UTextOffset
  699. ucol_getOffset(const UCollationElements *elems);
  700.  
  701. /**
  702.  * Set the offset of the current source character.
  703.  * This is an offset into the text of the character to be processed.
  704.  * @param elems The UCollationElements to set.
  705.  * @param offset The desired character offset.
  706.  * @param status A pointer to an UErrorCode to receive any errors.
  707.  * @see ucol_getOffset
  708.  */
  709. U_CAPI void
  710. ucol_setOffset(    UCollationElements    *elems,
  711.         UTextOffset        offset,
  712.         UErrorCode        *status);
  713.  
  714. #endif
  715.