home | help 
std::filesy...th::compare(3)   C++ Standard Libary  std::filesy...th::compare(3)

NAME
     std::filesystem::path::compare - std::filesystem::path::compare

Synopsis
	int  compare( const path& p ) const noexcept;		      (1) (since
     C++17)
	int compare( const string_type& str ) const;		     (2)  (since
     C++17)
	int compare( std::basic_string_view<value_type> str ) const;
	int  compare( const value_type* s ) const;		      (3) (since
     C++17)

	Compares the lexical representations of the path and another path.

	1) If root_name().native().compare(p.root_name().native())  is	nonzero,
     returns that
	value.
	Otherwise,  if has_root_directory() != p.has_root_directory(), returns a
     value less
	than zero if has_root_directory() is false and a value greater than zero
     otherwise.
	Otherwise returns a value less than, equal to or greater than 0  if  the
     relative
	portion  of the path (relative_path()) is respectively lexicographically
     less than,
	equal to or greater than the relative portion of p  (p.relative_path()).
     Comparison
	is performed element-wise, as if by iterating both paths from begin() to
     end() and
	comparing the result of native() for each element.
	2) Equivalent to compare(path(str)).
	3) Equivalent to compare(path(s)).

Parameters
	p   - a path to compare to
	str - a string or string view representing path to compare to
	s   - a null-terminated string representing path to compare to

Return value
	A value less than 0 if the path is lexicographically less than the given
     path.

	A  value  equal to 0 if the path is lexicographically equal to the given
     path.

	A value greater than 0 if the path is lexicographically greater than the
     given path.

Exceptions
	2,3) May throw implementation-defined exceptions.

Notes
	For two-way comparisons, binary operators may be more suitable.

Example
     // Run this code

      #include <filesystem>
      #include <iostream>
      #include <string_view>
      namespace fs = std::filesystem;

      void demo(fs::path p1, fs::path p2, std::string_view msg)
      {
	  std::cout << p1;
	  const int rc = p1.compare(p2);
	  if (rc < 0)
	      std::cout << " < ";
	  else if (rc > 0)
	      std::cout << " > ";
	  else
	      std::cout << " == ";
	  std::cout << p2 << " \t: " << msg << '\n';
      }

      int main()
      {
	  demo("/a/b/", "/a/b/", "simple");
	  demo("/a/b/", "/a/b/c", "simple");
	  demo("/a/b/../b", "/a/b", "no canonical conversion");
	  demo("/a/b", "/a/b/.", "no canonical conversion");
	  demo("/a/b/", "a/c", "absolute paths order after relative ones");
      }

Output:
      "/a/b/" == "/a/b/"      : simple
      "/a/b/" < "/a/b/c"   : simple
      "/a/b/../b" > "/a/b" : no canonical conversion
      "/a/b" < "/a/b/."    : no canonical conversion
      "/a/b/" > "a/c"		   : absolute paths order after relative ones

	Defect reports

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

	   DR	  Applied to   Behavior as published		  Correct behav-
     ior
	LWG 2936 C++17	    compared all path elements root name and root direc-
     tory handled
			    directly		       separately

See also
	operator==
	operator!=
	operator<
	operator<=
	operator>
	operator>=
	operator<=>	     lexicographically compares two paths
	(C++17) 	     (function)
	(C++17)(until C++20)
	(C++17)(until C++20)
	(C++17)(until C++20)
	(C++17)(until C++20)
	(C++17)(until C++20)
	(C++20)

http://cppreference.com 	   2024.06.10	    std::filesy...th::compare(3)
home | help