Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::lexico...e_three_way(3)  C++ Standard Libary std::lexico...e_three_way(3)

NAME
       std::lexicographical_compare_three_way	 -   std::lexicographical_com-
       pare_three_way

Synopsis
	  Defined in header <algorithm>
	  template< class InputIt1, class InputIt2, class Cmp >

	  constexpr auto lexicographical_compare_three_way( InputIt1 first1,
	  InputIt1							last1,
       (1) (since C++20)
	  InputIt2 first2, InputIt2 last2,
	  Cmp comp );

	  -> decltype(comp(*first1, *first2));
	  template< class InputIt1, class InputIt2 >

	  constexpr  auto  lexicographical_compare_three_way( InputIt1 first1,
       (2) (since C++20)
	  InputIt1 last1,

	  InputIt2 first2, InputIt2 last2 );

	  Lexicographically compares two ranges	[first1, last1)	 and  [first2,
       last2) using
	  three-way comparison and produces a result of	the strongest applica-
       ble comparison
	  category type.

	  1)  Returns  the order between the first non-equivalent pair of ele-
       ments according to
	  comp in both ranges if any, otherwise	(if one	ranges	is  equivalent
       to the prefix of
	  another  according to	comp), returns the order between the length of
       both ranges.
	  2) Equivalent	to:

	return std::lexicographical_compare_three_way(
	    first1, last1, first2, last2, std::compare_three_way());

Parameters
	  first1, last1	- the first range of elements to examine
	  first2, last2	- the second range of elements to examine
			  a function object type. The program is ill-formed if
       its return type
	  comp		- is not one of	the three comparison category types
			  (std::strong_ordering, std::weak_ordering, or
			  std::partial_ordering).

Type requirements
	  -
	  InputIt1, InputIt2 must meet the requirements	 of  LegacyInputItera-
       tor.

Return value
	  The value of a comparison category type specified above.

Complexity
	  At  most N applications of comp, where N is the smaller of length of
       both ranges.

Possible implementation
	 template< class I1, class I2, class Cmp >
	 constexpr auto	lexicographical_compare_three_way( I1 f1,  I1  l1,  I2
       f2, I2 l2, Cmp comp )
	     ->	decltype(comp(*f1, *f2))
	 {
	     using ret_t = decltype(comp(*f1, *f2));
	     static_assert(std::disjunction_v<
			       std::is_same<ret_t, std::strong_ordering>,
			       std::is_same<ret_t, std::weak_ordering>,
			       std::is_same<ret_t, std::partial_ordering>>,
			   "The	 return	 type  must  be	 a comparison category
       type.");

	     bool exhaust1 = (f1 == l1);
	     bool exhaust2 = (f2 == l2);
	     for (; !exhaust1 && !exhaust2; exhaust1 = (++f1 ==	l1),  exhaust2
       = (++f2 == l2))
		 if (auto c = comp(*f1,	*f2); c	!= 0)
		     return c;

	     return !exhaust1 ?	std::strong_ordering::greater :
		    !exhaust2 ?	std::strong_ordering::less :
				std::strong_ordering::equal;
	 }

Example
       // Run this code

	#include <algorithm>
	#include <cctype>
	#include <compare>
	#include <iomanip>
	#include <iostream>
	#include <string_view>
	#include <utility>
	using namespace	std::literals;

	void	show_result(std::string_view	s1,    std::string_view	   s2,
       std::strong_ordering o)
	{
	    std::cout << quoted(s1) << " is ";
	    (o < 0) ? std::cout	<< "less than "	:
	    (o > 0) ? std::cout	<< "greater than " :
		      std::cout	<< "equal to ";
	    std::cout << quoted(s2) << '\n';
	}

	int main()
	{
	    auto cmp_icase = [](char x,	char y)	{
		const auto ux {	std::toupper(x)	};
		const auto uy {	std::toupper(y)	};
		return (ux < uy) ? std::strong_ordering::less:
		       (ux > uy) ? std::strong_ordering::greater:
				   std::strong_ordering::equal;
	    };

	    for	(const auto& [s1, s2] :	{ std::pair{"one"sv, "ONE"sv},
						   {"two"sv, "four"sv},
						   {"three"sv, "two"sv}	}) {
		const auto res = std::lexicographical_compare_three_way(
		    s1.cbegin(),    s1.cend(),	   s2.cbegin(),	    s2.cend(),
       cmp_icase);
		show_result(s1,	s2, res);
	    }
	}

Output:
	"one" is equal to "ONE"
	"two" is greater than "four"
	"three"	is less	than "two"

	 Defect	reports

	  The following	behavior-changing defect reports were applied retroac-
       tively to
	  previously published C++ standards.

	     DR	   Applied to	       Behavior	as published		  Cor-
       rect behavior
	  LWG 3410 C++20      extraneous comparisons between	      such re-
       quirement removed
			      iterators	were required

See also
					  returns true if one range is lexico-
       graphically less
	  lexicographical_compare	  than another
					  (function template)
	  compare_three_way		  function object implementing x <=> y
	  (C++20)			  (class)
	  ranges::lexicographical_compare returns true if one range is lexico-
       graphically less
	  (C++20)			  than another
					  (niebloid)

http://cppreference.com		  2022.07.31	  std::lexico...e_three_way(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::lexicographical_compare_three_way&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help