Enhance Library Sort: key/reverse, gap rebalancing, docs

[leo-soumyajit]

Title
Enhance: Add Library Sort (gapped insertion) with docs and examples

Summary
Adds an educational, well-documented implementation of Library Sort (gapped insertion) to the sorts directory, including key/reverse parameters, gap rebalancing, and a minimal example script for quick verification. This provides learners with a practical, annotated reference for a distribution-aware insertion strategy.

What’s included
New: sorts/library_sort.py implementing Library Sort with:
key and reverse parameters aligned with Python’s sorting API.
epsilon parameter to control gap density and rebalance behavior.
detailed docstrings and inline comments explaining the data structures (gapped arrays, logical positions) and the rebalance heuristic.
Example: main block demonstrating usage with a small dataset.
Complexity notes in the header docstring: average O(n log n) with high probability, worst O(n^2), space O(n(1+epsilon)).

Motivation
Teaches a lesser-known, research-backed variant of insertion sort that achieves expected O(n log n) by maintaining evenly distributed gaps and rebalancing when clusters form. Ideal for learners comparing practical sort designs beyond classic algorithms.

Implementation notes
Uses a sparse backing array for keys/values plus a “pos” list for logical order; insertions do a binary search on logical order and choose a midpoint slot, rebalancing when local density prevents gap placement.
API mirrors built-in sorted where practical, enabling side-by-side comparison in exercises and tests.

How to test
Run the built-in example:
python sorts/library_sort.py should print a sorted “After:” list.
Sanity checks (suggested):
Compare against sorted on random arrays and edge cases (empty, single element, duplicates).

Verify key and reverse, e.g., key=lambda x: x % 10 and reverse=True.

Scope and trade-offs

Focuses on pedagogy and clarity; not a drop-in replacement for Timsort in production scenarios. For arbitrary real-world data, Python’s built-in sort remains recommended due to stability and adaptiveness.

Library Sort worst case remains O(n^2); documentation calls this out to set correct expectations.

Related

Closes #13203 (advanced sorting algorithms request).

References: Bender et al., “Insertion Sort is O(n log n)” (Library Sort analysis); Wikipedia overview for algorithm characteristics.

[algorithms-keeper]

Closing this pull request as invalid

@leo-soumyajit, this pull request is being closed as none of the checkboxes have been marked. It is important that you go through the checklist and mark the ones relevant to this pull request. Please read the Contributing guidelines.

If you're facing any problem on how to mark a checkbox, please read the following instructions:

• Read a point one at a time and think if it is relevant to the pull request or not.
• If it is, then mark it by putting a x between the square bracket like so: [x]

NOTE: Only [x] is supported so if you have put any other letter or symbol between the brackets, that will be marked as invalid. If that is the case then please open a new pull request with the appropriate changes.