Class for handling locale-aware collation (sorting) of strings. More...

Inherits BArchivable.

Public Member Functions
	BCollator ()
	Construct a collator with the default locale and strength.

	BCollator (BMessage *archive)
	Unarchive a collator from a message.

	BCollator (const BCollator &other)
	Copy constructor.

	BCollator (const char *locale, int8 strength=B_COLLATE_PRIMARY, bool ignorePunctuation=false)
	Construct a collator for the given locale and strength.

	~BCollator ()
	Destructor method.

status_t	Archive (BMessage *archive, bool deep) const
	Archive the object into a BMessage.

int	Compare (const char s1, const char s2) const
	Returns the difference betweens the two strings.

bool	Equal (const char s1, const char s2) const
	Compares two strings for equality.

status_t	GetSortKey (const char string, BString key) const
	Compute the sortkey of a string.

bool	Greater (const char s1, const char s2) const
	Determine if a string is greater than another.

bool	GreaterOrEqual (const char s1, const char s2) const
	Determines if one string is greater than another.

bool	IgnorePunctuation () const
	Gets the behavior of the collator with regards to punctuation.

BCollator &	operator= (const BCollator &source)
	Assignment operator.

void	SetIgnorePunctuation (bool ignore)
	Enable or disable punctuation handling.

status_t	SetNumericSorting (bool enable)
	Enable or disable numeric order sorting.

status_t	SetStrength (int8 strength) const
	Set the strength of the collator.

Public Member Functions inherited from BArchivable
	BArchivable ()
	Constructor. Does nothing.

	BArchivable (BMessage *from)
	Constructor. Does important behind-the-scenes work in the unarchiving process.

virtual	~BArchivable ()
	Destructor. Does nothing.

virtual status_t	AllArchived (BMessage *archive) const
	Method relating to the use of `BArchiver`.

virtual status_t	AllUnarchived (const BMessage *archive)
	Method relating to the use of `BUnarchiver`.

virtual status_t	Archive (BMessage *into, bool deep=true) const
	Archive the object into a BMessage.

virtual status_t	Perform (perform_code d, void *arg)
	Perform some action (Internal method defined for binary compatibility purposes).

Static Public Member Functions
static BArchivable *	Instantiate (BMessage *archive)
	Unarchive the collator.

Static Public Member Functions inherited from BArchivable
static BArchivable *	Instantiate (BMessage *archive)
	Static member to restore objects from messages.

Detailed Description

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. So if you want to use a BCollator from more than one thread you need to protect it with a lock.

Since: Haiku R1

Constructor & Destructor Documentation

◆ BCollator() [1/4]

BCollator::BCollator ( )

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 B_COLLATE_PRIMARY strength.

Since: Haiku R1

◆ BCollator() [2/4]

BCollator::BCollator	(	const char *	locale,
		int8	strength = `B_COLLATE_PRIMARY`,
		bool	ignorePunctuation = `false`
	)

Construct a collator for the given locale and strength.

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

Parameters

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

Since: Haiku R1

◆ BCollator() [3/4]

BCollator::BCollator ( BMessage * archive )

Unarchive a collator from a message.

Parameters

archive The message to unarchive the BCollator object from.

Since: Haiku R1

◆ BCollator() [4/4]

BCollator::BCollator ( const BCollator & other )

Copy constructor.

Copies a BCollator object from another BCollator object.

Parameters

other The BCollator to copy from.

Since: Haiku R1

◆ ~BCollator()

BCollator::~BCollator ( )

Destructor method.

Deletes the BCollator object freeing the resources it consumes.

Since: Haiku R1

Member Function Documentation

◆ Archive()

status_t BCollator::Archive	(	BMessage *	into,
		bool	deep
	)		const

virtual

Archive the object into a BMessage.

You should call this method from your derived implementation as it adds the data needed to instantiate your object to the message.

Parameters

into	The message you store your object in.
deep	If `true`, all children of this object should be archived as well.

Return values

B_OK	The archive operation was successful.
B_BAD_VALUE	`NULL` archive message.
B_ERROR	The archive operation failed.

Since: BeOS R3

Reimplemented from BArchivable.

◆ Compare()

int BCollator::Compare	(	const char *	s1,
		const char *	s2
	)		const

Returns the difference betweens the two strings.

const

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

Parameters

s1	The first string to compare.
s2	The second string to compare.

Returns: An integer value representing how the strings compare to each other.

Return values

0	if the strings are equal.
<0	if s1 is less than s2.
>0	if s1 is greater than s2.

Since: Haiku R1; Haiku R1

Referenced by Equal(), Greater(), and GreaterOrEqual().

◆ Equal()

bool BCollator::Equal	(	const char *	s1,
		const char *	s2
	)		const

inline

Compares two strings for equality.

const

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 strength used. Using B_QUANTERNARY_STRENGTH will force this method return true only if the strings are byte-for-byte identical.

Parameters

s1	The first string to compare.
s2	The second string to compare.

Returns: true if the strings are identical, false otherwise.

Since: Haiku R1

References Compare().

◆ GetSortKey()

status_t BCollator::GetSortKey	(	const char *	string,
		BString *	key
	)		const

Compute the sortkey of a string.

const

The sortkey is a modified version of the input 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.

Parameters

string	String from which to compute the sortkey.
key	The resulting sortkey.

Return values

B_OK	if everything went well.
B_ERROR	if an error occurred generating the sortkey.

Since: Haiku R1

◆ Greater()

bool BCollator::Greater	(	const char *	s1,
		const char *	s2
	)		const

inline

Determine if a string is greater than another.

const

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.

Parameters

s1	The first string to compare.
s2	The second string to compare.

Returns: true if s1 is greater than, but not equal to, s2.

Since: Haiku R1

References Compare().

◆ GreaterOrEqual()

bool BCollator::GreaterOrEqual	(	const char *	s1,
		const char *	s2
	)		const

inline

Determines if one string is greater than another.

const

Note: !GreaterOrEqual(s1, s2) is the same as Greater(s2, s1).

Parameters

s1	The first string to compare.
s2	The second string to compare.

Returns: true if s1 is greater or equal than s2.

Since: Haiku R1

References Compare().

◆ IgnorePunctuation()

bool BCollator::IgnorePunctuation ( ) const

Gets the behavior of the collator with regards to punctuation.

Returns: true if the collator will take punctuation into account when sorting, false otherwise.

Since: Haiku R1

◆ Instantiate()

static BArchivable * BCollator::Instantiate ( BMessage * archive )

static

Unarchive the collator.

This method allows you to restore a collator that you previously archived.

Parameters

archive The message to restore the collator from.

Returns: A pointer to a BArchivable object containing the BCollator or NULL if an error occurred restoring the archive.

Since: Haiku R1

◆ operator=()

Bcollator & BCollator::operator= ( const BCollator & other )

Assignment operator.

Parameters

other the BCollator object to assign from.

Since: Haiku R1

◆ SetIgnorePunctuation()

void BCollator::SetIgnorePunctuation ( bool ignore )

Enable or disable punctuation handling.

This function enables or disables the handling of punctuation.

Parameters

ignore Whether or not punctuation should be ignored.

Since: Haiku R1

◆ SetNumericSorting()

void BCollator::SetNumericSorting ( bool ignore )

Enable or disable numeric order sorting.

Numeric sorting enables the collator to identify strings of digits as numbers, and sort them in ascending number. For example, the string "123" is sorted after "234". Numbers and other characters can be mixed in the same string.

Since: Haiku R1

◆ SetStrength()

void BCollator::SetStrength ( int8 strength ) const

Set the strength of the collator.

Parameters

strength

The collator class provide four level of strength.

B_COLLATE_PRIMARY doesn't differentiate e from é,
B_COLLATE_SECONDARY takes letter accents into account,
B_COLLATE_TERTIARY is case sensitive,
B_COLLATE_QUATERNARY is very strict. Most of the time you shouldn't need to go this far.

Since: Haiku R1

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BCollator() [1/4]

◆ BCollator() [2/4]

◆ BCollator() [3/4]

◆ BCollator() [4/4]

◆ ~BCollator()

Member Function Documentation

◆ Archive()

◆ Compare()

◆ Equal()

◆ GetSortKey()

◆ Greater()

◆ GreaterOrEqual()

◆ IgnorePunctuation()

◆ Instantiate()

◆ operator=()

◆ SetIgnorePunctuation()

◆ SetNumericSorting()

◆ SetStrength()