xtd::basic_string_comparer< char_t > Class Template Reference

Inheritance diagram for xtd::basic_string_comparer< char_t >:

Definition

template<typename 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<typename 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 auto	current_culture () -> basic_string_comparer
	Gets a xtd::basic_string_comparer object that performs a case-sensitive string comparison using the word comparison rules of the current culture.
static auto	current_culture_ignore_case () -> basic_string_comparer
	Gets a xtd::basic_string_comparer object that performs case-insensitive string comparisons using the word comparison rules of the current culture.
static auto	invariant_culture () -> basic_string_comparer
static auto	invariant_culture_ignore_case () -> basic_string_comparer
static auto	ordinal () -> const basic_string_comparer &
	Gets a xtd::basic_string_comparer object that performs a case-sensitive ordinal string comparison.
static auto	ordinal_ignore_case () -> const basic_string_comparer &
	Gets a xtd::basic_string_comparer object that performs a case-insensitive ordinal string comparison.

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

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

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

Additional Inherited Members
	object ()=default
	Create a new instance of the ultimate base class object.
virtual auto	get_type () const noexcept -> type_object
	Gets the type of the current instance.
template<typename object_t>
auto	memberwise_clone () const -> xtd::unique_ptr_object< object_t >
	Creates a shallow copy of the current object.
virtual auto	to_string () const -> xtd::string
	Returns a xtd::string that represents the current object.
template<typename object_a_t, typename object_b_t>
static auto	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are considered equal.
template<typename object_a_t, typename object_b_t>
static auto	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept -> bool
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

basic_string_comparer()

template<typename 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<typename char_t>

auto xtd::basic_string_comparer< char_t >::current_culture ( ) -> basic_string_comparer

inlinestaticnodiscard

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<typename char_t>

auto xtd::basic_string_comparer< char_t >::current_culture_ignore_case ( ) -> basic_string_comparer

inlinestaticnodiscard

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<typename char_t>

auto xtd::basic_string_comparer< char_t >::invariant_culture ( ) -> basic_string_comparer

inlinestaticnodiscard

Todo

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

invariant_culture_ignore_case()

template<typename char_t>

auto xtd::basic_string_comparer< char_t >::invariant_culture_ignore_case ( ) -> basic_string_comparer

inlinestaticnodiscard

Todo

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

ordinal()

template<typename char_t>

auto xtd::basic_string_comparer< char_t >::ordinal ( ) -> const basic_string_comparer &

inlinestaticnodiscard

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<typename char_t>

auto xtd::basic_string_comparer< char_t >::ordinal_ignore_case ( ) -> const basic_string_comparer &

inlinestaticnodiscard

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<typename char_t>

template<typename object_t>

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

inlinenodiscard

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<typename char_t>

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

inlinenodiscardoverridevirtualnoexcept

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<typename char_t>

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

inlinenodiscardoverridevirtualnoexcept

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/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<typename char_t>

template<typename object_t>

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

inlinenodiscard

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<typename char_t>

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

inlinenodiscardoverridevirtualnoexcept

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/3]

template<typename char_t>

template<typename object_t>

auto xtd::basic_string_comparer< char_t >::get_hash_code ( const object_t & obj ) const -> xtd::usize

inlinenodiscard

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

Parameters

obj	An object.

Returns

A xtd::usize 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/3]

template<typename char_t>

auto xtd::basic_string_comparer< char_t >::get_hash_code ( const xtd::basic_string< char_t > & obj ) const -> xtd::usize

inlinenodiscardoverridevirtualnoexcept

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

Parameters

obj

A string.

Returns

A xtd::usize 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<typename char_t>

auto xtd::basic_string_comparer< char_t >::from_comparison ( xtd::string_comparison comparison ) -> basic_string_comparer

inlinestaticnodiscard

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<typename char_t>

auto 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 ) -> bool

inlinestaticnodiscard

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.

get_hash_code() [3/3]

template<typename char_t>

virtual auto xtd::object::get_hash_code ( ) const -> xtd::usize

nodiscardvirtualnoexcept

Serves as a hash function for a particular type.

Returns

A hash code for the current object.

Reimplemented from xtd::object.

---

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

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