[1.9.x] Fixed #25740 -- Documented GEOSGeometry operators.

Backport of 479ba5add23c119387baa60d5dce3a4e17d1b15b from master

1 files changed, 29 insertions, 0 deletions

diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt
index d539b2cbb9..9d7a77a015 100644
--- a/docs/ref/contrib/gis/geos.txt
+++ b/docs/ref/contrib/gis/geos.txt
@@ -141,6 +141,35 @@ just like a Python list::
     >>> line.coords
     ((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0))
 
+Geometries support set-like operators::
+
+    >>> from django.contrib.gis.geos import LineString
+    >>> ls1 = LineString((0, 0), (2, 2))
+    >>> ls2 = LineString((1, 1), (3, 3))
+    >>> print(ls1 | ls2)  # equivalent to `ls1.union(ls2)`
+    MULTILINESTRING ((0 0, 1 1), (1 1, 2 2), (2 2, 3 3))
+    >>> print(ls1 & ls2)  # equivalent to `ls1.intersection(ls2)`
+    LINESTRING (1 1, 2 2)
+    >>> print(ls1 - ls2)  # equivalent to `ls1.difference(ls2)`
+    LINESTRING(0 0, 1 1)
+    >>> print(ls1 ^ ls2)  # equivalent to `ls1.sym_difference(ls2)`
+    MULTILINESTRING ((0 0, 1 1), (2 2, 3 3))
+
+.. admonition:: Equality operator doesn't check spatial equality
+
+    The :class:`~GEOSGeometry` equality operator uses
+    :meth:`~GEOSGeometry.equals_exact`, not :meth:`~GEOSGeometry.equals`, i.e.
+    it requires the compared geometries to have the same coordinates in the
+    same positions::
+
+      >>> from django.contrib.gis.geos import LineString
+      >>> ls1 = LineString((0, 0), (1, 1))
+      >>> ls2 = LineString((1, 1), (0, 0))
+      >>> ls1.equals(ls2)
+      True
+      >>> ls1 == ls2
+      False
+
 Geometry Objects
 ================