docs/user/locale/Collator.dox

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