xref: /haiku/docs/user/locale/Collator.dox (revision a33f8fbdec035ff322cc1ef364877a3092e99a09)
1*a33f8fbdSAdrien Destugues/*
2*a33f8fbdSAdrien Destugues * Copyright 2011, Haiku, Inc. All Rights Reserved.
3*a33f8fbdSAdrien Destugues * Distributed under the terms of the MIT License.
4*a33f8fbdSAdrien Destugues *
5*a33f8fbdSAdrien Destugues * Authors:
6*a33f8fbdSAdrien Destugues *		Axel Dörfler, axeld@pinc-software.de
7*a33f8fbdSAdrien Destugues *		Adrien Destugues <pulkomandy@pulkomandy.ath.cx>
8*a33f8fbdSAdrien Destugues *		John Scipione, jscipione@gmail.com
9*a33f8fbdSAdrien Destugues *
10*a33f8fbdSAdrien Destugues * Corresponds to:
11*a33f8fbdSAdrien Destugues *		/trunk/headers/os/locale/Collator.h	 rev 42274
12*a33f8fbdSAdrien Destugues *		/trunk/src/kits/locale/Collator.cpp	 rev 42274
13*a33f8fbdSAdrien Destugues */
14*a33f8fbdSAdrien Destugues
15*a33f8fbdSAdrien Destugues
16*a33f8fbdSAdrien Destugues/*!
17*a33f8fbdSAdrien Destugues	\file Collator.h
18*a33f8fbdSAdrien Destugues	\brief Provides the BCollator class.
19*a33f8fbdSAdrien Destugues*/
20*a33f8fbdSAdrien Destugues
21*a33f8fbdSAdrien Destugues
22e82e8f36SAdrien Destugues/*!
23e82e8f36SAdrien Destugues	\class BCollator
24e82e8f36SAdrien Destugues	\ingroup locale
25e82e8f36SAdrien Destugues	\brief Class for handling collation of string
26e82e8f36SAdrien Destugues
27e82e8f36SAdrien Destugues	BCatalog is designed to handle collations (sorting) of strings.
28*a33f8fbdSAdrien Destugues	The collation is done using a set of rules that changes from a country
29*a33f8fbdSAdrien Destugues	to another.  For example, in spanish, 'ch' is consiidered as a letter
30*a33f8fbdSAdrien Destugues	and is sorted between 'c' and 'd'. This class is alsoable to perform
31*a33f8fbdSAdrien Destugues	natural sorting, so that '2' is sorted before '10', which is not the
32*a33f8fbdSAdrien Destugues	case when you do a simple ASCII sort.
33e82e8f36SAdrien Destugues
34*a33f8fbdSAdrien Destugues	\warning This class is not multithread-safe, as Compare() and GetKey()
35*a33f8fbdSAdrien Destugues	change the ICUCollator (the strength). So if you want to use a
36*a33f8fbdSAdrien Destugues	BCollator from more than one thread, you need to protect it with a lock.
37e82e8f36SAdrien Destugues*/
38e82e8f36SAdrien Destugues
39e82e8f36SAdrien Destugues/*!
40e82e8f36SAdrien Destugues	\fn BCollator::BCollator()
41e82e8f36SAdrien Destugues	\brief Construct a collator for the default locale.
42*a33f8fbdSAdrien Destugues
43*a33f8fbdSAdrien Destugues	Empty contructor.
44e82e8f36SAdrien Destugues*/
45e82e8f36SAdrien Destugues
46e82e8f36SAdrien Destugues/*!
47*a33f8fbdSAdrien Destugues	\fn BCollator::BCollator(const char* locale,
48*a33f8fbdSAdrien Destugues		int8 strength = B_COLLATE_PRIMARY, bool ignorePunctuation = false)
49e82e8f36SAdrien Destugues	\brief Construct a collator for the given locale.
50e82e8f36SAdrien Destugues
51*a33f8fbdSAdrien Destugues	This constructor loads the data for the given locale. You can also
52*a33f8fbdSAdrien Destugues	adjust the strength and tell if the collator should take punctuation
53*a33f8fbdSAdrien Destugues	into account when sorting.
54*a33f8fbdSAdrien Destugues
55*a33f8fbdSAdrien Destugues	\param locale The \a locale.
56*a33f8fbdSAdrien Destugues	\param strength The collator class provide four level of strength. These
57*a33f8fbdSAdrien Destugues		define the handling of various things.
58*a33f8fbdSAdrien Destugues		\li \c B_COLLATE_PRIMARY doesn't differentiate e from é,
59*a33f8fbdSAdrien Destugues		\li \c B_COLLATE_SECONDARY takes letter accents into account,
60*a33f8fbdSAdrien Destugues		\li \c B_COLLATE_TERTIARY is case sensitive,
61*a33f8fbdSAdrien Destugues		\li \c B_COLLATE_QUATERNARY is very strict. Most of the time you
62*a33f8fbdSAdrien Destugues			shouldn't need to go that far.
63*a33f8fbdSAdrien Destugues	\param ignorePunctuation Ignore punctuation in the Collator when sorting.
64e82e8f36SAdrien Destugues*/
65e82e8f36SAdrien Destugues
66e82e8f36SAdrien Destugues/*!
67e82e8f36SAdrien Destugues	\fn BCollator::BCollator(BMessage* archive)
68*a33f8fbdSAdrien Destugues	\brief Unarchive a collator from a message.
69*a33f8fbdSAdrien Destugues
70*a33f8fbdSAdrien Destugues	\param archive The message to unarchive the BCollator from.
71e82e8f36SAdrien Destugues*/
72e82e8f36SAdrien Destugues
73e82e8f36SAdrien Destugues/*!
74e82e8f36SAdrien Destugues	\fn BCollator::BCollator(const BCollator& other)
75e82e8f36SAdrien Destugues	\brief Copy constructor.
76*a33f8fbdSAdrien Destugues
77*a33f8fbdSAdrien Destugues	Constructs a BCollator by making a copy of another BCollator.
78*a33f8fbdSAdrien Destugues
79*a33f8fbdSAdrien Destugues	\param other The BCollator to copy from.
80e82e8f36SAdrien Destugues*/
81e82e8f36SAdrien Destugues
82e82e8f36SAdrien Destugues/*!
83*a33f8fbdSAdrien Destugues	\fn BCollator::~BCollator()
84e82e8f36SAdrien Destugues	\brief Destructor.
85*a33f8fbdSAdrien Destugues
86*a33f8fbdSAdrien Destugues	Standard destructor method.
87e82e8f36SAdrien Destugues*/
88e82e8f36SAdrien Destugues
89e82e8f36SAdrien Destugues/*!
90*a33f8fbdSAdrien Destugues	\fn Bcollator& BCollator::operator=(const BCollator& other)
91e82e8f36SAdrien Destugues	\brief Assignment operator.
92*a33f8fbdSAdrien Destugues
93*a33f8fbdSAdrien Destugues	\param other the BCollator to assign from.
94e82e8f36SAdrien Destugues*/
95e82e8f36SAdrien Destugues
96e82e8f36SAdrien Destugues/*!
97e82e8f36SAdrien Destugues	\fn void BCollator::SetDefaultStrength(int8 strength)
98e82e8f36SAdrien Destugues	\brief Set the strength of the collator.
99e82e8f36SAdrien Destugues
100*a33f8fbdSAdrien Destugues	Note that the \a strength can also be given on a case-by-case basis
101*a33f8fbdSAdrien Destugues	when calling other methods.
102e82e8f36SAdrien Destugues
103*a33f8fbdSAdrien Destugues	\param strength The collator class provide four level of strength.
104*a33f8fbdSAdrien Destugues	These define the handling of various things.
105*a33f8fbdSAdrien Destugues	 \li \c B_COLLATE_PRIMARY doesn't differentiate e from é,
106*a33f8fbdSAdrien Destugues	 \li \c B_COLLATE_SECONDARY takes letter accents into account,
107*a33f8fbdSAdrien Destugues	 \li \c B_COLLATE_TERTIARY is case sensitive,
108*a33f8fbdSAdrien Destugues	 \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you
109*a33f8fbdSAdrien Destugues		 shouldn't need to go that far.
110e82e8f36SAdrien Destugues*/
111e82e8f36SAdrien Destugues
112e82e8f36SAdrien Destugues/*!
113e82e8f36SAdrien Destugues	\fn int8 BCollator::DefaultStrength() const
114*a33f8fbdSAdrien Destugues	\brief Get the current strength of this catalog.
115*a33f8fbdSAdrien Destugues
116*a33f8fbdSAdrien Destugues	\returns the current strength of this catalog.
117e82e8f36SAdrien Destugues*/
118e82e8f36SAdrien Destugues
119e82e8f36SAdrien Destugues/*!
120e82e8f36SAdrien Destugues	\fn void BCollator::SetIgnorePunctuation(bool ignore)
121e82e8f36SAdrien Destugues	\brief Enable or disable punctuation handling
122e82e8f36SAdrien Destugues
123e82e8f36SAdrien Destugues	This function enables or disables the handling of punctuations.
124e82e8f36SAdrien Destugues
125e82e8f36SAdrien Destugues	\param ignore Boolean telling if the punctuation should be ignored.
126e82e8f36SAdrien Destugues*/
127e82e8f36SAdrien Destugues
128e82e8f36SAdrien Destugues/*!
129e82e8f36SAdrien Destugues	\fn bool BCollator::IgnorePunctuation() const
130*a33f8fbdSAdrien Destugues	\brief Gets the behavior of the collator regarding punctuation.
131e82e8f36SAdrien Destugues
132*a33f8fbdSAdrien Destugues	This function returns \c true if the collator will take punctuation into
133*a33f8fbdSAdrien Destugues	account when sorting.
134e82e8f36SAdrien Destugues*/
135e82e8f36SAdrien Destugues
136e82e8f36SAdrien Destugues/*!
137*a33f8fbdSAdrien Destugues	\fn satus_t BCollator::GetSortKey(const char* string, BString* key,
138*a33f8fbdSAdrien Destugues		int8 strength) const
139*a33f8fbdSAdrien Destugues	\brief Compute the sortkey of a string.
140e82e8f36SAdrien Destugues
141cae874d3SAdrien Destugues	A sortkey is a modified version of the string that you can use for faster
142*a33f8fbdSAdrien Destugues	comparison with other sortkeys, using strcmp or a similar ASCII comparison.
143*a33f8fbdSAdrien Destugues	If you need to compare a string with other ones a lot of times, storing
144*a33f8fbdSAdrien Destugues	the sortkey will allow you to do the comparisons faster.
145e82e8f36SAdrien Destugues
146e82e8f36SAdrien Destugues	\param string String from which to compute the sortkey.
147e82e8f36SAdrien Destugues	\param key The resulting sortkey.
148*a33f8fbdSAdrien Destugues	\param strength The \a strength to use for computing the sortkey.
149e82e8f36SAdrien Destugues
150e82e8f36SAdrien Destugues	\returns B_OK if everything went well.
151e82e8f36SAdrien Destugues*/
152e82e8f36SAdrien Destugues
153e82e8f36SAdrien Destugues/*!
154*a33f8fbdSAdrien Destugues	\fn int BCollator::Compare(const char* s1, const char* s2,
155*a33f8fbdSAdrien Destugues		int8 strength) const
156e82e8f36SAdrien Destugues	\brief Compare two strings.
157e82e8f36SAdrien Destugues
158*a33f8fbdSAdrien Destugues	Returns the difference betweens the two strings similar to strcmp().
159e82e8f36SAdrien Destugues
160*a33f8fbdSAdrien Destugues	\param s1 The first string to compare.
161*a33f8fbdSAdrien Destugues	\param s2 The second string to compare.
162*a33f8fbdSAdrien Destugues	\param strength The \a strength to use for comparing the strings.
163*a33f8fbdSAdrien Destugues
164*a33f8fbdSAdrien Destugues	\retval 0 if the strings are equal.
165*a33f8fbdSAdrien Destugues	\retval <0 if s1 is less than s2.
166*a33f8fbdSAdrien Destugues	\retval >0 if s1 is greater than s2.
167e82e8f36SAdrien Destugues*/
168e82e8f36SAdrien Destugues
169e82e8f36SAdrien Destugues/*!
170*a33f8fbdSAdrien Destugues	\fn bool BCollator::Equal(const char* s1, const char* s2,
171*a33f8fbdSAdrien Destugues		int8 strength) const
172e82e8f36SAdrien Destugues	\brief Checks two strings for equality.
173e82e8f36SAdrien Destugues
174*a33f8fbdSAdrien Destugues	Compares two strings for equality. Note that different strings may end
175*a33f8fbdSAdrien Destugues	up being equal, for example if the differences are only in case and
176*a33f8fbdSAdrien Destugues	punctuation, depending on the strength used. Quaterary strength will
177*a33f8fbdSAdrien Destugues	make this function return true only if the strings are byte-for-byte
178*a33f8fbdSAdrien Destugues	identical.
179e82e8f36SAdrien Destugues
180*a33f8fbdSAdrien Destugues	\param s1 The first string to compare.
181*a33f8fbdSAdrien Destugues	\param s2 The second string to compare.
182*a33f8fbdSAdrien Destugues	\param strength The \a strength to use for comparing the strings.
183*a33f8fbdSAdrien Destugues
184*a33f8fbdSAdrien Destugues	\returns \c true if the strings are identical, otherwise \c false.
185e82e8f36SAdrien Destugues*/
186e82e8f36SAdrien Destugues
187e82e8f36SAdrien Destugues/*!
188*a33f8fbdSAdrien Destugues	\fn bool BCollator::Greater(cosnt char* s1, const char* s2,
189*a33f8fbdSAdrien Destugues		int8 strength) const
190*a33f8fbdSAdrien Destugues	\brief Determine if a string is greater than another.
191e82e8f36SAdrien Destugues
192e82e8f36SAdrien Destugues	\note !Greater(s1, s2) does the same thing as Greater(s2, s1)
193*a33f8fbdSAdrien Destugues
194*a33f8fbdSAdrien Destugues	\param s1 The first string to compare.
195*a33f8fbdSAdrien Destugues	\param s2 The second string to compare.
196*a33f8fbdSAdrien Destugues	\param strength The \a strength to use for comparing the strings.
197*a33f8fbdSAdrien Destugues
198*a33f8fbdSAdrien Destugues	\returns \c true if s1 is greater than, but not equal to, s2.
199e82e8f36SAdrien Destugues*/
200e82e8f36SAdrien Destugues
201e82e8f36SAdrien Destugues/*!
202*a33f8fbdSAdrien Destugues	\fn bool BCollator::GreaterOrEqual(cosnt char* s1, const char* s2,
203*a33f8fbdSAdrien Destugues		int8 strength) const
204e82e8f36SAdrien Destugues	\brief Tell if a string is greater than another.
205e82e8f36SAdrien Destugues
206*a33f8fbdSAdrien Destugues	\param s1 The first string to compare.
207*a33f8fbdSAdrien Destugues	\param s2 The second string to compare.
208*a33f8fbdSAdrien Destugues	\param strength The \a strength to use for comparing the strings.
209*a33f8fbdSAdrien Destugues
210*a33f8fbdSAdrien Destugues	\returns \c true if s1 is greater or equal than s2.
211e82e8f36SAdrien Destugues*/
212cae874d3SAdrien Destugues
213cae874d3SAdrien Destugues/*!
214*a33f8fbdSAdrien Destugues	\fn static BArchivable* BCollator::Instantiate(BMessage* archive)
215cae874d3SAdrien Destugues	\brief Unarchive the collator
216cae874d3SAdrien Destugues
217*a33f8fbdSAdrien Destugues	This function allows you to restore a collator that you previously
218*a33f8fbdSAdrien Destugues	archived. It is faster to do that than to buid a collator and set
219*a33f8fbdSAdrien Destugues	it up by hand every time you need it with the same settings.
220*a33f8fbdSAdrien Destugues
221*a33f8fbdSAdrien Destugues	\param archive The message to restore the collator from.
222*a33f8fbdSAdrien Destugues
223*a33f8fbdSAdrien Destugues	\returns A BArchivable object containing the BCollator or \c NULL.
224cae874d3SAdrien Destugues*/
225*a33f8fbdSAdrien Destugues
226