820dca4df6
* Fixed headers including: - All rights reserved not All Rights Reserved. - name, email@domain.com not name <email@domain.com> - tabs and spaces - Authors: not Documented by: * Renamed string.dox to String.dox * Renamed midixxx.dox files to MidiXxx.dox * Moved images into images subdirectories and updated Doxfile. * Re-format all files with tabs instead of spaces. * Fix many spelling mistakes. * Added all files, classes, structs, and enums to libbe group.
256 lines
7.5 KiB
Plaintext
256 lines
7.5 KiB
Plaintext
/*
|
|
* 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.
|
|
*/
|