query(Predicates const &, OutIter)

| Home | Libraries | People | FAQ | More

##### query(Predicates const &, OutIter)

Finds values meeting passed predicates e.g. nearest to some Point and/or intersecting some Box.

###### Description

This query function performs spatial and k-nearest neighbor searches. It allows to pass a set of predicates. Values will be returned only if all predicates are met.

Spatial predicates

Spatial predicates may be generated by one of the functions listed below:

- `boost::geometry::index::contains()`,
- `boost::geometry::index::covered_by()`,
- `boost::geometry::index::covers()`,
- `boost::geometry::index::disjoint()`,
- `boost::geometry::index::intersects()`,
- `boost::geometry::index::overlaps()`,
- `boost::geometry::index::within()`,

It is possible to negate spatial predicates:

- ``!` boost::geometry::index::contains()`,
- ``!` boost::geometry::index::covered_by()`,
- ``!` boost::geometry::index::covers()`,
- ``!` boost::geometry::index::disjoint()`,
- ``!` boost::geometry::index::intersects()`,
- ``!` boost::geometry::index::overlaps()`,
- ``!` boost::geometry::index::within()`

Satisfies predicate

This is a special kind of predicate which allows to pass a user-defined function or function object which checks if Value should be returned by the query. It's generated by:

- `boost::geometry::index::satisfies()`.

Nearest predicate

If the nearest predicate is passed a k-nearest neighbor search will be performed. This query will result in returning k values to the output iterator. Only one nearest predicate may be passed to the query. It may be generated by:

- `boost::geometry::index::nearest()`.

Connecting predicates

Predicates may be passed together connected with ``operator&&()``.

###### Synopsis

    template<typename Predicates, typename OutIter>
    size_type query(Predicates const & predicates, OutIter out_it)

###### Modifier(s)

    const

###### Parameter(s)

Type | Name | Description
--- | --- | ---
`Predicates const &` | `predicates` | Predicates.
`OutIter` | `out_it` | The output iterator, e.g. generated by std::back_inserter().

###### Returns

The number of values found.

###### Example

    // return elements intersecting box
    tree.query(bgi::intersects(box), std::back_inserter(result));
    // return elements intersecting poly but not within box
    tree.query(bgi::intersects(poly) && !bgi::within(box), std::back_inserter(result));
    // return elements overlapping box and meeting my_fun unary predicate
    tree.query(bgi::overlaps(box) && bgi::satisfies(my_fun), std::back_inserter(result));
    // return 5 elements nearest to pt and elements are intersecting box
    tree.query(bgi::nearest(pt, 5) && bgi::intersects(box), std::back_inserter(result));

    // For each found value do_something (it is a type of function object)
    tree.query(bgi::intersects(box),
               boost::make_function_output_iterator(do_something()));

    // For each value stored in the rtree do_something
    // always_true is a type of function object always returning true
    tree.query(bgi::satisfies(always_true()),
               boost::make_function_output_iterator(do_something()));

    // C++11 (lambda expression)
    tree.query(bgi::intersects(box),
               boost::make_function_output_iterator([](value_type const& val){
                   // do something
               }));

    // C++14 (generic lambda expression)
    tree.query(bgi::intersects(box),
               boost::make_function_output_iterator([](auto const& val){
                   // do something
               }));

###### Throws

If Value copy constructor or copy assignment throws. If predicates copy throws.

| Warning
Only one `nearest()` perdicate may be passed to the query. Passing more of them results in compile-time error.