Euclidean extended gcd (#59)

* extended gcd

* nits

* fix code cov

* add tests with big numbers

* rename

* fix cargo test

---------

Co-authored-by: Luke Videckis <lukevideckis@gmail.com>

Author: lrvideckis

Cargo.toml

@@ -133,3 +133,7 @@ path = "examples/graphs/hld_jump_on_tree_nodes.rs"
 [[example]]
 name = "hld_jump_on_tree_edges"
 path = "examples/graphs/hld_jump_on_tree_edges.rs"
+
+[[example]]
+name = "ext_gcd"
+path = "examples/numbers/ext_gcd.rs"

examples/numbers/ext_gcd.rs

@@ -0,0 +1,42 @@
+// verification-helper: PROBLEM https://judge.u-aizu.ac.jp/onlinejudge/description.jsp?id=ALDS1_1_B
+
+use proconio::input;
+use programming_team_code_rust::numbers::ext_gcd::ext_gcd;
+
+fn do_asserts(a: i64, b: i64) {
+    let (gcd, x, y) = ext_gcd(a, b);
+    assert_eq!(a as i128 * x as i128 + b as i128 * y as i128, gcd as i128);
+    if gcd != 0 {
+        assert_eq!(a % gcd, 0);
+        assert_eq!(b % gcd, 0);
+    }
+    if b != 0 {
+        assert!(-(b / gcd).abs() < x);
+        assert!(x < (b / gcd).abs());
+    }
+}
+
+fn main() {
+    input! {
+        a: i64,
+        b: i64,
+    }
+
+    let vals = [
+        a,
+        b,
+        -a,
+        -b,
+        0_i64,
+        1_000_000_000_000_000_000_i64,
+        i64::MAX / 2,
+        i64::MIN / 2,
+    ];
+    for &val_one in &vals {
+        for &val_two in &vals {
+            do_asserts(val_one, val_two);
+        }
+    }
+
+    println!("{}", ext_gcd(a, b).0);
+}

src/numbers/ext_gcd.rs

@@ -0,0 +1,30 @@
+//! # Extended GCD
+
+/// See <https://nor-blog.codeberg.page/posts/2023-11-27-std-exchange-cpp/>
+///
+/// ext_gcd(a, b) returns (gcd, x, y) such that a * x + b * y == gcd
+/// if a and b are coprime, then x is the inverse of a (mod b)
+///
+/// # Example
+/// ```
+/// use programming_team_code_rust::numbers::ext_gcd::ext_gcd;
+///
+/// let (a, b) = (4, -6);
+/// let (gcd, x, y) = ext_gcd(a, b);
+/// assert_eq!(gcd, -2);
+/// assert_eq!(a * x + b * y, gcd);
+/// assert_eq!(ext_gcd(0, 0), (0, 1, 0));
+/// ```
+///
+/// - Time: O(log(min(a, b)))
+/// - Space: O(1)
+pub fn ext_gcd(mut a: i64, mut b: i64) -> (i64, i64, i64) {
+    let (mut x, mut y, mut i, mut j) = (1, 0, 0, 1);
+    while b != 0 {
+        let quot = a / b;
+        (a, b) = (b, a - quot * b);
+        (x, i) = (i, x - quot * i);
+        (y, j) = (j, y - quot * j);
+    }
+    (a, x, y)
+}

src/numbers/mod.rs

@@ -1,4 +1,5 @@
 //! # Number Theory and Combinatorics
 pub mod binom;
+pub mod ext_gcd;
 pub mod fft;
 pub mod primes;