_bigint helpers

[youknowone]

Summary by CodeRabbit

• New Features

  • Extended math module with arbitrary-precision versions of standard mathematical operations through an optional feature gate.

• Documentation

  • Added compatibility guidance note documenting the library's alignment with Python's math module interface.

• Refactor

  • Improved internal module organization and dependencies.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@youknowone has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 12 minutes and 0 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between aa6112d and ab02686.

📒 Files selected for processing (4)

• README.md
• src/math.rs
• src/math/bigint.rs
• src/math/integer.rs

📝 Walkthrough

Walkthrough

This pull request adds BigInt-based mathematical utilities to RustPython's math module, including functions for permutation, combination, and logarithm calculations. New functions are gated behind a "_bigint" feature flag. Documentation is updated with a compatibility note. Integration changes to existing modules are also introduced.

Changes

Cohort / File(s)	Summary
Documentation README.md	Added "Important Note" section clarifying library compatibility with Python's math module but not mathematical correctness
Module and API Exposure src/math.rs	Conditionally compiles and re-exports new bigint module and functions (comb_bigint, ldexp_bigint, log_bigint, log2_bigint, log10_bigint, perm_bigint) when "_bigint" feature is enabled
BigInt Implementation src/math/bigint.rs	New module providing 6 BigInt-based mathematical functions with divide-and-conquer algorithms for permutation/combination, logarithm calculations with frexp-like fallback for large values, and ldexp with overflow/underflow handling; includes comprehensive tests with property-based testing against Python math results
Module Integration src/math/integer.rs	Visibility change: perm_comb_small elevated from private to pub(super); removed unused internal perm_comb helper function; updated imports to reference super::bigint

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 A BigInt feast we celebrate today,
With logarithms dancing in every way,
Permutations and combinations bloom,
While Python's math finds new room,
Our burrow of numbers grows!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title '_bigint helpers' directly references the main feature being introduced: a new internal _bigint module with helper functions (comb_bigint, ldexp_bigint, log_bigint, log2_bigint, log10_bigint, perm_bigint).
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @src/math/bigint.rs:
- Around line 104-133: In log_bigint replace the direct f64 .ln() calls with the
CPython-wrapper functions: call crate::m::log(x) instead of x.ln() when
computing log_n (after frexp_bigint returns x) and use crate::m::log(b) (or
crate::m::log(b) for the base) instead of b.ln() in the base-division branch;
update references inside the log_bigint function so log_n is computed via
crate::m::log(x) + std::f64::consts::LN_2 * (e as f64) and the final value is
divided by crate::m::log(b).

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f95c66d and aa6112d.

📒 Files selected for processing (4)

• README.md
• src/math.rs
• src/math/bigint.rs
• src/math/integer.rs

🧰 Additional context used

📓 Path-based instructions (3)

src/math/**/*.rs

📄 CodeRabbit inference engine (AGENTS.md)

src/math/**/*.rs: Use existing CPython helper equivalents: FUNC1 → math_1(x, func, can_overflow), FUNC2 → math_2(x, y, func), m_log/m_log10/m_log2 in exponential.rs. If CPython uses a helper, use the corresponding Rust helper.
Use crate::mul_add(a, b, c) instead of a * b + c for expressions of the form a * b + c or c + a * b to match CPython's FMA (fused multiply-add) behavior on platforms like macOS where it's enabled.

Files:

• src/math/bigint.rs
• src/math/integer.rs

src/**/*.rs

📄 CodeRabbit inference engine (AGENTS.md)

Error handling: Return Result directly with Err(crate::Error::EDOM) or Err(crate::Error::ERANGE) instead of using set_errno. Only valid set_errno call is set_errno(0) to clear errno before libm calls.

Files:

• src/math/bigint.rs
• src/math.rs
• src/math/integer.rs

src/math.rs

📄 CodeRabbit inference engine (AGENTS.md)

Create missing helpers if CPython has a helper we don't have yet, such as math_1_fn for Rust function pointers or special case handlers for specific functions.

Files:

• src/math.rs

🧠 Learnings (11)

📓 Common learnings

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/math/**/*.rs : Use existing CPython helper equivalents: FUNC1 → math_1(x, func, can_overflow), FUNC2 → math_2(x, y, func), m_log/m_log10/m_log2 in exponential.rs. If CPython uses a helper, use the corresponding Rust helper.

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/math.rs : Create missing helpers if CPython has a helper we don't have yet, such as math_1_fn for Rust function pointers or special case handlers for specific functions.

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/cmath/**/*.rs : Use mul_add in cmath functions for expressions like 1.0 + x * x, cross-product calculations (mul_add(s1.re, s2.im, -(s2.re * s1.im))), and squared terms to achieve bit-exact matching with CPython.

📚 Learning: 2026-01-10T13:40:01.981Z

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Every function must match CPython exactly - same logic, same special case handling, same error conditions. Reference CPython source in Modules/mathmodule.c for math module and Modules/cmathmodule.c for cmath module.

Applied to files:

• README.md

📚 Learning: 2026-01-10T13:40:01.981Z

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/math/**/*.rs : Use existing CPython helper equivalents: FUNC1 → math_1(x, func, can_overflow), FUNC2 → math_2(x, y, func), m_log/m_log10/m_log2 in exponential.rs. If CPython uses a helper, use the corresponding Rust helper.

Applied to files:

• README.md
• src/math/bigint.rs
• src/math.rs
• src/math/integer.rs

📚 Learning: 2026-01-10T13:40:01.981Z

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/cmath/**/*.rs : Use mul_add in cmath functions for expressions like 1.0 + x * x, cross-product calculations (mul_add(s1.re, s2.im, -(s2.re * s1.im))), and squared terms to achieve bit-exact matching with CPython.

Applied to files:

• README.md
• src/math/bigint.rs
• src/math.rs

📚 Learning: 2026-01-10T13:40:01.981Z

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/math.rs : Create missing helpers if CPython has a helper we don't have yet, such as math_1_fn for Rust function pointers or special case handlers for specific functions.

Applied to files:

• README.md
• src/math/bigint.rs
• src/math.rs
• src/math/integer.rs

📚 Learning: 2026-01-10T13:40:01.981Z

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/cmath/trigonometric.rs : In cmath functions that use both sin and cos of the same angle (cosh, sinh, exp, rect), use m::sincos(x) which returns (sin, cos) tuple instead of calling sin and cos separately to match CPython's macOS __sincos_stret behavior.

Applied to files:

• README.md
• src/math.rs

📚 Learning: 2026-01-10T13:40:01.981Z

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/cmath/**/*.rs : For complex math (cmath module), copy special_type() enum and function, 7x7 special value tables (e.g., tanh_special_values), SPECIAL_VALUE macro usage, and complex-specific error handling from Modules/cmathmodule.c.

Applied to files:

• README.md
• src/math.rs

📚 Learning: 2026-01-10T13:40:01.981Z

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/math/**/*.rs : Use crate::mul_add(a, b, c) instead of a * b + c for expressions of the form a * b + c or c + a * b to match CPython's FMA (fused multiply-add) behavior on platforms like macOS where it's enabled.

Applied to files:

• README.md
• src/math/bigint.rs
• src/math.rs

📚 Learning: 2026-01-10T13:40:01.981Z

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/math/exponential.rs : Copy CPython's explicit special case handling for IEEE specials (NaN, Inf, etc.) exactly, including logic for cases like NaN**0 = 1.

Applied to files:

• src/math/bigint.rs
• src/math.rs
• src/math/integer.rs

📚 Learning: 2026-01-10T13:40:01.981Z

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/**/*test*.rs : All float functions must be tested with crate::test::EDGE_VALUES which includes zeros, infinities, NaNs with different payloads, subnormals, boundary values (MIN_POSITIVE, MAX, MIN), large values near infinity, and trigonometric special values (PI, PI/2, PI/4, TAU).

Applied to files:

• src/math/bigint.rs

📚 Learning: 2026-01-10T13:40:01.981Z

Learnt from: CR
Repo: RustPython/pymath PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-10T13:40:01.981Z
Learning: Applies to src/**/*test*.rs : Tests must verify both correct values for Ok results and correct error types (EDOM vs ERANGE) for Err results. Python ValueError maps to Error::EDOM and OverflowError maps to Error::ERANGE.

Applied to files:

• src/math/bigint.rs

🧬 Code graph analysis (2)

src/math/bigint.rs (2)

src/math/integer.rs (1)

• perm_comb_small (586-651)

src/test.rs (1)

• with_py_math (95-103)

src/math.rs (1)

src/math/bigint.rs (6)

• comb_bigint (40-57)
• ldexp_bigint (183-212)
• log_bigint (107-133)
• log2_bigint (138-154)
• log10_bigint (159-175)
• perm_bigint (20-34)

🪛 markdownlint-cli2 (0.18.1)

README.md

160-160: Heading style
Expected: setext; Actual: atx

(MD003, heading-style)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build and test (windows-latest)

🔇 Additional comments (10)

src/math/bigint.rs (7)

1-13: LGTM: Module structure and imports are appropriate.

The feature-gated BigInt imports and module documentation clearly state the internal nature of these helpers.

---

36-57: LGTM: Combination logic follows CPython's divide-and-conquer approach.

The use of perm_comb_small(k, j, true) for the divisor is appropriate since k fits in u64.

---

135-175: Verify bit-exact compatibility of Rust's log2() and log10().

Similar to log_bigint, these functions use Rust's standard log2() (line 153) and log10() (line 174) methods for large values. Confirm these produce bit-exact results matching CPython's implementations.

---

177-212: LGTM: ldexp_bigint correctly handles overflow and underflow.

The function properly:

• Returns special values unchanged (line 185-187)
• Clamps BigInt exponent to i64, then checks i32 bounds
• Returns ERANGE for overflow (line 205)
• Returns signed zero for underflow (line 208)
• Delegates to super::ldexp for valid ranges

Error handling follows the coding guidelines.

---

214-499: LGTM: Comprehensive test coverage with PyO3 comparisons.

The tests appropriately:

• Compare against Python's math module using PyO3
• Convert BigInt via string representation (lines 222-229)
• Allow small relative error (1e-10) for logarithm results
• Verify error cases match Python's behavior
• Include property-based tests for broader coverage

---

61-102: Verify algorithm correctness against CPython's _PyLong_Frexp implementation.

The frexp_bigint function properly delegates to crate::m::frexp for small integers (≤53 bits) and extracts 55 bits for large integers to match DBL_MANT_DIG + 2 precision. The rounding edge case (x == 1.0) is handled correctly. Confirm the large-integer scaling logic (dividing by 2^55 to get [0.5, 1.0)) and exponent adjustment (bits + 1) match CPython's implementation exactly by comparing against Objects/longobject.c.

---

16-34: Recursion depth is safe and not a concern for this implementation.

The divide-and-conquer approach with j = k/2 produces O(log k) recursion depth. For k values up to u64::MAX, this yields a maximum recursion depth of approximately 64 levels, which is well within safe stack limits and poses no overflow risk.

src/math.rs (1)

5-17: LGTM: Feature-gated bigint module and re-exports.

The _bigint feature flag is consistently applied to both the module declaration (lines 5-6) and the public re-exports (lines 16-17). All functions from src/math/bigint.rs are properly exposed.

src/math/integer.rs (2)

6-6: LGTM: Import path updated to use internal bigint module.

The change from feature-gated external crate imports to super::bigint aligns with the new module structure introduced in this PR.

---

586-586: LGTM: Visibility change enables bigint module integration.

Changing perm_comb_small to pub(super) allows the new src/math/bigint.rs::comb_bigint function to call it (line 55 of bigint.rs), which is necessary for the divide-and-conquer algorithm when computing C(k, j) for the divisor.