[integer][BigInt2] Implement GCD, extended GCD, and modular arithmetic

[forfudan]

This PR implements number theory operations for BigInt2, completing Item PR7 the BigInt2 roadmap. It adds greatest common divisor (GCD), extended GCD, least common multiple (LCM), modular exponentiation, and modular inverse functionality to the BigInt2 arbitrary-precision integer type. The implementation uses efficient algorithms optimized for the base-2^32 representation and includes comprehensive test coverage.

Changes:

• Implements binary GCD (Stein's algorithm), extended GCD, LCM, modular exponentiation (mod_pow), and modular inverse (mod_inverse) in a new number_theory.mojo module
• Adds 31 comprehensive tests covering edge cases, mathematical properties, and error conditions
• Applies performance optimization to shrink() calls in bitwise and arithmetic operations, replacing loops with single calls when target length is known

[Copilot]

Pull request overview

This PR implements number theory operations for BigInt2, completing PR #7 from the BigInt2 roadmap. It adds greatest common divisor (GCD), extended GCD, least common multiple (LCM), modular exponentiation, and modular inverse functionality to the BigInt2 arbitrary-precision integer type. The implementation uses efficient algorithms optimized for the base-2^32 representation and includes comprehensive test coverage.

Changes:

• Implements binary GCD (Stein's algorithm), extended GCD, LCM, modular exponentiation (mod_pow), and modular inverse (mod_inverse) in a new number_theory.mojo module
• Adds 31 comprehensive tests covering edge cases, mathematical properties, and error conditions
• Applies performance optimization to shrink() calls in bitwise and arithmetic operations, replacing loops with single calls when target length is known

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/decimojo/bigint2/number_theory.mojo	New module implementing GCD (binary/Stein's algorithm), extended GCD (iterative Euclidean), LCM, modular exponentiation (binary exponentiation), and modular inverse using established number theory algorithms
tests/bigint2/test_bigint2_number_theory.mojo	Comprehensive test suite with 31 tests covering all number theory operations including edge cases, mathematical properties, and error handling
src/decimojo/bigint2/arithmetics.mojo	Performance optimization: replace loop-based shrink with single shrink call in right_shift_inplace
src/decimojo/bigint2/bitwise.mojo	Performance optimization: replace loop-based shrink with single shrink call in _binary_bitwise_op_inplace
src/decimojo/bigint2/bigint2.mojo	Add imports for bitwise and number_theory modules
docs/readme_unreleased.md	New comprehensive documentation file (will become README.md) with updated description emphasizing BigInt2 as the primary integer type
docs/plans/bigint2_benchmark_analysis.md	Update PR7 status to DONE with detailed implementation notes
docs/plans/big_binary_integer.md	New planning document explaining the BigInt2 design rationale and future renaming plan
README.md	Update description to emphasize integer types before decimal types, positioning DeciMojo as a drop-in replacement for Python's int and Decimal

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.