[apple/javascriptcore.git] / icu / unicode / ucol.h

/*
*******************************************************************************
* 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" &lt; "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.
Commit	Line	Data
9dae56ea A	1	/*
	2	*******************************************************************************
	3	* Copyright (c) 1996-2005, International Business Machines Corporation and others.
	4	* All Rights Reserved.
	5	*******************************************************************************
	6	*/
	7
	8	#ifndef UCOL_H
	9	#define UCOL_H
	10
	11	#include "unicode/utypes.h"
	12
	13	#if !UCONFIG_NO_COLLATION
	14
	15	#include "unicode/unorm.h"
	16	#include "unicode/parseerr.h"
	17	#include "unicode/uloc.h"
	18	#include "unicode/uset.h"
	19
	20	/**
	21	* \file
	22	* \brief C API: Collator
	23	*
	24	* <h2> Collator C API </h2>
	25	*
	26	* The C API for Collator performs locale-sensitive
	27	* string comparison. You use this service to build
	28	* searching and sorting routines for natural language text.
	29	* <em>Important: </em>The ICU collation service has been reimplemented
	30	* in order to achieve better performance and UCA compliance.
	31	* For details, see the
	32	* <a href="http://icu.sourceforge.net/cvs/icu/~checkout~/icuhtml/design/collation/ICU_collation_design.htm">
	33	* collation design document</a>.
	34	* <p>
	35	* For more information about the collation service see
	36	* <a href="http://icu.sourceforge.net/icu/userguide/Collate_Intro.html">the users guide</a>.
	37	* <p>
	38	* Collation service provides correct sorting orders for most locales supported in ICU.
	39	* If specific data for a locale is not available, the orders eventually falls back
	40	* to the <a href="http://www.unicode.org/unicode/reports/tr10/">UCA sort order</a>.
	41	* <p>
	42	* Sort ordering may be customized by providing your own set of rules. For more on
	43	* this subject see the
	44	* <a href="http://icu.sourceforge.net/icu/userguide/Collate_Customization.html">
	45	* Collation customization</a> section of the users guide.
	46	* <p>
	47	* @see UCollationResult
	48	* @see UNormalizationMode
	49	* @see UCollationStrength
	50	* @see UCollationElements
	51	*/
	52
	53	/** A collation element iterator.
	54	* For usage in C programs.
	55	*/
	56	struct collIterate;
	57	/** structure representing collation element iterator instance
	58	* @stable ICU 2.0
	59	*/
	60	typedef struct collIterate collIterate;
	61
	62	/** A collator.
	63	* For usage in C programs.
	64	*/
65	struct UCollator;
66	/** structure representing a collator object instance
67	* @stable ICU 2.0
68	*/
69	typedef struct UCollator UCollator;
70
71
72	/**
73	* UCOL_LESS is returned if source string is compared to be less than target
74	* string in the u_strcoll() method.
75	* UCOL_EQUAL is returned if source string is compared to be equal to target
76	* string in the u_strcoll() method.
77	* UCOL_GREATER is returned if source string is compared to be greater than
78	* target string in the u_strcoll() method.
79	* @see u_strcoll()
80	* <p>
81	* Possible values for a comparison result
82	* @stable ICU 2.0
83	*/
84	typedef enum {
85	/** string a == string b */
86	UCOL_EQUAL = 0,
87	/** string a > string b */
88	UCOL_GREATER = 1,
89	/** string a < string b */
90	UCOL_LESS = -1
91	} UCollationResult ;
92
93
94	/** Enum containing attribute values for controling collation behavior.
95	* Here are all the allowable values. Not every attribute can take every value. The only
96	* universal value is UCOL_DEFAULT, which resets the attribute value to the predefined
97	* value for that locale
98	* @stable ICU 2.0
99	*/
100	typedef enum {
101	/** accepted by most attributes */
102	UCOL_DEFAULT = -1,
103
104	/** Primary collation strength */
105	UCOL_PRIMARY = 0,
106	/** Secondary collation strength */
107	UCOL_SECONDARY = 1,
108	/** Tertiary collation strength */
109	UCOL_TERTIARY = 2,
110	/** Default collation strength */
111	UCOL_DEFAULT_STRENGTH = UCOL_TERTIARY,
112	UCOL_CE_STRENGTH_LIMIT,
113	/** Quaternary collation strength */
114	UCOL_QUATERNARY=3,
115	/** Identical collation strength */
116	UCOL_IDENTICAL=15,
117	UCOL_STRENGTH_LIMIT,
118
119	/** Turn the feature off - works for UCOL_FRENCH_COLLATION,
120	UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE
121	& UCOL_DECOMPOSITION_MODE*/
122	UCOL_OFF = 16,
123	/** Turn the feature on - works for UCOL_FRENCH_COLLATION,
124	UCOL_CASE_LEVEL, UCOL_HIRAGANA_QUATERNARY_MODE
125	& UCOL_DECOMPOSITION_MODE*/
126	UCOL_ON = 17,
127
128	/** Valid for UCOL_ALTERNATE_HANDLING. Alternate handling will be shifted */
129	UCOL_SHIFTED = 20,
130	/** Valid for UCOL_ALTERNATE_HANDLING. Alternate handling will be non ignorable */
131	UCOL_NON_IGNORABLE = 21,
132
133	/** Valid for UCOL_CASE_FIRST -
134	lower case sorts before upper case */
135	UCOL_LOWER_FIRST = 24,
136	/** upper case sorts before lower case */
137	UCOL_UPPER_FIRST = 25,
138
139	UCOL_ATTRIBUTE_VALUE_COUNT
140
141	} UColAttributeValue;
142
143	/**
144	* Base letter represents a primary difference. Set comparison
145	* level to UCOL_PRIMARY to ignore secondary and tertiary differences.
146	* Use this to set the strength of a Collator object.
147	* Example of primary difference, "abc" < "abd"
148	*
149	* Diacritical differences on the same base letter represent a secondary
150	* difference. Set comparison level to UCOL_SECONDARY to ignore tertiary
151	* differences. Use this to set the strength of a Collator object.
152