BCollator Class Reference

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

Inheritance diagram for BCollator:

List of all members.

Public Member Functions
	BCollator ()
	Construct a collator with the default locale and strength.
	BCollator (const char *locale, int8 strength=B_COLLATE_PRIMARY, bool ignorePunctuation=false)
	Construct a collator for the given locale and strength.
	BCollator (BMessage *archive)
	Unarchive a collator from a message.
	BCollator (const BCollator &other)
	Copy constructor.
	~BCollator ()
	Destructor method.
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.
status_t	Archive (BMessage *archive, bool deep) const
	Archive the object into a BMessage.
int	Compare (const char *s1, const char *s2, int8 strength=B_COLLATE_DEFAULT) const
	Returns the difference betweens the two strings according to the collation defined by the strength parameter.
int8	DefaultStrength () const
	Get the current strength of this catalog.
bool	Equal (const char *s1, const char *s2, int8 strength=B_COLLATE_DEFAULT) const
	Compares two strings for equality.
status_t	GetSortKey (const char *string, BString *key, int8 strength=B_COLLATE_DEFAULT) const
	Compute the sortkey of a string.
bool	Greater (const char *s1, const char *s2, int8 strength=B_COLLATE_DEFAULT) const
	Determine if a string is greater than another.
bool	GreaterOrEqual (const char *s1, const char *s2, int8 strength=B_COLLATE_DEFAULT) 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.
virtual status_t	Perform (perform_code d, void *arg)
	Perform some action (Internal method defined for binary compatibility purposes).
void	SetDefaultStrength (int8 strength)
	Set the strength of the collator.
void	SetIgnorePunctuation (bool ignore)
	Enable or disable punctuation handling.
Static Public Member Functions
static BArchivable *	Instantiate (BMessage *archive)
	Unarchive the collator.

---

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, 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.

---

Constructor & Destructor Documentation

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.

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.

BCollator::BCollator

(

BMessage *

archive

)

Unarchive a collator from a message.

Parameters:

archive

The message to unarchive the BCollator object from.

BCollator::BCollator

(

const BCollator &

other

)

Copy constructor.

Copies a BCollator object from another BCollator object.

Parameters:

other

The BCollator to copy from.

BCollator::~BCollator

(

)

Destructor method.

Deletes the BCollator object freeing the resources it consumes.

---

Member Function Documentation

status_t BArchivable::AllArchived

(

BMessage *

into

)

const [virtual, inherited]

Method relating to the use of BArchiver.

This hook function is called once the first BArchiver that was created in an archiving session is either destroyed, or has its Finish() method called. Implementations of this method can be used, in conjunction with BArchiver::IsArchived(), to reference objects in your archive that you do not own, depending on whether or not those objects were archived by their owners. Implementations of this method should call the implementation of their parent class, the same as for the Archive() method.

Warning:

To guarantee that your AllArchived() method will be called during archival, you must create a BArchiver object in your Archive() implementation.

You should archive any objects you own in your Archive() method implementation, and NOT your AllArchived() method.

See also:

BArchiver BArchiver::Finish()

Reimplemented in BView, BLayout, BGridLayout, BLayoutItem, BTwoDimensionalLayout, BAbstractLayout, and BGroupLayout.

status_t BArchivable::AllUnarchived

(

const BMessage *

archive

)

[virtual, inherited]

Method relating to the use of BUnarchiver.

This hook function is called triggered in the BUnarchiver::Finish() method. In this method, you can rebuild references to objects that may be direct children of your object, or may be children of other objects. Implementations of this method should call the implementation of their parent class, the same as for the Archive() method.

Warning:

To guarantee that your AllUnarchived() method will be called during unarchival, you must create a BUnarchiver object in your archive constructor.

See also:

BUnarchiver, BUnarchiver::Finish()

Reimplemented in BView, BLayout, BGridLayout, BLayoutItem, BTwoDimensionalLayout, BAbstractLayout, and BGroupLayout.

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.

Reimplemented from BArchivable.

int BCollator::Compare	(	const char *	s1,
		const char *	s2,
		int8	strength = B_COLLATE_DEFAULT
	)		const

Returns the difference betweens the two strings according to the collation defined by the strength parameter.

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.
strength	The strength to use for the string comparison.

Return values:

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

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

int8 BCollator::DefaultStrength

(

)

const

Get the current strength of this catalog.

Returns:

The current strength of the catalog.

bool BCollator::Equal	(	const char *	s1,
		const char *	s2,
		int8	strength = B_COLLATE_DEFAULT
	)		const [inline]

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 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.
strength	The strength to use for the string comparison.

Returns:

true if the strings are identical, false otherwise.

References Compare().

status_t BCollator::GetSortKey	(	const char *	string,
		BString *	key,
		int8	strength = B_COLLATE_DEFAULT
	)		const

Compute the sortkey of a string.

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.
strength	The strength to use to compute the sortkey.

Return values:

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

bool BCollator::Greater	(	const char *	s1,
		const char *	s2,
		int8	strength = B_COLLATE_DEFAULT
	)		const [inline]

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.

Parameters:

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

Returns:

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

References Compare().

bool BCollator::GreaterOrEqual	(	const char *	s1,
		const char *	s2,
		int8	strength = B_COLLATE_DEFAULT
	)		const [inline]

Determines if one string is greater than another.

Note:

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

Parameters:

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

Returns:

true if s1 is greater or equal than s2.

References Compare().

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.

static BArchivable * BCollator::Instantiate

(

BMessage *

archive

)

[static]

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.

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.

Reimplemented from BArchivable.

Bcollator & BCollator::operator=

(

const BCollator &

other

)

Assignment operator.

Parameters:

other

the BCollator object to assign from.

void BCollator::SetDefaultStrength

(

int8

strength

)

Set the strength of the collator.

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

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.

void BCollator::SetIgnorePunctuation

(

bool

ignore

)

Enable or disable punctuation handling.

This function enables or disables the handling of punctuation.

Parameters:

ignore

Boolean indicating whether or not punctuation should be ignored.