MySQL  8.0.26
Source Code Documentation
relops.h
Go to the documentation of this file.
1 #ifndef SQL_GIS_RELOPS_H_INCLUDED
2 #define SQL_GIS_RELOPS_H_INCLUDED
3 
4 // Copyright (c) 2017, 2021, Oracle and/or its affiliates.
5 //
6 // This program is free software; you can redistribute it and/or modify
7 // it under the terms of the GNU General Public License, version 2.0,
8 // as published by the Free Software Foundation.
9 //
10 // This program is also distributed with certain software (including
11 // but not limited to OpenSSL) that is licensed under separate terms,
12 // as designated in a particular file or component or in included license
13 // documentation. The authors of MySQL hereby grant you an additional
14 // permission to link the program and your derivative works with the
15 // separately licensed software that they have included with MySQL.
16 //
17 // This program is distributed in the hope that it will be useful,
18 // but WITHOUT ANY WARRANTY; without even the implied warranty of
19 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 // GNU General Public License, version 2.0, for more details.
21 //
22 // You should have received a copy of the GNU General Public License
23 // along with this program; if not, write to the Free Software
24 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
25 
26 /// @file
27 ///
28 /// This file declares the interface of relational GIS operations. These are
29 /// boolean operations that compute relations between geometries.
30 
31 #include "sql/dd/types/spatial_reference_system.h" // dd::Spatial_reference_system
32 #include "sql/gis/geometries.h"
33 
34 namespace gis {
35 
36 /// Computes the crosses relation between two geometries.
37 ///
38 /// Both geometries must be in the same coordinate system (Cartesian or
39 /// geographic), and the coordinate system of the geometries must match
40 /// the coordinate system of the SRID. It is the caller's responsibility
41 /// to guarantee this.
42 ///
43 /// @param[in] srs The spatial reference system, common to both geometries.
44 /// @param[in] g1 First geometry.
45 /// @param[in] g2 Second geometry.
46 /// @param[in] func_name Function name used in error reporting.
47 /// @param[out] crosses Whether g1 crosses g2.
48 /// @param[out] null True if the return value is NULL.
49 ///
50 /// @retval false Success.
51 /// @retval true An error has occurred. The error has been reported with
52 /// my_error().
53 bool crosses(const dd::Spatial_reference_system *srs, const Geometry *g1,
54  const Geometry *g2, const char *func_name, bool *crosses,
55  bool *null) noexcept;
56 
57 /// Computes the disjoint relation between two geometries.
58 ///
59 /// Both geometries must be in the same coordinate system (Cartesian or
60 /// geographic), and the coordinate system of the geometries must match
61 /// the coordinate system of the SRID. It is the caller's responsibility
62 /// to guarantee this.
63 ///
64 /// @param[in] srs The spatial reference system, common to both geometries.
65 /// @param[in] g1 First geometry.
66 /// @param[in] g2 Second geometry.
67 /// @param[in] func_name Function name used in error reporting.
68 /// @param[out] disjoint Whether g1 is disjoint from g2.
69 /// @param[out] null True if the return value is NULL.
70 ///
71 /// @retval false Success.
72 /// @retval true An error has occurred. The error has been reported with
73 /// my_error().
74 bool disjoint(const dd::Spatial_reference_system *srs, const Geometry *g1,
75  const Geometry *g2, const char *func_name, bool *disjoint,
76  bool *null) noexcept;
77 
78 /// Computes the equals relation between two geometries.
79 ///
80 /// Both geometries must be in the same coordinate system (Cartesian or
81 /// geographic), and the coordinate system of the geometries must match
82 /// the coordinate system of the SRID. It is the caller's responsibility
83 /// to guarantee this.
84 ///
85 /// @param[in] srs The spatial reference system, common to both geometries.
86 /// @param[in] g1 First geometry.
87 /// @param[in] g2 Second geometry.
88 /// @param[in] func_name Function name used in error reporting.
89 /// @param[out] equals Whether g1 equals g2.
90 /// @param[out] null True if the return value is NULL.
91 ///
92 /// @retval false Success.
93 /// @retval true An error has occurred. The error has been reported with
94 /// my_error().
95 bool equals(const dd::Spatial_reference_system *srs, const Geometry *g1,
96  const Geometry *g2, const char *func_name, bool *equals,
97  bool *null) noexcept;
98 
99 /// Computes the intersects relation between two geometries.
100 ///
101 /// Both geometries must be in the same coordinate system (Cartesian or
102 /// geographic), and the coordinate system of the geometries must match
103 /// the coordinate system of the SRID. It is the caller's responsibility
104 /// to guarantee this.
105 ///
106 /// @param[in] srs The spatial reference system, common to both geometries.
107 /// @param[in] g1 First geometry.
108 /// @param[in] g2 Second geometry.
109 /// @param[in] func_name Function name used in error reporting.
110 /// @param[out] intersects Whether g1 intersects g2.
111 /// @param[out] null True if the return value is NULL.
112 ///
113 /// @retval false Success.
114 /// @retval true An error has occurred. The error has been reported with
115 /// my_error().
116 bool intersects(const dd::Spatial_reference_system *srs, const Geometry *g1,
117  const Geometry *g2, const char *func_name, bool *intersects,
118  bool *null) noexcept;
119 
120 /// Computes the covered by relation between the minimum bounding rectangles of
121 /// two geometries.
122 ///
123 /// Both geometries must be in the same coordinate system (Cartesian or
124 /// geographic), and the coordinate system of the geometries must match
125 /// the coordinate system of the SRID. It is the caller's responsibility
126 /// to guarantee this.
127 ///
128 /// @param[in] srs The spatial reference system, common to both geometries.
129 /// @param[in] g1 First geometry.
130 /// @param[in] g2 Second geometry.
131 /// @param[in] func_name Function name used in error reporting.
132 /// @param[out] covered_by Whether the MBR of g1 is covered by the MBR of g2.
133 /// @param[out] null True if the return value is NULL.
134 ///
135 /// @retval false Success.
136 /// @retval true An error has occurred. The error has been reported with
137 /// my_error().
138 bool mbr_covered_by(const dd::Spatial_reference_system *srs, const Geometry *g1,
139  const Geometry *g2, const char *func_name, bool *covered_by,
140  bool *null) noexcept;
141 
142 /// Computes the disjoint relation between the minimum bounding rectangles of
143 /// two geometries.
144 ///
145 /// Both geometries must be in the same coordinate system (Cartesian or
146 /// geographic), and the coordinate system of the geometries must match
147 /// the coordinate system of the SRID. It is the caller's responsibility
148 /// to guarantee this.
149 ///
150 /// @param[in] srs The spatial reference system, common to both geometries.
151 /// @param[in] g1 First geometry.
152 /// @param[in] g2 Second geometry.
153 /// @param[in] func_name Function name used in error reporting.
154 /// @param[out] disjoint Whether the MBR of g1 is disjoint from the MBR of g2.
155 /// @param[out] null True if the return value is NULL.
156 ///
157 /// @retval false Success.
158 /// @retval true An error has occurred. The error has been reported with
159 /// my_error().
160 bool mbr_disjoint(const dd::Spatial_reference_system *srs, const Geometry *g1,
161  const Geometry *g2, const char *func_name, bool *disjoint,
162  bool *null) noexcept;
163 
164 /// Computes the equals relation between the minimum bounding rectangles of
165 /// two geometries.
166 ///
167 /// Both geometries must be in the same coordinate system (Cartesian or
168 /// geographic), and the coordinate system of the geometries must match
169 /// the coordinate system of the SRID. It is the caller's responsibility
170 /// to guarantee this.
171 ///
172 /// @param[in] srs The spatial reference system, common to both geometries.
173 /// @param[in] g1 First geometry.
174 /// @param[in] g2 Second geometry.
175 /// @param[in] func_name Function name used in error reporting.
176 /// @param[out] equals Whether the MBR of g1 equals the MBR of g2.
177 /// @param[out] null True if the return value is NULL.
178 ///
179 /// @retval false Success.
180 /// @retval true An error has occurred. The error has been reported with
181 /// my_error().
182 bool mbr_equals(const dd::Spatial_reference_system *srs, const Geometry *g1,
183  const Geometry *g2, const char *func_name, bool *equals,
184  bool *null) noexcept;
185 
186 /// Computes the intersects relation between the minimum bounding rectangles of
187 /// two geometries.
188 ///
189 /// Both geometries must be in the same coordinate system (Cartesian or
190 /// geographic), and the coordinate system of the geometries must match
191 /// the coordinate system of the SRID. It is the caller's responsibility
192 /// to guarantee this.
193 ///
194 /// @param[in] srs The spatial reference system, common to both geometries.
195 /// @param[in] g1 First geometry.
196 /// @param[in] g2 Second geometry.
197 /// @param[in] func_name Function name used in error reporting.
198 /// @param[out] intersects Whether the MBR of g1 intersects the MBR of g2.
199 /// @param[out] null True if the return value is NULL.
200 ///
201 /// @retval false Success.
202 /// @retval true An error has occurred. The error has been reported with
203 /// my_error().
204 bool mbr_intersects(const dd::Spatial_reference_system *srs, const Geometry *g1,
205  const Geometry *g2, const char *func_name, bool *intersects,
206  bool *null) noexcept;
207 
208 /// Computes the overlaps relation between the minimum bounding rectangles of
209 /// two geometries.
210 ///
211 /// Both geometries must be in the same coordinate system (Cartesian or
212 /// geographic), and the coordinate system of the geometries must match
213 /// the coordinate system of the SRID. It is the caller's responsibility
214 /// to guarantee this.
215 ///
216 /// @param[in] srs The spatial reference system, common to both geometries.
217 /// @param[in] g1 First geometry.
218 /// @param[in] g2 Second geometry.
219 /// @param[in] func_name Function name used in error reporting.
220 /// @param[out] overlaps Whether the MBR of g1 overlaps the MBR of g2.
221 /// @param[out] null True if the return value is NULL.
222 ///
223 /// @retval false Success.
224 /// @retval true An error has occurred. The error has been reported with
225 /// my_error().
226 bool mbr_overlaps(const dd::Spatial_reference_system *srs, const Geometry *g1,
227  const Geometry *g2, const char *func_name, bool *overlaps,
228  bool *null) noexcept;
229 
230 /// Computes the touches relation between the minimum bounding rectangles of
231 /// two geometries.
232 ///
233 /// Both geometries must be in the same coordinate system (Cartesian or
234 /// geographic), and the coordinate system of the geometries must match
235 /// the coordinate system of the SRID. It is the caller's responsibility
236 /// to guarantee this.
237 ///
238 /// @param[in] srs The spatial reference system, common to both geometries.
239 /// @param[in] g1 First geometry.
240 /// @param[in] g2 Second geometry.
241 /// @param[in] func_name Function name used in error reporting.
242 /// @param[out] touches Whether the MBR of g1 touches the MBR of g2.
243 /// @param[out] null True if the return value is NULL.
244 ///
245 /// @retval false Success.
246 /// @retval true An error has occurred. The error has been reported with
247 /// my_error().
248 bool mbr_touches(const dd::Spatial_reference_system *srs, const Geometry *g1,
249  const Geometry *g2, const char *func_name, bool *touches,
250  bool *null) noexcept;
251 
252 /// Computes the within relation between the minimum bounding rectangles of
253 /// two geometries.
254 ///
255 /// Both geometries must be in the same coordinate system (Cartesian or
256 /// geographic), and the coordinate system of the geometries must match
257 /// the coordinate system of the SRID. It is the caller's responsibility
258 /// to guarantee this.
259 ///
260 /// @param[in] srs The spatial reference system, common to both geometries.
261 /// @param[in] g1 First geometry.
262 /// @param[in] g2 Second geometry.
263 /// @param[in] func_name Function name used in error reporting.
264 /// @param[out] within Whether the MBR of g1 is within the MBR of g2.
265 /// @param[out] null True if the return value is NULL.
266 ///
267 /// @retval false Success.
268 /// @retval true An error has occurred. The error has been reported with
269 /// my_error().
270 bool mbr_within(const dd::Spatial_reference_system *srs, const Geometry *g1,
271  const Geometry *g2, const char *func_name, bool *within,
272  bool *null) noexcept;
273 
274 /// Computes the overlaps relation between two geometries.
275 ///
276 /// Both geometries must be in the same coordinate system (Cartesian or
277 /// geographic), and the coordinate system of the geometries must match
278 /// the coordinate system of the SRID. It is the caller's responsibility
279 /// to guarantee this.
280 ///
281 /// @param[in] srs The spatial reference system, common to both geometries.
282 /// @param[in] g1 First geometry.
283 /// @param[in] g2 Second geometry.
284 /// @param[in] func_name Function name used in error reporting.
285 /// @param[out] overlaps Whether g1 overlaps g2.
286 /// @param[out] null True if the return value is NULL.
287 ///
288 /// @retval false Success.
289 /// @retval true An error has occurred. The error has been reported with
290 /// my_error().
291 bool overlaps(const dd::Spatial_reference_system *srs, const Geometry *g1,
292  const Geometry *g2, const char *func_name, bool *overlaps,
293  bool *null) noexcept;
294 
295 /// Computes the touches relation between two geometries.
296 ///
297 /// Both geometries must be in the same coordinate system (Cartesian or
298 /// geographic), and the coordinate system of the geometries must match
299 /// the coordinate system of the SRID. It is the caller's responsibility
300 /// to guarantee this.
301 ///
302 /// @param[in] srs The spatial reference system, common to both geometries.
303 /// @param[in] g1 First geometry.
304 /// @param[in] g2 Second geometry.
305 /// @param[in] func_name Function name used in error reporting.
306 /// @param[out] touches Whether g1 touches g2.
307 /// @param[out] null True if the return value is NULL.
308 ///
309 /// @retval false Success.
310 /// @retval true An error has occurred. The error has been reported with
311 /// my_error().
312 bool touches(const dd::Spatial_reference_system *srs, const Geometry *g1,
313  const Geometry *g2, const char *func_name, bool *touches,
314  bool *null) noexcept;
315 
316 /// Computes the within relation between two geometries.
317 ///
318 /// Both geometries must be in the same coordinate system (Cartesian or
319 /// geographic), and the coordinate system of the geometries must match
320 /// the coordinate system of the SRID. It is the caller's responsibility
321 /// to guarantee this.
322 ///
323 /// @param[in] srs The spatial reference system, common to both geometries.
324 /// @param[in] g1 First geometry.
325 /// @param[in] g2 Second geometry.
326 /// @param[in] func_name Function name used in error reporting.
327 /// @param[out] within Whether g1 lies within g2.
328 /// @param[out] null True if the return value is NULL.
329 ///
330 /// @retval false Success.
331 /// @retval true An error has occurred. The error has been reported with
332 /// my_error().
333 bool within(const dd::Spatial_reference_system *srs, const Geometry *g1,
334  const Geometry *g2, const char *func_name, bool *within,
335  bool *null) noexcept;
336 
337 } // namespace gis
338 
339 #endif // SQL_GIS_RELOPS_H_INCLUDED
Definition: spatial.h:214
Definition: spatial_reference_system.h:52
This file declares the geometry class hierarchy used by the server as the internal representation of ...
Definition: area.cc:46
bool mbr_equals(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *equals, bool *null) noexcept
Computes the equals relation between the minimum bounding rectangles of two geometries.
Definition: equals.cc:772
bool overlaps(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *overlaps, bool *null) noexcept
Computes the overlaps relation between two geometries.
Definition: overlaps.cc:810
bool equals(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *equals, bool *null) noexcept
Computes the equals relation between two geometries.
Definition: equals.cc:739
bool disjoint(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *disjoint, bool *null) noexcept
Computes the disjoint relation between two geometries.
Definition: disjoint.cc:645
bool intersects(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *intersects, bool *null) noexcept
Computes the intersects relation between two geometries.
Definition: intersects.cc:639
bool within(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *within, bool *null) noexcept
Computes the within relation between two geometries.
Definition: within.cc:1346
bool mbr_intersects(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *intersects, bool *null) noexcept
Computes the intersects relation between the minimum bounding rectangles of two geometries.
Definition: intersects.cc:663
bool touches(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *touches, bool *null) noexcept
Computes the touches relation between two geometries.
Definition: touches.cc:1228
bool crosses(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *crosses, bool *null) noexcept
Computes the crosses relation between two geometries.
Definition: crosses.cc:868
bool mbr_disjoint(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *disjoint, bool *null) noexcept
Computes the disjoint relation between the minimum bounding rectangles of two geometries.
Definition: disjoint.cc:669
bool mbr_overlaps(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *overlaps, bool *null) noexcept
Computes the overlaps relation between the minimum bounding rectangles of two geometries.
Definition: overlaps.cc:837
bool mbr_within(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *within, bool *null) noexcept
Computes the within relation between the minimum bounding rectangles of two geometries.
Definition: within.cc:1370
bool mbr_touches(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *touches, bool *null) noexcept
Computes the touches relation between the minimum bounding rectangles of two geometries.
Definition: touches.cc:1255
bool mbr_covered_by(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, const char *func_name, bool *covered_by, bool *null) noexcept
Computes the covered by relation between the minimum bounding rectangles of two geometries.
Definition: covered_by.cc:86