1/* 2 * Copyright 2011 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Axel Dörfler, axeld@pinc-software.de 7 * Adrien Destugues <pulkomandy@pulkomandy.ath.cx> 8 * John Scipione, jscipione@gmail.com 9 * 10 * Corresponds to: 11 * headers/os/locale/Collator.h rev 42274 12 * src/kits/locale/Collator.cpp rev 42274 13 */ 14 15 16/*! 17 \file Collator.h 18 \ingroup locale 19 \ingroup libbe 20 \brief Provides the BCollator class. 21*/ 22 23 24/*! 25 \class BCollator 26 \ingroup locale 27 \ingroup libbe 28 \brief Class for handling locale-aware collation (sorting) of strings. 29 30 BCollator is designed to handle collation (sorting) of strings. Unlike 31 string sorting using strcmp() or similar functions that compare raw bytes 32 the collation is done using a set of rules that changes from one locale 33 to another. For example, in Spanish, 'ch' is considered to be a letter 34 and is sorted between 'c' and 'd'. This class is also able to perform 35 natural number sorting so that 2 is sorted before 10 unlike byte-based 36 sorting. 37 38 \warning This class is not multithread-safe, as Compare() change the 39 ICUCollator (the strength). So if you want to use a BCollator 40 from more than one thread you need to protect it with a lock. 41 42 \since Haiku R1 43*/ 44 45 46/*! 47 \fn BCollator::BCollator() 48 \brief Construct a collator with the default locale and strength. 49 50 \attention The default collator should be constructed by the BLocale 51 instead since it is aware of the currently defined locale. 52 53 This constructor uses \c B_COLLATE_PRIMARY strength. 54 55 \since Haiku R1 56*/ 57 58 59/*! 60 \fn BCollator::BCollator(const char* locale, 61 int8 strength = B_COLLATE_PRIMARY, bool ignorePunctuation = false) 62 \brief Construct a collator for the given \a locale and \a strength. 63 64 This constructor loads the data for the given locale. You can also 65 set the \a strength and choose if the collator should take 66 punctuation into account or not. 67 68 \param locale The \a locale to build the constructor for. 69 \param strength The collator class provide four level of \a strength. 70 \li \c B_COLLATE_PRIMARY doesn't differentiate e from é, 71 \li \c B_COLLATE_SECONDARY takes letter accents into account, 72 \li \c B_COLLATE_TERTIARY is case sensitive, 73 \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you 74 shouldn't need to go this far. 75 \param ignorePunctuation Ignore punctuation during sorting. 76 77 \since Haiku R1 78*/ 79 80 81/*! 82 \fn BCollator::BCollator(BMessage* archive) 83 \brief Unarchive a collator from a message. 84 85 \param archive The message to unarchive the BCollator object from. 86 87 \since Haiku R1 88*/ 89 90 91/*! 92 \fn BCollator::BCollator(const BCollator& other) 93 \brief Copy constructor. 94 95 Copies a BCollator object from another BCollator object. 96 97 \param other The BCollator to copy from. 98 99 \since Haiku R1 100*/ 101 102 103/*! 104 \fn BCollator::~BCollator() 105 \brief Destructor method. 106 107 Deletes the BCollator object freeing the resources it consumes. 108 109 \since Haiku R1 110*/ 111 112 113/*! 114 \fn Bcollator& BCollator::operator=(const BCollator& other) 115 \brief Assignment operator. 116 117 \param other the BCollator object to assign from. 118 119 \since Haiku R1 120*/ 121 122 123/*! 124 \fn void BCollator::SetDefaultStrength(int8 strength) 125 \brief Set the \a strength of the collator. 126 127 Note that the \a strength can also be chosen on a case-by-case basis 128 when calling other methods. 129 130 \param strength The collator class provide four level of \a strength. 131 \li \c B_COLLATE_PRIMARY doesn't differentiate e from é, 132 \li \c B_COLLATE_SECONDARY takes letter accents into account, 133 \li \c B_COLLATE_TERTIARY is case sensitive, 134 \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you 135 shouldn't need to go this far. 136 137 \since Haiku R1 138*/ 139 140 141/*! 142 \fn int8 BCollator::DefaultStrength() const 143 \brief Get the current strength of this catalog. 144 145 \returns The current strength of the catalog. 146 147 \since Haiku R1 148*/ 149 150 151/*! 152 \fn void BCollator::SetIgnorePunctuation(bool ignore) 153 \brief Enable or disable punctuation handling. 154 155 This function enables or disables the handling of punctuation. 156 157 \param ignore Whether or not punctuation should be ignored. 158 159 \since Haiku R1 160*/ 161 162 163/*! 164 \fn bool BCollator::IgnorePunctuation() const 165 \brief Gets the behavior of the collator with regards to punctuation. 166 167 \returns \c true if the collator will take punctuation into account 168 when sorting, \c false otherwise. 169 170 \since Haiku R1 171*/ 172 173 174/*! 175 \fn status_t BCollator::GetSortKey(const char* string, BString* key, 176 int8 strength) const 177 \brief Compute the sortkey of a \a string. 178 179 The sortkey is a modified version of the input \a string that you can use 180 to perform faster comparisons with other sortkeys using strcmp() or a 181 similar comparison function. If you need to compare one string with other 182 many times, storing the sortkey will allow you to perform the comparisons 183 faster. 184 185 \param string String from which to compute the sortkey. 186 \param key The resulting sortkey. 187 \param strength The \a strength to use to compute the sortkey. 188 189 \retval B_OK if everything went well. 190 \retval B_ERROR if an error occurred generating the sortkey. 191 192 \since Haiku R1 193*/ 194 195 196/*! 197 \fn int BCollator::Compare(const char* s1, const char* s2, 198 int8 strength) const 199 \brief Returns the difference betweens the two strings according to the 200 collation defined by the \a strength parameter. 201 202 This method should be used in place of the strcmp() function to perform 203 locale-aware comparisons. 204 205 \param s1 The first string to compare. 206 \param s2 The second string to compare. 207 \param strength The \a strength to use for the string comparison. 208 209 \returns An integer value representing how the strings compare to each 210 other. 211 \retval 0 if the strings are equal. 212 \retval <0 if s1 is less than s2. 213 \retval >0 if s1 is greater than s2. 214 215 \since Haiku R1 216 217 \since Haiku R1 218*/ 219 220 221/*! 222 \fn bool BCollator::Equal(const char* s1, const char* s2, 223 int8 strength) const 224 \brief Compares two strings for equality. 225 226 Note that strings that are not byte-by-byte identical may end up being 227 treated as equal by this method. For example two strings may be 228 considered equal if the only differences between them are in case and 229 punctuation, depending on the \a strength used. Using 230 \c B_QUANTERNARY_STRENGTH will force this method return \c true only 231 if the strings are byte-for-byte identical. 232 233 \param s1 The first string to compare. 234 \param s2 The second string to compare. 235 \param strength The \a strength to use for the string comparison. 236 237 \returns \c true if the strings are identical, \c false otherwise. 238 239 \since Haiku R1 240*/ 241 242 243/*! 244 \fn bool BCollator::Greater(const char* s1, const char* s2, 245 int8 strength = B_COLLATE_DEFAULT) const 246 \brief Determine if a string is greater than another. 247 248 \note !Greater(s1, s2) is the same as GreaterOrEqual(s2, s1). This means 249 there is no need for Lesser(s1, s2) and LesserOrEqual(s1, s2) methods. 250 251 \param s1 The first string to compare. 252 \param s2 The second string to compare. 253 \param strength The \a strength to use for the string comparison. 254 255 \returns \c true if s1 is greater than, but not equal to, s2. 256 257 \since Haiku R1 258*/ 259 260 261/*! 262 \fn bool BCollator::GreaterOrEqual(const char* s1, const char* s2, 263 int8 strength = B_COLLATE_DEFAULT) const 264 \brief Determines if one string is greater than another. 265 266 \note !GreaterOrEqual(s1, s2) is the same as Greater(s2, s1). 267 268 \param s1 The first string to compare. 269 \param s2 The second string to compare. 270 \param strength The \a strength to use for the string comparison. 271 272 \returns \c true if s1 is greater or equal than s2. 273 274 \since Haiku R1 275*/ 276 277 278/*! 279 \fn static BArchivable* BCollator::Instantiate(BMessage* archive) 280 \brief Unarchive the collator 281 282 This method allows you to restore a collator that you previously 283 archived. It is faster to archive and unarchive a collator than it is 284 to create a new one up each time you need a BCollator object with the 285 same settings. 286 287 \param archive The message to restore the collator from. 288 289 \returns A pointer to a BArchivable object containing the BCollator or 290 \c NULL if an error occurred restoring the \a archive. 291 292 \since Haiku R1 293*/ 294