README.md

linear-converter

Flexible linear converter

Table of contents

• Installation
• Basic usage
• Conversion inversion
• Conversions composition
• Custom conversions
• Coefficients
• Conversion equivalence
• Arbitrary precision
• Currying
• See more
• Related projects

Installation

npm

npm i linear-converter

Bower

bower install linear-converter

To use it in the browser, include the following on your site:

<script src="bower_components/linear-converter/dist/linear-converter.min.js"></script>

Basic usage

linear-converter uses the arbitrary-precision package to support arbitrary precision. See all available adapters.

var Decimal = require('arbitrary-precision')(require('floating-adapter'));
var lc = require('linear-converter')(Decimal);

// 0°C and 100°C are 32°F and 212°F
var celsiusToFahrenheit = [[0, 100], [32, 212]];

lc.convert(celsiusToFahrenheit, 25); // => new Decimal('77')

// also accepts Decimals
lc.convert(celsiusToFahrenheit, new Decimal('25'));

Ready-to-use conversions can be found in the linear-presets package.

For a quick interactive intro, see CodePen example.

Variants:

• linear-converter-to-go: opinionated, zero-configuration version with floating point precision and built-in conversion presets.
• linear-conversion: if you prefer the object-oriented paradigm.
• linear-converter-cli: for CLI use.

Conversion inversion

var fahrenheitToCelsius = lc.invertConversion(celsiusToFahrenheit);

lc.convert(fahrenheitToCelsius, 77); // => 25 (as decimal)

Conversions composition

var kelvinToCelsius = [[273.15, 373.15], [0, 100]];
var kelvinToFahrenheit = lc.composeConversions(kelvinToCelsius, celsiusToFahrenheit);

lc.convert(kelvinToFahrenheit, 293.15); // => 68 (as decimal)

Custom conversions

Custom conversions are achieved by passing an array with 2 scales, each of those an array with 2 values. For example, [[0, 1], [0, 2]] means that 0 and 1 in the first scale map to 0 and 2 in the second scale respectively; in short, it multiplies by 2. Any linear conversion can be described that way:

// f(x) = ax + b
lc.convert([[0, 1], [b, a+b]], x); // => ax + b (as Decimal)
lc.convert([[1/a, -b/a], [b+1, 0]], x); // => ax + b (as Decimal)

For an arbitrary f(x) = ax + b, any [[x₁, x₂], [f(x₁), f(x₂)]] is a valid conversion.

More examples:

// degrees to radians
lc.convert([[0, 180], [0, Math.PI]], 240); // => 4 * Math.PI / 3 (as Decimal)

// f(x) = 3x
lc.convert([[0, 1/3], [0, 1]], 5); // => 15 (as Decimal)

// f(x) = -2x - 46
lc.convert([[0, 1], [-46, -48]], -23); // => 0 (as Decimal)

Coefficients

// f(x) = 2x + 1
lc.getCoefficientA([[0, 1], [1, 3]]); // => 2 (as Decimal)
lc.getCoefficientB([[0, 1], [1, 3]]); // => 1 (as Decimal)

// f(x) = ax + b
lc.getCoefficientA([[x1, x2], [f(x1), f(x2)]]); // => a (as Decimal)
lc.getCoefficientB([[x1, x2], [f(x1), f(x2)]]); // => b (as Decimal)

Conversion equivalence

// f(x) = -3x + 6
lc.equivalentConversions(
  [[1, 5], [3, -9]],
  [[-1, 100], [9, -294]]
); // => true

lc.equivalentConversions(
  [[0, 1], [0, 2]], // f(x) = 2x
  [[0, 1], [0, 3]]  // f(x) = 3x
); // => false

Arbitrary precision

Arbitrary precision support is provided via the arbitrary-precision package. See all available adapters.

// without arbitrary precision (very lightweight)
var Decimal = require('arbitrary-precision')(require('floating-adapter'));
var lc = require('linear-converter')(Decimal);

lc.getCoefficientA([[0, 0.1], [0.1, 0.3]]); // => 1.9999999999999998 (as Decimal)

// with arbitrary precision
var Decimal = require('arbitrary-precision')(require('bigjs-adapter'));
var lc = require('linear-converter')(Decimal);

lc.getCoefficientA([[0, 0.1], [0.1, 0.3]]); // => 2 (as Decimal)

See CodePen example.

Currying

var convert = require('lodash.curry')(lc.convert);

convert(celsiusToFahrenheit, 25); // => 77 (as Decimal)

var cToF = convert(celsiusToFahrenheit);

cToF(25); // => 77 (as Decimal)

See CodePen example.

See more

• spec
• all conversion presets

Related projects

• linear-conversion: linear conversion class for linear-converter.
• linear-converter-cli: CLI for linear-converter.
• rescale: rescales a point given two scales.
• scale: scales normalised data.
• normalise: normalise data to [0, 1].
• rescale-util: rescale utilities.