feat(collection): Replace quickSort with pdqsort for performance and robustness

[abbashosseinii]

This PR enhances the performance and robustness of the default unstable sort in package:collection by replacing the existing quickSort implementation with a modern, state-of-the-art Pattern-Defeating Quicksort (pdqsort) algorithm. The implementation is a Dart port of the concepts from the canonical C++ version by Orson Peters.

Motivation

The pdqsort algorithm is the default unstable sort in other high-performance ecosystems (like Rust) for good reason. It offers two key advantages over the existing implementation:

1. Superior Performance on Common Patterns: Through more intelligent pivot selection (median-of-three/ninther), it consistently outperforms the random-pivot strategy on a wide variety of real-world data patterns.
2. Guaranteed Worst-Case Performance: It includes a heapsort fallback mechanism that activates on pathological inputs, providing a hard guarantee of O(n log n) performance and preventing worst-case O(n²) behavior.

This change is a pure, non-breaking enhancement that makes the standard library sort faster and safer with no API changes or regressions.

Benchmark Results

To validate this enhancement, a comprehensive benchmark was created, comparing the new pdqsort implementation against a direct copy of the existing SDK quickSort across five critical data patterns.

The results demonstrate a consistent and significant performance improvement across all tested scenarios, with no regressions.

Benchmark Results:
pdqsort (Enhancement) vs. SDK quickSort (Baseline)

Data Condition	Baseline (µs)	Enhancement (µs)	Improvement	Winner
Mean
Random	7584	6654	+12.27%	Enhancement 🚀
Sorted	7515	7207	+4.10%	Enhancement 🚀
Reverse Sorted	7598	7341	+3.38%	Enhancement 🚀
Few Unique	1741	1560	+10.40%	Enhancement 🚀
Pathological	8564	8034	+6.19%	Enhancement 🚀
Median
Random	7612	6672	+12.35%	Enhancement 🚀
Sorted	7596	7220	+4.95%	Enhancement 🚀
Reverse Sorted	7598	7363	+3.09%	Enhancement 🚀
Few Unique	1712	1567	+8.47%	Enhancement 🚀
Pathological	8537	8063	+5.55%	Enhancement 🚀

(Results are the average/median time in microseconds to sort 50,000 integers, aggregated over 12 runs.)

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

Note: The Dart team is trialing Gemini Code Assist. Don't take its comments as final Dart team feedback. Use the suggestions if they're helpful; otherwise, wait for a human reviewer.

[github-actions]

PR Health

Breaking changes ⚠️

Package	Change	Current Version	New Version	Needed Version	Looking good?
collection	Breaking	1.19.1	1.20.0-wip	2.0.0 Got "1.20.0-wip" expected >= "2.0.0" (breaking changes)	⚠️

This check can be disabled by tagging the PR with skip-breaking-check.

Changelog Entry ❗

Package	Changed Files
package:collection	pkgs/collection/lib/src/algorithms.dart

Changes to files need to be accounted for in their respective changelogs.

This check can be disabled by tagging the PR with skip-changelog-check.

Coverage ⚠️

File	Coverage
pkgs/collection/benchmark/sort_comparison_benchmark.dart	💔 Not covered
pkgs/collection/lib/src/algorithms.dart	💔 91 % ⬇️ 9 %

This check for test coverage is informational (issues shown here will not fail the PR).

This check can be disabled by tagging the PR with skip-coverage-check.

API leaks ✔️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbol	Leaking sources

This check can be disabled by tagging the PR with skip-leaking-check.

License Headers ✔️

// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

Files
no missing headers

All source files should start with a license header.

This check can be disabled by tagging the PR with skip-license-check.

[lrhn]

Looks pretty convincing. I'll have to look at it a little more to see if it's so universally better that we want to replace the simple quicksort, or if we may want to have both.

I don't know how many people actually use the sort functions in package:collection instead of just using List.sort.
(So should we change List.sort?)

The only nit I noticed in a quick read-through is that I'd avoid calling keyOf more than once per element when it can be avoided. The keyOf operation may not be trivial.

@natebosch WDYT?

[lrhn]

(Don't use classes with only static members. Put the members into a separate library that can be imported with a prefix if desired.)

[abbashosseinii]

You're absolutely right — using classes with only static members isn't ideal. I just wrote this file as a temporary setup so we could benchmark the new sort implementation against the old one. It’s not meant to be merged into the main codebase.

[abbashosseinii]

This has been resolved in this commit.

[lrhn]

(Drop the "Represents" word. All classes represent something. Just say what that is.)

[abbashosseinii]

This has been resolved in the recent commit.

[lrhn]

(Here we could optimize:

  var largest = root;
  var rootKey = keyOf(elements[start + root]);
  while (true) {
    var child = 2 * root + 1; // Left child.
    if (child < n) {
      var largestKey = rootKey;
      var childKey = keyOf(elements[start + child]);
      if (compare(largestKey, childKey) < 0) {
        largest = child;
        largestKey = childKey;
      }
      child++; // Right child.
      if (child < n) {
        var childKey = keyOf(elements[start + child]);
        if (compare(largestKey, childKey) < 0) {
          largest = child;
          largestKey = childKey;
        }
      }    
      if (largest != root) {
        _pdqSwap(elements, start + root, start + largest);
        root = largest; 
        continue;
      }
    }    
    break;
  }

This should avoid calling keyOf on the same element more than once, including the root. (I'll assume this only gets called if the root is not a leaf.)

[abbashosseinii]

Thanks for the detailed review!
The latest commit reflects these updates. Please let me know if there's anything else that needs attention!

[abbashosseinii]

Hi @lrn, thank you for the thoughtful review and feedback! This is a great discussion. Let me address your points directly.

...see if it's so universally better that we want to replace the simple quicksort, or if we may want to have both.

That's the key question. I believe replacing it is the right move because pdqsort is designed to be a "drop-in" replacement that is strictly better than the existing quickSort.

• No Regressions: As the benchmarks show, it offers a performance improvement over the baseline quickSort on every tested data pattern. It doesn't trade performance in one area for another.
• Safety Net: The heapsort fallback provides a hard O(n log n) guarantee, which the current implementation lacks. This makes the library sort more robust.

For these reasons, I don't see a scenario where a user would knowingly choose the older, less robust implementation, which argues against keeping both.

I don't know how many people actually use the sort functions in package:collection instead of just using List.sort. (So should we change List.sort?)

This was an excellent question, and it prompted me to add List.sort to the benchmark to get a clear answer. The results are fascinating and, I believe, make a strong case for this PR.

Benchmark Results: pdqsort (Enhancement) vs. SDK quickSort (Baseline) vs. List.sort

Data Condition	Baseline (µs)	Enhancement (µs)	List.sort (µs)	Enh vs Base	List.sort vs Base	Best
Mean
Random	7468	6546	6588	+12.34%	+11.78%	Enhancement 🚀
Sorted	7344	7087	2364	+3.51%	+67.81%	List.sort
Reverse Sorted	7351	7138	2769	+2.90%	+62.33%	List.sort
Few Unique	1750	1567	2314	+10.44%	-32.26%	Enhancement 🚀
Pathological	8531	8026	4971	+5.92%	+41.73%	List.sort
Median
Random	7566	6576	6588	+13.08%	+12.93%	Enhancement 🚀
Sorted	7353	7055	2383	+4.05%	+67.59%	List.sort
Reverse Sorted	7325	7154	2776	+2.33%	+62.10%	List.sort
Few Unique	1738	1567	2316	+9.84%	-33.26%	Enhancement 🚀
Pathological	8562	8018	4992	+6.35%	+41.70%	List.sort

1. Native Code Wins on Structure: As expected, the VM's native C++ List.sort is unbeatable on structured data (sorted, reverse-sorted). It likely has low-level optimizations to detect sorted runs that a pure-Dart implementation can't match.

2. This pdqsort Wins on Chaos: Most importantly, this new pdqsort implementation is the fastest of all three on chaotic data—both random data and data with few unique values.

This shows that the goal of this PR isn't to replace List.sort, but to make the pure-Dart implementation in package:collection the best it can possibly be. By doing so, we've achieved a sort that is so efficient it can even surpass the native VM's implementation for common "messy" data scenarios.

The only nit I noticed in a quick read-through is that I'd avoid calling keyOf more than once per element when it can be avoided. The keyOf operation may not be trivial.

Excellent point, and thank you for catching that! You are absolutely right. I've just pushed a new commit that caches the keys for the pivot and the currently inspected element in the partitioning and insertion sort loops. This will avoid the redundant calls and improve performance when keyOf is an expensive operation.

Thank you again for the review! Let me know if you have any other questions.