Add Int#tdivmod (#16258)

Author: andrykonchin

spec/std/int_spec.cr

@@ -521,7 +521,61 @@ describe "Int" do
   end
 
   describe "divmod" do
-    it { 5.divmod(3).should eq({1, 2}) }
+    it "returns a Tuple of two elements containing the quotient and modulus obtained by dividing self by argument" do
+      5.divmod(3).should eq({1, 2})
+      -5.divmod(3).should eq({-2, 1})
+      5.divmod(-3).should eq({-2, -1})
+      -5.divmod(-3).should eq({1, -2})
+    end
+
+    it "preserves type of lhs" do
+      {% for type in [UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64, UInt128, Int128] %}
+        {{type}}.new(7).divmod(2).should be_a(Tuple({{type}}, {{type}}))
+      {% end %}
+    end
+
+    it "raises when divides by zero" do
+      expect_raises(DivisionByZeroError) { 5.divmod(0) }
+    end
+
+    it "raises when divides Int::MIN by -1" do
+      expect_raises(ArgumentError) { Int8::MIN.divmod(-1) }
+      expect_raises(ArgumentError) { Int16::MIN.divmod(-1) }
+      expect_raises(ArgumentError) { Int32::MIN.divmod(-1) }
+      expect_raises(ArgumentError) { Int64::MIN.divmod(-1) }
+      expect_raises(ArgumentError) { Int128::MIN.divmod(-1) }
+
+      (UInt8::MIN.divmod(-1)).should eq({0, 0})
+    end
+  end
+
+  describe "tdivmod" do
+    it "returns a Tuple of two elements containing the quotient and modulus obtained by dividing self by argument using truncated division" do
+      5.tdivmod(3).should eq({1, 2})
+      -5.tdivmod(3).should eq({-1, -2})
+      5.tdivmod(-3).should eq({-1, 2})
+      -5.tdivmod(-3).should eq({1, -2})
+    end
+
+    it "preserves type of lhs" do
+      {% for type in [UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64, UInt128, Int128] %}
+        {{type}}.new(7).tdivmod(2).should be_a(Tuple({{type}}, {{type}}))
+      {% end %}
+    end
+
+    it "raises when divides by zero" do
+      expect_raises(DivisionByZeroError) { 5.tdivmod(0) }
+    end
+
+    it "raises when divides Int::MIN by -1" do
+      expect_raises(ArgumentError) { Int8::MIN.tdivmod(-1) }
+      expect_raises(ArgumentError) { Int16::MIN.tdivmod(-1) }
+      expect_raises(ArgumentError) { Int32::MIN.tdivmod(-1) }
+      expect_raises(ArgumentError) { Int64::MIN.tdivmod(-1) }
+      expect_raises(ArgumentError) { Int128::MIN.tdivmod(-1) }
+
+      (UInt8::MIN.tdivmod(-1)).should eq({0, 0})
+    end
   end
 
   describe "fdiv" do
@@ -757,11 +811,33 @@ describe "Int" do
     end
   end
 
-  it "tdivs" do
-    5.tdiv(3).should eq(1)
-    -5.tdiv(3).should eq(-1)
-    5.tdiv(-3).should eq(-1)
-    -5.tdiv(-3).should eq(1)
+  describe "tdiv" do
+    it "divides self by argument using truncated division" do
+      5.tdiv(3).should eq(1)
+      -5.tdiv(3).should eq(-1)
+      5.tdiv(-3).should eq(-1)
+      -5.tdiv(-3).should eq(1)
+    end
+
+    it "preserves type of lhs" do
+      {% for type in [UInt8, UInt16, UInt32, UInt64, Int8, Int16, Int32, Int64, UInt128, Int128] %}
+        {{type}}.new(7).tdiv(2).should be_a({{type}})
+      {% end %}
+    end
+
+    it "raises when divides by zero" do
+      expect_raises(DivisionByZeroError) { 5.tdiv(0) }
+    end
+
+    it "raises when divides Int::MIN by -1" do
+      expect_raises(ArgumentError) { Int8::MIN.tdiv(-1) }
+      expect_raises(ArgumentError) { Int16::MIN.tdiv(-1) }
+      expect_raises(ArgumentError) { Int32::MIN.tdiv(-1) }
+      expect_raises(ArgumentError) { Int64::MIN.tdiv(-1) }
+      expect_raises(ArgumentError) { Int128::MIN.tdiv(-1) }
+
+      (UInt8::MIN.tdiv(-1)).should eq(0)
+    end
   end
 
   it "holds true that x == q*y + r" do

src/int.cr

@@ -118,7 +118,7 @@ struct Int
   #
   # In truncated division, given two integers x and y:
   # * `q = x.tdiv(y)` is rounded toward zero
-  # * `r = x.remainder(y)` has the sign of the first argument
+  # * `r = x.remainder(y)` has the sign of x
   # * `x == q*y + r`
   #
   # For example:
@@ -152,6 +152,39 @@ struct Int
     {% end %}
   end
 
+  # Returns a `Tuple` of two elements containing the quotient
+  # and modulus obtained by dividing `self` by *number* using
+  # truncated division.
+  #
+  # ```
+  # 11.tdivmod(3)  # => {3, 2}
+  # 11.tdivmod(-3) # => {-4, -1}
+  # ```
+  #
+  # In truncated division, given two integers x and y:
+  # * `q = x.tdiv(y)` is rounded toward zero
+  # * `r = x.remainder(y)` has the sign of x
+  # * `x == q*y + r`
+  #
+  # For example:
+  #
+  # ```text
+  #  x     y     x / y     x % y
+  #  5     3       1         2
+  # -5     3      -1        -2
+  #  5    -3      -1         2
+  # -5    -3       1        -2
+  # ```
+  #
+  # Raises if *other* is `0`, or if *other* is `-1` and
+  # `self` is signed and is the minimum value for that
+  # integer type.
+  def tdivmod(other : Int)
+    check_div_argument other
+
+    {unsafe_div(other), unsafe_mod(other)}
+  end
+
   def fdiv(other) : Float64
     to_f / other
   end