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