Description

Renvoie TRUE si la géométrie A contient la géométrie B. A contient B si et seulement si tous les points de B se trouvent à l'intérieur (c'est-à-dire à l'intérieur ou à la limite) de A (ou, de manière équivalente, si aucun point de B ne se trouve à l'extérieur de A), et si les intérieurs de A et de B ont au moins un point en commun.

In mathematical terms: ST_Contains(A, B) ⇔ (A ⋂ B = B) ∧ (Int(A) ⋂ Int(B) ≠ ∅)

La relation contains est réflexive : toute géométrie se contient elle-même. (En revanche, dans le prédicat ST_ContainsProperly, une géométrie ne se contientpas elle-même correctement). La relation est antisymétrique : si ST_Contains(A,B) = true et ST_Contains(B,A) = true, alors les deux géométries doivent être topologiquement égales (ST_Equals(A,B) = true).

ST_Contains est le contraire de ST_Within. Ainsi, ST_Contains(A,B) = ST_Within(B,A).

	Comme les intérieurs doivent avoir un point commun, une subtilité de la définition est que les polygones et les lignes ne contiennent pas de lignes et de points se trouvant entièrement dans leur limite. Pour plus de détails, voir Subtleties of OGC Covers, Contains, Within. Le prédicat ST_Covers fournit une relation plus inclusive.

	Cette fonction inclut une comparaison de la boîte englobante qui utilise tous les index disponibles sur les géométries. Pour éviter l'utilisation d'un index, utilisez la fonction _ST_Contains.

Effectué par le module GEOS

Amélioré : 2.3.0 Amélioration du court-circuit PIP étendu à la prise en charge des multipoints avec peu de points. Les versions précédentes ne prenaient en charge que les points dans les polygones.

	Amélioration : 3.0.0 a permis la prise en charge de GEOMETRYCOLLECTION

	N'utilisez pas cette fonction avec des géométries non valides. Vous obtiendrez des résultats inattendus.

NOTE : il s'agit de la version "autorisée" qui renvoie un booléen et non un entier.

Cette méthode implémente la spécification OGC Simple Features Implementation Specification for SQL 1.1.

s2.1.1.2 // s2.1.13.3 - identique à within(geometry B, geometry A)

Cette méthode implémente la spécification SQL/MM.

SQL-MM 3: 5.1.31

Exemples

ST_Contains renvoie TRUE dans les situations suivantes :

LINESTRING / MULTIPOINT	POLYGON / POINT
POLYGON / LINESTRING	POLYGON / POLYGON

La ST_Contains renvoie FALSE dans les situations suivantes :

POLYGON / MULTIPOINT

POLYGON / LINESTRING

En raison de la condition d'intersection intérieure, la ST_Contains renvoie FALSE dans les situations suivantes (alors que la ST_Covers renvoie TRUE) :

LINESTRING / POINT

POLYGON / LINESTRING

-- A circle within a circle
SELECT ST_Contains(smallc, bigc) As smallcontainsbig,
     ST_Contains(bigc,smallc) As bigcontainssmall,
     ST_Contains(bigc, ST_Union(smallc, bigc)) as bigcontainsunion,
     ST_Equals(bigc, ST_Union(smallc, bigc)) as bigisunion,
     ST_Covers(bigc, ST_ExteriorRing(bigc)) As bigcoversexterior,
     ST_Contains(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
  smallcontainsbig | bigcontainssmall | bigcontainsunion | bigisunion | bigcoversexterior | bigcontainsexterior
------------------+------------------+------------------+------------+-------------------+---------------------
 f                | t                | t                | 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

 

Voir aussi

ST_Boundary, ST_ContainsProperly, ST_Covers, ST_CoveredBy, ST_Equals, ST_Within