Line data Source code
1 : /*-------------------------------------------------------------------------
2 : *
3 : * ts_type.h
4 : * Definitions for the tsvector and tsquery types
5 : *
6 : * Copyright (c) 1998-2026, PostgreSQL Global Development Group
7 : *
8 : * src/include/tsearch/ts_type.h
9 : *
10 : *-------------------------------------------------------------------------
11 : */
12 : #ifndef _PG_TSTYPE_H_
13 : #define _PG_TSTYPE_H_
14 :
15 : #include "fmgr.h"
16 : #include "utils/memutils.h"
17 :
18 :
19 : /*
20 : * TSVector type.
21 : *
22 : * Structure of tsvector datatype:
23 : * 1) standard varlena header
24 : * 2) int32 size - number of lexemes (WordEntry array entries)
25 : * 3) Array of WordEntry - one per lexeme; must be sorted according to
26 : * tsCompareString() (ie, memcmp of lexeme strings).
27 : * WordEntry->pos gives the number of bytes from end of WordEntry
28 : * array to start of lexeme's string, which is of length len.
29 : * 4) Per-lexeme data storage:
30 : * lexeme string (not null-terminated)
31 : * if haspos is true:
32 : * padding byte if necessary to make the position data 2-byte aligned
33 : * uint16 number of positions that follow
34 : * WordEntryPos[] positions
35 : *
36 : * The positions for each lexeme must be sorted.
37 : *
38 : * Note that while the WordEntry items must be sorted per tsCompareString(),
39 : * the per-lexeme data storage could be in some other order, ie the series
40 : * of WordEntry->pos values need not be strictly ascending.
41 : */
42 :
43 : typedef struct
44 : {
45 : uint32
46 : haspos:1,
47 : len:11, /* MAX 2Kb */
48 : pos:20; /* MAX 1Mb */
49 : } WordEntry;
50 :
51 : #define MAXSTRLEN ( (1<<11) - 1) /* maximum value of WordEntry.len */
52 : #define MAXSTRPOS ( (1<<20) - 1) /* maximum value of WordEntry.pos */
53 :
54 : extern int compareWordEntryPos(const void *a, const void *b);
55 :
56 : /*
57 : * Representation of positions (and weights) associated with a lexeme.
58 : *
59 : * WordEntryPos is equivalent to
60 : * typedef struct {
61 : * uint16
62 : * weight:2,
63 : * pos:14;
64 : * }
65 : */
66 :
67 : typedef uint16 WordEntryPos;
68 :
69 : typedef struct
70 : {
71 : uint16 npos;
72 : WordEntryPos pos[FLEXIBLE_ARRAY_MEMBER];
73 : } WordEntryPosVector;
74 :
75 : /* WordEntryPosVector with exactly 1 entry */
76 : typedef struct
77 : {
78 : uint16 npos;
79 : WordEntryPos pos[1];
80 : } WordEntryPosVector1;
81 :
82 : #define MAXNUMPOS (256) /* semi-arbitrary limit on npos */
83 :
84 : /* Macros for getting/setting the fields of a WordEntryPos */
85 : #define WEP_GETWEIGHT(x) ( (x) >> 14 )
86 : #define WEP_GETPOS(x) ( (x) & 0x3fff )
87 :
88 : #define WEP_SETWEIGHT(x,v) ( (x) = ( (v) << 14 ) | ( (x) & 0x3fff ) )
89 : #define WEP_SETPOS(x,v) ( (x) = ( (x) & 0xc000 ) | ( (v) & 0x3fff ) )
90 :
91 : #define MAXENTRYPOS (1<<14) /* max value of WordEntryPos pos field, +1 */
92 : /* Macro for clamping a position to what will fit in WordEntryPos pos field */
93 : #define LIMITPOS(x) ( ( (x) >= MAXENTRYPOS ) ? (MAXENTRYPOS-1) : (x) )
94 :
95 : /* This struct represents a complete tsvector datum */
96 : typedef struct
97 : {
98 : int32 vl_len_; /* varlena header (do not touch directly!) */
99 : int32 size; /* number of entries[] items */
100 : WordEntry entries[FLEXIBLE_ARRAY_MEMBER];
101 : /* lexemes follow the entries[] array */
102 : } TSVectorData;
103 :
104 : typedef TSVectorData *TSVector;
105 :
106 : /*
107 : * Calculate the size of a TSVector given the number of WordEntries and
108 : * the total space needed for lexeme text and positions. NOTE: callers
109 : * must enforce lenstr <= MAXSTRPOS, which ensures that WordEntry.pos
110 : * fields will not overflow, and also protects against integer overflow here.
111 : * (Since we prohibit empty lexemes, nentries can't exceed lenstr.)
112 : */
113 : #define DATAHDRSIZE (offsetof(TSVectorData, entries))
114 : #define CALCDATASIZE(nentries, lenstr) (DATAHDRSIZE + (nentries) * sizeof(WordEntry) + (lenstr) )
115 :
116 : /* pointer to start of a tsvector's WordEntry array */
117 : #define ARRPTR(tsv) ( (tsv)->entries )
118 :
119 : /* pointer to start of a tsvector's lexeme storage */
120 : #define STRPTR(tsv) ( (char *) &(tsv)->entries[(tsv)->size] )
121 :
122 : /* pointer to WordEntryPosVector for a WordEntry */
123 : #define _POSVECPTR(tsv,we) ((WordEntryPosVector *) \
124 : (STRPTR(tsv) + SHORTALIGN((we)->pos + (we)->len)))
125 : /* number of positions stored for a WordEntry */
126 : #define POSDATALEN(tsv,we) ( (we)->haspos ? _POSVECPTR(tsv,we)->npos : 0 )
127 : /* pointer to start of positions stored for a WordEntry */
128 : #define POSDATAPTR(tsv,we) (_POSVECPTR(tsv,we)->pos)
129 :
130 : /*
131 : * fmgr interface functions
132 : */
133 :
134 : static inline TSVector
135 164942 : DatumGetTSVector(Datum X)
136 : {
137 164942 : return (TSVector) PG_DETOAST_DATUM(X);
138 : }
139 :
140 : static inline TSVector
141 20 : DatumGetTSVectorCopy(Datum X)
142 : {
143 20 : return (TSVector) PG_DETOAST_DATUM_COPY(X);
144 : }
145 :
146 : static inline Datum
147 5723 : TSVectorGetDatum(const TSVectorData *X)
148 : {
149 5723 : return PointerGetDatum(X);
150 : }
151 :
152 : #define PG_GETARG_TSVECTOR(n) DatumGetTSVector(PG_GETARG_DATUM(n))
153 : #define PG_GETARG_TSVECTOR_COPY(n) DatumGetTSVectorCopy(PG_GETARG_DATUM(n))
154 : #define PG_RETURN_TSVECTOR(x) return TSVectorGetDatum(x)
155 :
156 :
157 : /*
158 : * TSQuery
159 : *
160 : *
161 : */
162 :
163 : typedef int8 QueryItemType;
164 :
165 : /* Valid values for QueryItemType: */
166 : #define QI_VAL 1
167 : #define QI_OPR 2
168 : #define QI_VALSTOP 3 /* This is only used in an intermediate stack
169 : * representation in parse_tsquery. It's not a
170 : * legal type elsewhere. */
171 :
172 : /*
173 : * QueryItem is one node in tsquery - operator or operand.
174 : */
175 : typedef struct
176 : {
177 : QueryItemType type; /* operand or kind of operator (ts_tokentype) */
178 : uint8 weight; /* weights of operand to search. It's a
179 : * bitmask of allowed weights. if it =0 then
180 : * any weight are allowed. Weights and bit
181 : * map: A: 1<<3 B: 1<<2 C: 1<<1 D: 1<<0 */
182 : bool prefix; /* true if it's a prefix search */
183 : int32 valcrc; /* XXX: pg_crc32 would be a more appropriate
184 : * data type, but we use comparisons to signed
185 : * integers in the code. They would need to be
186 : * changed as well. */
187 :
188 : /* pointer to text value of operand, must correlate with WordEntry */
189 : uint32
190 : length:12,
191 : distance:20;
192 : } QueryOperand;
193 :
194 :
195 : /*
196 : * Legal values for QueryOperator.operator.
197 : */
198 : #define OP_NOT 1
199 : #define OP_AND 2
200 : #define OP_OR 3
201 : #define OP_PHRASE 4 /* highest code, tsquery_cleanup.c */
202 : #define OP_COUNT 4
203 :
204 : extern PGDLLIMPORT const int tsearch_op_priority[OP_COUNT];
205 :
206 : /* get operation priority by its code */
207 : #define OP_PRIORITY(x) ( tsearch_op_priority[(x) - 1] )
208 : /* get QueryOperator priority */
209 : #define QO_PRIORITY(x) OP_PRIORITY(((QueryOperator *) (x))->oper)
210 :
211 : typedef struct
212 : {
213 : QueryItemType type;
214 : int8 oper; /* see above */
215 : int16 distance; /* distance between args for OP_PHRASE */
216 : uint32 left; /* pointer to left operand. Right operand is
217 : * item + 1, left operand is placed
218 : * item+item->left */
219 : } QueryOperator;
220 :
221 : /*
222 : * Note: TSQuery is 4-bytes aligned, so make sure there's no fields
223 : * inside QueryItem requiring 8-byte alignment, like int64.
224 : */
225 : typedef union
226 : {
227 : QueryItemType type;
228 : QueryOperator qoperator;
229 : QueryOperand qoperand;
230 : } QueryItem;
231 :
232 : /*
233 : * Storage:
234 : * (len)(size)(array of QueryItem)(operands as '\0'-terminated c-strings)
235 : */
236 :
237 : typedef struct
238 : {
239 : int32 vl_len_; /* varlena header (do not touch directly!) */
240 : int32 size; /* number of QueryItems */
241 : char data[FLEXIBLE_ARRAY_MEMBER]; /* data starts here */
242 : } TSQueryData;
243 :
244 : typedef TSQueryData *TSQuery;
245 :
246 : #define HDRSIZETQ ( VARHDRSZ + sizeof(int32) )
247 :
248 : /*
249 : * Computes the size of header and all QueryItems. size is the number of
250 : * QueryItems, and lenofoperand is the total length of all operands
251 : */
252 : #define COMPUTESIZE(size, lenofoperand) ( HDRSIZETQ + (size) * sizeof(QueryItem) + (lenofoperand) )
253 : #define TSQUERY_TOO_BIG(size, lenofoperand) \
254 : ((size_t) (lenofoperand) > MaxAllocSize - HDRSIZETQ || \
255 : (size) > (MaxAllocSize - HDRSIZETQ - (lenofoperand)) / sizeof(QueryItem))
256 :
257 : /* Returns a pointer to the first QueryItem in a TSQuery */
258 : #define GETQUERY(x) ((QueryItem*)( (char*)(x)+HDRSIZETQ ))
259 :
260 : /* Returns a pointer to the beginning of operands in a TSQuery */
261 : #define GETOPERAND(x) ( (char*)GETQUERY(x) + ((TSQuery)(x))->size * sizeof(QueryItem) )
262 :
263 : /*
264 : * fmgr interface functions
265 : * Note, TSQuery type marked as plain storage, so it can't be toasted
266 : * but PG_DETOAST_DATUM_COPY is used for simplicity
267 : */
268 :
269 : static inline TSQuery
270 378408 : DatumGetTSQuery(Datum X)
271 : {
272 378408 : return (TSQuery) DatumGetPointer(X);
273 : }
274 :
275 : static inline TSQuery
276 904 : DatumGetTSQueryCopy(Datum X)
277 : {
278 904 : return (TSQuery) PG_DETOAST_DATUM_COPY(X);
279 : }
280 :
281 : static inline Datum
282 2809 : TSQueryGetDatum(const TSQueryData *X)
283 : {
284 2809 : return PointerGetDatum(X);
285 : }
286 :
287 : #define PG_GETARG_TSQUERY(n) DatumGetTSQuery(PG_GETARG_DATUM(n))
288 : #define PG_GETARG_TSQUERY_COPY(n) DatumGetTSQueryCopy(PG_GETARG_DATUM(n))
289 : #define PG_RETURN_TSQUERY(x) return TSQueryGetDatum(x)
290 :
291 : #endif /* _PG_TSTYPE_H_ */
|
