map-number

processing/p5.js map like function, including floating point numbers support

⚠️ this map function has nothing to do with Array.prototype.map method.

In this guide

• Install
• CDN
• Usage
• API
  • function map
  • function floor
  • function ceil
  • function round
  • function limit
  • function compile
  • function transformed
• Types
  • type MapFunction
  • type CompiledMapFunction
  • type TransformFunction
  • type MapNumberFunction
  • type CompiledMapNumberFunction

Install

using npm

npm install map-number

using yarn

yarn add map-number

using pnpm

pnpm add map-number

CDN

jsDelivr

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

for production

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

for production

<script src="https://unpkg.com/map-number@latest/dist/umd/map.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

function map

Maps a number within a given range to a different range, returning a floating 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(
  input: number,
  inputMin: number,
  inputMax: number,
  outputMin: number,
  outputMax: number,
): number;

• example

map(4, 0, 10, 0, 100); // => returns 40

function 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(
  input: number,
  inputMin: number,
  inputMax: number,
  outputMin: number,
  outputMax: number,
): number;

function 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(
  input: number,
  inputMin: number,
  inputMax: number,
  outputMin: number,
  outputMax: number,
): number;

function 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(
  input: number,
  inputMin: number,
  inputMax: number,
  outputMin: number,
  outputMax: number,
): number;

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

function limit

alias: clamp

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

syntax

function limit(
  input: number,
  inputMin: number,
  inputMax: number,
  outputMin: number,
  outputMax: number,
): number;

function 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<O, I>(
  map: MapFunction<O, I>,
  inputMin: number,
  inputMax: number,
  outputMin: number,
  outputMax: number,
): CompiledMapFunction<O, I>;

See MapFunction and CompiledMapFunction.

example

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

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

myMap(-0.2);
myMap(0.33);
myMap(0.51);

// ... is equivalent to...

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

function transformed

alias: 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 transformed<O = number, M = number, I = number>(
  map: MapFunction<M, I>,
  transform: TransformFunction<M, O>,
): MapFunction<O, I>;

See MapFunction and TransformFunction.

example

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

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

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

Types

type MapFunction

type MapFunction<O = number, I = number> = (value: I, inMin: number, inMax: number, outMin: number, outMax: number) => O;

type CompiledMapFunction

type CompiledMapFunction<O = number, I = number> = (value: I) => O;

type TransformFunction

type TransformFunction<I = number, O = number> = (value: I) => O;

type MapNumberFunction

type MapNumberFunction = MapFunction<number, number>;

See MapFunction

type CompiledMapNumberFunction

type CompiledMapNumberFunction = CompiledMapFunction<number, number>;

See CompiledMapFunction

License

MIT © 2019-2024 Manuel Fernández