MobilityDB  1.0
temporal_util.h
Go to the documentation of this file.
1 /*****************************************************************************
2  *
3  * This MobilityDB code is provided under The PostgreSQL License.
4  *
5  * Copyright (c) 2016-2021, Université libre de Bruxelles and MobilityDB
6  * contributors
7  *
8  * MobilityDB includes portions of PostGIS version 3 source code released
9  * under the GNU General Public License (GPLv2 or later).
10  * Copyright (c) 2001-2021, PostGIS contributors
11  *
12  * Permission to use, copy, modify, and distribute this software and its
13  * documentation for any purpose, without fee, and without a written
14  * agreement is hereby granted, provided that the above copyright notice and
15  * this paragraph and the following two paragraphs appear in all copies.
16  *
17  * IN NO EVENT SHALL UNIVERSITE LIBRE DE BRUXELLES BE LIABLE TO ANY PARTY FOR
18  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
19  * LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
20  * EVEN IF UNIVERSITE LIBRE DE BRUXELLES HAS BEEN ADVISED OF THE POSSIBILITY
21  * OF SUCH DAMAGE.
22  *
23  * UNIVERSITE LIBRE DE BRUXELLES SPECIFICALLY DISCLAIMS ANY WARRANTIES,
24  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
25  * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON
26  * AN "AS IS" BASIS, AND UNIVERSITE LIBRE DE BRUXELLES HAS NO OBLIGATIONS TO
27  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. 
28  *
29  *****************************************************************************/
30 
36 #ifndef __TEMPORAL_UTIL_H__
37 #define __TEMPORAL_UTIL_H__
38 
39 #include <postgres.h>
40 #include <catalog/pg_type.h>
41 #include <utils/array.h>
42 #if POSTGRESQL_VERSION_NUMBER >= 120000
43 #include <utils/float.h>
44 #endif
45 #include <utils/rangetypes.h>
46 
47 #include "temporal.h"
48 #include "point/postgis.h"
49 
50 /*****************************************************************************/
51 
52 /* Temporal/base types tests */
53 
54 extern bool temporal_type(Oid temptypid);
55 extern void ensure_temporal_base_type(Oid basetypid);
56 extern bool base_type_continuous(Oid basetypid);
57 extern void ensure_base_type_continuous(Temporal *temp);
58 extern bool base_type_byvalue(Oid basetypid);
59 extern int16 base_type_length(Oid basetypid);
60 extern bool talpha_base_type(Oid basetypid);
61 extern bool tnumber_type(Oid temptypid);
62 extern bool tnumber_base_type(Oid basetypid);
63 extern void ensure_tnumber_base_type(Oid basetypid);
64 extern bool tnumber_range_type(Oid rangetype);
65 extern void ensure_tnumber_range_type(Oid rangetype);
66 extern bool tspatial_type(Oid temptypid);
67 extern bool tspatial_base_type(Oid basetypid);
68 extern bool tgeo_base_type(Oid basetypid);
69 extern void ensure_tgeo_base_type(Oid basetypid);
70 extern bool type_has_precomputed_trajectory(Oid basetypid);
71 extern size_t temporal_bbox_size(Oid basetypid);
72 
73 /* Oid functions */
74 
75 extern Oid range_oid_from_base(Oid basetypid);
76 extern Oid temporal_oid_from_base(Oid basetypid);
77 extern Oid base_oid_from_temporal(Oid temptypid);
78 
79 /* Miscellaneous functions */
80 
81 extern size_t double_pad(size_t size);
82 extern Datum datum_copy(Datum value, Oid type);
83 extern double datum_double(Datum d, Oid basetypid);
84 extern char *text2cstring(const text *textptr);
85 
86 /* PostgreSQL call helpers */
87 
88 extern Datum call_input(Oid type, char *str);
89 extern char *call_output(Oid type, Datum value);
90 extern bytea *call_send(Oid type, Datum value);
91 extern Datum call_recv(Oid type, StringInfo buf);
92 extern Datum call_function1(PGFunction func, Datum arg1);
93 extern Datum call_function2(PGFunction func, Datum arg1, Datum arg2);
94 extern Datum call_function3(PGFunction func, Datum arg1, Datum arg2,
95  Datum arg3);
96 extern Datum call_function4(PGFunction func, Datum arg1, Datum arg2,
97  Datum arg3, Datum arg4);
98 
99 extern Datum CallerFInfoFunctionCall4(PGFunction func, FmgrInfo *flinfo,
100  Oid collation, Datum arg1, Datum arg2, Datum arg3, Datum arg4);
101 
102 extern Datum CallerFInfoFunctionCall4(PGFunction func, FmgrInfo *flinfo,
103  Oid collation, Datum arg1, Datum arg2, Datum arg3, Datum arg4);
104 
105 /* Array functions */
106 
107 extern void pfree_array(void **array, int count);
108 extern void pfree_datumarr(Datum *array, int count);
109 extern char *stringarr_to_string(char **strings, int count, int outlen,
110  char *prefix, char open, char close);
111 extern Datum *datumarr_extract(ArrayType *array, int *count);
112 extern TimestampTz *timestamparr_extract(ArrayType *array, int *count);
113 extern Period **periodarr_extract(ArrayType *array, int *count);
114 extern RangeType **rangearr_extract(ArrayType *array, int *count);
115 extern Temporal **temporalarr_extract(ArrayType *array, int *count);
116 
117 extern ArrayType *datumarr_to_array(Datum *values, int count, Oid type);
118 extern ArrayType *timestamparr_to_array(const TimestampTz *times, int count);
119 extern ArrayType *periodarr_to_array(const Period **periods, int count);
120 extern ArrayType *rangearr_to_array(RangeType **ranges, int count, Oid type);
121 extern ArrayType *textarr_to_array(text **textarr, int count);
122 extern ArrayType *temporalarr_to_array(const Temporal **temporal, int count);
123 extern ArrayType *stboxarr_to_array(STBOX *boxarr, int count);
124 
125 /* Sort functions */
126 
127 extern void datumarr_sort(Datum *values, int count, Oid basetypid);
128 extern void timestamparr_sort(TimestampTz *times, int count);
129 extern void double2arr_sort(double2 *doubles, int count);
130 extern void double3arr_sort(double3 *triples, int count);
131 extern void periodarr_sort(Period **periods, int count);
132 extern void rangearr_sort(RangeType **ranges, int count);
133 extern void tinstantarr_sort(TInstant **instants, int count);
134 extern void tsequencearr_sort(TSequence **sequences, int count);
135 
136 /* Remove duplicate functions */
137 
138 extern int datumarr_remove_duplicates(Datum *values, int count,
139  Oid basetypid);
140 extern int timestamparr_remove_duplicates(TimestampTz *values, int count);
141 extern int tinstantarr_remove_duplicates(const TInstant **instants, int count);
142 
143 /* Text functions */
144 
145 extern int text_cmp(text *arg1, text *arg2, Oid collid);
146 
147 /* Arithmetic functions */
148 
149 extern Datum datum_add(Datum l, Datum r, Oid typel, Oid typer);
150 extern Datum datum_sub(Datum l, Datum r, Oid typel, Oid typer);
151 extern Datum datum_mult(Datum l, Datum r, Oid typel, Oid typer);
152 extern Datum datum_div(Datum l, Datum r, Oid typel, Oid typer);
153 
154 /* Comparison functions on datums */
155 
156 extern bool datum_eq(Datum l, Datum r, Oid type);
157 extern bool datum_ne(Datum l, Datum r, Oid type);
158 extern bool datum_lt(Datum l, Datum r, Oid type);
159 extern bool datum_le(Datum l, Datum r, Oid type);
160 extern bool datum_gt(Datum l, Datum r, Oid type);
161 extern bool datum_ge(Datum l, Datum r, Oid type);
162 
163 extern bool datum_eq2(Datum l, Datum r, Oid typel, Oid typer);
164 extern bool datum_ne2(Datum l, Datum r, Oid typel, Oid typer);
165 extern bool datum_lt2(Datum l, Datum r, Oid typel, Oid typer);
166 extern bool datum_le2(Datum l, Datum r, Oid typel, Oid typer);
167 extern bool datum_gt2(Datum l, Datum r, Oid typel, Oid typer);
168 extern bool datum_ge2(Datum l, Datum r, Oid typel, Oid typer);
169 
170 extern Datum datum2_eq2(Datum l, Datum r, Oid typel, Oid typer);
171 extern Datum datum2_ne2(Datum l, Datum r, Oid typel, Oid typer);
172 extern Datum datum2_lt2(Datum l, Datum r, Oid typel, Oid typer);
173 extern Datum datum2_le2(Datum l, Datum r, Oid typel, Oid typer);
174 extern Datum datum2_gt2(Datum l, Datum r, Oid typel, Oid typer);
175 extern Datum datum2_ge2(Datum l, Datum r, Oid typel, Oid typer);
176 
177 /* Hypothenuse functions */
178 
179 extern double hypot3d(double x, double y, double z);
180 extern double hypot4d(double x, double y, double z, double m);
181 
182 /*****************************************************************************/
183 
184 #endif
Datum * datumarr_extract(ArrayType *array, int *count)
Extract a C array from a PostgreSQL array containing datums.
Definition: temporal_util.c:1010
bool datum_ne2(Datum l, Datum r, Oid typel, Oid typer)
Returns true if the two values are different.
Definition: temporal_util.c:509
Structure to represent periods.
Definition: timetypes.h:52
bool datum_ne(Datum l, Datum r, Oid type)
Returns true if the two values are different.
Definition: temporal_util.c:415
int timestamparr_remove_duplicates(TimestampTz *values, int count)
Remove duplicates from an array of timestamps.
Definition: temporal_util.c:1338
bool tnumber_type(Oid temptypid)
Returns true if the Oid is a temporal number type.
Definition: temporal_util.c:177
int text_cmp(text *arg1, text *arg2, Oid collid)
Comparison function for text values.
Definition: temporal_util.c:1372
ArrayType * periodarr_to_array(const Period **periods, int count)
Convert a C array of periods into a PostgreSQL array.
Definition: temporal_util.c:1094
void pfree_array(void **array, int count)
Free a C array of pointers.
Definition: temporal_util.c:958
void timestamparr_sort(TimestampTz *times, int count)
Sort function for timestamps.
Definition: temporal_util.c:1247
void rangearr_sort(RangeType **ranges, int count)
Sort function for ranges.
Definition: temporal_util.c:1289
void ensure_temporal_base_type(Oid basetypid)
Ensures that the Oid is a base type supported by MobilityDB.
Definition: temporal_util.c:80
bool datum_ge2(Datum l, Datum r, Oid typel, Oid typer)
Returns true if the first value is greater than or equal to the second one.
Definition: temporal_util.c:571
void tsequencearr_sort(TSequence **sequences, int count)
Sort function for temporal sequences.
Definition: temporal_util.c:1309
void ensure_tnumber_base_type(Oid basetypid)
Returns true if the Oid is a number base type supported by MobilityDB.
Definition: temporal_util.c:199
Period ** periodarr_extract(ArrayType *array, int *count)
Extract a C array from a PostgreSQL array containing periods.
Definition: temporal_util.c:1035
Datum datum2_ge2(Datum l, Datum r, Oid typel, Oid typer)
Returns a Datum true if the first value is greater than or equal to the second one.
Definition: temporal_util.c:627
void pfree_datumarr(Datum *array, int count)
Free a C array of Datum pointers.
Definition: temporal_util.c:970
Structure to represent the common structure of temporal values of any temporal subtype.
Definition: temporal.h:241
void periodarr_sort(Period **periods, int count)
Sort function for double2 This function is currently not used void double2arr_sort(double2 *doubles...
Definition: temporal_util.c:1279
Oid base_oid_from_temporal(Oid temptypid)
Returns the Oid of the base type corresponding to the Oid of the temporal type.
Definition: temporal_util.c:376
Datum call_function4(PGFunction func, Datum arg1, Datum arg2, Datum arg3, Datum arg4)
Datum call_function2(PGFunction func, Datum arg1, Datum arg2)
Call PostgreSQL function with 2 arguments.
Definition: temporal_util.c:846
Datum datum_sub(Datum l, Datum r, Oid typel, Oid typer)
Returns the subtraction of the two numbers.
Definition: temporal_util.c:1421
double hypot4d(double x, double y, double z, double m)
Determine the 4D hypotenuse.
Definition: temporal_util.c:1558
bytea * call_send(Oid type, Datum value)
Call send function of the base type.
Definition: temporal_util.c:730
ArrayType * datumarr_to_array(Datum *values, int count, Oid type)
Convert a C array of datums into a PostgreSQL array.
Definition: temporal_util.c:1067
double hypot3d(double x, double y, double z)
Determine the 3D hypotenuse.
Definition: temporal_util.c:1507
Structure to represent spatiotemporal boxes.
Definition: stbox.h:51
Datum datum_div(Datum l, Datum r, Oid typel, Oid typer)
Returns the division of the two numbers.
Definition: temporal_util.c:1469
bool temporal_type(Oid temptypid)
Returns true if the Oid is a EXTERNAL temporal type.
Definition: temporal_util.c:66
void ensure_tgeo_base_type(Oid basetypid)
Ensures that the Oid is a point base type supported by MobilityDB.
Definition: temporal_util.c:276
Datum call_function3(PGFunction func, Datum arg1, Datum arg2, Datum arg3)
Call PostgreSQL function with 3 arguments.
Definition: temporal_util.c:868
bool datum_eq(Datum l, Datum r, Oid type)
Returns true if the two values are equal.
Definition: temporal_util.c:406
size_t double_pad(size_t size)
Align to double.
Definition: temporal_util.c:640
bool base_type_byvalue(Oid basetypid)
Returns true if the values of the type are passed by value.
Definition: temporal_util.c:125
size_t temporal_bbox_size(Oid basetypid)
Returns the size of the bounding box.
Definition: temporal_util.c:313
ArrayType * stboxarr_to_array(STBOX *boxarr, int count)
Convert a C array of spatiotemporal boxes into a PostgreSQL array.
Definition: temporal_util.c:1143
Datum call_input(Oid type, char *str)
Call input function of the base type.
Definition: temporal_util.c:702
void double2arr_sort(double2 *doubles, int count)
Structure to represent values of the internal type for computing aggregates for temporal number types...
Definition: temporal.h:318
int tinstantarr_remove_duplicates(const TInstant **instants, int count)
Remove duplicates from an array of temporal instants.
Definition: temporal_util.c:1352
void tinstantarr_sort(TInstant **instants, int count)
Sort function for temporal instants.
Definition: temporal_util.c:1299
ArrayType * rangearr_to_array(RangeType **ranges, int count, Oid type)
Convert a C array of ranges into a PostgreSQL array.
Definition: temporal_util.c:1106
void ensure_base_type_continuous(Temporal *temp)
Ensures that the Oid is an internal or external base type that is continuous.
Definition: temporal_util.c:110
Datum datum_copy(Datum value, Oid type)
Copy a Datum if it is passed by reference.
Definition: temporal_util.c:651
bool base_type_continuous(Oid basetypid)
Returns true if the Oid corresponds to a continuous base type.
Definition: temporal_util.c:96
Basic functions for temporal types of any subtype.
bool datum_gt2(Datum l, Datum r, Oid typel, Oid typer)
Returns true if the first value is greater than the second one.
Definition: temporal_util.c:562
bool datum_eq2(Datum l, Datum r, Oid typel, Oid typer)
Returns true if the first value is greater than or equal to the second one This function is currently...
Definition: temporal_util.c:469
Temporal ** temporalarr_extract(ArrayType *array, int *count)
Extract a C array from a PostgreSQL array containing temporal values.
Definition: temporal_util.c:1053
bool tnumber_range_type(Oid rangetype)
Returns true if the Oid is a temporal number type.
Definition: temporal_util.c:212
Oid range_oid_from_base(Oid basetypid)
Returns the Oid of the range type corresponding to the Oid of the base type.
Definition: temporal_util.c:336
char * text2cstring(const text *textptr)
Convert a text value into a C string.
Definition: temporal_util.c:685
bool talpha_base_type(Oid basetypid)
Returns true if the Oid is a alpha base type (i.e., those whose bounding box is a period) supported b...
Definition: temporal_util.c:164
Datum datum_add(Datum l, Datum r, Oid typel, Oid typer)
Returns the addition of the two numbers.
Definition: temporal_util.c:1397
bool tspatial_type(Oid temptypid)
Returns true if the Oid is a spatiotemporal type.
Definition: temporal_util.c:238
bool datum_lt(Datum l, Datum r, Oid type)
Returns true if the first value is less than the second one.
Definition: temporal_util.c:424
Datum datum2_lt2(Datum l, Datum r, Oid typel, Oid typer)
Returns a Datum true if the first value is less than the second one.
Definition: temporal_util.c:600
void datumarr_sort(Datum *values, int count, Oid basetypid)
Sort function for datums.
Definition: temporal_util.c:1237
int16 base_type_length(Oid basetypid)
Returns the length of type.
Definition: temporal_util.c:141
Datum datum2_ne2(Datum l, Datum r, Oid typel, Oid typer)
Returns a Datum true if the two values are different.
Definition: temporal_util.c:591
bool datum_ge(Datum l, Datum r, Oid type)
bool datum_gt(Datum l, Datum r, Oid type)
Returns true if the first value is greater than the second one.
Definition: temporal_util.c:442
bool tnumber_base_type(Oid basetypid)
Test whether the Oid is a number base type supported by MobilityDB.
Definition: temporal_util.c:188
PostGIS definitions that are needed in MobilityDB but are not exported in PostGIS headers...
void double3arr_sort(double3 *triples, int count)
Datum call_function1(PGFunction func, Datum arg1)
Call PostgreSQL function with 1 argument.
Definition: temporal_util.c:826
Oid temporal_oid_from_base(Oid basetypid)
Returns the Oid of the temporal type corresponding to the Oid of the base type.
Definition: temporal_util.c:351
bool datum_le(Datum l, Datum r, Oid type)
Returns true if the first value is less than or equal to the second one.
Definition: temporal_util.c:433
Structure to represent values of the internal type for computing aggregates for 2D temporal point typ...
Definition: temporal.h:328
Datum call_recv(Oid type, StringInfo buf)
Call receive function of the base type.
Definition: temporal_util.c:744
TimestampTz * timestamparr_extract(ArrayType *array, int *count)
Extract a C array from a PostgreSQL array containing timestamps.
Definition: temporal_util.c:1026
Datum datum_mult(Datum l, Datum r, Oid typel, Oid typer)
Returns the multiplication of the two numbers.
Definition: temporal_util.c:1445
Datum datum2_le2(Datum l, Datum r, Oid typel, Oid typer)
Returns a Datum true if the first value is less than or equal to the second one.
Definition: temporal_util.c:609
double datum_double(Datum d, Oid basetypid)
Convert a number to a double.
Definition: temporal_util.c:668
bool datum_lt2(Datum l, Datum r, Oid typel, Oid typer)
Returns true if the first value is less than the second one (base type dispatch function) ...
Definition: temporal_util.c:519
RangeType ** rangearr_extract(ArrayType *array, int *count)
Extract a C array from a PostgreSQL array containing ranges.
Definition: temporal_util.c:1044
char * call_output(Oid type, Datum value)
Call output function of the base type.
Definition: temporal_util.c:716
bool type_has_precomputed_trajectory(Oid basetypid)
Returns true if the temporal type corresponding to the Oid of the base type has its trajectory precom...
Definition: temporal_util.c:288
ArrayType * temporalarr_to_array(const Temporal **temporal, int count)
Convert a C array of temporal values into a PostgreSQL array.
Definition: temporal_util.c:1130
ArrayType * textarr_to_array(text **textarr, int count)
Convert a C array of text values into a PostgreSQL array.
Definition: temporal_util.c:1118
char * stringarr_to_string(char **strings, int count, int outlen, char *prefix, char open, char close)
Returns the string resulting from assembling the array of strings.
Definition: temporal_util.c:983
bool tspatial_base_type(Oid basetypid)
Returns true if the Oid is a spatiotemporal type.
Definition: temporal_util.c:253
bool tgeo_base_type(Oid basetypid)
Returns true if the Oid is a point base type supported by MobilityDB.
Definition: temporal_util.c:265
Datum datum2_eq2(Datum l, Datum r, Oid typel, Oid typer)
Returns a Datum true if the two values are equal.
Definition: temporal_util.c:582
Datum datum2_gt2(Datum l, Datum r, Oid typel, Oid typer)
Returns a Datum true if the first value is greater than the second one.
Definition: temporal_util.c:618
Datum CallerFInfoFunctionCall4(PGFunction func, FmgrInfo *flinfo, Oid collation, Datum arg1, Datum arg2, Datum arg3, Datum arg4)
Definition: temporal_util.c:895
Structure to represent temporal values of sequence subtype.
Definition: temporal.h:279
ArrayType * timestamparr_to_array(const TimestampTz *times, int count)
Convert a C array of timestamps into a PostgreSQL array.
Definition: temporal_util.c:1082
int datumarr_remove_duplicates(Datum *values, int count, Oid basetypid)
Remove duplicates from an array of datums.
Definition: temporal_util.c:1324
bool datum_le2(Datum l, Datum r, Oid typel, Oid typer)
Returns true if the first value is less than or equal to the second one.
Definition: temporal_util.c:553
void ensure_tnumber_range_type(Oid rangetype)
Ensures that the Oid is a range type.
Definition: temporal_util.c:223
Structure to represent temporal values of instant subtype.
Definition: temporal.h:253