https://github.com/zeh/moremath
The missing JavaScript Math functions
https://github.com/zeh/moremath
clamps map math math-functions npm-module range typescript
Last synced: 4 months ago
JSON representation
The missing JavaScript Math functions
- Host: GitHub
- URL: https://github.com/zeh/moremath
- Owner: zeh
- License: mit
- Created: 2016-11-20T17:24:05.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-09-24T06:25:39.000Z (almost 2 years ago)
- Last Synced: 2024-10-04T14:17:09.983Z (over 1 year ago)
- Topics: clamps, map, math, math-functions, npm-module, range, typescript
- Language: JavaScript
- Size: 419 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# MoreMath
[](https://www.npmjs.com/package/moremath)
[](https://travis-ci.org/zeh/moremath)
[](https://coveralls.io/github/zeh/moremath?branch=master)
[](https://david-dm.org/zeh/moremath)
*MoreMath* is a library that provides useful Math functions -- functions that either should have been part of the core `Math` package from the start, or that are otherwise commonly needed.
## Install
```shell
npm install moremath
```
MoreMath is written in TypeScript. It can be used both in JavaScript and TypeScript, but in TypeScript projects you get the benefit of code completion by default.
## Usage
MoreMath can be used as a separate package (in which it acts like a *Static Class*) or by importing the specific functions one need.
Import the whole package:
```javascript
// Import everything (JavaScript ES5)
var MoreMath = require('moremath');
// Import everything (JavaScript ES6 and TypeScript)
import MoreMath from 'moremath';
```
Then use any of its functions:
```javascript
let value = MoreMath.clamp(11, 0, 10); // 10
```
Another way to use it is just importing the functions you want then using them directly.
Import a function:
```javascript
// Import clamp() (JavaScript ES5)
var clamp = require('moremath').clamp;
// Import clamp() (JavaScript ES6 and TypeScript)
import { clamp } from 'moremath';
```
Then use it:
```javascript
let value = clamp(11, 0, 10); // 10
```
The advantage of importing only specific functions is that the resulting code is shorter and easier to read, and JavaScript packagers that perform *tree-shaking* can get rid of functions that are not used from inside the MoreMath library. In the above case, for example, `clamp` would be the only exported function included in your final project.
## Full reference
### `map(value:number, oldMin:number, oldMax:number, newMin:number = 0, newMax:number = 1, shouldClamp:Boolean = false):number`
Maps a value from a range, determined by old minimum and maximum values, to a new range, determined by new minimum and maximum values. These minimum and maximum values are referential; the new value is not clamped by them.
Parameters:
* `value`: The value to be re-mapped.
* `oldMin`: The previous minimum value.
* `oldMax`: The previous maximum value.
* `newMin`: The new minimum value.
* `newMax`: The new maximum value.
Returns:
* The new value, mapped to the new range.
### `clamp(value:number, min:number = 0, max:number = 1):number`
Clamps a number to a range, by restricting it to a minimum and maximum values: if the passed value is lower than the minimum value, it's replaced by the minimum; if it's higher than the maximum value, it's replaced by the maximum; if neither, it's unchanged.
Parameters:
* `value`: The value to be clamped.
* `min`: Minimum value allowed.
* `max`: Maximum value allowed.
Returns:
* The newly clamped value.
### `clampAuto(value:number, clamp1:number = 0, clamp2:number = 1):number`
Clamps a number to a range, by restricting it to a range of values: if the passed value is lower than the minimum value, it's replaced by the minimum; if it's higher than the maximum value, it's replaced by the maximum; if neither, it's unchanged.
This function is similar to `clamp()`, but it switches the range values if necessary, without assuming the first value is the lower value.
Parameters:
* `value`: The value to be clamped.
* `clamp1`: One end of the allowed range.
* `clamp2`: Other end of the allowed range.
Returns:
* The newly clamped value.
### `getHighestPowerOfTwo(value:number):number`
Returns a power of two value that is higher than the passed value.
Parameters:
* `value`: The minimum value desired.
Returns:
* A power of two value that is equal to or higher than the input value.
### `getUniqueNumber():number`
Returns a unique number for this session. This is simply a global integer sequence, starting at 1.
Returns:
* A unique integer for the session.
### `isPowerOfTwo(value:number):Boolean`
Returns whether a number is a power of two (2, 4, 8, 16, etc).
Parameters:
* `value`: A number to be tested.
Returns:
* Whether the input number is a power of two.
### `rangeMod(value:number, min:number, pseudoMax:number):number`
Restricts a value to a range, by restricting it to a minimum and maximum values but folding the value to the range instead of simply clamping to the minimum and maximum. It works like a more powerful Modulo function because it allows arbitrary ranges.
Parameters:
* `value`: The value to be clamped.
* `min`: Minimum value allowed.
* `max`: Pseudo-maximum value allowed. This value is never reached; the minimum would be used instead.
Returns:
* The new value, mapped to the range.
Examples:
```javascript
console.log(rangeMod(14, 0, 10));
// Result: 4
console.log(rangeMod(360, 0, 360));
// Result: 0
console.log(rangeMod(360, -180, 180));
// Result: 0
console.log(rangeMod(21, 0, 10));
// Result: 1
console.log(rangeMod(-98, 0, 100));
// Result: 2
```
## License
[MIT](LICENSE.md).