path: root/libs/windfield/mlib/README.md

MLib
====

__MLib__ is a math and shape-intersection detection library written in Lua. It's aim is to be __robust__ and __easy to use__.

__NOTE:__ 
- I am (slowly) working on completely rewriting this in order to be easier to use and less bug-prone. You can check out the progress [here](../../tree/dev).
- I am currently slowing development of MLib while moving over to helping with [CPML](https://github.com/excessive/cpml). To discuss this, please comment [here](../../issues/12).

If you are looking for a library that handles updating/collision responses for you, take a look at [hxdx](https://github.com/adonaac/hxdx). It uses MLib functions as well as Box2d to handle physics calculations. 

## Downloading
You can download the latest __stable__ version of MLib by downloading the latest [release](../../releases/).
You can download the latest __working__ version of MLib by downloading the latest [commit](../../commits/master/). Documentation will __only__ be updated upon releases, not upon commits.

## Implementing
To use MLib, simply place [mlib.lua](mlib.lua) inside the desired folder in your project. Then use the `require 'path.to.mlib'` to use any of the functions.

## Examples
If you don't have [LÖVE](https://love2d.org/) installed, you can download the .zip of the demo from the [Executables](Examples/Executables) folder and extract and run the .exe that way.
You can see some examples of the code in action [here](Examples).
All examples are done using the *awesome* engine of [LÖVE](https://love2d.org/).
To run them properly, download the [.love file](Examples/LOVE) and install LÖVE to your computer.
After that, make sure you set .love files to open with "love.exe".
For more, see [here](https://love2d.org/).

## When should I use MLib?
- If you need to know exactly where two objects intersect.
- If you need general mathematical equations to be done.
- If you need very precise details about point intersections.

## When should I __not__ use MLib?
- All of the objects in a platformer, or other game, for instance, should not be registered with MLib. Only ones that need very specific information.
- When you don't need precise information/odd shapes.

## Specs
#### For Windows
If you run Windows and have Telescope in `%USERPROFILE%\Documents\GitHub` (you can also manually change the path in [test.bat](test.bat)) you can simply run [test.bat](test.bat) and it will display the results, and then clean up after it's finished.

#### Default
Alternatively, you can find the tests [here](spec.lua). Keep in mind that you may need to change certain semantics to suit your OS.
You can run them via [Telescope](https://github.com/norman/telescope/) and type the following command in the command-line of the root folder:
```
tsc -f specs.lua
```
If that does not work, you made need to put a link to Lua inside of the folder for `telescope` and run the following command:
```
lua tsc -f specs.lua
```
If you encounter further errors, try to run the command line as an administrator (usually located in `C:\Windows\System32\`), then right-click on `cmd.exe` and select `Run as administrator`, then do
```
cd C:\Path\to\telescope\
```
And __then__ run one of the above commands. If none of those work, just take my word for it that all the tests pass and look at this picture.
![Success](Reference Pictures/Success.png)

## Functions
- [mlib.line](#mlibline)
  - [mlib.line.checkPoint](#mliblinecheckpoint)
  - [mlib.line.getClosestPoint](#mliblinegetclosestpoint)
  - [mlib.line.getYIntercept](#mliblinegetintercept)
  - [mlib.line.getIntersection](#mliblinegetintersection)
  - [mlib.line.getLength](#mliblinegetlength)
  - [mlib.line.getMidpoint](#mliblinegetmidpoint)
  - [mlib.line.getPerpendicularSlope](#mliblinegetperpendicularslope)
  - [mlib.line.getSegmentIntersection](#mliblinegetsegmentintersection)
  - [mlib.line.getSlope](#mliblinegetslope)
- [mlib.segment](#mlibsegment)
  - [mlib.segment.checkPoint](#mlibsegmentcheckpoint)
  - [mlib.segment.getPerpendicularBisector](#mlibsegmentgetperpendicularbisector)
  - [mlib.segment.getIntersection](#mlibsegmentgetintersection)
- [mlib.polygon](#mlibpolygon)
  - [mlib.polygon.checkPoint](#mlibpolygoncheckpoint)
  - [mlib.polygon.getCentroid](#mlibpolygongetcentroid)
  - [mlib.polygon.getCircleIntersection](#mlibpolygongetcircleintersection)
  - [mlib.polygon.getLineIntersection](#mlibpolygongetlineintersection)
  - [mlib.polygon.getPolygonArea](#mlibpolygongetpolygonarea)
  - [mlib.polygon.getPolygonIntersection](#mlibpolygongetpolygonintersection)
  - [mlib.polygon.getSegmentIntersection](#mlibpolygongetsegmentintersection)
  - [mlib.polygon.getSignedPolygonArea](#mlibpolygongetsignedpolygonarea)
  - [mlib.polygon.getTriangleHeight](#mlibpolygongettriangleheight)
  - [mlib.polygon.isCircleInside](#mlibpolygoniscircleinside)
  - [mlib.polygon.isCircleCompletelyInside](#mlibpolygoniscirclecompletelyinside)
  - [mlib.polygon.isPolygonInside](#mlibpolygonispolygoninside)
  - [mlib.polygon.isPolygonCompletelyInside](#mlibpolygonispolygoncompletelyinside)
  - [mlib.polygon.isSegmentInside](#mlibpolygonissegmentinside)
  - [mlib.polygon.isSegmentCompletelyInside](#mlibpolygonissegmentcompletelyinside)
- [mlib.circle](#mlibcircle)
  - [mlib.circle.checkPoint](#mlibcirclecheckpoint)
  - [mlib.circle.getArea](#mlibcirclegetarea)
  - [mlib.circle.getCircleIntersection](#mlibcirclegetcircleintersection)
  - [mlib.circle.getCircumference](#mlibcirclegetcircumference)
  - [mlib.circle.getLineIntersection](#mlibcirclegetlineintersection)
  - [mlib.circle.getSegmentIntersection](#mlibcirclegetsegmentintersection)
  - [mlib.circle.isCircleCompletelyInside](#mlibcircleiscirclecompletelyinside)
  - [mlib.circle.isCircleCompletelyInsidePolygon](#mlibcircleiscirclecompletelyinsidepolygon)
  - [mlib.circle.isPointOnCircle](#mlibcircleispointoncircle)
  - [mlib.circle.isPolygonCompletelyInside](#mlibcircleispolygoncompletelyinside)
- [mlib.statistics](#mlibstatistics)
  - [mlib.statistics.getCentralTendency](#mlibstatisticsgetcentraltendency)
  - [mlib.statistics.getDispersion](#mlibstatisticsgetdispersion)
  - [mlib.statistics.getMean](#mlibstatisticsgetmean)
  - [mlib.statistics.getMedian](#mlibstatisticsgetmedian)
  - [mlib.statistics.getMode](#mlibstatisticsgetmode)
  - [mlib.statistics.getRange](#mlibstatisticsgetrange)
  - [mlib.statistics.getStandardDeviation](#mlibstatisticsgetstandarddeviation)
  - [mlib.statistics.getVariance](#mlibstatisticsgetvariance)
  - [mlib.statistics.getVariationRatio](#mlibstatisticsgetvariationratio)
- [mlib.math](#mlibmath)
  - [mlib.math.getAngle](#mlibmathgetangle)
  - [mlib.math.getPercentage](#mlibmathgetpercentage)
  - [mlib.math.getPercentOfChange](#mlibmathgetpercentofchange)
  - [mlib.math.getQuadraticRoots](#mlibmathgetquadraticroots)
  - [mlib.math.getRoot](#mlibmathgetroot)
  - [mlib.math.getSummation](#mlibmathgetsummation)
  - [mlib.math.isPrime](#mlibmathisprime)
  - [mlib.math.round](#mlibmathround)
- [Aliases](#aliases)

#### mlib.line
- Deals with linear aspects, such as slope and length.

##### mlib.line.checkPoint
- Checks if a point lies on a line.
- Synopsis:
  - `onPoint = mlib.line.checkPoint( px, px, x1, y1, x2, y2 )`
- Arguments:
  - `px`, `py`: Numbers. The x and y coordinates of the point being tested.
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates of the line being tested.
- Returns:
  - `onPoint`: Boolean.
    - `true` if the point is on the line.
	- `false` if it does not.
- Notes:
  - You cannot use the format `mlib.line.checkPoint( px, px, slope, intercept )` because this would lead to errors on vertical lines.

##### mlib.line.getClosestPoint
- Gives the closest point to a line.
- Synopses:
  - `cx, cy = mlib.line.getClosestPoint( px, py, x1, y1, x2, y2 )`
  - `cx, cy = mlib.line.getClosestPoint( px, py, slope, intercept )`
- Arguments:
  - `x`, `y`: Numbers. The x and y coordinates of the point.
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates on the line.
  - `slope`, `intercept`:
    - Numbers. The slope and y-intercept of the line.
	- Booleans (`false`). The slope and y-intercept of a vertical line.
- Returns:
  - `cx`, `cy`: Numbers. The closest points that lie on the line to the point.

##### mlib.line.getYIntercept
- Gives y-intercept of the line.
- Synopses:
  - `intercept, isVertical = mlib.line.getYIntercept( x1, y1, x2, y2 )`
  - `intercept, isVertical = mlib.line.getYIntercept( x1, y1, slope )`
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates that lie on the line.
  - `slope`:
    - Number. The slope of the line.
- Returns:
  - `intercept`:
    - Number. The y-intercept of the line.
    - Number. The `x1` coordinate of the line if the line is vertical.
  - `isVertical`:
    - Boolean. `true` if the line is vertical, `false` if the line is not vertical.

##### mlib.line.getIntersection
- Gives the intersection of two lines.
- Synopses:
  - `x, y = mlib.line.getIntersection( x1, y1, x2, y2, x3, y3, x4, y4 )`
  - `x, y = mlib.line.getIntersection( slope1, intercept1, x3, y3, x4, y4 )`
  - `x, y = mlib.line.getIntersection( slope1, intercept1, slope2, intercept2 )`
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates that lie on the first line.
  - `x3`, `y3`, `x4`, `y4`: Numbers. Two x and y coordinates that lie on the second line.
  - `slope1`, `intercept1`:
    - Numbers. The slope and y-intercept of the first line.
	- Booleans (`false`). The slope and y-intercept of the first line (if the first line is vertical).
  - `slope2`, `intercept2`:
    - Numbers. The slope and y-intercept of the second line.
	- Booleans (`false`). The slope and y-intercept of the second line (if the second line is vertical).
- Returns:
  - `x`, `y`:
    - Numbers. The x and y coordinate where the lines intersect.
	- Boolean:
	  - `true`, `nil`: The lines are collinear.
	  - `false`, `nil`: The lines are parallel and __not__ collinear.

##### mlib.line.getLength
- Gives the distance between two points.
- Synopsis:
  - `length = mlib.line.getLength( x1, y1, x2, y2 )
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates.
- Returns:
  - `length`: Number. The distance between the two points.

##### mlib.line.getMidpoint
- Gives the midpoint of two points.
- Synopsis:
  - `x, y = mlib.line.getMidpoint( x1, y1, x2, y2 )`
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates.
- Returns:
  - `x`, `y`: Numbers. The midpoint x and y coordinates.

##### mlib.line.getPerpendicularSlope
- Gives the perpendicular slope of a line.
- Synopses:
  - `perpSlope = mlib.line.getPerpendicularSlope( x1, y1, x2, y2 )`
  - `perpSlope = mlib.line.getPerpendicularSlope( slope )`
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates.
  - `slope`: Number. The slope of the line.
- Returns:
  - `perpSlope`:
    - Number. The perpendicular slope of the line.
	- Boolean (`false`). The perpendicular slope of the line (if the original line was horizontal).

##### mlib.line.getSegmentIntersection
- Gives the intersection of a line segment and a line.
- Synopses:
  - `x1, y1, x2, y2 = mlib.line.getSegmentIntersection( x1, y1, x2, y2, x3, y3, x4, y4 )`
  - `x1, y1, x2, y2 = mlib.line.getSegmentIntersection( x1, y1, x2, y2, slope, intercept )`
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates that lie on the line segment.
  - `x3`, `y3`, `x4`, `y4`: Numbers. Two x and y coordinates that lie on the line.
  - `slope`, `intercept`:
    - Numbers. The slope and y-intercept of the the line.
	- Booleans (`false`). The slope and y-intercept of the line (if the line is vertical).
- Returns:
  - `x1`, `y1`, `x2`, `y2`:
    - Number, Number, Number, Number.
	  - The points of the line segment if the line and segment are collinear.
	- Number, Number, Boolean (`nil`), Boolean (`nil`).
	  - The coordinate of intersection if the line and segment intersect and are not collinear.
	- Boolean (`false`), Boolean (`nil`), Boolean (`nil`),
	  - Boolean (`nil`). If the line and segment don't intersect.

##### mlib.line.getSlope
- Gives the slope of a line.
- Synopsis:
  - `slope = mlib.line.getSlope( x1, y1, x2, y2 )
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates.
- Returns:
  - `slope`:
    - Number. The slope of the line.
	- Boolean (`false`). The slope of the line (if the line is vertical).

#### mlib.segment
- Deals with line segments.

##### mlib.segment.checkPoint
- Checks if a point lies on a line segment.
- Synopsis:
  - `onSegment = mlib.segment.checkPoint( px, py, x1 y1, x2, y2 )`
- Arguments:
  - `px`, `py`: Numbers. The x and y coordinates of the point being checked.
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates.
- Returns:
  - `onSegment`: Boolean.
    - `true` if the point lies on the line segment.
	- `false` if the point does not lie on the line segment.

##### mlib.segment.getPerpendicularBisector
- Gives the perpendicular bisector of a line.
- Synopsis:
  - `x, y, slope = mlib.segment.getPerpendicularBisector( x1, y1, x2, y2 )`
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates.
- Returns:
  - `x`, `y`: Numbers. The midpoint of the line.
  - `slope`:
    - Number. The perpendicular slope of the line.
	- Boolean (`false`). The perpendicular slope of the line (if the original line was horizontal).

##### mlib.segment.getIntersection
- Checks if two line segments intersect.
- Synopsis:
  - `cx1, cy1, cx2, cy2 = mlib.segment.getIntersection( x1, y1, x2, y2, x3, y3 x4, y4 )`
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates of the first line segment.
  - `x3`, `y3`, `x4`, `y4`: Numbers. Two x and y coordinates of the second line segment.
- Returns:
  - `cx1`, `cy1`, `cx2`, `cy2`:
    - Number, Number, Number, Number.
	  - The points of the resulting intersection if the line segments are collinear.
	- Number, Number, Boolean (`nil`), Boolean (`nil`).
	  - The point of the resulting intersection if the line segments are not collinear.
	- Boolean (`false`), Boolean (`nil`), Boolean (`nil`) , Boolean (`nil`).
	  - If the line segments don't intersect.

#### mlib.polygon
- Handles aspects involving polygons.

##### mlib.polygon.checkPoint
- Checks if a point is inside of a polygon.
- Synopses:
  - `inPolygon = mlib.polygon.checkPoint( px, py, vertices )`
  - `inPolygon = mlib.polygon.checkPoint( px, py, ... )`
- Arguments:
  - `px`, `py`: Numbers. The x and y coordinate of the point being checked.
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `inPolygon`: Boolean.
    - `true` if the point is inside the polygon.
	- `false` if the point is not inside the polygon.

##### mlib.polygon.getCentroid
- Returns the centroid of the polygon.
- Synopses:
  - `cx, cy = mlib.polygon.getCentroid( vertices )`
  - `cx, cy = mlib.polygon.getCentroid( ... )`
- Arguments:
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `cx`, `cy`: Numbers. The x and y coordinates of the centroid.

##### mlib.polygon.getCircleIntersection
- Returns the coordinates of where a circle intersects a polygon.
- Synopses:
  - `intersections = mlib.polygon.getCircleIntersection( cx, cy, radius, vertices )`
  - `intersections = mlib.polygon.getCircleIntersection( cx, cy, radius, ... )
- Arguments:
  - `cx`, `cy`: Number. The coordinates of the center of the circle.
  - `radius`: Number. The radius of the circle.
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `intersections`: Table. Contains the intersections and type.
- Example:
```lua
local tab = _.polygon.getCircleIntersection( 5, 5, 1, 4, 4, 6, 4, 6, 6, 4, 6 )
for i = 1, # tab do
	print( i .. ':', unpack( tab[i] ) )
end
-- 1: 	tangent		5		4
-- 2: 	tangent		6 		5
-- 3: 	tangent 	5		6
-- 4: 	tagnent 	4		5
```
- For more see [mlib.circle.getSegmentIntersection](#mlibcirclegetsegmentintersection) or the [specs](spec.lua# L676)

##### mlib.polygon.getLineIntersection
- Returns the coordinates of where a line intersects a polygon.
- Synopses:
  - `intersections = mlib.polygon.getLineIntersection( x1, y1, x2, y2, vertices )`
  - `intersections = mlib.polygon.getLineIntersection( x1, y1, x2, y2, ... )
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates.
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `intersections`: Table. Contains the intersections.
- Notes:
  - With collinear lines, they are actually broken up. i.e. `{ 0, 4, 0, 0 }` would become `{ 0, 4 }, { 0, 0 }`.

##### mlib.polygon.getPolygonArea
- Gives the area of a polygon.
- Synopses:
  - `area = mlib.polygon.getArea( vertices )`
  - `area = mlib.polygon.getArea( ... )
- Arguments:
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `area`: Number. The area of the polygon.

##### mlib.polygon.getPolygonIntersection
- Gives the intersection of two polygons.
- Synopsis:
  - `intersections = mlib.polygon.getPolygonIntersections( polygon1, polygon2 )`
- Arguments:
  - `polygon1`: Table. The vertices of the first polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `polygon2`: Table. The vertices of the second polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
- Returns:
  - `intersections`: Table. A table of the points of intersection.

##### mlib.polygon.getSegmentIntersection
- Returns the coordinates of where a line segmeing intersects a polygon.
- Synopses:
  - `intersections = mlib.polygon.getSegmentIntersection( x1, y1, x2, y2, vertices )`
  - `intersections = mlib.polygon.getSegmentIntersection( x1, y1, x2, y2, ... )
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates.
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `intersections`: Table. Contains the intersections.
- Notes:
  - With collinear line segments, they are __not__ broken up. See the [specs](spec.lua# L508) for more.

##### mlib.polygon.getSignedPolygonArea
- Gets the signed area of the polygon. If the points are ordered counter-clockwise the area is positive. If the points are ordered clockwise the number is negative.
- Synopses:
  - `area = mlib.polygon.getLineIntersection( vertices )`
  - `area = mlib.polygon.getLineIntersection( ... )
- Arguments:
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `area`: Number. The __signed__ area of the polygon. If the points are ordered counter-clockwise the area is positive. If the points are ordered clockwise the number is negative.

##### mlib.polygon.getTriangleHeight
- Gives the height of a triangle.
- Synopses:
  - `height = mlib.polygon.getTriangleHeigh( base, x1, y1, x2, y2, x3, y3 )`
  - `height = mlib.polygon.getTriangleHeight( base, area )`
- Arguments:
  - `base`: Number. The length of the base of the triangle.
  - `x1`, `y1`, `x2`, `y2`, `x3`, `y3`: Numbers. The x and y coordinates of the triangle.
  - `area`: Number. The regular area of the triangle. __Not__ the signed area.
- Returns:
  - `height`: Number. The height of the triangle.

##### mlib.polygon.isCircleInside
- Checks if a circle is inside the polygon.
- Synopses:
  - `inPolygon = mlib.polygon.isCircleInside( cx, cy, radius, vertices )`
  - `inPolygon = mlib.polygon.isCircleInside( cx, cy, radius, ... )`
- Arguments:
  - `cx`, `cy`: Numbers. The x and y coordinates for the center of the circle.
  - `radius`: Number. The radius of the circle.
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `inPolygon`: Boolean.
    - `true` if the circle is inside the polygon.
	- `false` if the circle is not inside the polygon.
- Notes:
  - Only returns true if the center of the circle is inside the circle.

##### mlib.polygon.isCircleCompletelyInside
- Checks if a circle is completely inside the polygon.
- Synopses:
  - `inPolygon = mlib.polygon.isCircleCompletelyInside( cx, cy, radius, vertices )`
  - `inPolygon = mlib.polygon.isCircleCompletelyInside( cx, cy, radius, ... )`
- Arguments:
  - `cx`, `cy`: Numbers. The x and y coordinates for the center of the circle.
  - `radius`: Number. The radius of the circle.
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `inPolygon`: Boolean.
    - `true` if the circle is __completely__ inside the polygon.
	- `false` if the circle is not inside the polygon.

##### mlib.polygon.isPolygonInside
- Checks if a polygon is inside a polygon.
- Synopsis:
  - `inPolygon = mlib.polygon.isPolygonInside( polygon1, polygon2 )`
- Arguments:
  - `polygon1`: Table. The vertices of the first polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `polygon2`: Table. The vertices of the second polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
- Returns:
  - `inPolygon`: Boolean.
    - `true` if the `polygon2` is inside of `polygon1`.
	- `false` if `polygon2` is not inside of `polygon2`.
- Notes:
  - Returns true as long as any of the line segments of `polygon2` are inside of the `polygon1`.

##### mlib.polygon.isPolygonCompletelyInside
- Checks if a polygon is completely inside a polygon.
- Synopsis:
  - `inPolygon = mlib.polygon.isPolygonCompletelyInside( polygon1, polygon2 )`
- Arguments:
  - `polygon1`: Table. The vertices of the first polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `polygon2`: Table. The vertices of the second polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
- Returns:
  - `inPolygon`: Boolean.
    - `true` if the `polygon2` is __completely__ inside of `polygon1`.
	- `false` if `polygon2` is not inside of `polygon2`.

##### mlib.polygon.isSegmentInside
- Checks if a line segment is inside a polygon.
- Synopses:
  - `inPolygon = mlib.polygon.isSegmentInside( x1, y1, x2, y2, vertices )`
  - `inPolygon = mlib.polygon.isSegmentInside( x1, y1, x2, y2, ... )`
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. The x and y coordinates of the line segment.
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `inPolygon`: Boolean.
    - `true` if the line segment is inside the polygon.
	- `false` if the line segment is not inside the polygon.
- Note:
  - Only one of the points has to be in the polygon to be considered 'inside' of the polygon.
  - This is really just a faster version of [mlib.polygon.getPolygonIntersection](#mlibpolygongetpolygonintersection) that does not give the points of intersection.

##### mlib.polygon.isSegmentCompletelyInside
- Checks if a line segment is completely inside a polygon.
- Synopses:
  - `inPolygon = mlib.polygon.isSegmentCompletelyInside( x1, y1, x2, y2, vertices )`
  - `inPolygon = mlib.polygon.isSegmentCompletelyInside( x1, y1, x2, y2, ... )`
- Arguments:
  - `x1`, `y1`, `x2`, `y2`: Numbers. The x and y coordinates of the line segment.
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `inPolygon`: Boolean.
    - `true` if the line segment is __completely__ inside the polygon.
	- `false` if the line segment is not inside the polygon.

#### mlib.circle
- Handles aspects involving circles.

##### mlib.circle.checkPoint
- Checks if a point is on the inside or on the edge the circle.
- Synopsis:
  - `inCircle = mlib.circle.checkPoint( px, px, cx, cy, radius )`
- Arguments:
  - `px`, `py`: Numbers. The x and y coordinates of the point being tested.
  - `cx`, `cy`: Numbers. The x and y coordinates of the center of the circle.
  - `radius`: Number. The radius of the circle.
- Returns:
  - `inCircle`: Boolean.
    - `true` if the point is inside or on the circle.
	- `false` if the point is outside of the circle.

##### mlib.circle.getArea
- Gives the area of a circle.
- Synopsis:
  - `area = mlib.circle.getArea( radius )`
- Arguments:
  - `radius`: Number. The radius of the circle.
- Returns:
  - `area`: Number. The area of the circle.

##### mlib.circle.getCircleIntersection
- Gives the intersections of two circles.
- Synopsis:
  - `intersections = mlib.circle.getCircleIntersection( c1x, c1y, radius1, c2x, c2y, radius2 )
- Arguments:
  - `c1x`, `c1y`: Numbers. The x and y coordinate of the first circle.
  - `radius1`: Number. The radius of the first circle.
  - `c2x`, `c2y`: Numbers. The x and y coordinate of the second circle.
  - `radius2`: Number. The radius of the second circle.
- Returns:
  - `intersections`: Table. A table that contains the type and where the circle collides. See the [specs](spec.lua# L698) for more.

##### mlib.circle.getCircumference
- Returns the circumference of a circle.
- Synopsis:
  - `circumference = mlib.circle.getCircumference( radius )`
- Arguments:
  - `radius`: Number. The radius of the circle.
- Returns:
  - `circumference`: Number. The circumference of a circle.

##### mlib.circle.getLineIntersection
- Returns the intersections of a circle and a line.
- Synopsis:
  - `intersections = mlib.circle.getLineIntersections( cx, cy, radius, x1, y1, x2, y2 )`
- Arguments:
  - `cx`, `cy`: Numbers. The x and y coordinates for the center of the circle.
  - `radius`: Number. The radius of the circle.
  - `x1`, `y1`, `x2`, `y2`: Numbers. Two x and y coordinates the lie on the line.
- Returns:
  - `intersections`: Table. A table with the type and where the intersections happened. Table is formatted:
    - `type`, `x1`, `y1`, `x2`, `y2`
	  - String (`'secant'`), Number, Number, Number, Number
	    - The numbers are the x and y coordinates where the line intersects the circle.
	  - String (`'tangent'`), Number, Number, Boolean (`nil`), Boolean (`nil`)
	    - `x1` and `x2` represent where the line intersects the circle.
	  - Boolean (`false`), Boolean (`nil`), Boolean (`nil`), Boolean (`nil`), Boolean (`nil`)
	    - No intersection.
    - For more see the [specs](spec.lua# L660).

##### mlib.circle.getSegmentIntersection
- Returns the intersections of a circle and a line segment.
- Synopsis:
  - `intersections = mlib.circle.getSegmentIntersections( cx, cy, radius, x1, y1, x2, y2 )`
- Arguments:
  - `cx`, `cy`: Numbers. The x and y coordinates for the center of the circle.
  - `radius`: Number. The radius of the circle.
  - `x1`, `y1`, `x2`, `y2`: Numbers. The two x and y coordinates of the line segment.
- Returns:
  - `intersections`: Table. A table with the type and where the intersections happened. Table is formatted:
    - `type`, `x1`, `y1`, `x2`, `y2`
	  - String (`'chord'`), Number, Number, Number, Number
	    - The numbers are the x and y coordinates where the line segment is on both edges of the circle.
	  - String (`'enclosed'`), Number, Number, Number, Number
	    - The numbers are the x and y coordinates of the line segment if it is fully inside of the circle.
	  - String (`'secant'`), Number, Number, Number, Number
	    - The numbers are the x and y coordinates where the line segment intersects the circle.
	  - String (`'tangent'`), Number, Number, Boolean (`nil`), Boolean (`nil`)
	    - `x1` and `x2` represent where the line segment intersects the circle.
	  - Boolean (`false`), Boolean (`nil`), Boolean (`nil`), Boolean (`nil`), Boolean (`nil`)
	    - No intersection.
    - For more see the [specs](spec.lua# L676).

##### mlib.circle.isCircleCompletelyInside
- Checks if one circle is completely inside of another circle.
- Synopsis:
  - `completelyInside = mlib.circle.isCircleCompletelyInside( c1x, c1y, c1radius, c2x, c2y, c2radius )`
- Arguments:
  - `c1x`, `c1y`: Numbers. The x and y coordinates of the first circle.
  - `c1radius`: Number. The radius of the first circle.
  - `c2x`, `c2y`: Numbers. The x and y coordinates of the second circle.
  - `c2radius`: Number. The radius of the second circle.
- Returns:
  - `completelyInside`: Boolean.
    - `true` if circle1 is inside of circle2.
	- `false` if circle1 is not __completely__ inside of circle2.

##### mlib.circle.isCircleCompletelyInsidePolygon
- Checks if a circle is completely inside the polygon.
- Synopses:
  - `inPolygon = mlib.polygon.isCircleCompletelyInside( cx, cy, radius, vertices )`
  - `inPolygon = mlib.polygon.isCircleCompletelyInside( cx, cy, radius, ... )`
- Arguments:
  - `cx`, `cy`: Numbers. The x and y coordinates for the center of the circle.
  - `radius`: Number. The radius of the circle.
  - `vertices`: Table. The vertices of the polygon in the format `{ x1, y1, x2, y2, x3, y3, ... }`
  - `...`: Numbers. The x and y coordinates of the polygon. (Same as using `unpack( vertices )`)
- Returns:
  - `inPolygon`: Boolean.
    - `true` if the circle is __completely__ inside the polygon.
	- `false` if the circle is not inside the polygon.

##### mlib.circle.isPointOnCircle
- Checks if a point is __exactly__ on the edge of the circle.
- Synopsis:
  - `onCircle = mlib.circle.checkPoint( px, px, cx, cy, radius )`
- Arguments:
  - `px`, `py`: Numbers. The x and y coordinates of the point being tested.
  - `cx`, `cy`: Numbers. The x and y coordinates of the center of the circle.
  - `radius`: Number. The radius of the circle.
- Returns:
  - `onCircle`: Boolean.
    - `true` if the point is on the circle.
	- `false` if the point is on the inside or outside of the circle.
- Notes:
  - Will return false if the point is inside __or__ outside of the circle.

##### mlib.circle.isPolygonCompletelyInside
- Checks if a polygon is completely inside of a circle.
- Synopsis:
  - `completelyInside = mlib.circle.isPolygonCompletelyInside( circleX, circleY, circleRadius, vertices )`
  - `completelyInside = mlib.circle.isPolygonCompletelyInside( circleX, circleY, circleRadius, ... )`
- Arguments:
  - `circleX`, `circleY`: Numbers. The x and y coordinates of the circle.
  - `circleRadius`: Number. The radius of the circle.
  - `vertices`: Table. A table containing all of the vertices of the polygon.
  - `...`: Numbers. All of the points of the polygon.
- Returns:
  - `completelyInside`: Boolean.
    - `true` if the polygon is inside of the circle.
	- `false` if the polygon is not __completely__ inside of the circle.

#### mlib.statistics
- Handles statistical aspects of math.

##### mlib.statistics.getCentralTendency
- Gets the central tendency of the data.
- Synopses:
  - `modes, occurrences, median, mean = mlib.statistics.getCentralTendency( data )`
  - `modes, occurrences, median, mean = mlib.statistics.getCentralTendency( ... )`
- Arguments:
  - `data`: Table. A table containing the values of data.
  - `...`: Numbers. All of the numbers in the data set.
- Returns:
  - `modes, occurrences`: Table, Number. The modes of the data and the number of times it occurs. See [mlib.statistics.getMode](#mlibstatisticsgetmode).
  - `median`: Number. The median of the data set.
  - `mean`: Number. The mean of the data set.

##### mlib.statistics.getDispersion
- Gets the dispersion of the data.
- Synopses:
  - `variationRatio, range, standardDeviation = mlib.statistics.getDispersion( data )`
  - `variationRatio, range, standardDeviation = mlib.statistics.getDispersion( ... )`
- Arguments:
  - `data`: Table. A table containing the values of data.
  - `...`: Numbers. All of the numbers in the data set.
- Returns:
  - `variationRatio`: Number. The variation ratio of the data set.
  - `range`: Number. The range of the data set.
  - `standardDeviation`: Number. The standard deviation of the data set.

##### mlib.statistics.getMean
- Gets the arithmetic mean of the data.
- Synopses:
  - `mean = mlib.statistics.getMean( data )`
  - `mean = mlib.statistics.getMean( ... )`
- Arguments:
  - `data`: Table. A table containing the values of data.
  - `...`: Numbers. All of the numbers in the data set.
- Returns:
  - `mean`: Number. The arithmetic mean of the data set.

##### mlib.statistics.getMedian
- Gets the median of the data set.
- Synopses:
  - `median = mlib.statistics.getMedian( data )`
  - `median = mlib.statistics.getMedian( ... )`
- Arguments:
  - `data`: Table. A table containing the values of data.
  - `...`: Numbers. All of the numbers in the data set.
- Returns:
  - `median`: Number. The median of the data.

##### mlib.statistics.getMode
- Gets the mode of the data set.
- Synopses:
  - `mode, occurrences = mlib.statistics.getMode( data )`
  - `mode, occurrences = mlib.statistics.getMode( ... )`
- Arguments:
  - `data`: Table. A table containing the values of data.
  - `...`: Numbers. All of the numbers in the data set.
- Returns:
  - `mode`: Table. The mode(s) of the data.
  - `occurrences`: Number. The number of time the mode(s) occur.

##### mlib.statistics.getRange
- Gets the range of the data set.
- Synopses:
  - `range = mlib.statistics.getRange( data )`
  - `range = mlib.statistics.getRange( ... )`
- Arguments:
  - `data`: Table. A table containing the values of data.
  - `...`: Numbers. All of the numbers in the data set.
- Returns:
  - `range`: Number. The range of the data.

##### mlib.statistics.getStandardDeviation
- Gets the standard deviation of the data.
- Synopses:
  - `standardDeviation = mlib.statistics.getStandardDeviation( data )`
  - `standardDeviation = mlib.statistics.getStandardDeviation( ... )`
- Arguments:
  - `data`: Table. A table containing the values of data.
  - `...`: Numbers. All of the numbers in the data set.
- Returns:
  - `standardDeviation`: Number. The standard deviation of the data set.

##### mlib.statistics.getVariance
- Gets the variation of the data.
- Synopses:
  - `variance = mlib.statistics.getVariance( data )`
  - `variance = mlib.statistics.getVariance( ... )`
- Arguments:
  - `data`: Table. A table containing the values of data.
  - `...`: Numbers. All of the numbers in the data set.
- Returns:
  - `variance`: Number. The variation of the data set.

##### mlib.statistics.getVariationRatio
- Gets the variation ratio of the data.
- Synopses:
  - `variationRatio = mlib.statistics.getVariationRatio( data )`
  - `variationRatio = mlib.statistics.getVariationRatio( ... )`
- Arguments:
  - `data`: Table. A table containing the values of data.
  - `...`: Numbers. All of the numbers in the data set.
- Returns:
  - `variationRatio`: Number. The variation ratio of the data set.

#### mlib.math
- Miscellaneous functions that have no home.

##### mlib.math.getAngle
- Gets the angle between three points.
- Synopsis:
  - `angle = mlib.math.getAngle( x1, y1, x2, y2, x3, y3 )`
- Arguments:
  - `x1`, `y1`: Numbers. The x and y coordinates of the first point.
  - `x2`, `y2`: Numbers. The x and y coordinates of the vertex of the two points.
  - `x3`, `y3`: Numbers. The x and y coordinates of the second point.

##### mlib.math.getPercentage
- Gets the percentage of a number.
- Synopsis:
  - `percentage = mlib.math.getPercentage( percent, number )`
- Arguments:
  - `percent`: Number. The decimal value of the percent (i.e. 100% is 1, 50% is .5).
  - `number`: Number. The number to get the percentage of.
- Returns:
  - `percentage`: Number. The `percent`age or `number`.

##### mlib.math.getPercentOfChange
- Gets the percent of change from one to another.
- Synopsis:
  - `change = mlib.math.getPercentOfChange( old, new )`
- Arguments:
  - `old`: Number. The original number.
  - `new`: Number. The new number.
- Returns:
  - `change`: Number. The percent of change from `old` to `new`.

##### mlib.math.getQuadraticRoots
- Gets the quadratic roots of the the equation.
- Synopsis:
  - `root1, root2 = mlib.math.getQuadraticRoots( a, b, c )`
- Arguments:
  - `a`, `b`, `c`: Numbers. The a, b, and c values of the equation `a * x ^ 2 + b * x ^ 2 + c`.
- Returns:
  - `root1`, `root2`: Numbers. The roots of the equation (where `a * x ^ 2 + b * x ^ 2 + c = 0`).

##### mlib.math.getRoot
- Gets the `n`th root of a number.
- Synopsis:
  - `x = mlib.math.getRoot( number, root )`
- Arguments:
  - `number`: Number. The number to get the root of.
  - `root`: Number. The root.
- Returns:
  - `x`: The `root`th root of `number`.
- Example:
```lua
local a = mlib.math.getRoot( 4, 2 ) -- Same as saying 'math.pow( 4, .5 )' or 'math.sqrt( 4 )' in this case.
local b = mlib.math.getRoot( 27, 3 )

print( a, b ) --> 2, 3
```
  - For more, see the [specs](spec.lua# L860).

##### mlib.math.getSummation
- Gets the summation of numbers.
- Synopsis:
  - `summation = mlib.math.getSummation( start, stop, func )`
- Arguments:
  - `start`: Number. The number at which to start the summation.
  - `stop`: Number. The number at which to stop the summation.
  - `func`: Function. The method to add the numbers.
    - Arguments:
	  - `i`: Number. Index.
	  - `previous`: Table. The previous values used.
- Returns:
  - `Summation`: Number. The summation of the numbers.
  - For more, see the [specs](spec.lua# L897).

##### mlib.math.isPrime
- Checks if a number is prime.
- Synopsis:
  - `isPrime = mlib.math.isPrime( x )`
- Arguments:
  - `x`: Number. The number to check if it's prime.
- Returns:
  - `isPrime`: Boolean.
    - `true` if the number is prime.
	- `false` if the number is not prime.

##### mlib.math.round
- Rounds a number to the given decimal place.
- Synopsis:
  - `rounded = mlib.math.round( number, [place] )
- Arguments:
  - `number`: Number. The number to round.
  - `place (1)`: Number. The decimal place to round to. Defaults to 1.
- Returns:
  - The rounded number.
  - For more, see the [specs](spec.lua# L881).

#### Aliases
| Alias                                         | Corresponding Function                                                            |
| ----------------------------------------------|:---------------------------------------------------------------------------------:|
| milb.line.getDistance                         | [mlib.line.getLength](#mliblinegetlength)                                         |
| mlib.line.getCircleIntersection               | [mlib.circle.getLineIntersection](#mlibcirclegetlineintersection)                 |
| milb.line.getPolygonIntersection              | [mlib.polygon.getLineIntersection](#mlibpolygongetlineintersection)               |
| mlib.line.getLineIntersection                 | [mlib.line.getIntersection](#mliblinegetintersection)                             |
| mlib.segment.getCircleIntersection            | [mlib.circle.getSegmentIntersection](#mlibcirclegetsegmentintersection)           |
| milb.segment.getPolygonIntersection           | [mlib.pollygon.getSegmentIntersection](#mlibpollygongetsegmentintersection)       |
| mlib.segment.getLineIntersection              | [mlib.line.getSegmentIntersection](#mliblinegetsegmentintersection)               |
| mlib.segment.getSegmentIntersection           | [mlib.segment.getIntersection](#mlibsegmentgetintersection)                       |
| milb.segment.isSegmentCompletelyInsideCircle  | [mlib.circle.isSegmentCompletelyInside](#mlibcircleissegmentcompletelyinside)     |
| mlib.segment.isSegmentCompletelyInsidePolygon | [mlib.polygon.isSegmentCompletelyInside](#mlibpolygonissegmentcompletelyinside)   |
| mlib.circle.getPolygonIntersection            | [mlib.polygon.getCircleIntersection](#mlibpolygongetcircleintersection)           |
| mlib.circle.isCircleInsidePolygon             | [mlib.polygon.isCircleInside](#mlibpolygoniscircleinside)                         |
| mlib.circle.isCircleCompletelyInsidePolygon   | [mlib.polygon.isCircleCompletelyInside](#mlibpolygoniscirclecompletelyinside)     |
| mlib.polygon.isCircleCompletelyOver           | [mlib.circleisPolygonCompletelyInside](#mlibcircleispolygoncompletelyinside)      |

## License
A math library made in Lua
copyright (C) 2014 Davis Claiborne
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
Contact me at davisclaib at gmail.com