Add trigonometry functionality

docs/functions.md

@@ -96,6 +96,22 @@ clamp(35, 10, [20, 30, 40, 50]) // returns [20, 30, 35, 35]
 clamp([1, 9], 3, [4, 5]) // returns [clamp([1, 3, 4]), clamp([9, 3, 5])] = [3, 5]
 ```
 ***
+## _cos(_ _a_ _)_
+Calculates the the cosine of a number. For arrays, the function will be applied index-wise to each element.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| a | <code>number</code> \| <code>Array.&lt;number&gt;</code> | a number or an array of numbers, `a` is expected to be given in radians. |
+
+**Returns**: <code>number</code> \| <code>Array.&lt;number&gt;</code> - The cosine of `a`. Returns an array with the the cosine of each element if `a` is an array.  
+**Example**  
+```js
+cos(0) // returns 1
+cos(1.5707963267948966) // returns 6.123233995736766e-17
+cos([0, 1.5707963267948966]) // returns [1, 6.123233995736766e-17]
+```
+***
 ## _count(_ _a_ _)_
 Returns the length of an array. Alias for size
 
@@ -131,6 +147,22 @@ cube(-3) // returns -27
 cube([3, 4, 5]) // returns [27, 64, 125]
 ```
 ***
+## _degtorad(_ _a_ _)_
+Converts degrees to radians for a number. For arrays, the function will be applied index-wise to each element.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| a | <code>number</code> \| <code>Array.&lt;number&gt;</code> | a number or an array of numbers, `a` is expected to be given in degrees. |
+
+**Returns**: <code>number</code> \| <code>Array.&lt;number&gt;</code> - The radians of `a`. Returns an array with the the radians of each element if `a` is an array.  
+**Example**  
+```js
+degtorad(0) // returns 0
+degtorad(90) // returns 1.5707963267948966
+degtorad([0, 90, 180, 360]) // returns [0, 1.5707963267948966, 3.141592653589793, 6.283185307179586]
+```
+***
 ## _divide(_ _a_,  _b_ _)_
 Divides two numbers. If at least one array of numbers is passed into the function, the function will be applied index-wise to each element.
 
@@ -410,6 +442,15 @@ multiply(10, [1, 2, 5, 10]) // returns [10, 20, 50, 100]
 multiply([1, 2, 3, 4], [2, 7, 5, 12]) // returns [2, 14, 15, 48]
 ```
 ***
+## _pi(__)_
+Returns the mathematical constant PI
+
+**Returns**: <code>number</code> - The mathematical constant PI  
+**Example**  
+```js
+pi() // 3.141592653589793
+```
+***
 ## _pow(_ _a_,  _b_ _)_
 Calculates the cube root of a number. For arrays, the function will be applied index-wise to each element.
 
@@ -430,6 +471,22 @@ pow(2,3) // returns 8
 pow([1, 2, 3], 4) // returns [1, 16, 81]
 ```
 ***
+## _radtodeg(_ _a_ _)_
+Converts radians to degrees for a number. For arrays, the function will be applied index-wise to each element.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| a | <code>number</code> \| <code>Array.&lt;number&gt;</code> | a number or an array of numbers, `a` is expected to be given in radians. |
+
+**Returns**: <code>number</code> \| <code>Array.&lt;number&gt;</code> - The degrees of `a`. Returns an array with the the degrees of each element if `a` is an array.  
+**Example**  
+```js
+radtodeg(0) // returns 0
+radtodeg(1.5707963267948966) // returns 90
+radtodeg([0, 1.5707963267948966, 3.141592653589793, 6.283185307179586]) // returns [0, 90, 180, 360]
+```
+***
 ## _random(_ _a_,  _b_ _)_
 Generates a random number within the given range where the lower bound is inclusive and the upper bound is exclusive. If no numbers are passed in, it will return a number between 0 and 1. If only one number is passed in, it will return .
 
@@ -486,6 +543,22 @@ round(10.93745987, 4) // returns 10.9375
 round([2.9234, 5.1234, 3.5234, 4.49234324], 2) // returns [2.92, 5.12, 3.52, 4.49]
 ```
 ***
+## _sin(_ _a_ _)_
+Calculates the the sine of a number. For arrays, the function will be applied index-wise to each element.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| a | <code>number</code> \| <code>Array.&lt;number&gt;</code> | a number or an array of numbers, `a` is expected to be given in radians. |
+
+**Returns**: <code>number</code> \| <code>Array.&lt;number&gt;</code> - The sine of `a`. Returns an array with the the sine of each element if `a` is an array.  
+**Example**  
+```js
+sin(0) // returns 0
+sin(1.5707963267948966) // returns 1
+sin([0, 1.5707963267948966]) // returns [0, 1]
+```
+***
 ## _size(_ _a_ _)_
 Returns the length of an array. Alias for count
 
@@ -580,6 +653,22 @@ sum([1, 2], 3, [4, 5], 6) // returns sum(1, 2, 3, 4, 5, 6) = 21
 sum([10, 20, 30, 40], 10, [1, 2, 3], 22) // returns sum(10, 20, 30, 40, 10, 1, 2, 3, 22) = 138
 ```
 ***
+## _tan(_ _a_ _)_
+Calculates the the tangent of a number. For arrays, the function will be applied index-wise to each element.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| a | <code>number</code> \| <code>Array.&lt;number&gt;</code> | a number or an array of numbers, `a` is expected to be given in radians. |
+
+**Returns**: <code>number</code> \| <code>Array.&lt;number&gt;</code> - The tangent of `a`. Returns an array with the the tangent of each element if `a` is an array.  
+**Example**  
+```js
+tan(0) // returns 0
+tan(1) // returns 1.5574077246549023
+tan([0, 1, -1]) // returns [0, 1.5574077246549023, -1.5574077246549023]
+```
+***
 ## _unique(_ _a_ _)_
 Counts the number of unique values in an array
 

src/functions/cos.js

@@ -0,0 +1,16 @@
+/**
+ * Calculates the the cosine of a number. For arrays, the function will be applied index-wise to each element.
+ * @param {(number|number[])} a a number or an array of numbers, `a` is expected to be given in radians.
+ * @return {(number|number[])} The cosine of `a`. Returns an array with the the cosine of each element if `a` is an array.
+ * @example
+ * cos(0) // returns 1
+ * cos(1.5707963267948966) // returns 6.123233995736766e-17
+ * cos([0, 1.5707963267948966]) // returns [1, 6.123233995736766e-17]
+ */
+
+export function cos(a) {
+  if (Array.isArray(a)) {
+    return a.map(a => Math.cos(a));
+  }
+  return Math.cos(a);
+}

src/functions/degtorad.js

@@ -0,0 +1,16 @@
+/**
+ * Converts degrees to radians for a number. For arrays, the function will be applied index-wise to each element.
+ * @param {(number|number[])} a a number or an array of numbers, `a` is expected to be given in degrees.
+ * @return {(number|number[])} The radians of `a`. Returns an array with the the radians of each element if `a` is an array.
+ * @example
+ * degtorad(0) // returns 0
+ * degtorad(90) // returns 1.5707963267948966
+ * degtorad([0, 90, 180, 360]) // returns [0, 1.5707963267948966, 3.141592653589793, 6.283185307179586]
+ */
+
+export function degtorad(a) {
+  if (Array.isArray(a)) {
+    return a.map(a => a * Math.PI / 180);
+  }
+  return a * Math.PI / 180;
+}

src/functions/index.js

@@ -3,8 +3,10 @@ import { add } from './add';
 import { cbrt } from './cbrt';
 import { ceil } from './ceil';
 import { clamp } from './clamp';
+import { cos } from './cos';
 import { count } from './count';
 import { cube } from './cube';
+import { degtorad } from './degtorad';
 import { divide } from './divide';
 import { exp } from './exp';
 import { first } from './first';
@@ -20,15 +22,19 @@ import { min } from './min';
 import { mod } from './mod';
 import { mode } from './mode';
 import { multiply } from './multiply';
+import { pi } from './pi';
 import { pow } from './pow';
+import { radtodeg } from './radtodeg';
 import { random } from './random';
 import { range } from './range';
 import { round } from './round';
+import { sin } from './sin';
 import { size } from './size';
 import { sqrt } from './sqrt';
 import { square } from './square';
 import { subtract } from './subtract';
 import { sum } from './sum';
+import { tan } from './tan';
 import { unique } from './unique';
 
 export const functions = {
@@ -37,8 +43,10 @@ export const functions = {
   cbrt,
   ceil,
   clamp,
+  cos,
   count,
   cube,
+  degtorad,
   divide,
   exp,
   first,
@@ -54,14 +62,18 @@ export const functions = {
   mod,
   mode,
   multiply,
+  pi,
   pow,
+  radtodeg,
   random,
   range,
   round,
+  sin,
   size,
   sqrt,
   square,
   subtract,
   sum,
+  tan,
   unique,
 };

src/functions/pi.js

@@ -0,0 +1,11 @@
+/**
+ * Returns the mathematical constant PI
+ * @return {(number)} The mathematical constant PI
+ *
+ * @example
+ * pi() // 3.141592653589793
+ */
+
+export function pi() {
+  return Math.PI;
+}

src/functions/radtodeg.js

@@ -0,0 +1,16 @@
+/**
+ * Converts radians to degrees for a number. For arrays, the function will be applied index-wise to each element.
+ * @param {(number|number[])} a a number or an array of numbers, `a` is expected to be given in radians.
+ * @return {(number|number[])} The degrees of `a`. Returns an array with the the degrees of each element if `a` is an array.
+ * @example
+ * radtodeg(0) // returns 0
+ * radtodeg(1.5707963267948966) // returns 90
+ * radtodeg([0, 1.5707963267948966, 3.141592653589793, 6.283185307179586]) // returns [0, 90, 180, 360]
+ */
+
+export function radtodeg(a) {
+  if (Array.isArray(a)) {
+    return a.map(a => a * 180 / Math.PI);
+  }
+  return a * 180 / Math.PI;
+}

src/functions/sin.js

@@ -0,0 +1,16 @@
+/**
+ * Calculates the the sine of a number. For arrays, the function will be applied index-wise to each element.
+ * @param {(number|number[])} a a number or an array of numbers, `a` is expected to be given in radians.
+ * @return {(number|number[])} The sine of `a`. Returns an array with the the sine of each element if `a` is an array.
+ * @example
+ * sin(0) // returns 0
+ * sin(1.5707963267948966) // returns 1
+ * sin([0, 1.5707963267948966]) // returns [0, 1]
+ */
+
+export function sin(a) {
+  if (Array.isArray(a)) {
+    return a.map(a => Math.sin(a));
+  }
+  return Math.sin(a);
+}

src/functions/tan.js

@@ -0,0 +1,16 @@
+/**
+ * Calculates the the tangent of a number. For arrays, the function will be applied index-wise to each element.
+ * @param {(number|number[])} a a number or an array of numbers, `a` is expected to be given in radians.
+ * @return {(number|number[])} The tangent of `a`. Returns an array with the the tangent of each element if `a` is an array.
+ * @example
+ * tan(0) // returns 0
+ * tan(1) // returns 1.5574077246549023
+ * tan([0, 1, -1]) // returns [0, 1.5574077246549023, -1.5574077246549023]
+ */
+
+export function tan(a) {
+  if (Array.isArray(a)) {
+    return a.map(a => Math.tan(a));
+  }
+  return Math.tan(a);
+}

test/functions/cos.spec.js

@@ -0,0 +1,13 @@
+import { expect } from 'chai';
+import { cos } from '../../src/functions/cos.js';
+
+describe('Cosine', () => {
+  it('numbers', () => {
+    expect(cos(0)).to.be.equal(1);
+    expect(cos(1.5707963267948966)).to.be.equal(6.123233995736766e-17);
+  });
+
+  it('arrays', () => {
+    expect(cos([0, 1.5707963267948966])).to.be.eql([1, 6.123233995736766e-17]);
+  });
+});

test/functions/degtorad.spec.js

@@ -0,0 +1,18 @@
+import { expect } from 'chai';
+import { degtorad } from '../../src/functions/degtorad.js';
+
+describe('Degrees to Radians', () => {
+  it('numbers', () => {
+    expect(degtorad(0)).to.be.equal(0);
+    expect(degtorad(90)).to.be.equal(1.5707963267948966);
+  });
+
+  it('arrays', () => {
+    expect(degtorad([0, 90, 180, 360])).to.be.eql([
+      0,
+      1.5707963267948966,
+      3.141592653589793,
+      6.283185307179586,
+    ]);
+  });
+});

test/functions/pi.spec.js

@@ -0,0 +1,8 @@
+import { expect } from 'chai';
+import { pi } from '../../src/functions/pi.js';
+
+describe('PI', () => {
+  it('constant', () => {
+    expect(pi()).to.be.equal(Math.PI);
+  });
+});

test/functions/radtodeg.spec.js

@@ -0,0 +1,18 @@
+import { expect } from 'chai';
+import { radtodeg } from '../../src/functions/radtodeg.js';
+
+describe('Radians to Degrees', () => {
+  it('numbers', () => {
+    expect(radtodeg(0)).to.be.equal(0);
+    expect(radtodeg(1.5707963267948966)).to.be.equal(90);
+  });
+
+  it('arrays', () => {
+    expect(radtodeg([0, 1.5707963267948966, 3.141592653589793, 6.283185307179586])).to.be.eql([
+      0,
+      90,
+      180,
+      360,
+    ]);
+  });
+});

test/functions/sin.spec.js

@@ -0,0 +1,13 @@
+import { expect } from 'chai';
+import { sin } from '../../src/functions/sin.js';
+
+describe('Sine', () => {
+  it('numbers', () => {
+    expect(sin(0)).to.be.equal(0);
+    expect(sin(1.5707963267948966)).to.be.equal(1);
+  });
+
+  it('arrays', () => {
+    expect(sin([0, 1.5707963267948966])).to.be.eql([0, 1]);
+  });
+});

test/functions/tan.spec.js

@@ -0,0 +1,13 @@
+import { expect } from 'chai';
+import { tan } from '../../src/functions/tan.js';
+
+describe('Tangent', () => {
+  it('numbers', () => {
+    expect(tan(0)).to.be.equal(0);
+    expect(tan(1)).to.be.equal(1.5574077246549023);
+  });
+
+  it('arrays', () => {
+    expect(tan([0, 1])).to.be.eql([0, 1.5574077246549023]);
+  });
+});

test/library.spec.js

@@ -165,6 +165,16 @@ describe('Evaluate', () => {
     expect(evaluate('3 + multiply(10, 4, 5)')).to.be.equal(203);
   });
 
+  it('equations with trigonometry', () => {
+    expect(evaluate('pi()')).to.be.equal(Math.PI);
+    expect(evaluate('sin(degtorad(0))')).to.be.equal(0);
+    expect(evaluate('sin(degtorad(180))')).to.be.equal(1.2246467991473532e-16);
+    expect(evaluate('cos(degtorad(0))')).to.be.equal(1);
+    expect(evaluate('cos(degtorad(180))')).to.be.equal(-1);
+    expect(evaluate('tan(degtorad(0))')).to.be.equal(0);
+    expect(evaluate('tan(degtorad(180))')).to.be.equal(-1.2246467991473532e-16);
+  });
+
   it('equations with variables', () => {
     expect(evaluate('3 + foo', { foo: 5 })).to.be.equal(8);
     expect(evaluate('3 + foo', { foo: [5, 10] })).to.be.eql([8, 13]);