Extension #

The library can easily be extended with functions and variables using the import function. The function import accepts an object with functions and variables.

Function import has the following syntax:

math.import(object: Object [, options: Object])

Where:

The following code example shows how to import a function and a value into math.js:

// define new functions and variables
math.import({
  myvalue: 42,
  hello: function (name) {
    return 'hello, ' + name + '!';
  }
});

// defined functions can be used in both JavaScript as well as the parser
math.myvalue * 2;               // 84
math.hello('user');             // 'hello, user!'

var parser = math.parser();
parser.eval('myvalue + 10');    // 52
parser.eval('hello("user")');   // 'hello, user!'

Import external libraries #

External libraries like numbers.js and numeric.js can be imported as follows. The libraries must be installed using npm:

$ npm install numbers
$ npm install numeric

The libraries can be easily imported into math.js using import. In order to convert math.js specific data types like Matrix to primitive types like Array, the imported functions can be wrapped by enabling {wrap: true}.

// import the numbers.js and numeric.js libraries into math.js
math.import(require('numbers'), {wrap: true, silent: true});
math.import(require('numeric'), {wrap: true, silent: true});

// use functions from numbers.js
math.fibonacci(7);                          // 13
math.eval('fibonacci(7)');                  // 13

// use functions from numeric.js
math.eval('eig([1, 2; 4, 3])').lambda.x;    // [5, -1]

Typed functions #

Typed functions can be created using math.typed. A typed function is a function which does type checking on the input arguments. It can have multiple signatures. And can automatically convert input types where needed.

A typed function can be created like:

var max = typed('max', {
  'number, number': function (a, b) {
    return Math.max(a, b);
  },

  'BigNumber, BigNumber': function (a, b) {
    return a.greaterThan(b) ? a : b;
  }
});

Typed functions can be merged as long as there are no conflicts in the signatures. This allows for extending existing functions in math.js with support for new data types.

// create a new data type
function MyType (value) {
  this.value = value;
}
MyType.prototype.isMyType = true;
MyType.prototype.toString = function () {
  return 'MyType:' + this.value;
}

// define a new datatype
math.typed.addType({
  name: 'MyType',
  test: function (x) {
    // test whether x is of type MyType
    return x && x.isMyType;
  }
})

// use the type in a new typed function
var add = typed('add', {
  'MyType, MyType': function (a, b) {
    return new MyType(a.value + b.value);
  }
});

// import in math.js, extend the existing function `add` with support for MyType
math.import({add: add});

// use the new type
var ans = math.add(new MyType(2), new MyType(3)); // returns MyType(5)
console.log(ans);                                 // outputs 'MyType:5'

Detailed information on typed functions is available here: https://github.com/josdejong/typed-function

Factory functions #

Regular JavaScript functions can be imported in math.js using math.import:

math.import({
  myFunction: function (a, b) {
     // ...
  }
});

The function can be stored in a separate file:

exports.myFunction = function (a, b) {
  // ...
}

Which can be imported like:

math.import(require('./myFunction.js'));

An issue arises when myFunction needs functionality from math.js: it doesn’t have access to the current instance of math.js when in a separate file. Factory functions can be used to solve this issue. A file exporting a factory function looks like:

exports.name = 'myFunction';
exports.factory = function (type, config, load, typed) {
  return myFunction (a, b) {
    // ...
  }
};

The file exports a name and a factory function. When running math.import, the factory function is invoked by math.js with four arguments:

The result returned by a factory function will be imported into the math namespace under the given name, math.myFunction in the above example.

A factory can contain the following properties:

To import a set of factory functions, the function math.import accepts an array containing factory functions:

math.import([
  require('./myFactoryFunction1.js'),
  require('./myFactoryFunction2.js'),
  require('./myFactoryFunction3.js'),
  // ...
]);
Fork me on GitHub