c++ - What does boost::geometry::intersection return

Question

The documentation for boost::geometry::intersection( https://www.boost.org/doc/libs/1_73_0/libs/geometry/doc/html/geometry/reference/algorithms/intersection/intersection_3.html ) says the function returns a bool. However the docs do NOT say what the return value indicates. I guessed it would return true if an intersection was found.

Wrong!!!

This code

#include <iostream>
#include <deque>
#include <boost/geometry.hpp>
#include <boost/geometry/geometries/register/point.hpp>

namespace bg = boost::geometry;
using namespace std;

class cxy
{
public:
    double x;
    double y;
    cxy( double X, double Y )
        : x( X )
        , y( Y )
    {

    }
    /// boost geometry insists on a default constructor
    cxy()
        : cxy(0,0)
    {

    }
};

BOOST_GEOMETRY_REGISTER_POINT_2D( cxy, double, bg::cs::cartesian, x, y )
typedef bg::model::segment<cxy> segment_t;

int main()
{
    cxy a(1,0);
    cxy b(1,1);
    cxy c(0,0.5);
    cxy d(0.5,0.5) ;

    segment_t ab( a, b );
    segment_t cd( c, d );
    std::vector<cxy> out;
    if( ! bg::intersection( ab, cd, out ) ) {
       std::cout << "intersection returned false
";
       return 1;
    }
    if( ! out.size() ) {
        std::cout << "no intersection point!
";
        return 2;
    }
    std::cout << "intersection at " << out[0].x <<" " << out[0].y << "
";

    return 0;
}

outputs

no intersection point!

What is the return of true indicating?

Answer 1

The return value is true indicating no errors. E.g. deep down the call chain:

template <typename RobustPolicy, typename GeometryOut, typename Strategy>
static inline bool apply(Geometry1 const& geometry1,
        Geometry2 const& geometry2,
        RobustPolicy const& robust_policy,
        GeometryOut& geometry_out,
        Strategy const& strategy)
{
    typedef typename geometry::detail::output_geometry_value
        <
            GeometryOut
        >::type SingleOut;

    intersection_insert
        <
            Geometry1, Geometry2, SingleOut,
            overlay_intersection
        >::apply(geometry1, geometry2, robust_policy,
                 geometry::detail::output_geometry_back_inserter(geometry_out),
                 strategy);

    return true;
}

That's at

#0  0x000055555555598c in boost::geometry::dispatch::intersection<boost::geometry::model::segment<cxy>, boost::geometry::model::segment<cxy>, boost::geometry::segment_tag, boost::geometry::segment_tag, false>::apply<boost::geometry::detail::no_rescale_policy, std::vector<cxy, std::allocator<cxy> >, boost::geometry::strategy::intersection::cartesian_segments<void> > (geometry1=..., geometry2=..., robust_policy=..., geometry_out=std::vector of length 0, capacity 0, strategy=...) at /home/sehe/custom/boost_1_73_0/boost/geometry/algorithms/detail/intersection/interface.hpp:63
#1  0x0000555555555842 in boost::geometry::resolve_strategy::intersection::apply<boost::geometry::model::segment<cxy>, boost::geometry::model::segment<cxy>, std::vector<cxy, std::allocator<cxy> > > (geometry1=..., geometry2=..., geometry_out=std::vector of length 0, capacity 0) at /home/sehe/custom/boost_1_73_0/boost/geometry/algorithms/detail/intersection/interface.hpp:175
#2  0x00005555555556ed in boost::geometry::resolve_variant::intersection<boost::geometry::model::segment<cxy>, boost::geometry::model::segment<cxy> >::apply<std::vector<cxy, std::allocator<cxy> >, boost::geometry::default_strategy> (geometry1=..., geometry2=..., geometry_out=std::vector of length 0, capacity 0, strategy=...) at /home/sehe/custom/boost_1_73_0/boost/geometry/algorithms/detail/intersection/interface.hpp:198
#3  0x00005555555554f3 in boost::geometry::intersection<boost::geometry::model::segment<cxy>, boost::geometry::model::segment<cxy>, std::vector<cxy, std::allocator<cxy> > > (geometry1=..., geometry2=..., geometry_out=std::vector of length 0, capacity 0) at /home/sehe/custom/boost_1_73_0/boost/geometry/algorithms/detail/intersection/interface.hpp:403
#4  0x0000555555554eab in main () at /home/sehe/Projects/stackoverflow/test.cpp:40

I looked at the OGC Simple Feature Specification that Boost Geoetry follows

The library follows existing conventions:

• conventions from boost
• conventions from the std library conventions and
• names from one of the OGC standards on geometry and, more specificly, from the OGC Simple Feature Specification

It conceptually models the algorithm without the return value:

I checked all the implementations in algorithms/detail/intersection (areal_areal.hpp, box_box.hpp, implementation.hpp, interface.hpp, multi.hpp) and nothing returns false.

TL;DR Summary

The return-value is specifically undocumented, in other words: it's an implementation detail you may not depend on.

In terms of the library interface, documented interface may not change (without warning) in new versions. A lot of things that are 'discoverable' through the headers are undocumented - most often indicated by a detail:: namespace and/or detail/ header folder(s).

---