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