Merge branch 'update-fractions-for-v0.2'

Author: delphidabbler

Fractions/0/API/TFraction-Abs.md

@@ -6,19 +6,30 @@
 
 **Record:** [_TFraction_](./TFraction.md)
 
-**Applies to:** ~>0.1
+**Applies to:** 0.1.x
 
 ```pascal
 class function Abs(const F: TFraction): TFraction; static;
 ```
 
+**Applies to:** ~>0.2
+
+```pascal
+class function Abs(const F: TFraction): TFraction; overload; static;
+function Abs: TFraction; overload;
+```
+
 ## Description
 
-Returns the absolute value of the given fraction _F_.
+Returns the absolute value of a fraction. The returned fraction is not simplified.
+
+The class method operates on the fraction passed as parameter _F_.
 
-The returned fraction is not simplified.
+[~>0.2] The instance method operates upon the fraction instance on which it is called.
 
-### Example
+### Examples
+
+Using the class method:
 
 ```pascal
 var
@@ -33,6 +44,21 @@ begin
 end;
 ```
 
+[~>0.2] Using the instance method:
+
+```pascal
+var
+  F, G: TFraction;
+begin
+  F := TFraction.Create(3, 4);
+  G := F.Abs;
+  Assert(G = +F);
+  F := TFraction.Create(-7, 8);
+  G := F.Abs;
+  Assert(G = -F);
+end;
+```
+
 ## See Also
 
 * [_Sign_](./TFraction-Sign.md) method

Fractions/0/API/TFraction-Create.md

@@ -82,4 +82,5 @@ end;
 
 ## See Also
 
-* [_Implicit_](./TFraction-Implicit.md) operator overload
+* [_Implicit_](./TFraction-Implicit.md) operator overload.
+* _[Intialize](./TFraction-Initialize.md) [~>0.2]_ operator overload (Delphi 10.4 and later only).

Fractions/0/API/TFraction-Hash.md

@@ -0,0 +1,31 @@
+# Hash method
+
+**Project:** [Fractions](../API.md)
+
+**Unit:** _DelphiDabbler.Lib.Fractions_
+
+**Record:** [_TFraction_](./TFraction.md)
+
+**Applies to:** ~>0.2
+
+```pascal
+function Hash: Integer;
+```
+
+## Description
+
+Computes and returns a hash value for the fraction as an _Integer_.
+
+If two fractions that simplify to the same fraction have the same hash.
+
+### Example
+
+```pascal
+var
+  F, G: TFraction;
+begin
+  F := TFraction.Create(1, 2);
+  G := TFraction.Create(3, 6);
+  Assert(F.Hash = G.Hash);
+end;
+```

Fractions/0/API/TFraction-Initialize.md

@@ -0,0 +1,27 @@
+# Initialize operator overload
+
+**Project:** [Fractions](../API.md)
+
+**Unit:** _DelphiDabbler.Lib.Fractions_
+
+**Record:** [_TFraction_](./TFraction.md)
+
+**Applies to:** ~>0.2
+
+```pascal
+class operator Initialize(out Dest: TFraction);
+```
+
+## Description
+
+> **This operator overload is conditionally compiled for Delphi 10.4 and later only.**
+
+_Initialize_ is called automatically whenever a new _TFraction_ record is created. It sets the values of the _[Numerator](./TFraction-Numerator.md)_ and _[Denominator](./TFraction-Denominator.md)_ properties to `0` and `1` respectively, to correctly represent a zero fraction.
+
+⚠️ When compiled with Delphi version prior to 10.4 the initial values of _[Numerator](./TFraction-Numerator.md)_ and _[Denominator](./TFraction-Denominator.md)_ properties are undefined.
+
+⛔ _Initialize_ should never be called explicitly.
+
+## See Also
+
+* [_Create_](./TFraction-Create.md) constructor

Fractions/0/API/TFraction-Power.md

@@ -6,23 +6,34 @@
 
 **Record:** [_TFraction_](./TFraction.md)
 
-**Applies to:** ~>0.1
+**Applies to:** 0.1.x
 
 ```pascal
 class function Power(const F: TFraction; Exponent: ShortInt): TFraction; static;
 ```
+**Applies to:** ~>0.2
+
+```pascal
+class function Power(const F: TFraction; Exponent: ShortInt): TFraction; 
+  overload; static;
+function Power(const Exponent: ShortInt): TFraction; overload;
+```
 
 ## Description
 
-Returns the given fraction _F_ raised to the power of integer _Exponent_.
+Return a fraction raised to an integer power specified by the _Exponent_ parameter. The resulting fraction is simplified.
+
+_Exponent_ can be positive, zero or negative except unless the fraction is zero when _Exponent_ must be non-negative. 
+
+When _Exponent_ is negative the reciprocal of _F_ is raised to the power of the absolute value of _Exponent_. This is because, for any number `n`, `n^-x = 1/(N^x)`.
 
-_Exponent_ can be positive, zero or negative. When _Exponent_ is negative the reciprocal of _F_ is raised to the power of the absolute value of _Exponent_. This is because, for any number `n`, `n^-x = 1/(N^x)`.
+The class method takes the fraction to be operated on, _F_, as its first parameter.
 
-If _F_ is zero, _Exponent_ must be non-negative.
+[~>0.2] The instance method operates on the fraction instance upon which it is called.
 
-The resulting fraction is simplified.
+### Examples 
 
-### Examples
+#### Class method examples
 
 Here's a simple function that squares the given fraction.
 
@@ -33,7 +44,7 @@ begin
 end;
 ```
 
-And here is some code that write out all the integer powers of 1/2 from -32 to +32:
+[~>0.2] Here is some code that write out all the integer powers of 1/2 from -32 to +32:
 
 ```pascal
 var
@@ -43,7 +54,7 @@ begin
   F := TFraction.Create(1, 2);  // 1/2
   for N := -32 to 32 do
   begin
-    G := TFraction.Power(F, N);
+    G := F.Power(N);
     WriteLn(
       Format(
         '1/2^%d = %d/%d', [N, G.Numerator, G.Denominator]

Fractions/0/API/TFraction.md

@@ -21,6 +21,9 @@ Furthermore a _TFraction_ variable can be instantiated by assigning a variable o
 * Another _TFraction_. Properties are simply copied.
 * Any integer type. This creates a fractions with numerator equal to the integer and denominator 1.
 * A _Single_, _Double_ or _Extended_ floating point type. The floating point value is converted to a fraction to an accuracy of 5 decimal places. The floating point value must be 0 or have an absolute value in the range 1.0e-19 to 1.0e+19.
+* [~>0.2] **When compiled with Delphi 10.4 or later only:** simply declaring a _TFraction_ variable will instantiate it as if `0` had been assigned to it.
+
+⚠️ Never use a _TFraction_ variable that has not been instantiated since its value is undefined.
 
 ### Properties
 
@@ -56,6 +59,7 @@ The operators are overloaded by the record
 | [_Modulus_](./TFraction-Modulus.md) | Enables the modulus operator (`mod`) to be used to get the fractional remainder after dividing one _TFraction_ record by another.  |
 | [_Round_](./TFraction-Round.md) | Enables the `Round` operator to round a _TFraction_ record to the nearest whole number value.  |
 | [_Trunc_](./TFraction-Trunc.md) | Enables the `Trunc` operator to truncate a _TFraction_ record to the nearest whole number in the direction of zero. |
+| _[Initialize](./TFraction-Initialize.md) [~>0.2]_ | When compiled with Delphi 10.4 or later, automatically initialises _TFraction_ records with _[Numerator](./TFraction-Numerator.md)_ = `0` and _[Denominator](./TFraction-Denominator.md)_ = `1`. |
 
 ### Methods
 
@@ -71,11 +75,14 @@ _TFraction_ defines several methods. Some are static class methods that operate
 
 | Method | Description |
 |:-------|:------------|
+| _[Abs](./TFraction-Abs.md) [~>0.2]_ | Returns the absolute value of the fraction (overloaded with class method). |
 | [_CompareTo_](./TFraction-CompareTo.md) | Compares the fraction to another and returns a value indicating which fraction is greatest or if they are equal. |
 | [_Convert_](./TFraction-Convert.md) | Converts the fraction into an equivalent one in which the numerator and denominator are a given integer multiple of their original values. |
 | [_HasCommonFactor_](./TFraction-HasCommonFactor.md) | Checks if a given integer is a common factor of the fraction. |
+| _[Hash](./TFraction-Hash.md) [~>0.2]_ | Computes a hash for the fraction. |
 | [_IsProper_](./TFraction-IsProper.md) | Checks if the fraction is a proper fraction. |
 | [_IsWholeNumber_](./TFraction-IsWholeNumber.md) | Checks if the fraction represents a whole number. |
+| _[Power](./TFraction-Power.md) [~>0.2]_ | Computes an integer power of a fraction (overloaded with class method). |
 | [_Reciprocal_](./TFraction-Reciprocal.md) | Returns the reciprocal of the fraction. |
 | [_RoundToMultiple_](./TFraction-RoundToMultiple.md) | Rounds the fraction to the nearest whole number multiple of another fraction. |
 | [_Sign_](./TFraction-Sign.md) | Returns a value representing the sign of the fraction.  |
@@ -86,9 +93,9 @@ _TFraction_ defines several methods. Some are static class methods that operate
 
 | Method | Description |
 |:-------|:------------|
-| [_Abs_](./TFraction-Abs.md) | Returns the absolute value of a given fraction. |
+| [_Abs_](./TFraction-Abs.md) | Returns the absolute value of a given fraction ([~>0.2] overloaded with instance method). |
 | [_Compare_](./TFraction-Compare.md) | Compares two fractions and returns a value indicating which of the two is greater or if they equal. |
 | [_LCD_](./TFraction-LCD.md) | Computes the least common denominator of two fractions. |
 | [_Max_](./TFraction-Max.md) | Overloaded methods that find the largest of two or more fractions. |
 | [_Min_](./TFraction-Min.md) | Overloaded methods that find the smallest of two or more fractions. |
-| [_Power_](./TFraction-Power.md) | Computes an integer power of a fraction. |
+| [_Power_](./TFraction-Power.md) | Computes an integer power of a fraction ([~>0.2] overloaded with instance method). |

Fractions/0/Overview.md

@@ -14,7 +14,7 @@ Operator overloading is used extensively to enable normal arithmetic operations
 
 ## Compatibility
 
-This unit is designed for compilation with 32 bit and 64 bit Windows Delphi compilers. It is designed to compile with compilers from Delphi 2009 onwards.
+This unit is designed for compilation with 32 bit and 64 bit Windows Delphi compilers. It is designed to compile with compilers from Delphi XE onwards. It may compile with Delphi 2009 and Delphi 2010, but this is not tested and not guaranteed.
 
 The code uses only Delphi RTL libraries and so should be able to compile for any platform supported by Delphi.