haiku/docs/user/locale/Collator.dox

/*!
\class BCollator
\ingroup locale
\brief Class for handling collation of string

BCatalog is designed to handle collations (sorting) of strings.
The collation is done using a set of rules that changes from a country to another.
For example, in spanish, 'ch' is consiidered as a letter and is sorted between 'c' and 'd'.
This class is alsoable to perform natural sorting, so that '2' is sorted before '10',
which is not the case when you do a simple ASCII sort.

\warning This class is not multithread-safe, as Compare() and GetKey() change
the ICUCollator (the strength). So if you want to use a BCollator from
more than one thread, you need to protect it with a lock.

*/

/*!
\fn BCollator::BCollator()
\brief Construct a collator for the default locale.
*/

/*!
\fn BCollator::BCollator(const char* locale, int8 strength = B_COLLATE_PRIMARY, bool ignorePunctiation = false)
\brief Construct a collator for the given locale.

This constructor loads the data for the given locale. You can also adjust the strength and
tell if the collator should take punctuation into account when sorting.
*/

/*!
\fn BCollator::BCollator(BMessage* archive)
\brief Unarchive a collator.
*/

/*!
\fn BCollator::BCollator(const BCollator& other)
\brief Copy constructor.
*/

/*!
\fn BCollator::~Bcollator()
\brief Destructor.
*/

/*!
\fn Bcollator& BCollator::operator=(const BColltr& other)
\brief Assignment operator.
*/

/*!
\fn void BCollator::SetDefaultStrength(int8 strength)
\brief Set the strength of the collator.

The collator class provide four level of strength. These define the handling of
various things.
\item B_COLLATE_PRIMARY doesn't differenciate e from é,
\item B_COLLATE_SECONDARY takes them into account,
\item B_COLLATE_TERTIARY is case sensitive,
\item B_COLLATE_QUATERNARY is very strict. Most of the time you shouldn't need
to go that far.

Note the strength can also be given on a case-by-case basis when calling other
methods.

\param strength The strength the catalog should use as default.
*/

/*!
\fn int8 BCollator::DefaultStrength() const
\brief Returns the current strength of this catalog.
*/

/*!
\fn void BCollator::SetIgnorePunctuation(bool ignore)
\brief Enable or disable punctuation handling

This function enables or disables the handling of punctuations.

\param ignore Boolean telling if the punctuation should be ignored.
*/

/*!
\fn bool BCollator::IgnorePunctuation() const
\brief Return the behaviour ofthe collator regarding punctuation.

This function returns true if the collator will take punctuation into account
when sorting.
*/

/*!
\fn satus_t BCollator::GetSortKey(const char* string, BString* key, int8 strength) const
\brief Compute the sortkey of a string

A sortkey is a modified version of the string that you can use for faster
comparison with other sortkeys, using strcmp or a similar ASCII comparison. If
you need to compare a string with other ones a lot of times, storing the sortkey
will allow you to do the comparisons faster.

\param string String from which to compute the sortkey.
\param key The resulting sortkey.
\param strength The strength to use for computing the sortkey.

\returns B_OK if everything went well.
*/

/*!
\fn int BCollator::Compare(const char* s1, const char* s2, int8 strength) const
\brief Compare two strings.

This function returns the difference betweens the two strings, in a way similar
to strcmp.

\param s1,s2 The strings to compare.
\returns The comparison value. 0 if the strings are equal, negative if s1<s2,
positive if s1>s2.
*/

/*!
\fn bool BCollator::Equal(const char* s1, const char* s2, int8 strength) const
\brief Checks two strings for equality.

Compares two strings for equality. Note that different strings may end up being
equal, for example if the differences are only in case and punctuation,
depending on the strenght used. Quaterary strength will make this function
return true only if the strings are byte-for-byte identical.

\returns True if the two strings are identical.
*/

/*!
\fn bool BCollator::Greater(cosnt char* s1, const char* s2, int8 strength) const)
\brief Tell if a string is greater than another.

\returns True if s1 is greater (not equal) than s2.

\note !Greater(s1, s2) does the same thing as Greater(s2, s1)
*/

/*!
\fn bool BCollator::GreaterOrEqual(cosnt char* s1, const char* s2, int8 strength) const)
\brief Tell if a string is greater than another.

\returns True if s1 is greater or equal to s2.
*/

/*!
\fn static BArchivable* BCollator::Instanciate(BMessage* archive)
\brief Unarchive the collator

Thif function allows you to restore a collator that you previously archived. It
is faster to do that than to buid a collator and set it up by hand every time
you need it with the same settings.
*/