turf/booleanContains (#797)

* turf/booleanContains

* Fixes as per comments. Additional tests.

* Removed ununsed methods

* Update package.json

* Add shapely tests

packages/turf-bbox/package.json

@@ -31,6 +31,7 @@
   },
   "homepage": "/~https://github.com/Turfjs/turf",
   "devDependencies": {
+    "@turf/helpers": "^4.4.0",
     "benchmark": "^2.1.4",
     "tape": "^4.6.3"
   },

packages/turf-boolean-contains/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 TurfJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/turf-boolean-contains/README.md

@@ -0,0 +1,63 @@
+# @turf/boolean-contains
+
+# booleanContains
+
+Boolean-contains returns True if the second geometry is completely contained by the first geometry.
+The interiors of both geometries must intersect and, the interior and boundary of the secondary (geometry b)
+must not intersect the exterior of the primary (geometry a).
+Boolean-contains returns the exact opposite result of the `@turf/boolean-within`.
+
+**Parameters**
+
+-   `feature1` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)<any>)** GeoJSON Feature or Geometry
+-   `feature2` **([Geometry](http://geojson.org/geojson-spec.html#geometry) \| [Feature](http://geojson.org/geojson-spec.html#feature-objects)<any>)** GeoJSON Feature or Geometry
+
+**Examples**
+
+```javascript
+const point = {
+  "type": "Feature",
+  "properties": {},
+  "geometry": {
+    "type": "Point",
+    "coordinates": [1, 2]
+  }
+}
+const line = {
+  "type": "Feature",
+  "properties": {},
+  "geometry": {
+    "type": "LineString",
+    "coordinates": [[1, 1], [1, 2], [1, 3], [1, 4]]
+  }
+}
+turf.booleanContains(line, point);
+//=true
+```
+
+Returns **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true/false
+
+<!-- This file is automatically generated. Please don't edit it directly:
+if you find an error, edit the source file (likely index.js), and re-run
+./scripts/generate-readmes in the turf project. -->
+
+---
+
+This module is part of the [Turfjs project](http://turfjs.org/), an open source
+module collection dedicated to geographic algorithms. It is maintained in the
+[Turfjs/turf](/~https://github.com/Turfjs/turf) repository, where you can create
+PRs and issues.
+
+### Installation
+
+Install this module individually:
+
+```sh
+$ npm install @turf/boolean-contains
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```

packages/turf-boolean-contains/bench.js

@@ -0,0 +1,52 @@
+const path = require('path');
+const glob = require('glob');
+const Benchmark = require('benchmark');
+const load = require('load-json-file');
+const bbox = require('@turf/bbox');
+const contains = require('./');
+
+/**
+ * Benchmark Results
+ *
+ * LineIsNotContainedByLine x 4,398,295 ops/sec ±1.43% (84 runs sampled)
+ * LineIsNotContainedByPolygon x 1,916,541 ops/sec ±3.03% (84 runs sampled)
+ * LineIsNotContainedByPolygonBoundary x 721,394 ops/sec ±3.84% (77 runs sampled)
+ * MultiPointAllOnBoundaryIsNotContainedByPolygon x 2,190,982 ops/sec ±2.56% (89 runs sampled)
+ * MultiPointIsNotContainedByMultiPoint x 7,368,141 ops/sec ±1.02% (90 runs sampled)
+ * MultiPointIsNotContainedByPolygon x 2,150,014 ops/sec ±0.92% (88 runs sampled)
+ * MultiPointsIsNotContainedByLine x 4,678,701 ops/sec ±0.88% (84 runs sampled)
+ * MultiPointsOnLineEndsIsNotContainedByLine x 3,713,593 ops/sec ±5.79% (86 runs sampled)
+ * PointIsNotContainedByLine x 6,149,162 ops/sec ±5.08% (82 runs sampled)
+ * PointIsNotContainedByLineBecauseOnEnd x 6,491,086 ops/sec ±0.79% (89 runs sampled)
+ * PointIsNotContainedBYMultiPoint x 10,046,634 ops/sec ±0.55% (92 runs sampled)
+ * PointIsNotContainedByPolygon x 2,310,881 ops/sec ±1.45% (88 runs sampled)
+ * PointOnEndIsContainedByLinestring x 6,252,890 ops/sec ±2.74% (79 runs sampled)
+ * PointOnPolygonBoundary x 2,607,654 ops/sec ±0.88% (90 runs sampled)
+ * PolygonIsNotContainedByPolygon x 1,706,009 ops/sec ±2.14% (87 runs sampled)
+ * LineIsContainedByLine x 4,310,811 ops/sec ±1.42% (89 runs sampled)
+ * LineIsContainedByPolygon x 1,101,408 ops/sec ±3.09% (89 runs sampled)
+ * LineIsContainedByPolygonWithNoInternalVertices x 1,153,415 ops/sec ±1.00% (88 runs sampled)
+ * LinesExactSame x 3,881,843 ops/sec ±3.83% (91 runs sampled)
+ * MultiPointIsContainedByPolygonBoundary x 1,262,263 ops/sec ±2.75% (89 runs sampled)
+ * MultiPointsContainedByMultiPoints x 7,074,094 ops/sec ±3.32% (92 runs sampled)
+ * MultipointsIsContainedByLine x 4,909,852 ops/sec ±2.85% (92 runs sampled)
+ * PointInsidePolygonBoundary x 2,323,817 ops/sec ±3.11% (88 runs sampled)
+ * PointIsContainedByLine x 7,894,080 ops/sec ±3.41% (89 runs sampled)
+ * PointIsContainedByMultiPoint x 11,832,775 ops/sec ±2.13% (89 runs sampled)
+ * PolygonIsContainedByPolygon x 1,907,608 ops/sec ±5.67% (87 runs sampled)
+ * PolygonsExactSameShape x 1,578,745 ops/sec ±7.73% (76 runs sampled)
+ */
+const suite = new Benchmark.Suite('turf-boolean-contains');
+glob.sync(path.join(__dirname, 'test', '**', '*.geojson')).forEach(filepath => {
+    const {name} = path.parse(filepath);
+    const geojson = load.sync(filepath);
+    const [feature1, feature2] = geojson.features;
+    feature1.bbox = bbox(feature1);
+    feature2.bbox = bbox(feature2);
+    suite.add(name, () => contains(feature1, feature2));
+});
+
+suite
+    .on('cycle', e => console.log(String(e.target)))
+    .on('complete', () => {})
+    .run();

packages/turf-boolean-contains/index.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="geojson" />
+
+type Feature = GeoJSON.Feature<any> | GeoJSON.GeometryObject;
+
+/**
+ * http://turfjs.org/docs/#boolean-contains
+ */
+declare function booleanContains(feature1: Feature, feature2: Feature): boolean;
+declare namespace booleanContains { }
+export = booleanContains;