turf/booleanContains

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,47 @@
+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,133,850 ops/sec ±1.62% (92 runs sampled)
+ * LineIsNotContainedByPolygon x 1,416,083 ops/sec ±2.47% (87 runs sampled)
+ * LineIsNotContainedByPolygonBoundary x 1,419,828 ops/sec ±1.85% (88 runs sampled)
+ * MultiPointIsNotContainedByMultiPoint x 6,705,712 ops/sec ±4.32% (76 runs sampled)
+ * MultiPointIsNotContainedByPolygon x 2,043,151 ops/sec ±3.21% (82 runs sampled)
+ * MultiPointsIsNotContainedByLine x 5,210,528 ops/sec ±3.21% (74 runs sampled)
+ * PointIsNotContainedByLine x 7,324,482 ops/sec ±4.22% (84 runs sampled)
+ * PointIsNotContainedByLineBecauseOnEnd x 6,024,271 ops/sec ±5.04% (78 runs sampled)
+ * PointIsNotContainedBYMultiPoint x 10,063,229 ops/sec ±3.50% (80 runs sampled)
+ * PointIsNotContainedByPolygon x 2,204,858 ops/sec ±3.03% (80 runs sampled)
+ * PointOnPolygonBoundary x 2,387,408 ops/sec ±2.47% (83 runs sampled)
+ * PolygonIsNotContainedByPolygon x 1,999,776 ops/sec ±3.20% (84 runs sampled)
+ * LineIsContainedByLine x 3,434,699 ops/sec ±3.43% (82 runs sampled)
+ * LineIsContainedByPolygon x 853,234 ops/sec ±2.43% (79 runs sampled)
+ * MultiPointIsContainedByPolygonBoundary x 1,197,014 ops/sec ±1.89% (85 runs sampled)
+ * MultiPointsContainedByMultiPoints x 6,601,619 ops/sec ±2.44% (80 runs sampled)
+ * MultipointsIsContainedByLine x 5,843,279 ops/sec ±2.37% (82 runs sampled)
+ * PointInsidePolygonBoundary x 2,110,993 ops/sec ±3.84% (79 runs sampled)
+ * PointIsContainedByLine x 7,436,720 ops/sec ±2.74% (80 runs sampled)
+ * PointIsContainedByMultiPoint x 10,256,333 ops/sec ±4.22% (75 runs sampled)
+ * PolygonIsContainedByPolygon x 757,885 ops/sec ±2.61% (82 runs sampled)
+ * PolygonsExactSameShape x 758,328 ops/sec ±2.27% (86 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 contains(feature1: Feature, feature2: Feature): boolean;
+declare namespace contains { }
+export = contains;