Boost C++ Libraries

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:

It is possible to negate spatial predicates:

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:

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:

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)

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() predicate may be passed to the query. Passing more of them results in compile-time error.