xtd::basic_string_comparer< char_t > Class Template Reference

Inheritance diagram for xtd::basic_string_comparer< char_t >:

Definition

template<class char_t>
class xtd::basic_string_comparer< char_t >

Represents a string comparison operation that uses specific case and culture-based or ordinal comparison rules.

Definition

template<class char_t>
class basic_string_comparer : public xtd::object, public xtd::collections::generic::icomparer<xtd::basic_string<char_t>>, public xtd::collections::generic::iequality_comparer<xtd::basic_string<char_t>>;

Header

#include <xtd/basic_string_comparer

Namespace

xtd

Library

xtd.core

Public Static Properties
static basic_string_comparer	current_culture ()
	Gets a xtd::basic_string_comparer object that performs a case-sensitive string comparison using the word comparison rules of the current culture.
static basic_string_comparer	current_culture_ignore_case ()
	Gets a xtd::basic_string_comparer object that performs case-insensitive string comparisons using the word comparison rules of the current culture.
static basic_string_comparer	invariant_culture ()
static basic_string_comparer	invariant_culture_ignore_case ()
static const basic_string_comparer &	ordinal ()
	Gets a xtd::basic_string_comparer object that performs a case-sensitive ordinal string comparison.
static const basic_string_comparer &	ordinal_ignore_case ()
	Gets a xtd::basic_string_comparer object that performs a case-insensitive ordinal string comparison.

Public Static Methods
static basic_string_comparer	from_comparison (xtd::string_comparison comparison)
	Converts the specified xtd::string_comparison instance to a StringComparer instance.
static bool	is_well_known_ordinal_comparer (const xtd::collections::generic::iequality_comparer< xtd::basic_string< char_t > > &comparer, bool &ignore_case)
	Determines whether the specified xtd::collections::generic::iequality_comparer <type_t> is a well-known ordinal string comparer.

Public Methods
template<class object_t >
int32	compare (const object_t &x, const object_t &y) const
	When overridden in a derived class, compares two objects and returns an indication of their relative sort order.
int32	compare (const xtd::basic_string< char_t > &x, const xtd::basic_string< char_t > &y) const noexcept override
	When overridden in a derived class, compares two strings and returns an indication of their relative sort order.
bool	equals (const object &obj) const noexcept override
	Determines whether the specified object is equal to the current object.
template<class object_t >
bool	equals (const object_t &x, const object_t &y) const
	When overridden in a derived class, indicates whether two objects are equal.
bool	equals (const xtd::basic_string< char_t > &x, const xtd::basic_string< char_t > &y) const noexcept override
	When overridden in a derived class, indicates whether two strings are equal.
template<class object_t >
xtd::size	get_hash_code (const object_t &obj) const
	When overridden in a derived class, gets the hash code for the specified object.
xtd::size	get_hash_code (const xtd::basic_string< char_t > &obj) const noexcept override
	When overridden in a derived class, gets the hash code for the specified string.

Protected Constructors
	basic_string_comparer ()=default
	Initializes a new instance of the xtd::basic_string_comparer class.

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t >
xtd::uptr< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.
virtual int32	compare (const xtd::basic_string< char_t > &x, const xtd::basic_string< char_t > &y) const=0
	Compares two entities and returns a value indicating whether one is less than, equal to, or greater than the other.
Public Member Functions inherited from xtd::collections::generic::iequality_comparer< xtd::basic_string< char_t > >
Static Public Member Functions inherited from xtd::object
template<class object_a_t , class object_b_t >
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t , class object_b_t >
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

basic_string_comparer()

template<class char_t >

xtd::basic_string_comparer< char_t >::basic_string_comparer ( )

protecteddefault

Initializes a new instance of the xtd::basic_string_comparer class.

Todo:

Uncomment following lines when xtd::globalization::culture_info and xtd::globalization::compare_options are developped.

Todo:

Uncomment following lines when xtd::globalization::culture_info and xtd::globalization::compare_options are developped.

Member Function Documentation

current_culture()

template<class char_t >

static basic_string_comparer xtd::basic_string_comparer< char_t >::current_culture ( )

inlinestatic

Gets a xtd::basic_string_comparer object that performs a case-sensitive string comparison using the word comparison rules of the current culture.

Returns

A xtd::basic_string_comparer object.

Remarks

The xtd::basic_string_comparer returned by the xtd::basic_string_comparer::current_culture property can be used when strings are linguistically relevant. For example, if strings are displayed to the user, or if strings are the result of user interaction, culture-sensitive string comparison should be used to order the string data.

The current culture is the xtd::globalization::culture_info object associated with the current thread.

The xtd::basic_string_comparer::current_culture property actually returns an instance of an anonymous class derived from the basic_string_comparer class.

Each call to the basic_string_comparer::current_culture property get accessor returns a new basic_string_comparer object, as the following code shows.

void compare_current_culture_basic_string_comparer() {
  basic_string_comparer basic_string_comparer1 = basic_string_comparer::current_culture;
  basic_string_comparer basic_string_comparer2 = basic_string_comparer::current_culture;
  // Displays false
  console::write_line(basic_string_comparer::reference_equals(basic_string_comparer1, basic_string_comparer2));
}

To improve performance, you can store the xtd::basic_string_comparer object in a local variable rather than retrieve the value of the xtd::basic_string_comparer::current_culture property multiple times.

current_culture_ignore_case()

template<class char_t >

static basic_string_comparer xtd::basic_string_comparer< char_t >::current_culture_ignore_case ( )

inlinestatic

Gets a xtd::basic_string_comparer object that performs case-insensitive string comparisons using the word comparison rules of the current culture.

Returns

A xtd::basic_string_comparer object.

Remarks

The current culture is the xtd::globalization::culture_info object associated with the current thread; it is returned by the xtd::globalization::culture_info::current_culture property.

The xtd::basic_string_comparer returned by the xtd::basic_string_comparer::current_culture_ignore_case property can be used when strings are linguistically relevant but their case is not. For example, if strings are displayed to the user but case is unimportant, culture-sensitive, case-insensitive string comparison should be used to order the string data.

Note

xtd running on Linux and macOS systems only: The collation behavior for the C and Posix cultures is always case-sensitive because these cultures do not use the expected Unicode collation order. We recommend that you use a culture other than C or Posix for performing culture-sensitive, case-insensitive sorting operations.

Remarks

The xtd::basic_string_comparer::current_culture_ignore_case property actually returns an instance of an anonymous class derived from the xtd::basic_string_comparer class.

Each call to the xtd::basic_string_comparer::current_culture_ignore_case property get accessor returns a new xtd::basic_string_comparer object, as the following code shows.

void compare_current_culture_basic_string_comparer() {
  basic_string_comparer basic_string_comparer1 = basic_string_comparer::current_culture_ignore_case;
  basic_string_comparer basic_string_comparer2 = basic_string_comparer::current_culture_ignore_case;
  // Displays false
  console::write_line(basic_string_comparer::reference_equals(basic_string_comparer1, basic_string_comparer2));
}

To improve performance, you can store the xtd::basic_string_comparer object in a local variable rather than retrieve the value of the xtd::basic_string_comparer::current_culture_ignore_case property multiple times.

Todo:

Uncomment following lines when xtd::globalization::culture_info and xtd::globalization::compare_options are developped.

invariant_culture()

template<class char_t >

static basic_string_comparer xtd::basic_string_comparer< char_t >::invariant_culture ( )

inlinestatic

Todo:

Uncomment following lines when xtd::globalization::culture_info and xtd::globalization::compare_options are developped.

invariant_culture_ignore_case()

template<class char_t >

static basic_string_comparer xtd::basic_string_comparer< char_t >::invariant_culture_ignore_case ( )

inlinestatic

Todo:

Uncomment following lines when xtd::globalization::culture_info and xtd::globalization::compare_options are developped.

ordinal()

template<class char_t >

static const basic_string_comparer & xtd::basic_string_comparer< char_t >::ordinal ( )

inlinestatic

Gets a xtd::basic_string_comparer object that performs a case-sensitive ordinal string comparison.

Returns

A xtd::basic_string_comparer object.

Remarks

The xtd::basic_string_comparer returned by the xtd::basic_string_comparer::ordinal property performs a simple byte comparison that is independent of language. This is most appropriate when comparing strings that are generated programmatically or when comparing case-sensitive resources such as passwords.

The xtd::basic_string_comparer::ordinal property actually returns an instance of an anonymous class derived from the xtd::basic_string_comparer class.

ordinal_ignore_case()

template<class char_t >

static const basic_string_comparer & xtd::basic_string_comparer< char_t >::ordinal_ignore_case ( )

inlinestatic

Gets a xtd::basic_string_comparer object that performs a case-insensitive ordinal string comparison.

Returns

A xtd::basic_string_comparer object.

Remarks

The xtd::basic_string_comparer returned by the xtd::basic_string_comparer::ordinal_ignore_case property treats the characters in the strings to compare as if they were converted to uppercase using the conventions of the invariant culture, and then performs a simple byte comparison that is independent of language. This is most appropriate when comparing strings that are generated programmatically or when comparing case-insensitive resources such as paths and filenames.

The xtd::basic_string_comparer::ordinal_ignore_case property actually returns an instance of an anonymous class derived from the xtd::basic_string_comparer class.

compare() [1/2]

template<class char_t >

template<class object_t >

int32 xtd::basic_string_comparer< char_t >::compare ( const object_t &  x, const object_t &  y  ) const

inline

When overridden in a derived class, compares two objects and returns an indication of their relative sort order.

Parameters

x	An object to compare to y.
y	An object to compare to x.

Returns

A signed integer that indicates the relative values of x and y, as shown in the following table.

Value	Meaning
Less than zero	x precedes y in the sort order.
Zero	x is equal to y.
Greater than zero	x follows y in the sort order.

Exceptions

xtd::argument_exception

Neither `x` nor `y` is a xtd::string object, and neither `x` nor `y` implements the `xtd::icomparable` interface.

Remarks

The xtd::basic_string_comparer::compare(const string&, const string&) method is slightly more efficient than the xtd::basic_string_comparer::compare(const object_t&, consy object_t&) method because no conversion of the x and y arguments is needed to perform the comparison.

compare() [2/2]

template<class char_t >

int32 xtd::basic_string_comparer< char_t >::compare ( const xtd::basic_string< char_t > &  x, const xtd::basic_string< char_t > &  y  ) const

inlineoverridevirtualnoexcept

When overridden in a derived class, compares two strings and returns an indication of their relative sort order.

Parameters

x	An object to compare to y.
y	An object to compare to x.

Returns

A signed integer that indicates the relative values of x and y, as shown in the following table.

Value	Meaning
Less than zero	x precedes y in the sort order.
Zero	x is equal to y.
Greater than zero	x follows y in the sort order.

Remarks

The xtd::basic_string_comparer::compare(const string&, const string&) method is slightly more efficient than the xtd::basic_string_comparer::compare(const object_t&, consy object_t&) method because no conversion of the x and y arguments is needed to perform the comparison.

Todo:

Uncomment following lines when xtd::globalization::culture_info and xtd::globalization::compare_options are developped.

Implements xtd::collections::generic::icomparer< xtd::basic_string< char_t > >.

equals() [1/3]

template<class char_t >

bool xtd::basic_string_comparer< char_t >::equals ( const object &  obj ) const

inlineoverridevirtualnoexcept

Determines whether the specified object is equal to the current object.

Parameters

obj	The object to compare with the current object.

Returns

true if the specified object is equal to the current object. otherwise, false.

Examples

The following code example compares the current instance with another object.

#include <xtd/console>
 
using namespace xtd;
 
auto main() -> int {
  auto object1 = new_ptr<object>();
  auto object2 = new_ptr<object>();
  
  auto object3 = object2;
  console::write_line(object1->equals(*object3));
  console::write_line(*object1 == *object3);
  object3 = object1;
  console::write_line(object1->equals(*object3));
  console::write_line(*object1 == *object3);
}
 
// This code produces the following output :
//
// false
// false
// true
// true

Reimplemented from xtd::object.

equals() [2/3]

template<class char_t >

template<class object_t >

bool xtd::basic_string_comparer< char_t >::equals ( const object_t &  x, const object_t &  y  ) const

inline

When overridden in a derived class, indicates whether two objects are equal.

Parameters

x	An object to compare to y.
y	An object to compare to x.

Returns

true if x and y refer to the same object, or x and y are both the same type of object and those objects are equal; otherwise, false.

Remarks

The xtd::basic_string_comparer::equals(const string&, const string&) method is slightly more efficient than the xtd::basic_string_comparer::equals(const object_t&, consy object_t&) method because no conversion of the x and y arguments is needed to perform the comparison.

equals() [3/3]

template<class char_t >

bool xtd::basic_string_comparer< char_t >::equals ( const xtd::basic_string< char_t > &  x, const xtd::basic_string< char_t > &  y  ) const

inlineoverridevirtualnoexcept

When overridden in a derived class, indicates whether two strings are equal.

Parameters

x	An object to compare to y.
y	An object to compare to x.

Returns

true if x and y refer to the same object, or x and y are both the same type of object and those objects are equal; otherwise, false.

Remarks

The xtd::basic_string_comparer::equals(const string&, const string&) method is slightly more efficient than the xtd::basic_string_comparer::equals(const object_t&, consy object_t&) method because no conversion of the x and y arguments is needed to perform the comparison.

Todo:

Uncomment following lines when xtd::globalization::culture_info and xtd::globalization::compare_options are developped.

Implements xtd::collections::generic::iequality_comparer< xtd::basic_string< char_t > >.

get_hash_code() [1/2]

template<class char_t >

template<class object_t >

xtd::size xtd::basic_string_comparer< char_t >::get_hash_code ( const object_t &  obj ) const

inline

When overridden in a derived class, gets the hash code for the specified object.

Parameters

obj	An object.

Returns

A xtd::size hash code calculated from the value of the obj parameter.

Remarks

The xtd::basic_string_comparer::get_hash_code(const string&) method is more efficient than the xtd::basic_string_comparer::get_hash_code(const object&) method because the obj parameter does not have to be converted to perform the operation.

get_hash_code() [2/2]

template<class char_t >

xtd::size xtd::basic_string_comparer< char_t >::get_hash_code ( const xtd::basic_string< char_t > &  obj ) const

inlineoverridevirtualnoexcept

When overridden in a derived class, gets the hash code for the specified string.

Parameters

obj

A string.

Returns

A xtd::size hash code calculated from the value of the obj parameter.

Remarks

The xtd::basic_string_comparer::get_hash_code(const string&) method is more efficient than the xtd::basic_string_comparer::get_hash_code(const object&) method because the obj parameter does not have to be converted to perform the operation.

Todo:

Uncomment following lines when xtd::globalization::culture_info and xtd::globalization::compare_options are developped.

Implements xtd::collections::generic::iequality_comparer< xtd::basic_string< char_t > >.

from_comparison()

template<class char_t >

static basic_string_comparer xtd::basic_string_comparer< char_t >::from_comparison ( xtd::string_comparison  comparison )

inlinestatic

Converts the specified xtd::string_comparison instance to a StringComparer instance.

Parameters

comparison

A string comparer instance to convert.

Returns

A xtd::basic_string_comparer instance representing the equivalent value of the specified xtd::string_comparison instance.

Exceptions

xtd::argument_exception

The specified string comparison is not supported.

is_well_known_ordinal_comparer()

template<class char_t >

static bool xtd::basic_string_comparer< char_t >::is_well_known_ordinal_comparer ( const xtd::collections::generic::iequality_comparer< xtd::basic_string< char_t > > &  comparer, bool &  ignore_case  )

inlinestatic

Determines whether the specified xtd::collections::generic::iequality_comparer <type_t> is a well-known ordinal string comparer.

Todo:

Uncomment following lines when xtd::globalization::culture_info and xtd::globalization::compare_options are developped.

Parameters

comparer	The comparer to query.
ignore_case	When this method returns, contains a value stating whether comparer is case-insensitive. Set to false if this method returns false.

Returns

true if comparer is a well-known ordinal string comparer; otherwise, false.

Remarks

A "well-known ordinal comparer" describes a comparer that behaves identically to xtd::basic_string_comparer::ordinal when passed to xtd::collections::generic::dictionary <key_t, value_t> or xtd::collections::generic::hash_set <type_t>. For example, xtd::collections::generic::equality_comparer::default_equality_comparer is a well-known ordinal comparer because a xtd::collections::generic::dictionary <key_t, value_t> given xtd::collections::generic::equality_comparer::default_equality_comparer as a constructor argument will behave identically to a xtd::collections::generic::dictionary <key_t, value_t> given xtd::string_comparer::ordinal as a constructor argument. If ignore_case is true on method exit, then comparer behaves identically to xtd::basic_string_comparer::ordinal_ignore_case when passed to the constructor of such a collection.

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/basic_string_comparer.hpp