Add FeetInches.ToArchitecturalString() (#1106)

Fixes #1075

* Add FeetInches.ToArchitecturalString and tests
* Fix broken link in readme

Author: lwestfall

README.md

@@ -424,7 +424,7 @@ Stargen is a decades old software to create realistic planets and satellites fro
 
 https://github.com/ebfortin/primoris.universe.stargen
 
-<img src="https://www.harringtonhoists.com/images/harrington_logo3.png" height="35">
+<img src="https://cdn.harringtonhoists.com/assets/harringtonhoists/logo-60629cc144429045d4c85740ab225e219add75b2c5c1e2c444ffa9500347a414.png" height="35">
 
 #### Harrington Hoists, Inc. (A Subsidiary of KITO Americas, Inc.)
 > Harrington Hoists, Inc. is located in Manheim, PA, Elizabethtown, PA, South Holland, IL and Corona, CA. Harrington is a leading manufacturer of manual, electric and air chain hoists as well as wire rope hoists and crane products serving the North American material handling industry.

UnitsNet.Tests/CustomCode/LengthTests.cs

@@ -233,5 +233,31 @@ public static void InverseReturnsReciprocalLength(double value, double expected)
 
             Assert.Equal(expected, inverseLength.InverseMeters);
         }
+
+        [Theory]
+        [InlineData(3, 2.563, 16, "3' - 2 9/16\"")]
+        [InlineData(3, 2.563, 32, "3' - 2 9/16\"")]
+        [InlineData(3, 2, 16, "3' - 2\"")]
+        [InlineData(3, 2.5, 1, "3' - 2\"")]
+        [InlineData(0, 2, 32, "2\"")]
+        [InlineData(3, 2.6, 1, "3' - 3\"")]
+        [InlineData(3, 2.6, 2, "3' - 2 1/2\"")]
+        [InlineData(3, 2.6, 4, "3' - 2 1/2\"")]
+        [InlineData(3, 2.6, 8, "3' - 2 5/8\"")]
+        [InlineData(3, 2.6, 16, "3' - 2 5/8\"")]
+        [InlineData(3, 2.6, 32, "3' - 2 19/32\"")]
+        [InlineData(3, 2.6, 128, "3' - 2 77/128\"")]
+        public static void ToArchitecturalString_ReturnsFormatted(double ft, double inch, int fractionDenominator, string expected)
+        {
+            var length = Length.FromFeetInches(ft, inch);
+
+            Assert.Equal(expected, length.FeetInches.ToArchitecturalString(fractionDenominator));
+        }
+
+        [Fact]
+        public static void ToArchitecturalString_DenomLessThan1_ThrowsArgumentOutOfRangeException()
+        {
+            Assert.Throws<ArgumentOutOfRangeException>(() => Length.FromFeetInches(1, 2).FeetInches.ToArchitecturalString(0));
+        }
     }
 }

UnitsNet/CustomCode/Quantities/Length.extra.cs

@@ -236,5 +236,82 @@ public string ToString(IFormatProvider? cultureInfo)
             // So inches are rounded when converting from base units to feet/inches.
             return string.Format(cultureInfo, "{0:n0} {1} {2:n0} {3}", Feet, footUnit, Math.Round(Inches), inchUnit);
         }
+
+        /// <summary>
+        ///     Outputs feet and inches on the format: {feetValue}' - {inchesValueIntegral}[ / {inchesValueFractional}]"
+        ///     The inches are rounded to the nearest fraction of the fractionDenominator argument and reduced over the greatest common divisor.
+        ///     The fractional inch value is omitted if the numerator is 0 after rounding, or if the provided denominator is 1.
+        /// </summary>
+        /// <param name="fractionDenominator">The maximum precision to express the rounded inch fraction part. Use 1 to round to nearest integer, with no fraction.</param>
+        /// <example>
+        /// <code>
+        /// var length = Length.FromFeetInches(3, 2.6);
+        /// length.ToArchitecturalString(1)   => 3' - 3"
+        /// length.ToArchitecturalString(2)   => 3' - 2 1/2"
+        /// length.ToArchitecturalString(4)   => 3' - 2 1/2"
+        /// length.ToArchitecturalString(8)   => 3' - 2 5/8"
+        /// length.ToArchitecturalString(16)  => 3' - 2 5/8"
+        /// length.ToArchitecturalString(32)  => 3' - 2 19/32"
+        /// length.ToArchitecturalString(128) => 3' - 2 77/128"
+        /// </code>
+        /// </example>
+        /// <exception cref="ArgumentOutOfRangeException">Denominator for fractional inch must be greater than zero.</exception>
+        public string ToArchitecturalString(int fractionDenominator)
+        {
+            if (fractionDenominator < 1)
+            {
+                throw new ArgumentOutOfRangeException(nameof(fractionDenominator), "Denominator for fractional inch must be greater than zero.");
+            }
+
+            var inchTrunc = (int)Math.Truncate(this.Inches);
+            var numerator = (int)Math.Round((this.Inches - inchTrunc) * fractionDenominator);
+
+            if (numerator == fractionDenominator)
+            {
+                inchTrunc++;
+                numerator = 0;
+            }
+
+            var inchPart = new System.Text.StringBuilder();
+
+            if (inchTrunc != 0 || numerator == 0)
+            {
+                inchPart.Append(inchTrunc);
+            }
+
+            if (numerator > 0)
+            {
+                int greatestCommonDivisor(int a, int b)
+                {
+                    while (a != 0 && b != 0)
+                    {
+                        if (a > b)
+                            a %= b;
+                        else
+                            b %= a;
+                    }
+
+                    return a | b;
+                }
+
+                int gcd = greatestCommonDivisor((int)Math.Abs(numerator), fractionDenominator);
+
+                if (inchPart.Length > 0)
+                {
+                    inchPart.Append(' ');
+                }
+
+                inchPart.Append($"{numerator / gcd}/{fractionDenominator / gcd}");
+            }
+
+            inchPart.Append('"');
+
+            if (this.Feet == 0)
+            {
+                return inchPart.ToString();
+            }
+
+            return $"{this.Feet}' - {inchPart}";
+        }
     }
 }