map-number

map-number

:warning: this map function has nothing to do with Array.prototype.map method.

Install

npm i map-number

CDN

jsDelivr

<script src="https://cdn.jsdelivr.net/npm/map-number@latest/dist/map.umd.js"></script>

for production

<script src="https://cdn.jsdelivr.net/npm/map-number@latest/dist/map.umd.min.js"></script>

for production you may want to replace the "latest" version for a specific one.

more options...

unpkg

<script src="https://unpkg.com/map-number@latest/dist/map.umd.js"></script>

for production

<script src="https://unpkg.com/map-number@latest/dist/map.umd.min.js"></script>

for production you may want to replace the "latest" version for a specific one.

more options...

Usage

Node.js

const { map } = require('map-number');
const result = map(Math.sin(angle), -1, 1, 100, 0);

using javascript modules...

import { map } from 'map-number';
const result = map(Math.sin(angle), -1, 1, 100, 0);

Browser

After the script tag has been added, mapNum will be available globally.

const result = mapNum.map(Math.sin(angle), -1, 1, 100, 0);

API

map

Maps a number within a given range to a different range, returning a floting point number. The result WILL NOT be limited (clamped) to the the given output range.

This is the core function and all other map function variants depend on it.

syntax

function map(num: number, inMin: number, inMax: number, outMin: number, outMax: number): number;

floor

Maps a number within a given range to a different range, returning a number rounded down to the previous integer number. The result WILL NOT be limited (clamped) to the the given output range.

syntax

function floor(num: number, inMin: number, inMax: number, outMin: number, outMax: number): number;

ceil

Maps a number within a given range to a different range, returning a number rounded up to the next integer number. The result WILL NOT be limited (clamped) to the the given output range.

syntax

function ceil(num: number, inMin: number, inMax: number, outMin: number, outMax: number): number;

round

Maps a number within a given range to a different range, returning a number rounded to the closest integer number. The result WILL NOT be limited (clamped) to the the given output range.

syntax

function round(num: number, inMin: number, inMax: number, outMin: number, outMax: number): number;

If you need to round to a specific number of decimal places, you can use the transform method and write your own round function.

limit

alias: clamp

Maps a number within a given range to a different range, returning a floting point number. The result will be limited (clamped) to the given output range.

syntax

function limit(num: number, inMin: number, inMax: number, outMin: number, outMax: number): number;

compile

alias: wrap, create

Creates a single argument function implementing the given map, floor, ceil, round, limit, clamp or user created function. Useful when you need to map values multiple times within the same range, see example below.

syntax

function compile<T>(func: MapFunction<T>, inMin: number, inMax: number, outMin: number, outMax: number): Compiled<T>;

type Compiled<T> = (num: number) => T;

example

import { map, round, compile } from "map-number";

const myMap = compile(map, -1, 1, 100, 0);

myMap(-0.2);
myMap(0.33);
myMap(0.5);

// ... is equivalent to...

map(-0.2, -1, 1, 100, 0);
map(0.33, -1, 1, 100, 0);
map(0.5, -1, 1, 100, 0);

transform

Creates a map function where the result of the given function is transformed to a different value. This method is used internally to create the floor, ceil and round methods.

syntax

function transform<T>(func: MapNumberFunction, transformer: (value: number) => T): MapFunction<T>;

example

import { transform, map } from "map-number";

const plusOne = transform(
  map,
  (value) => value + 1,
);

plusOne(0.4, 0, 1, 0, 100); // => 41

License

MIT © Manuel Fernández