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. So if you want to use a 39 BCollator from more than one thread you need to protect it with 40 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::SetStrength(int8 strength) 125 \brief Set the \a strength of the collator. 126 127 \param strength The collator class provide four level of \a strength. 128 \li \c B_COLLATE_PRIMARY doesn't differentiate e from ��, 129 \li \c B_COLLATE_SECONDARY takes letter accents into account, 130 \li \c B_COLLATE_TERTIARY is case sensitive, 131 \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you 132 shouldn't need to go this far. 133 134 \since Haiku R1 135*/ 136 137 138/*! 139 \fn void BCollator::SetIgnorePunctuation(bool ignore) 140 \brief Enable or disable punctuation handling. 141 142 This function enables or disables the handling of punctuation. 143 144 \param ignore Whether or not punctuation should be ignored. 145 146 \since Haiku R1 147*/ 148 149 150/*! 151 \fn bool BCollator::IgnorePunctuation() const 152 \brief Gets the behavior of the collator with regards to punctuation. 153 154 \returns \c true if the collator will take punctuation into account 155 when sorting, \c false otherwise. 156 157 \since Haiku R1 158*/ 159 160 161/*! 162 \fn void BCollator::SetNumericSorting(bool ignore) 163 \brief Enable or disable numeric order sorting. 164 165 Numeric sorting enables the collator to identify strings of digits as 166 numbers, and sort them in ascending number. For example, the string "123" 167 is sorted after "234". Numbers and other characters can be mixed in the 168 same string. 169 170 \since Haiku R1 171*/ 172 173 174/*! 175 \fn status_t BCollator::GetSortKey(const char* string, BString* key) 176 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 188 \retval B_OK if everything went well. 189 \retval B_ERROR if an error occurred generating the sortkey. 190 191 \since Haiku R1 192*/ 193 194 195/*! 196 \fn int BCollator::Compare(const char* s1, const char* s2) 197 const 198 \brief Returns the difference betweens the two strings. 199 200 This method should be used in place of the strcmp() function to perform 201 locale-aware comparisons. 202 203 \param s1 The first string to compare. 204 \param s2 The second string to compare. 205 206 \returns An integer value representing how the strings compare to each 207 other. 208 \retval 0 if the strings are equal. 209 \retval <0 if s1 is less than s2. 210 \retval >0 if s1 is greater than s2. 211 212 \since Haiku R1 213 214 \since Haiku R1 215*/ 216 217 218/*! 219 \fn bool BCollator::Equal(const char* s1, const char* s2) 220 const 221 \brief Compares two strings for equality. 222 223 Note that strings that are not byte-by-byte identical may end up being 224 treated as equal by this method. For example two strings may be 225 considered equal if the only differences between them are in case and 226 punctuation, depending on the \a strength used. Using 227 \c B_QUANTERNARY_STRENGTH will force this method return \c true only 228 if the strings are byte-for-byte identical. 229 230 \param s1 The first string to compare. 231 \param s2 The second string to compare. 232 233 \returns \c true if the strings are identical, \c false otherwise. 234 235 \since Haiku R1 236*/ 237 238 239/*! 240 \fn bool BCollator::Greater(const char* s1, const char* s2) 241 const 242 \brief Determine if a string is greater than another. 243 244 \note !Greater(s1, s2) is the same as GreaterOrEqual(s2, s1). This means 245 there is no need for Lesser(s1, s2) and LesserOrEqual(s1, s2) methods. 246 247 \param s1 The first string to compare. 248 \param s2 The second string to compare. 249 250 \returns \c true if s1 is greater than, but not equal to, s2. 251 252 \since Haiku R1 253*/ 254 255 256/*! 257 \fn bool BCollator::GreaterOrEqual(const char* s1, const char* s2) 258 const 259 \brief Determines if one string is greater than another. 260 261 \note !GreaterOrEqual(s1, s2) is the same as Greater(s2, s1). 262 263 \param s1 The first string to compare. 264 \param s2 The second string to compare. 265 266 \returns \c true if s1 is greater or equal than s2. 267 268 \since Haiku R1 269*/ 270 271 272/*! 273 \fn static BArchivable* BCollator::Instantiate(BMessage* archive) 274 \brief Unarchive the collator 275 276 This method allows you to restore a collator that you previously 277 archived. 278 279 \param archive The message to restore the collator from. 280 281 \returns A pointer to a BArchivable object containing the BCollator or 282 \c NULL if an error occurred restoring the \a archive. 283 284 \since Haiku R1 285*/ 286