Merge branch 'feature/32-logarithmic-mean-function' into develop

Fixes #32

Author: delphidabbler

Diff for: collection/690.dat

@@ -0,0 +1,11 @@
+function LogarithmicMean(const X, Y: Double): Double;
+begin
+  if (X <= 0) or (Y <= 0) then
+    raise SysUtils.EArgumentException.Create(
+      'Parameters X & Y must both be positive'
+    );
+  if Math.SameValue(X, Y) then
+    Result := X
+  else
+    Result := (Y - X) / (System.Ln(Y) - System.Ln(X));
+end;

Diff for: collection/maths.ini

@@ -2211,3 +2211,17 @@ AdvancedTest.URL="https://github.com/delphidabbler/code-snippets/tree/master/tes
 Snip=689.dat
 DelphiXE=Y
 Delphi12A=Y
+
+[LogarithmicMean]
+DisplayName="LogarithmicMean"
+DescEx="<p>Returns the logarithmic mean of two positive floating point values, <var>X</var> and <var>Y</var>.</p><p>Raises <var>EArgumentException</var> if either <var>X</var> or <var>Y</var> is not positive.</p>"
+Extra="<p>See <a href="https://www.ryantoomey.org/wiki/Logarithmic_mean_average">Chemepedia</a> for information about the logarithmic mean.</p>"
+Kind=routine
+Units=SysUtils,Math
+SeeAlso=ArithmeticMean_Double,GeometricMean_Double,HarmonicMean_Double
+TestInfo=advanced
+AdvancedTest.Level=unit-tests
+AdvancedTest.URL="https://github.com/delphidabbler/code-snippets/tree/master/tests/Cat-Maths"
+Snip=690.dat
+DelphiXE=Y
+Delphi12A=Y

Diff for: tests/Cat-Maths/TestUMathsCatSnippets.pas

@@ -64,6 +64,8 @@   TestMathsCatSnippets = class(TTestCase)
     procedure TestWeightedHarmonicMean_Double_ExceptDiffSizeArrays;
     procedure TestWeightedHarmonicMean_Double_ExceptNegativeWeights;
     procedure TestWeightedHarmonicMean_Double_ExceptZeroWeights;
+    procedure TestLogarithmicMean_ExceptNonPositive;
+    procedure TestLogarithmicMean_ExceptZero;
     function EqualArrays(const Left, Right: TBytes): Boolean; overload;
     function EqualArrays(const Left, Right: array of Double;
       Fudge: Double = 0.0): Boolean; overload;
@@ -153,6 +155,7 @@   TestMathsCatSnippets = class(TTestCase)
     procedure TestWeightedHarmonicMean_Double;  // required by Integer & Cardinal overloads
     procedure TestWeightedHarmonicMean_Cardinal;
     procedure TestWeightedHarmonicMean_Integer;
+    procedure TestLogarithmicMean;
   end;
 
 implementation
@@ -1022,6 +1025,40 @@ procedure TestMathsCatSnippets.TestLCD;
   CheckEquals(9, LCD(-9, -9), 'LCD(-9, -9)');
 end;
 
+procedure TestMathsCatSnippets.TestLogarithmicMean;
+const
+  Fudge = 0.000000001;
+  // Expected values calculated with Windows Calc
+  XA = 42.456;                          EA = XA;
+  XB = 42.456;      YB = 56.847;        EB = 49.3019407666718697;
+  XC = 0.000001;    YC = 0.000002;      EC = 1.4426950408889634e-6;
+  XD = 0.000001;                        ED = XD;
+  XE = 18374983.0;  YE = 2768293.9362;  EE = 8245471.247628288866;
+  XF = 18.374983;   YF = 2768293.9362;  EF = 232184.284293825682;
+  XG = 0.00002356;  YG = 2768293.9362;  EG = 108604.405745470878;
+begin
+  CheckTrue(SameValue(EA, LogarithmicMean(XA, XA), Fudge), 'A (x,x)');
+  CheckTrue(SameValue(EB, LogarithmicMean(XB, YB), Fudge), 'B (x,y)');
+  CheckTrue(SameValue(EB, LogarithmicMean(YB, XB), Fudge), 'B (y,x)');
+  CheckTrue(SameValue(EC, LogarithmicMean(XC, YC), Fudge), 'C (x,y)');
+  CheckTrue(SameValue(ED, LogarithmicMean(XD, XD), Fudge), 'D (x,x)');
+  CheckTrue(SameValue(EE, LogarithmicMean(XE, YE), Fudge), 'E (x,y)');
+  CheckTrue(SameValue(EF, LogarithmicMean(XF, YF), Fudge), 'F (x,y)');
+  CheckTrue(SameValue(EG, LogarithmicMean(XG, YG), Fudge), 'G (x,y)');
+  CheckException(TestLogarithmicMean_ExceptNonPositive, EArgumentException, 'Not positive exception');
+  CheckException(TestLogarithmicMean_ExceptZero, EArgumentException, 'Zero exception');
+end;
+
+procedure TestMathsCatSnippets.TestLogarithmicMean_ExceptNonPositive;
+begin
+  LogarithmicMean(-2.4, 1.0);
+end;
+
+procedure TestMathsCatSnippets.TestLogarithmicMean_ExceptZero;
+begin
+  LogarithmicMean(2.4, 0.0);
+end;
+
 procedure TestMathsCatSnippets.TestLSE;
 const
   Fudge = 0.000001;

Diff for: 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, 14 Jan 2025 10:14:17 GMT.
+ * Generated on : Tue, 14 Jan 2025 11:37:09 GMT.
  * Generated by : DelphiDabbler CodeSnip Release 4.24.0.
  * 
  * The latest version of CodeSnip is available from the CodeSnip GitHub project
@@ -269,6 +269,12 @@ function IsRectNormal(const R: Windows.TRect): Boolean;
 }
 function LCD(A, B: Integer): Integer;
 
+{
+  Returns the logarithmic mean of two positive floating point values, X and Y.
+  Raises EArgumentException if either X or Y is not positive.
+}
+function LogarithmicMean(const X, Y: Double): Double;
+
 {
   Returns the logarithm of the sum of the exponentials of the given array of
   floating pointing point numbers.
@@ -1505,6 +1511,22 @@ function LCD(A, B: Integer): Integer;
   Result := Abs((A * B)) div GCD(A, B);
 end;
 
+{
+  Returns the logarithmic mean of two positive floating point values, X and Y.
+  Raises EArgumentException if either X or Y is not positive.
+}
+function LogarithmicMean(const X, Y: Double): Double;
+begin
+  if (X <= 0) or (Y <= 0) then
+    raise SysUtils.EArgumentException.Create(
+      'Parameters X & Y must both be positive'
+    );
+  if Math.SameValue(X, Y) then
+    Result := X
+  else
+    Result := (Y - X) / (System.Ln(Y) - System.Ln(X));
+end;
+
 {
   Returns the logarithm of the sum of the exponentials of the given array of
   floating pointing point numbers.