std::qsort(3)

🌸 NAME 🌸

okay so bestie, this is the std::qsort(3) page — the C++ Standard Library one, and the NAME section is literally just std::qsort — std::qsort. Minimal. Iconic. No further notes. 💅✨

---

✨ Synopsis ✨

Bestie, it's Defined in header <cstdlib> and the synopsis is giving “two overloads plus exposition-only alias energy.” Copying this exactly because these little details matter, fr fr:

Defined in header <cstdlib>
void qsort( void *ptr, std::size_t count,

            std::size_t size, /* c-compare-pred */* comp );   (1)
void qsort( void *ptr, std::size_t count,

            std::size_t size, /* compare-pred */* comp );
extern "C" using /* c-compare-pred */ = int(const void*,
const void*);                                                 (2)
(exposition only*)
extern "C++" using /* compare-pred */ = int(const void*,
const void*);

So what does it do? It sorts the given array pointed to by ptr into ascending order. The array has count elements, and each one is size bytes. The function pointed to by comp is the one doing the object comparison. 🌈

If comp says two elements are equivalent, then their order is unspecified. Not “stable,” not “alphabetical,” just unspecified — write that down. 😭

And if the type of the array elements is not a PODType (until C++11), or not a TriviallyCopyable type (since C++11), the behavior is undefined. So yeah, that's a real “do not do that” moment. 💀

---

🎀 Parameters 🎀

• ptr — pointer to the array to sort.
• count — number of elements in the array.
• size — size of each element in the array, in bytes.
• comp — comparison function. It returns a negative integer value if the first argument is less than the second, a positive integer value if the first argument is greater than the second, and zero if the arguments are equivalent.

The signature of the comparison function should be equivalent to this, bestie:

int cmp(const void *a, const void *b);

The function must not modify the objects passed to it, and it must return consistent results when called for the same objects, regardless of their positions in the array. Like, be consistent, please. 🫶

---

💖 Return value 💖

(none) — that's it. It does the sort and dips. 💅

---

🦋 Notes 🦋

Despite the name, C++, C, and POSIX standards do not require this function to be implemented using Quicksort, and they make no complexity or stability guarantees. So the name is lowkey just a name, okay? 👑

The two overloads provided by the C++ standard library are distinct because the types of the parameter comp are distinct — language linkage is part of its type. That's the detail. That's the lore. ✨

---

🌸 Example 🌸

The following code sorts an array of integers using qsort(). The page has a little // Run this code label right before it, and then this exact code:

#include <array>
#include <climits>
#include <compare>
#include <cstdlib>
#include <iostream>

int main()
{
    std::array a{-2, 99, 0, -743, INT_MAX, 2, INT_MIN, 4};

    std::qsort
    (
        a.data(),
        a.size(),
        sizeof(decltype(a)::value_type),
        [](const void* x, const void* y)
        {
            const int arg1 = *static_cast<const int*>(x);
            const int arg2 = *static_cast<const int*>(y);
            const auto cmp = arg1 <=> arg2;
            if (cmp < 0)
                return -1;
            if (cmp > 0)
                return 1;
            return 0;
        }
    );

    for (int ai : a)
        std::cout << ai << ' ';
    std::cout << '\n';
}

Output is giving sorted-array perfection:

-2147483648 -743 -2 0 2 4 99 2147483647

---

⭐ Defect reports ⭐

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. Yes, we're doing lore. 🧚

• LWG 405, applied to C++98 — behavior as published: the elements of the array could have any type. Correct behavior: limited to PODType. Slay for fixing that, honestly. 💜

---

👑 See also 👑

• bsearch — searches an array for an element of unspecified type (function).
• sort — sorts a range into ascending order (function template).
• is_trivial — checks if a type is trivial (C++11) (class template).
• C documentation for qsort.

---

kisses and sorted arrays, bestie 💖 — this was cppreference.com, version/date 2024.06.10, page std::qsort(3). Mwah! 🫶🎀