pass item bbox to filterFn in search (#68)

Author: mourner

README.md

@@ -92,13 +92,21 @@ Returns an array of indices of items intersecting or touching a given bounding b
 const ids = index.search(10, 10, 20, 20);
 ```
 
-If given a `filterFn`, calls it on every found item (passing an item index)
+If given a `filterFn`, calls it on every found item (passing the item's index & bounding box coordinates)
 and only includes it if the function returned a truthy value.
 
 ```js
 const ids = index.search(10, 10, 20, 20, (i) => items[i].foo === 'bar');
 ```
 
+Alternatively, instead of using the array of indices returned by `search`, you can handle the results in the function:
+
+```js
+index.search(10, 10, 20, 20, (i, x0, y0, x1, y1) => {
+    console.log(`Item found: ${items[i]}, bbox: ${x0} ${y0} ${x1} ${y1}`);
+})
+```
+
 #### `index.neighbors(x, y[, maxResults, maxDistance, filterFn])`
 
 Returns an array of item indices in order of distance from the given `x, y`
@@ -109,7 +117,10 @@ const ids = index.neighbors(10, 10, 5); // returns 5 ids
 ```
 
 `maxResults` and `maxDistance` are `Infinity` by default.
-Also accepts a `filterFn` similar to `index.search`.
+
+If given a `filterFn`, calls it on items that potentially belong to the results (passing the item's index)
+and only includes an item if the function returned a truthy value.
+Unlike `search`, it shouldn't be used for handling results.
 
 #### `Flatbush.from(data[, byteOffset])`
 

index.js

@@ -210,7 +210,7 @@ export default class Flatbush {
      * @param {number} minY
      * @param {number} maxX
      * @param {number} maxY
-     * @param {(index: number) => boolean} [filterFn] An optional function for filtering the results.
+     * @param {(index: number, x0: number, y0: number, x1: number, y1: number) => boolean} [filterFn] An optional function that is called on every found item; if supplied, only items for which this function returns true will be included in the results array.
      * @returns {number[]} An array of indices of items intersecting or touching the given bounding box.
      */
     search(minX, minY, maxX, maxY, filterFn) {
@@ -230,17 +230,21 @@ export default class Flatbush {
             // search through child nodes
             for (let /** @type number */ pos = nodeIndex; pos < end; pos += 4) {
                 // check if node bbox intersects with query bbox
-                if (maxX < this._boxes[pos]) continue; // maxX < nodeMinX
-                if (maxY < this._boxes[pos + 1]) continue; // maxY < nodeMinY
-                if (minX > this._boxes[pos + 2]) continue; // minX > nodeMaxX
-                if (minY > this._boxes[pos + 3]) continue; // minY > nodeMaxY
+                const x0 = this._boxes[pos];
+                if (maxX < x0) continue;
+                const y0 = this._boxes[pos + 1];
+                if (maxY < y0) continue;
+                const x1 = this._boxes[pos + 2];
+                if (minX > x1) continue;
+                const y1 = this._boxes[pos + 3];
+                if (minY > y1) continue;
 
                 const index = this._indices[pos >> 2] | 0;
 
                 if (nodeIndex >= this.numItems * 4) {
                     queue.push(index); // node; add it to the search queue
 
-                } else if (filterFn === undefined || filterFn(index)) {
+                } else if (filterFn === undefined || filterFn(index, x0, y0, x1, y1)) {
                     results.push(index); // leaf item
                 }
             }