Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/filesystem/path/compare"

From cppreference.com
< cpp‎ | filesystem‎ | path
m (Text replace - "(===\s*Exceptions\s*===[^=]*)\(none\)" to "$1{{cpp/impldef exception item}}")
m (fmt, {{c}}, @-@ -> @,@, headers sorted, +std::cout)
 
(4 intermediate revisions by 3 users not shown)
Line 2: Line 2:
 
{{cpp/filesystem/path/navbar}}
 
{{cpp/filesystem/path/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl | num=1 | since=c++17 | 1=
+
{{dcl|num=1|since=c++17|1=
 
int compare( const path& p ) const noexcept;
 
int compare( const path& p ) const noexcept;
 
}}
 
}}
−
{{dcl | num=2 | since=c++17 | 1=
+
{{dcl|num=2|since=c++17|1=
 
int compare( const string_type& str ) const;
 
int compare( const string_type& str ) const;
 
int compare( std::basic_string_view<value_type> str ) const;
 
int compare( std::basic_string_view<value_type> str ) const;
 
}}
 
}}
−
{{dcl | num=3 | since=c++17 | 1=
+
{{dcl|num=3|since=c++17|1=
 
int compare( const value_type* s ) const;
 
int compare( const value_type* s ) const;
 
}}
 
}}
Line 18: Line 18:
 
@1@ If {{c|root_name().native().compare(p.root_name().native())}} is nonzero, returns that value.  
 
@1@ If {{c|root_name().native().compare(p.root_name().native())}} is nonzero, returns that value.  
 
@@ Otherwise, if {{c|has_root_directory() !{{=}} p.has_root_directory()}}, returns a value less than zero if {{rlpf|has_path|has_root_directory}} is {{c|false}} and a value greater than zero otherwise.
 
@@ Otherwise, if {{c|has_root_directory() !{{=}} p.has_root_directory()}}, returns a value less than zero if {{rlpf|has_path|has_root_directory}} is {{c|false}} and a value greater than zero otherwise.
−
@@ Otherwise returns a value less than, equal to or greater than {{math|0}} if the relative portion of the path ({{rlpf|relative_path}}) is respectively lexicographically less than, equal to or greater than the relative portion of {{tt|p}} ({{c|p.relative_path()}}). Comparison is performed element-wise, as if by iterating both paths from {{rlpf|begin}} to {{rlpf|begin|end}} and comparing the result of {{rlpf|native}} for each element.
+
@@ Otherwise returns a value less than, equal to or greater than {{c|0}} if the relative portion of the path ({{rlpf|relative_path}}) is respectively lexicographically less than, equal to or greater than the relative portion of {{c|p}} ({{c|p.relative_path()}}). Comparison is performed element-wise, as if by iterating both paths from {{rlpf|begin}} to {{rlpf|begin|end}} and comparing the result of {{rlpf|native}} for each element.
 
@2@ Equivalent to {{c|compare(path(str))}}.
 
@2@ Equivalent to {{c|compare(path(str))}}.
 
@3@ Equivalent to {{c|compare(path(s))}}.
 
@3@ Equivalent to {{c|compare(path(s))}}.
Line 24: Line 24:
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | p | a path to compare to}}
+
{{par|p|a path to compare to}}
−
{{par | str | a string or string view representing path to compare to}}
+
{{par|str|a string or string view representing path to compare to}}
−
{{par | s | a null-terminated string representing path to compare to}}
+
{{par|s|a null-terminated string representing path to compare to}}
 
{{par end}}
 
{{par end}}
  
 
===Return value===
 
===Return value===
−
A value less than {{math|0}} if the path is lexicographically less than the given path.
+
A value less than {{c|0}} if the path is lexicographically less than the given path.
  
−
A value equal to {{math|0}} if the path is lexicographically equal to the given path.
+
A value equal to {{c|0}} if the path is lexicographically equal to the given path.
  
−
A value greater than {{math|0}} if the path is lexicographically greater than the given path.
+
A value greater than {{c|0}} if the path is lexicographically greater than the given path.
  
 
===Exceptions===
 
===Exceptions===
−
@2-3@ {{cpp/impldef exception item}}
+
@2,3@ {{cpp/impldef exception item}}
  
 
===Notes===
 
===Notes===
Line 43: Line 43:
  
 
===Example===
 
===Example===
−
{{example|code=
+
{{example
−
#include <iostream>
+
|code=
 
#include <filesystem>
 
#include <filesystem>
 +
#include <iostream>
 +
#include <string_view>
 
namespace fs = std::filesystem;
 
namespace fs = std::filesystem;
−
void demo(int rc, fs::path p1, fs::path p2) {
+
 
−
     if(rc < 0) std::cout << p1 << " < " << p2 << '\n';
+
void demo(fs::path p1, fs::path p2, std::string_view msg)
−
     else if(rc > 0) std::cout << p1 << " > " << p2 << '\n';
+
{
−
     else if(rc == 0) std::cout << p1 << " == " << p2 << '\n';
+
    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() {
+
 
−
     fs::path p1 = "/a/b/"; // as if "/a/b" for lexicographical iteration
+
int main()
−
     fs::path p2 = "/a/b/c";
+
{
−
     demo(p1.compare(p2), p1, p2);
+
     demo("/a/b/", "/a/b/", "simple");
−
     demo(p1.compare("a/c"), p1, "a/c"); // absolute paths order after relative ones
+
     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=
 
|output=
−
"/a/b/" < "/a/b/c"
+
"/a/b/" == "/a/b/"      : simple
−
"/a/b/" > "a/c"
+
"/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
 
}}
 
}}
  
Line 67: Line 83:
 
{{dr list item|wg=lwg|dr=2936|std=C++17|before=compared all path elements directly|after=root name and root directory handled separately}}
 
{{dr list item|wg=lwg|dr=2936|std=C++17|before=compared all path elements directly|after=root name and root directory handled separately}}
 
{{dr list end}}
 
{{dr list end}}
 +
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/filesystem/path/dsc operator_cmp}}
+
{{dsc inc|cpp/filesystem/path/dsc operator_cmp}}
 
{{dsc end}}
 
{{dsc end}}
  
−
{{langlinks|ja|zh}}
+
{{langlinks|de|es|ja|ru|zh}}

Latest revision as of 10:36, 5 September 2023

 
C++
 
Filesystem library
Classes
Functions
File types
 
std::filesystem::path
Constants
Member functions
Path decomposition
Non-member functions
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
Helper Classes
(C++26)
 
int compare( const path& p ) const noexcept;
 (1) (since C++17)
int compare( const string_type& str ) const;
int compare( std::basic_string_view<value_type> str ) const;
 (2) (since C++17)
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)).

Contents

[edit] 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

[edit] 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.

[edit] Exceptions

2,3) May throw implementation-defined exceptions.

[edit] Notes

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

[edit] 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

[edit] Defect reports

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

DR Applied to Behavior as published Correct behavior
LWG 2936 C++17 compared all path elements directly root name and root directory handled separately

[edit] See also

(C++17)(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)
 lexicographically compares two paths
(function) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/filesystem/path/compare&oldid=158016"