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