std::filesy...th::compare(3)

okay so bestie, this is the tea on std::filesystem::path::compare(3) from the C++ Standard Libary — the page header is out here looking like std::filesy...th::compare(3) because columns are literally fighting for their life, but we move 💅

💖 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)

It compares the lexical representations of the path and another path, no cap.

1. If root_name().native().compare(p.root_name().native()) is nonzero, it returns that value.

Otherwise, if has_root_directory() != p.has_root_directory(), it returns a value less than zero if has_root_directory() is false and a value greater than zero otherwise.

Otherwise, it 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.

bestie, those are implementation-defined, so don’t act surprised if your standard library has opinions 😭

---

🦋 Notes 🦋

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

---

🧪 Example 🧪

Run this code, bestie:

#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 retroactively to previously published C++ standards.

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

---

👀 See also 👀

All of these are the lexicographically compares two paths (function) besties:

• operator== — (C++17)
• operator!= — (C++17)(until C++20)
• operator< — (C++17)(until C++20)
• operator<= — (C++17)(until C++20)
• operator> — (C++17)(until C++20)
• operator>= — (C++17)(until C++20)
• operator<=> — (C++20)

---

mwah 💋 sourced from http://cppreference.com, version/date 2024.06.10, and the footer is out here serving std::filesy...th::compare(3). Bye bestie! 🎀