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