npm package: @ishoa/math-helpers
Description: Some useful Math functions not built into the Javascript Math Object. Mainly useful for Web Games.
Author: Shane Coates
Latest version: 1.1.1

# Math-Helper-Functions

Some useful Math functions not built into the Javascript Math Object. Mainly useful for Web Games.

## Functions

<dl>
<dt><a href="#map">map(x, istart, istop, ostart, ostop)</a> ⇒ <code>Number</code></dt>
<dd>
    <p>Map a value from a range of numbers to another range of numbers.</p>
    <p>x is the intial value between istart and istop and return the value between ostart and ostop</p>
</dd>
<dt><a href="#limit">limit(x, min, max)</a> ⇒ <code>Number</code></dt>
<dd><p>Limit a value between a min/max value</p>
</dd>
<dt><a href="#toRad">toRad(x)</a> ⇒ <code>Number</code></dt>
<dd><p>Convert the angle, provided in degrees (0-360), into radians (0-2*PI)</p>
</dd>
<dt><a href="#toDeg">toDeg(x)</a> ⇒ <code>Number</code></dt>
<dd><p>Convert the angle, provided in radians (0-2*PI), into degrees (0-360)</p>
</dd>
<dt><a href="#range">range(min, max)</a> ⇒ <code>Number</code></dt>
<dd><p>Get random Float value between range of numbers</p>
</dd>
<dt><a href="#distance">distance(a, b)</a> ⇒ <code>Number</code></dt>
<dd><p>Distance between two points</p>
</dd>
<dt><a href="#lerp">lerp(current, target, time)</a> ⇒ <code>Number</code></dt>
<dd><p>Lerp between current position to target position over a period of time</p>
</dd>
<dt><a href="#average">average(a, b)</a> ⇒ <code>Number</code></dt>
<dd><p>Returns the average or the midpoint between two numbers</p>
</dd>
<dt><a href="#midpoint">midpoint(v1, v2)</a> ⇒ <code>Object</code></dt>
<dd><p>Get the midpoint between two points</p>
</dd>
<dt><a href="#chance">chance(percent)</a></dt>
<dd><p>Return a true or false for a random chance of a percentage</p>
</dd>
</dl>

<a name="map"></a>

## map(x, istart, istop, ostart, ostop) ⇒ <code>Number</code>
---
Map a value from a range of numbers to another range of numbers
x is to istart and istop segment.
 
**Returns**: <code>Number</code> - The number that is in the same relation to ostart and ostop segment  

| Param | Type | Description |
| --- | --- | --- |
| x | <code>Number</code> | Value we are testing |
| istart | <code>Number</code> | Min value to test |
| istop | <code>Number</code> | Max value to test |
| ostart | <code>Number</code> | Min value to map to (based on x value) |
| ostop | <code>Number</code> | Max value to map to (based on x value) |

**Example**  
```js
map(Math.random(), 0, 1, 10, 20); will provided a number between 10 and 20
```

<a name="limit"></a>

## limit(x, min, max) ⇒ <code>Number</code>
---
Limit a value between a min/max value
 
**Returns**: <code>Number</code> - Either x, or the nearest limit if x is out of bounds.  

| Param | Type | Description |
| --- | --- | --- |
| x | <code>Number</code> | Value we need to limit |
| min | <code>Number</code> | Min number to return |
| max | <code>Number</code> | Max number to return |

<a name="toRad"></a>

## toRad(x) ⇒ <code>Number</code>
---
Convert the angle, provided in degrees (0-360), into radians (0-2*PI)
 
**Returns**: <code>Number</code> - Angle in Radians  

| Param | Type | Description |
| --- | --- | --- |
| x | <code>Number</code> | Angle in Degrees |

<a name="toDeg"></a>

## toDeg(x) ⇒ <code>Number</code>
---
Convert the angle, provided in radians (0-2*PI), into degrees (0-360)
 
**Returns**: <code>Number</code> - Angle in Degrees  

| Param | Type | Description |
| --- | --- | --- |
| x | <code>Number</code> | Angle in Radians |

<a name="range"></a>

## range(min, max) ⇒ <code>Number</code>
---
Get random Float value between range of numbers
 
**Returns**: <code>Number</code> - Return random Float value between min and max range  

| Param | Type | Description |
| --- | --- | --- |
| min | <code>Number</code> | Min range value |
| max | <code>Number</code> | Max range value |

<a name="distance"></a>

## distance(a, b) ⇒ <code>Number</code>
---
Distance between two points
 
**Returns**: <code>Number</code> - Distance between points  

| Param | Type | Description |
| --- | --- | --- |
| a | <code>Object</code> | first point {x: 0, y: 0} |
| b | <code>Object</code> | second point {x: 0, y: 0} |

**Example**  
```js
- can supply 2D or 3D point {x: 0, y: 0, z: 0}
```

<a name="lerp"></a>

## lerp(current, target, time) ⇒ <code>Number</code>
---
Lerp between current position to target position over a period of time
 
**Returns**: <code>Number</code> - Value between current/target over the time  

| Param | Type | Description |
| --- | --- | --- |
| current | <code>Number</code> | Current position value |
| target | <code>Number</code> | Target position value |
| time | <code>Number</code> | Time value |

<a name="average"></a>

## average(a, b) ⇒ <code>Number</code>
---
Returns the average or the midpoint between two numbers
 
**Returns**: <code>Number</code> - - the midpoint between two numbers  

| Param | Type | Description |
| --- | --- | --- |
| a | <code>Number</code> | first number |
| b | <code>Number</code> | second number |

<a name="midpoint"></a>

## midpoint(v1, v2) ⇒ <code>Object</code>
---
Get the midpoint between two points
 
**Returns**: <code>Object</code> - - {x: x, y: y, z: z}  

| Param | Type | Description |
| --- | --- | --- |
| v1 | <code>Object</code> | {x: 0, y: 0} |
| v2 | <code>Object</code> | {x: 0, y: 0} |

**Example**  
```js
- Also accepts 3D point {x: 0, y: 0, z: 0}
```
<a name="chance"></a>

## chance(percent)
---
Return a true or false for a random chance of a percentage

| Param | Type | Description |
| --- | --- | --- |
| percent | <code>Number</code> | float percentage 0 -> 1 |

**Example**  
```js
if(chance(0.2)){ console.log('20% chance true') }
```