1/*! 2\class BCollator 3\ingroup locale 4\brief Class for handling collation of string 5 6BCatalog is designed to handle collations (sorting) of strings. 7The collation is done using a set of rules that changes from a country to another. 8For example, in spanish, 'ch' is consiidered as a letter and is sorted between 'c' and 'd'. 9This class is alsoable to perform natural sorting, so that '2' is sorted before '10', 10which is not the case when you do a simple ASCII sort. 11 12\warning This class is not multithread-safe, as Compare() and GetKey() change 13the ICUCollator (the strength). So if you want to use a BCollator from 14more than one thread, you need to protect it with a lock. 15 16*/ 17 18/*! 19\fn BCollator::BCollator() 20\brief Construct a collator for the default locale. 21*/ 22 23/*! 24\fn BCollator::BCollator(const char* locale, int8 strength = B_COLLATE_PRIMARY, bool ignorePunctiation = false) 25\brief Construct a collator for the given locale. 26 27This constructor loads the data for the given locale. You can also adjust the strength and 28tell if the collator should take punctuation into account when sorting. 29*/ 30 31/*! 32\fn BCollator::BCollator(BMessage* archive) 33\brief Unarchive a collator. 34*/ 35 36/*! 37\fn BCollator::BCollator(const BCollator& other) 38\brief Copy constructor. 39*/ 40 41/*! 42\fn BCollator::~Bcollator() 43\brief Destructor. 44*/ 45 46/*! 47\fn Bcollator& BCollator::operator=(const BColltr& other) 48\brief Assignment operator. 49*/ 50 51/*! 52\fn void BCollator::SetDefaultStrength(int8 strength) 53\brief Set the strength of the collator. 54 55The collator class provide four level of strength. These define the handling of 56various things. 57\item B_COLLATE_PRIMARY doesn't differenciate e from é, 58\item B_COLLATE_SECONDARY takes them into account, 59\item B_COLLATE_TERTIARY is case sensitive, 60\item B_COLLATE_QUATERNARY is very strict. Most of the time you shouldn't need 61to go that far. 62 63Note the strength can also be given on a case-by-case basis when calling other 64methods. 65 66\param strength The strength the catalog should use as default. 67*/ 68 69/*! 70\fn int8 BCollator::DefaultStrength() const 71\brief Returns the current strength of this catalog. 72*/ 73 74/*! 75\fn void BCollator::SetIgnorePunctuation(bool ignore) 76\brief Enable or disable punctuation handling 77 78This function enables or disables the handling of punctuations. 79 80\param ignore Boolean telling if the punctuation should be ignored. 81*/ 82 83/*! 84\fn bool BCollator::IgnorePunctuation() const 85\brief Return the behaviour ofthe collator regarding punctuation. 86 87This function returns true if the collator will take punctuation into account 88when sorting. 89*/ 90 91/*! 92\fn satus_t BCollator::GetSortKey(const char* string, BString* key, int8 strength) const 93\brief Compute the sortkey of a string 94 95A sortkey is a modified version of the string that you can use for faster 96comparison with other sortkeys, using strcmp or a similar ASCII comparison. If 97you need to compare a string with other ones a lot of times, storing the sortkey 98will allow you to do the comparisons faster. 99 100\param string String from which to compute the sortkey. 101\param key The resulting sortkey. 102\param strength The strength to use for computing the sortkey. 103 104\returns B_OK if everything went well. 105*/ 106 107/*! 108\fn int BCollator::Compare(const char* s1, const char* s2, int8 strength) const 109\brief Compare two strings. 110 111This function returns the difference betweens the two strings, in a way similar 112to strcmp. 113 114\param s1,s2 The strings to compare. 115\returns The comparison value. 0 if the strings are equal, negative if s1<s2, 116positive if s1>s2. 117*/ 118 119/*! 120\fn bool BCollator::Equal(const char* s1, const char* s2, int8 strength) const 121\brief Checks two strings for equality. 122 123Compares two strings for equality. Note that different strings may end up being 124equal, for example if the differences are only in case and punctuation, 125depending on the strenght used. Quaterary strength will make this function 126return true only if the strings are byte-for-byte identical. 127 128\returns True if the two strings are identical. 129*/ 130 131/*! 132\fn bool BCollator::Greater(cosnt char* s1, const char* s2, int8 strength) const) 133\brief Tell if a string is greater than another. 134 135\returns True if s1 is greater (not equal) than s2. 136 137\note !Greater(s1, s2) does the same thing as Greater(s2, s1) 138*/ 139 140/*! 141\fn bool BCollator::GreaterOrEqual(cosnt char* s1, const char* s2, int8 strength) const) 142\brief Tell if a string is greater than another. 143 144\returns True if s1 is greater or equal to s2. 145*/ 146 147/*! 148\fn static BArchivable* BCollator::Instanciate(BMessage* archive) 149\brief Unarchive the collator 150 151Thif function allows you to restore a collator that you previously archived. It 152is faster to do that than to buid a collator and set it up by hand every time 153you need it with the same settings. 154*/ 155