| Home | Libraries | People | FAQ | More

##### covered_by

Checks if the first geometry is inside or on border the second geometry.

###### Description

The free function covered_by checks if the first geometry is inside or on border the second geometry.

###### Synopsis

    template<typename Geometry1, typename Geometry2>
    bool covered_by(Geometry1 const & geometry1, Geometry2 const & geometry2)

###### Parameters

Type | Concept | Name | Description
--- | --- | --- | ---
Geometry1 const & | Any type fulfilling a Geometry Concept | geometry1 | A model of the specified concept which might be inside or on the border of the second geometry
Geometry2 const & | Any type fulfilling a Geometry Concept | geometry2 | A model of the specified concept which might cover the first geometry

###### Returns

true if geometry1 is inside of or on the border of geometry2, else false

###### Header

Either

`#include <boost/geometry.hpp>`

Or

`#include <boost/geometry/algorithms/covered_by.hpp>`

###### Conformance

The function covered_by is not defined by OGC.

| Note
Both PostGIS and Oracle contain an algorithm with the same name and the same functionality. See the PostGIS documentation.

###### Supported geometries

| Point | Segment | Box | Linestring | Ring | Polygon | MultiPoint | MultiLinestring | MultiPolygon | Variant
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
Point |  |  |  |  |  |  |  |  |  |
Segment |  |  |  |  |  |  |  |  |  |
Box |  |  |  |  |  |  |  |  |  |
Linestring |  |  |  |  |  |  |  |  |  |
Ring |  |  |  |  |  |  |  |  |  |
Polygon |  |  |  |  |  |  |  |  |  |
MultiPoint |  |  |  |  |  |  |  |  |  |
MultiLinestring |  |  |  |  |  |  |  |  |  |
MultiPolygon |  |  |  |  |  |  |  |  |  |
Variant |  |  |  |  |  |  |  |  |  |

| Note
In this status matrix above: columns are types of first parameter and rows are types of second parameter. So a point can be checked to be covered by a polygon, but not vice versa.

###### Complexity

Linear

###### See also

- within

| Note
The difference with the `within` algorithm is that this algorithm checks the border by default

###### Examples

Checks if the first geometry is inside or on border the second geometry

    #include <iostream>

    #include <boost/geometry.hpp>
    #include <boost/geometry/geometries/point_xy.hpp>
    #include <boost/geometry/geometries/polygon.hpp>

    namespace bg = boost::geometry;

    int main()
    {
        // Checks if the first geometry is inside or on border the second geometry.
        bg::model::polygon<bg::model::d2::point_xy<double> > poly1;
        bg::read_wkt("POLYGON((0 2,0 3,2 4,1 2,0 2))", poly1);
        bg::model::polygon<bg::model::d2::point_xy<double> > poly2;
        bg::read_wkt("POLYGON((0 4,3 4,2 2,0 1,0 4))", poly2);
        bool check_covered = bg::covered_by(poly1, poly2);
        if (check_covered) {
             std::cout << "Covered: Yes" << std::endl;
        } else {
            std::cout << "Covered: No" << std::endl;
        }

        bg::model::polygon<bg::model::d2::point_xy<double> > poly3;
        bg::read_wkt("POLYGON((-1 -1,-3 -4,-7 -7,-4 -3,-1 -1))", poly3);
        check_covered = bg::covered_by(poly1, poly3);
        if (check_covered) {
             std::cout << "Covered: Yes" << std::endl;
        } else {
            std::cout << "Covered: No" << std::endl;
        }

        // This should return true since both polygons are same, so they are lying on each other.
        check_covered = bg::covered_by(poly1, poly1);
        if (check_covered) {
             std::cout << "Covered: Yes" << std::endl;
        } else {
            std::cout << "Covered: No" << std::endl;
        }

        return 0;
    }

| Convenient namespace alias

Output:

    Covered: Yes

    Covered: No
    Covered: Yes