chore: Update to latest fraction.js (#2467)

Resolves #2427.

  Also adds tests verifying that creating a fraction from two numbers
  requires them both to be integers, and slightly updates documentation.

Co-authored-by: Jos de Jong <[email protected]>

Author: gwhitney

package-lock.json

@@ -29,7 +29,7 @@
     "complex.js": "^2.0.15",
     "decimal.js": "^10.3.1",
     "escape-latex": "^1.2.0",
-    "fraction.js": "^4.1.3",
+    "fraction.js": "^4.2.0",
     "javascript-natural-sort": "^0.7.1",
     "seedrandom": "^3.0.5",
     "tiny-emitter": "^2.1.0",

package.json

@@ -3,13 +3,17 @@ export const fractionDocs = {
   category: 'Construction',
   syntax: [
     'fraction(num)',
-    'fraction(num,den)'
+    'fraction(matrix)',
+    'fraction(num,den)',
+    'fraction({n: num, d: den})'
   ],
   description:
-    'Create a fraction from a number or from a numerator and denominator.',
+    'Create a fraction from a number or from integer numerator and denominator.',
   examples: [
     'fraction(0.125)',
-    'fraction(1, 3) + fraction(2, 5)'
+    'fraction(1, 3) + fraction(2, 5)',
+    'fraction({n: 333, d: 53})',
+    'fraction([sqrt(9), sqrt(10), sqrt(11)])'
   ],
   seealso: [
     'bignumber', 'boolean', 'complex', 'index', 'matrix', 'string', 'unit'

src/expression/embeddedDocs/construction/fraction.js

@@ -6,27 +6,39 @@ const dependencies = ['typed', 'Fraction']
 
 export const createFraction = /* #__PURE__ */ factory(name, dependencies, ({ typed, Fraction }) => {
   /**
-   * Create a fraction convert a value to a fraction.
+   * Create a fraction or convert a value to a fraction.
+   *
+   * With one numeric argument, produces the closest rational approximation to the
+   * input.
+   * With two arguments, the first is the numerator and the second is the denominator,
+   * and creates the corresponding fraction. Both numerator and denominator must be
+   * integers.
+   * With one object argument, looks for the integer numerator as the value of property
+   * 'n' and the integer denominator as the value of property 'd'.
+   * With a matrix argument, creates a matrix of the same shape with entries
+   * converted into fractions.
    *
    * Syntax:
+   *     math.fraction(value)
    *     math.fraction(numerator, denominator)
    *     math.fraction({n: numerator, d: denominator})
-   *     math.fraction(matrix: Array | Matrix)         Turn all matrix entries
-   *                                                   into fractions
+   *     math.fraction(matrix: Array | Matrix)
    *
    * Examples:
    *
-   *     math.fraction(1, 3)
-   *     math.fraction('2/3')
-   *     math.fraction({n: 2, d: 3})
-   *     math.fraction([0.2, 0.25, 1.25])
+   *     math.fraction(6.283)             // returns Fraction 6283/1000
+   *     math.fraction(1, 3)              // returns Fraction 1/3
+   *     math.fraction('2/3')             // returns Fraction 2/3
+   *     math.fraction({n: 2, d: 3})      // returns Fraction 2/3
+   *     math.fraction([0.2, 0.25, 1.25]) // returns Array [1/5, 1/4, 5/4]
+   *     math.fraction(4, 5.1)            // throws Error: Parameters must be integer
    *
    * See also:
    *
    *    bignumber, number, string, unit
    *
    * @param {number | string | Fraction | BigNumber | Array | Matrix} [args]
-   *            Arguments specifying the numerator and denominator of
+   *            Arguments specifying the value, or numerator and denominator of
    *            the fraction
    * @return {Fraction | Array | Matrix} Returns a fraction
    */

src/type/fraction/function/fraction.js

@@ -11,6 +11,17 @@ describe('fraction', function () {
     equalFraction(math.fraction(null), new Fraction(0))
   })
 
+  it('should fail to create a fraction in case of non-integer quotient', () => {
+    assert.throws(() => math.fraction(4, 5.1), /Parameters must be integer/)
+    assert.throws(() => math.fraction(62.8, 10), /Parameters must be integer/)
+    assert.throws(() => math.fraction(Infinity, 3), /Parameters must be integer/)
+  })
+
+  it('should create a fraction from a quotient regardless of integrality', () => {
+    equalFraction(math.divide(math.fraction(4), math.fraction(5.1)),
+      math.fraction(40, 51))
+  })
+
   it('should create a fraction from a BigNumber', function () {
     const b = math.bignumber(2).div(3)
     const f = math.fraction(b)