[ADD] C++ STL Algorithms & Binary Search Suites Integration (v1.1.4)

[AnshMNSoni]

This PR implements and integrates the C++ STL Algorithms Suite and the Binary Search Suite into PythonSTL. It exposes high-performance Rust-compiled backends using PyO3/Maturin and registers them as part of the public facade API, while introducing robust, optimized pure-Python fallback implementations.

Key Features Added

1. STL Algorithms Suite ( replicas)

• next_permutation / prev_permutation: Lexicographical permutation generator operating in-place on Python lists.
• nth_element: Quickselect implementation to find elements at a sorted index in $O(N)$ expected time.
• partition: In-place array partitioning based on custom Python predicates.

2. Binary Search Suite

• lower_bound: First element index not comparing less than target ($\ge$).
• upper_bound: First element index comparing greater than target ($>$).
• binary_search: $O(\log N)$ presence check in a sorted range.
• equal_range: Returns (lower_bound, upper_bound) index bounds.

Performance Benchmarks & Systems Insights

1. Algorithms Benchmark Results

• next_permutation: Achieved a 1.7x speedup over pure Python.
• nth_element: Bypassed a severe Lomuto partition worst-case vulnerability ($O(N^2)$ taking 70.85s on reversed arrays) by introducing middle-pivot selection, reducing the runtime to 0.0028s (a 25,000x+ speedup).
• partition: Shows 1.3x speedup; performance is dominated by FFI callback transitions to evaluate the Python predicate function.

2. Binary Search Benchmark Results (5,000 queries on 1,000,000 elements)

• Standard (< comparison): 7.5x speedup (0.0028s vs 0.0214s).
• Custom Comparator (lambda): 3.4x speedup (0.0074s vs 0.0251s).

3. Key Systems Design Decisions:

• GIL-Bound Indexing Optimization: Rust implementations for binary search access elements directly using arr.get_item(mid) rather than copy-extracting the entire list. This preserves the $O(\log N)$ time and $O(1)$ space constraints.
• FFI Callback vs. Compiled Loop Overhead: Custom lambdas require crossing the Python-Rust FFI boundary to evaluate comparison predicates. While this slows Rust down (from 0.0028s to 0.0074s), Rust's loop compiling easily overcomes Python's bytecode interpreter overhead, resulting in a 3.4x net speedup.

Verifications & Quality Gates

• Unit Tests: Created comprehensive pytest suites in tests/test_algorithms.py and tests/test_binary_search.py covering duplicate elements, out-of-bounds inputs, empty lists, and custom comparators. All 81 package tests are passing.
• Packaging: Configured and validated package distributions on PyPI (Twine validation: PASSED). Version 1.1.4 is live on PyPI.

[deepsource-io]

DeepSource Code Review

We reviewed changes in 2bd671c...263431f on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade

Security   Reliability   Complexity   Hygiene

Code Review Summary

Analyzer	Status	Updated (UTC)	Details
Rust		Jun 12, 2026 9:06a.m.	Review ↗
Python		Jun 12, 2026 9:06a.m.	Review ↗

---

Important

AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.

[deepsource-io]

Unused stl_set imported from pythonstl

An object has been imported but is not used anywhere in the file.
It should either be used or the import should be removed.

[deepsource-io]

Body doesn't contain any code

In most cases, an empty body of for, while or if implies some piece of code is missing.
Such empty block must be either filled or removed.

[deepsource-io]

Body doesn't contain any code

In most cases, an empty body of for, while or if implies some piece of code is missing.
Such empty block must be either filled or removed.

[deepsource-io]

Starting a process with a partial executable path

Python possesses many mechanisms to invoke an external executable. If the desired executable path is not fully qualified relative to the filesystem root then this may present a potential security risk.

[deepsource-io]

Starting a process with a partial executable path

Python possesses many mechanisms to invoke an external executable. If the desired executable path is not fully qualified relative to the filesystem root then this may present a potential security risk.

[deepsource-io]

Access to a protected member _data of a client class

Accessing a protected member (a member prefixed with _) of a class from outside that class is not recommended, since the creator of that class did not intend this member to be exposed. If accesing this attribute outside of the class is absolutely needed, refactor it such that it becomes part of the public interface of the class.

[deepsource-io]

Access to a protected member _data of a client class

Accessing a protected member (a member prefixed with _) of a class from outside that class is not recommended, since the creator of that class did not intend this member to be exposed. If accesing this attribute outside of the class is absolutely needed, refactor it such that it becomes part of the public interface of the class.

[deepsource-io]

Access to a protected member _capacity of a client class

Accessing a protected member (a member prefixed with _) of a class from outside that class is not recommended, since the creator of that class did not intend this member to be exposed. If accesing this attribute outside of the class is absolutely needed, refactor it such that it becomes part of the public interface of the class.

[deepsource-io]

Access to a protected member _capacity of a client class

Accessing a protected member (a member prefixed with _) of a class from outside that class is not recommended, since the creator of that class did not intend this member to be exposed. If accesing this attribute outside of the class is absolutely needed, refactor it such that it becomes part of the public interface of the class.

[deepsource-io]

Unused import pytest

An object has been imported but is not used anywhere in the file.
It should either be used or the import should be removed.