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 from 40 more than one thread you need to protect it with a lock. 41*/ 42 43 44/*! 45 \fn BCollator::BCollator() 46 \brief Construct a collator with the default locale and strength. 47 48 \attention The default collator should be constructed by the BLocale 49 instead since it is aware of the currently defined locale. 50 51 This constructor uses \c B_COLLATE_PRIMARY strength. 52*/ 53 54 55/*! 56 \fn BCollator::BCollator(const char* locale, 57 int8 strength = B_COLLATE_PRIMARY, bool ignorePunctuation = false) 58 \brief Construct a collator for the given \a locale and \a strength. 59 60 This constructor loads the data for the given locale. You can also 61 set the \a strength and choose if the collator should take 62 punctuation into account or not. 63 64 \param locale The \a locale to build the constructor for. 65 \param strength The collator class provide four level of \a strength. 66 \li \c B_COLLATE_PRIMARY doesn't differentiate e from é, 67 \li \c B_COLLATE_SECONDARY takes letter accents into account, 68 \li \c B_COLLATE_TERTIARY is case sensitive, 69 \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you 70 shouldn't need to go this far. 71 \param ignorePunctuation Ignore punctuation during sorting. 72*/ 73 74 75/*! 76 \fn BCollator::BCollator(BMessage* archive) 77 \brief Unarchive a collator from a message. 78 79 \param archive The message to unarchive the BCollator object from. 80*/ 81 82 83/*! 84 \fn BCollator::BCollator(const BCollator& other) 85 \brief Copy constructor. 86 87 Copies a BCollator object from another BCollator object. 88 89 \param other The BCollator to copy from. 90*/ 91 92 93/*! 94 \fn BCollator::~BCollator() 95 \brief Destructor method. 96 97 Deletes the BCollator object freeing the resources it consumes. 98*/ 99 100 101/*! 102 \fn Bcollator& BCollator::operator=(const BCollator& other) 103 \brief Assignment operator. 104 105 \param other the BCollator object to assign from. 106*/ 107 108 109/*! 110 \fn void BCollator::SetDefaultStrength(int8 strength) 111 \brief Set the \a strength of the collator. 112 113 Note that the \a strength can also be chosen on a case-by-case basis 114 when calling other methods. 115 116 \param strength The collator class provide four level of \a strength. 117 \li \c B_COLLATE_PRIMARY doesn't differentiate e from é, 118 \li \c B_COLLATE_SECONDARY takes letter accents into account, 119 \li \c B_COLLATE_TERTIARY is case sensitive, 120 \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you 121 shouldn't need to go this far. 122*/ 123 124 125/*! 126 \fn int8 BCollator::DefaultStrength() const 127 \brief Get the current strength of this catalog. 128 129 \returns The current strength of the catalog. 130*/ 131 132 133/*! 134 \fn void BCollator::SetIgnorePunctuation(bool ignore) 135 \brief Enable or disable punctuation handling. 136 137 This function enables or disables the handling of punctuation. 138 139 \param ignore Boolean indicating whether or not punctuation should 140 be ignored. 141*/ 142 143/*! 144 \fn bool BCollator::IgnorePunctuation() const 145 \brief Gets the behavior of the collator with regards to punctuation. 146 147 \returns \c true if the collator will take punctuation into account 148 when sorting, \c false otherwise. 149*/ 150 151 152/*! 153 \fn status_t BCollator::GetSortKey(const char* string, BString* key, 154 int8 strength) const 155 \brief Compute the sortkey of a \a string. 156 157 The sortkey is a modified version of the input \a string that you can use 158 to perform faster comparisons with other sortkeys using strcmp() or a 159 similar comparison function. If you need to compare one string with other 160 many times, storing the sortkey will allow you to perform the comparisons 161 faster. 162 163 \param string String from which to compute the sortkey. 164 \param key The resulting sortkey. 165 \param strength The \a strength to use to compute the sortkey. 166 167 \retval B_OK if everything went well. 168 \retval B_ERROR if an error occurred generating the sortkey. 169*/ 170 171 172/*! 173 \fn int BCollator::Compare(const char* s1, const char* s2, 174 int8 strength) const 175 \brief Returns the difference betweens the two strings according to the 176 collation defined by the \a strength parameter. 177 178 This method should be used in place of the strcmp() function to perform 179 locale-aware comparisons. 180 181 \param s1 The first string to compare. 182 \param s2 The second string to compare. 183 \param strength The \a strength to use for the string comparison. 184 185 \retval 0 if the strings are equal. 186 \retval <0 if s1 is less than s2. 187 \retval >0 if s1 is greater than s2. 188*/ 189 190 191/*! 192 \fn bool BCollator::Equal(const char* s1, const char* s2, 193 int8 strength) const 194 \brief Compares two strings for equality. 195 196 Note that strings that are not byte-by-byte identical may end up being 197 treated as equal by this method. For example two strings may be 198 considered equal if the only differences between them are in case and 199 punctuation, depending on the \a strength used. Using 200 \c B_QUANTERNARY_STRENGTH will force this method return \c true only 201 if the strings are byte-for-byte identical. 202 203 \param s1 The first string to compare. 204 \param s2 The second string to compare. 205 \param strength The \a strength to use for the string comparison. 206 207 \returns \c true if the strings are identical, \c false otherwise. 208*/ 209 210 211/*! 212 \fn bool BCollator::Greater(const char* s1, const char* s2, 213 int8 strength = B_COLLATE_DEFAULT) const 214 \brief Determine if a string is greater than another. 215 216 \note !Greater(s1, s2) is the same as GreaterOrEqual(s2, s1). This means 217 there is no need for Lesser(s1, s2) and LesserOrEqual(s1, s2) methods. 218 219 \param s1 The first string to compare. 220 \param s2 The second string to compare. 221 \param strength The \a strength to use for the string comparison. 222 223 \returns \c true if s1 is greater than, but not equal to, s2. 224*/ 225 226 227/*! 228 \fn bool BCollator::GreaterOrEqual(const char* s1, const char* s2, 229 int8 strength = B_COLLATE_DEFAULT) const 230 \brief Determines if one string is greater than another. 231 232 \note !GreaterOrEqual(s1, s2) is the same as Greater(s2, s1). 233 234 \param s1 The first string to compare. 235 \param s2 The second string to compare. 236 \param strength The \a strength to use for the string comparison. 237 238 \returns \c true if s1 is greater or equal than s2. 239*/ 240 241 242/*! 243 \fn static BArchivable* BCollator::Instantiate(BMessage* archive) 244 \brief Unarchive the collator 245 246 This method allows you to restore a collator that you previously 247 archived. It is faster to archive and unarchive a collator than it is 248 to create a new one up each time you need a BCollator object with the 249 same settings. 250 251 \param archive The message to restore the collator from. 252 253 \returns A pointer to a BArchivable object containing the BCollator or 254 \c NULL if an error occurred restoring the \a archive. 255*/ 256