xref: /haiku/docs/user/locale/Collator.dox (revision 820dca4df6c7bf955c46e8f6521b9408f50b2900)

/*
 * Copyright 2011 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Axel Dörfler, axeld@pinc-software.de
 *		Adrien Destugues <pulkomandy@pulkomandy.ath.cx>
 *		John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *		headers/os/locale/Collator.h	 rev 42274
 *		src/kits/locale/Collator.cpp	 rev 42274
 */


/*!
	\file Collator.h
	\ingroup locale
	\ingroup libbe
	\brief Provides the BCollator class.
*/


/*!
	\class BCollator
	\ingroup locale
	\ingroup libbe
	\brief Class for handling locale-aware collation (sorting) of strings.

	BCollator is designed to handle collation (sorting) of strings. Unlike
	string sorting using strcmp() or similar functions that compare raw bytes
	the collation is done using a set of rules that changes from one locale
	to another. For example, in Spanish, 'ch' is considered to be a letter
	and is sorted between 'c' and 'd'. This class is also able to perform
	natural number sorting so that 2 is sorted before 10 unlike byte-based
	sorting.

	\warning This class is not multithread-safe, as Compare() 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 with the default locale and strength.

	\attention The default collator should be constructed by the BLocale
		instead since it is aware of the currently defined locale.

	This constructor uses \c B_COLLATE_PRIMARY strength.
*/


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

	This constructor loads the data for the given locale. You can also
	set the \a strength and choose if the collator should take
	punctuation into account or not.

	\param locale The \a locale to build the constructor for.
	\param strength The collator class provide four level of \a strength.
		\li \c B_COLLATE_PRIMARY doesn't differentiate e from é,
		\li \c B_COLLATE_SECONDARY takes letter accents into account,
		\li \c B_COLLATE_TERTIARY is case sensitive,
		\li \c B_COLLATE_QUATERNARY is very strict. Most of the time you
			shouldn't need to go this far.
	\param ignorePunctuation Ignore punctuation during sorting.
*/


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

	\param archive The message to unarchive the BCollator object from.
*/


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

	Copies a BCollator object from another BCollator object.

	\param other The BCollator to copy from.
*/


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

	Deletes the BCollator object freeing the resources it consumes.
*/


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

	\param other the BCollator object to assign from.
*/


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

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

	\param strength The collator class provide four level of \a strength.
	 \li \c B_COLLATE_PRIMARY doesn't differentiate e from é,
	 \li \c B_COLLATE_SECONDARY takes letter accents into account,
	 \li \c B_COLLATE_TERTIARY is case sensitive,
	 \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you
		 shouldn't need to go this far.
*/


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

	\returns The current strength of the catalog.
*/


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

	This function enables or disables the handling of punctuation.

	\param ignore Boolean indicating whether or not punctuation should
		be ignored.
*/

/*!
	\fn bool BCollator::IgnorePunctuation() const
	\brief Gets the behavior of the collator with regards to punctuation.

	\returns \c true if the collator will take punctuation into account
	when sorting, \c false otherwise.
*/


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

	The sortkey is a modified version of the input \a string that you can use
	to perform faster comparisons with other sortkeys using strcmp() or a
	similar comparison function. If you need to compare one string with other
	many times, storing the sortkey will allow you to perform the comparisons
	faster.

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

	\retval B_OK if everything went well.
	\retval B_ERROR if an error occurred generating the sortkey.
*/


/*!
	\fn int BCollator::Compare(const char* s1, const char* s2,
		int8 strength) const
	\brief Returns the difference betweens the two strings according to the
		collation defined by the \a strength parameter.

	This method should be used in place of the strcmp() function to perform
	locale-aware comparisons.

	\param s1 The first string to compare.
	\param s2 The second string to compare.
	\param strength The \a strength to use for the string comparison.

	\retval 0 if the strings are equal.
	\retval <0 if s1 is less than s2.
	\retval >0 if s1 is greater than s2.
*/


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

	Note that strings that are not byte-by-byte identical may end up being
	treated as equal by this method. For example two strings may be
	considered equal if the only differences between them are in case and
	punctuation, depending on the \a strength used. Using
	\c B_QUANTERNARY_STRENGTH will force this method return \c true only
	if the strings are byte-for-byte identical.

	\param s1 The first string to compare.
	\param s2 The second string to compare.
	\param strength The \a strength to use for the string comparison.

	\returns \c true if the strings are identical, \c false otherwise.
*/


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

	\note !Greater(s1, s2) is the same as GreaterOrEqual(s2, s1). This means
	there is no need for Lesser(s1, s2) and LesserOrEqual(s1, s2) methods.

	\param s1 The first string to compare.
	\param s2 The second string to compare.
	\param strength The \a strength to use for the string comparison.

	\returns \c true if s1 is greater than, but not equal to, s2.
*/


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

	\note !GreaterOrEqual(s1, s2) is the same as Greater(s2, s1).

	\param s1 The first string to compare.
	\param s2 The second string to compare.
	\param strength The \a strength to use for the string comparison.

	\returns \c true if s1 is greater or equal than s2.
*/


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

	This method allows you to restore a collator that you previously
	archived. It is faster to archive and unarchive a collator than it is
	to create a new one up each time you need a BCollator object with the
	same settings.

	\param archive The message to restore the collator from.

	\returns A pointer to a BArchivable object containing the BCollator or
		\c NULL if an error occurred restoring the \a archive.
*/