ST_ContainsProperly

Description

Returns true if B intersects the interior of A but not the boundary (or exterior).

A does not contain properly itself, but does contain itself.

Every point of the other geometry is a point of this geometry's interior. The DE-9IM Intersection Matrix for the two geometries matches [T**FF*FF*] used in ST_Relate

From JTS docs slightly reworded: The advantage to using this predicate over ST_Contains and ST_Intersects is that it can be computed efficiently, with no need to compute topology at individual points. An example use case for this predicate is computing the intersections of a set of geometries with a large polygonal geometry. Since intersection is a fairly slow operation, it can be more efficient to use containsProperly to filter out test geometries which lie wholly inside the area. In these cases the intersection is known a priori to be exactly the original test geometry.

Availability: 1.4.0 - requires GEOS >= 3.1.0.

	Do not call with a GEOMETRYCOLLECTION as an argument

	Do not use this function with invalid geometries. You will get unexpected results.

This function call will automatically include a bounding box comparison that will make use of any indexes that are available on the geometries. To avoid index use, use the function _ST_ContainsProperly.

Examples

	--a circle within a circle
	SELECT ST_ContainsProperly(smallc, bigc) As smallcontainspropbig,
	ST_ContainsProperly(bigc,smallc) As bigcontainspropsmall,
	ST_ContainsProperly(bigc, ST_Union(smallc, bigc)) as bigcontainspropunion,
	ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion,
	ST_Covers(bigc, ST_ExteriorRing(bigc)) As bigcoversexterior,
	ST_ContainsProperly(bigc, ST_ExteriorRing(bigc)) As bigcontainsexterior
	FROM (SELECT ST_Buffer(ST_GeomFromText('POINT(1 2)'), 10) As smallc,
	ST_Buffer(ST_GeomFromText('POINT(1 2)'), 20) As bigc) As foo;
	--Result
  smallcontainspropbig | bigcontainspropsmall | bigcontainspropunion | bigisunion | bigcoversexterior | bigcontainsexterior
------------------+------------------+------------------+------------+-------------------+---------------------
 f                     | t                    | f                    | t          | t                 | f

 --example demonstrating difference between contains and contains properly
 SELECT ST_GeometryType(geomA) As geomtype, ST_Contains(geomA,geomA) AS acontainsa, ST_ContainsProperly(geomA, geomA) AS acontainspropa,
 ST_Contains(geomA, ST_Boundary(geomA)) As acontainsba, ST_ContainsProperly(geomA, ST_Boundary(geomA)) As acontainspropba
 FROM (VALUES ( ST_Buffer(ST_Point(1,1), 5,1) ),
		  ( ST_MakeLine(ST_Point(1,1), ST_Point(-1,-1) ) ),
		  ( ST_Point(1,1) )
	) As foo(geomA);

  geomtype    | acontainsa | acontainspropa | acontainsba | acontainspropba
--------------+------------+----------------+-------------+-----------------
ST_Polygon    | t          | f              | f           | f
ST_LineString | t          | f              | f           | f
ST_Point      | t          | t              | f           | f
 

See Also

ST_GeometryType , ST_Boundary , ST_Contains , ST_Covers , ST_CoveredBy , ST_Equals , ST_Relate , ST_Within