Public Member Functions | Static Public Member Functions | List of all members
BCollator Class Reference

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. More...
 
 BCollator (const char *locale, int8 strength=B_COLLATE_PRIMARY, bool ignorePunctuation=false)
 Construct a collator for the given locale and strength. More...
 
 BCollator (BMessage *archive)
 Unarchive a collator from a message. More...
 
 BCollator (const BCollator &other)
 Copy constructor. More...
 
 ~BCollator ()
 Destructor method. More...
 
status_t Archive (BMessage *archive, bool deep) const
 Archive the object into a BMessage. More...
 
int Compare (const char *s1, const char *s2) const
 Returns the difference betweens the two strings. More...
 
bool Equal (const char *s1, const char *s2) const
 Compares two strings for equality. More...
 
status_t GetSortKey (const char *string, BString *key) const
 Compute the sortkey of a string. More...
 
bool Greater (const char *s1, const char *s2) const
 Determine if a string is greater than another. More...
 
bool GreaterOrEqual (const char *s1, const char *s2) const
 Determines if one string is greater than another. More...
 
bool IgnorePunctuation () const
 Gets the behavior of the collator with regards to punctuation. More...
 
BCollatoroperator= (const BCollator &source)
 Assignment operator. More...
 
void SetIgnorePunctuation (bool ignore)
 Enable or disable punctuation handling. More...
 
status_t SetNumericSorting (bool enable)
 Enable or disable numeric order sorting. More...
 
status_t SetStrength (int8 strength) const
 Set the strength of the collator. More...
 
- Public Member Functions inherited from BArchivable
 BArchivable (BMessage *from)
 Constructor. Does important behind-the-scenes work in the unarchiving process. More...
 
 BArchivable ()
 Constructor. Does nothing. More...
 
virtual ~BArchivable ()
 Destructor. Does nothing. More...
 
virtual status_t AllArchived (BMessage *archive) const
 Method relating to the use of BArchiver. More...
 
virtual status_t AllUnarchived (const BMessage *archive)
 Method relating to the use of BUnarchiver. More...
 
virtual status_t Perform (perform_code d, void *arg)
 Perform some action (Internal method defined for binary compatibility purposes).
 

Static Public Member Functions

static BArchivableInstantiate (BMessage *archive)
 Unarchive the collator. More...
 
- Static Public Member Functions inherited from BArchivable
static BArchivableInstantiate (BMessage *archive)
 Static member to restore objects from messages. More...
 

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
localeThe locale to build the constructor for.
strengthThe 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.
ignorePunctuationIgnore punctuation during sorting.
Since
Haiku R1

◆ BCollator() [3/4]

BCollator::BCollator ( BMessage archive)

Unarchive a collator from a message.

Parameters
archiveThe 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
otherThe 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
intoThe message you store your object in.
deepIf true, all children of this object should be archived as well.
Return values
B_OKThe archive operation was successful.
B_BAD_VALUENULL archive message.
B_ERRORThe 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
s1The first string to compare.
s2The second string to compare.
Returns
An integer value representing how the strings compare to each other.
Return values
0if the strings are equal.
<0if s1 is less than s2.
>0if s1 is greater than s2.
Since
Haiku R1
Haiku R1

◆ 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
s1The first string to compare.
s2The 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
stringString from which to compute the sortkey.
keyThe resulting sortkey.
Return values
B_OKif everything went well.
B_ERRORif 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
s1The first string to compare.
s2The 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
s1The first string to compare.
s2The 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
archiveThe 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
otherthe 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
ignoreWhether 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
strengthThe 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