Merge branch 'feature/39-add-digitpowersum-routine' into develop

Fixes #39

Author: delphidabbler

collection/634.dat

@@ -1,12 +1,22 @@
 function PowNZN(const X: Integer; const N: Cardinal): Int64;
 var
   I: Integer;
+  OverflowGuard: Int64;
 begin
-  if (X = 0) and (N > 0) then
-    Exit(0);
-  if X = 1 then
+  if N = 0 then
+    // IEEE: pown(x, 0) is 1, even when X is zero
     Exit(1);
+  if X = 0 then
+    // pown(0, n) = 0, for all positive n
+    Exit(0);
+  OverflowGuard := High(Int64) div Abs(X);
   Result := 1;
   for I := 1 to N do
+  begin
+    if OverflowGuard < Abs(Result) then
+      raise SysUtils.EOverflow.CreateFmt(
+        'Overflow calculating %d to the power %d', [X, N]
+      );
     Result := Result * X;
+  end;
 end;

collection/661.dat

@@ -0,0 +1,27 @@
+function DigitPowerSum(N: Integer; const Base: Byte; const Exponent: Byte):
+  Int64;
+var
+  SignOfN: Math.TValueSign;
+  Digit: Integer;
+  PowerDigit: Int64;
+begin
+  if Base < 2 then
+    raise SysUtils.EArgumentException.Create(
+      'Base must be in the range 2..255'
+    );
+  if N = 0 then
+    Exit(0);
+  SignOfN := Math.Sign(N);
+  N := Abs(N);
+  Result := 0;
+  repeat
+    Digit := N mod Base;
+    PowerDigit := PowNZN(Digit, Exponent);
+    if High(Int64) - PowerDigit < Abs(Result) then
+      raise SysUtils.EOverflow.Create('Overflow calculating digit power sum');
+    Result := Result + PowerDigit;
+    N := N div Base;
+  until N = 0;
+  if SignOfN = Math.NegativeValue then
+    Result := -1 * Result;
+end;

collection/maths.ini

@@ -620,7 +620,7 @@ Extra="<p>Sums of digits of negative numbers are negative, for example <mono>Dig
 TestInfo=advanced
 AdvancedTest.Level=unit-tests
 AdvancedTest.URL="https://github.com/delphidabbler/code-snippets/tree/master/tests/Cat-Maths"
-SeeAlso=DigitSumBase
+SeeAlso=DigitSumBase,DigitPowerSum
 Snip=418.dat
 Delphi2=N
 Delphi3=N
@@ -1391,8 +1391,9 @@ Delphi11A=Y
 Delphi12A=Y
 
 [PowNZN]
-DescEx="<p>Raises integer <var>X</var> to non-negative integer power <var>N</var>.</p>"
+DescEx="<p>Raises integer <var>X</var> to non-negative integer power <var>N</var>.</p><p>If the result is too large to be represented as an <var>Int64</var> value then an <var>EOverflow</var> exception is raised.</p>"
 Extra="<p>Returns an <var>integer</var> value because the power <var>N</var> is non-negative which guarantees that the result is integral.</p><p>Based on IEEE standard 754-2008 for Floating-Point Arithmetic, page 44, but which restricts <var>X</var> to an integer and <var>N</var> to a non-negative integer.</p>"
+Units=SysUtils
 SeeAlso=Pow,PowN,PowNZZ
 TestInfo=advanced
 AdvancedTest.Level=unit-tests
@@ -1762,7 +1763,7 @@ DisplayName="DigitSumBase"
 DescEx="<p>Calculates the sum of all the digits of integer <var>N</var> when epxressed in base <var>Base</var>. The returned value has the same sign as <var>N</var>.</p><p>Bases up to 255 are supported. If <var>Base</var> &lt; 2 then an <var>EArgumentException</var> exception is raised.</p>"
 Kind=routine
 Units=SysUtils,Math
-SeeAlso=DigitSum
+SeeAlso=DigitSum,DigitPowerSum
 TestInfo=advanced
 AdvancedTest.Level=unit-tests
 AdvancedTest.URL="https://github.com/delphidabbler/code-snippets/tree/master/tests/Cat-Maths"
@@ -1797,3 +1798,17 @@ AdvancedTest.URL="https://github.com/delphidabbler/code-snippets/tree/master/tes
 Snip=659.dat
 DelphiXE=Y
 Delphi12A=Y
+
+[DigitPowerSum]
+DisplayName=DigitPowerSum
+DescEx="<p>Calculates the sum of all the digits of integer <var>N</var> in base <var>Base</var> where each digit is raised to the power <var>Exponent</var>. The returned value has the same sign as <var>N</var>.</p><p>If the result is too large to be represented as an <var>Int64</var> value then an <var>EOverflow</var> exception is raised.</p><p>Bases up to 255 are supported. If <var>Base</var> &lt;= 2 then an <var>EArgumentException</var> exception is raised.</p>"
+Kind=routine
+Units=SysUtils,Math
+Depends=PowNZN
+SeeAlso=DigitSum,DigitSumBase
+TestInfo=advanced
+AdvancedTest.Level=unit-tests
+AdvancedTest.URL="https://github.com/delphidabbler/code-snippets/tree/master/tests/Cat-Maths"
+Snip=661.dat
+DelphiXE=Y
+Delphi12A=Y

tests/Cat-Maths/TestUMathsCatSnippets.pas

@@ -20,6 +20,9 @@   TestMathsCatSnippets = class(TTestCase)
     procedure TestWeightedArithMean_Double_Except4;
     procedure TestDigitSumBase_Except;
     procedure TestDigitsOf_ArgExcept;
+    procedure TestPowNZN_EOverflow;
+    procedure TestDigitPowerSum_EOverflow;
+    procedure TestDigitPowerSum_EArgumentException;
     function EqualArrays(const Left, Right: TBytes): Boolean;
     function ReverseArray(const A: TBytes): TBytes;
   published
@@ -51,7 +54,7 @@   TestMathsCatSnippets = class(TTestCase)
     procedure TestMaxOfArray_Single;
     procedure TestMaxOfArray_Double;
     procedure TestMaxOfArray_Extended;
-    procedure TestPowNZN;
+    procedure TestPowNZN;   // required by DigitPowerSum
     procedure TestPowNZZ;
     procedure TestPowN;
     procedure TestArraySum_Single;
@@ -77,6 +80,7 @@   TestMathsCatSnippets = class(TTestCase)
     procedure TestDigitCountBase;
     procedure TestDigitSumBase;
     procedure TestDigitsOf;
+    procedure TestDigitPowerSum;
   end;
 
 implementation
@@ -416,6 +420,33 @@ procedure TestMathsCatSnippets.TestDigitCountR;
   CheckEquals(5, DigitCountR(-12345), 'DigitCountR(-12345)');
 end;
 
+procedure TestMathsCatSnippets.TestDigitPowerSum;
+begin
+  CheckEquals(35, DigitPowerSum(135, 10, 2), '#1');
+  CheckEquals(0, DigitPowerSum(0, 8, 5), '#2');
+  CheckEquals(3, DigitPowerSum(510, 10, 0), '#3');
+  CheckEquals(30, DigitPowerSum($FF, 16, 1), '#4');
+  CheckEquals(12613, DigitPowerSum(1685237180, 10, 4), '#5');
+  CheckEquals(77907, DigitPowerSum(1685237180 {6472ADBC hex}, 16, 4), '#6');
+  CheckEquals(6740, DigitPowerSum(1685237180 {14434526674 oct}, 8, 4), '#7');
+  CheckEquals(-6740, DigitPowerSum(-1685237180 {14434526674 oct}, 8, 4), '#8');
+  CheckEquals(17, DigitPowerSum(1685237180 {1100100011100101010110110111100 bin}, 2, 4), '#9');
+  CheckEquals(2409140909625644483, DigitPowerSum(MaxInt {C87E66B7 base 15}, 15, 16), '#10');
+  CheckException(TestDigitPowerSum_EArgumentException, EArgumentException, 'EArgumentException');
+  CheckException(TestDigitPowerSum_EOverflow, EOverflow, 'EOverflow');
+  // EOverflow can also be raised by PowNZN, not tested here
+end;
+
+procedure TestMathsCatSnippets.TestDigitPowerSum_EArgumentException;
+begin
+  DigitPowerSum(42, 1, 2); // Base = 1 => EArgumentException
+end;
+
+procedure TestMathsCatSnippets.TestDigitPowerSum_EOverflow;
+begin
+  DigitPowerSum(88888888, 10, 20); // overflows High(Int64) by 1
+end;
+
 procedure TestMathsCatSnippets.TestDigitsOf;
 var
   E: TBytes;
@@ -930,6 +961,12 @@ procedure TestMathsCatSnippets.TestPowNZN;
   CheckEquals(10000,  PowNZN(10, 4),  'PowNZN(10,2)');
   CheckEquals(-1000,  PowNZN(-10, 3), 'PowNZN(-10,3)');
   CheckEquals(10000,  PowNZN(-10, 4), 'PowNZN(-10,4)');
+  CheckException(TestPowNZN_EOverflow, EOverflow, 'EOverflow');
+end;
+
+procedure TestMathsCatSnippets.TestPowNZN_EOverflow;
+begin
+  PowNZN(2, 63);
 end;
 
 procedure TestMathsCatSnippets.TestPowNZZ;

tests/Cat-Maths/UMathsCatSnippets.pas

@@ -6,7 +6,7 @@
  * The unit is copyright © 2005-2024 by Peter Johnson & Contributors and is
  * licensed under the MIT License (https://opensource.org/licenses/MIT).
  * 
- * Generated on : Tue, 07 Jan 2025 13:13:01 GMT.
+ * Generated on : Thu, 09 Jan 2025 10:55:06 GMT.
  * Generated by : DelphiDabbler CodeSnip Release 4.24.0.
  * 
  * The latest version of CodeSnip is available from the CodeSnip GitHub project
@@ -129,6 +129,18 @@ function DigitCountBase(N: Int64; const Base: Byte): Cardinal;
 }
 function DigitCountR(AValue: Int64): Integer;
 
+{
+  Calculates the sum of all the digits of integer N in base Base where each
+  digit is raised to the power Exponent. The returned value has the same sign as
+  N.
+  If the result is too large to be represented as an Int64 value then an
+  EOverflow exception is raised.
+  Bases up to 255 are supported. If Base <= 2 then an EArgumentException
+  exception is raised.
+}
+function DigitPowerSum(N: Integer; const Base: Byte; const Exponent: Byte):
+  Int64;
+
 {
   Returns an array containing the digits of integer N when expressed in base
   Base. The array is ordered with the least significant digit first.
@@ -358,6 +370,8 @@ function PowN(const X: Extended; const N: Integer): Extended;
 
 {
   Raises integer X to non-negative integer power N.
+  If the result is too large to be represented as an Int64 value then an
+  EOverflow exception is raised.
 }
 function PowNZN(const X: Integer; const N: Cardinal): Int64;
 
@@ -894,6 +908,43 @@ function DigitCountR(AValue: Int64): Integer;
     Result := 1 + DigitCountR(AValue div 10)
 end;
 
+{
+  Calculates the sum of all the digits of integer N in base Base where each
+  digit is raised to the power Exponent. The returned value has the same sign as
+  N.
+  If the result is too large to be represented as an Int64 value then an
+  EOverflow exception is raised.
+  Bases up to 255 are supported. If Base <= 2 then an EArgumentException
+  exception is raised.
+}
+function DigitPowerSum(N: Integer; const Base: Byte; const Exponent: Byte):
+  Int64;
+var
+  SignOfN: Math.TValueSign;
+  Digit: Integer;
+  PowerDigit: Int64;
+begin
+  if Base < 2 then
+    raise SysUtils.EArgumentException.Create(
+      'Base must be in the range 2..255'
+    );
+  if N = 0 then
+    Exit(0);
+  SignOfN := Math.Sign(N);
+  N := Abs(N);
+  Result := 0;
+  repeat
+    Digit := N mod Base;
+    PowerDigit := PowNZN(Digit, Exponent);
+    if High(Int64) - PowerDigit < Abs(Result) then
+      raise SysUtils.EOverflow.Create('Overflow calculating digit power sum');
+    Result := Result + PowerDigit;
+    N := N div Base;
+  until N = 0;
+  if SignOfN = Math.NegativeValue then
+    Result := -1 * Result;
+end;
+
 {
   Returns an array containing the digits of integer N when expressed in base
   Base. The array is ordered with the least significant digit first.
@@ -1610,18 +1661,30 @@ function PowN(const X: Extended; const N: Integer): Extended;
 
 {
   Raises integer X to non-negative integer power N.
+  If the result is too large to be represented as an Int64 value then an
+  EOverflow exception is raised.
 }
 function PowNZN(const X: Integer; const N: Cardinal): Int64;
 var
   I: Integer;
+  OverflowGuard: Int64;
 begin
-  if (X = 0) and (N > 0) then
-    Exit(0);
-  if X = 1 then
+  if N = 0 then
+    // IEEE: pown(x, 0) is 1, even when X is zero
     Exit(1);
+  if X = 0 then
+    // pown(0, n) = 0, for all positive n
+    Exit(0);
+  OverflowGuard := High(Int64) div Abs(X);
   Result := 1;
   for I := 1 to N do
+  begin
+    if OverflowGuard < Abs(Result) then
+      raise SysUtils.EOverflow.CreateFmt(
+        'Overflow calculating %d to the power %d', [X, N]
+      );
     Result := Result * X;
+  end;
 end;
 
 {