Debian Codegraph @

src/backend/utils/adt/datum.c

raw
1 /*-------------------------------------------------------------------------
2 *
3 * datum.c
4 * POSTGRES Datum (abstract data type) manipulation routines.
5 *
6 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
7 * Portions Copyright (c) 1994, Regents of the University of California
8 *
9 *
10 * IDENTIFICATION
11 * src/backend/utils/adt/datum.c
12 *
13 *-------------------------------------------------------------------------
14 */
15
16 /*
17 * In the implementation of these routines we assume the following:
18 *
19 * A) if a type is "byVal" then all the information is stored in the
20 * Datum itself (i.e. no pointers involved!). In this case the
21 * length of the type is always greater than zero and not more than
22 * "sizeof(Datum)"
23 *
24 * B) if a type is not "byVal" and it has a fixed length (typlen > 0),
25 * then the "Datum" always contains a pointer to a stream of bytes.
26 * The number of significant bytes are always equal to the typlen.
27 *
28 * C) if a type is not "byVal" and has typlen == -1,
29 * then the "Datum" always points to a "struct varlena".
30 * This varlena structure has information about the actual length of this
31 * particular instance of the type and about its value.
32 *
33 * D) if a type is not "byVal" and has typlen == -2,
34 * then the "Datum" always points to a null-terminated C string.
35 *
36 * Note that we do not treat "toasted" datums specially; therefore what
37 * will be copied or compared is the compressed data or toast reference.
38 * An exception is made for datumCopy() of an expanded object, however,
39 * because most callers expect to get a simple contiguous (and pfree'able)
40 * result from datumCopy(). See also datumTransfer().
41 */
42
43 #include "postgres.h"
44
45 #include "access/detoast.h"
46 #include "common/hashfn.h"
47 #include "fmgr.h"
48 #include "utils/datum.h"
49 #include "utils/expandeddatum.h"
50 #include "utils/fmgrprotos.h"
51
52
53 /*-------------------------------------------------------------------------
54 * datumGetSize
55 *
56 * Find the "real" size of a datum, given the datum value,
57 * whether it is a "by value", and the declared type length.
58 * (For TOAST pointer datums, this is the size of the pointer datum.)
59 *
60 * This is essentially an out-of-line version of the att_addlength_datum()
61 * macro in access/tupmacs.h. We do a tad more error checking though.
62 *-------------------------------------------------------------------------
63 */
64 Size
65 datumGetSize(Datum value, bool typByVal, int typLen)
66 {
67 Size size;
68
69 if (typByVal)
70 {
71 /* Pass-by-value types are always fixed-length */
72 Assert(typLen > 0 && typLen <= sizeof(Datum));
73 size = (Size) typLen;
74 }
75 else
76 {
77 if (typLen > 0)
78 {
79 /* Fixed-length pass-by-ref type */
80 size = (Size) typLen;
81 }
82 else if (typLen == -1)
83 {
84 /* It is a varlena datatype */
85 struct varlena *s = (struct varlena *) DatumGetPointer(value);
86
87 if (!PointerIsValid(s))
88 ereport(ERROR,
89 (errcode(ERRCODE_DATA_EXCEPTION),
90 errmsg("invalid Datum pointer")));
91
92 size = (Size) VARSIZE_ANY(s);
93 }
94 else if (typLen == -2)
95 {
96 /* It is a cstring datatype */
97 char *s = (char *) DatumGetPointer(value);
98
99 if (!PointerIsValid(s))
100 ereport(ERROR,
101 (errcode(ERRCODE_DATA_EXCEPTION),
102 errmsg("invalid Datum pointer")));
103
104 size = (Size) (strlen(s) + 1);
105 }
106 else
107 {
108 elog(ERROR, "invalid typLen: %d", typLen);
109 size = 0; /* keep compiler quiet */
110 }
111 }
112
113 return size;
114 }
115
116 /*-------------------------------------------------------------------------
117 * datumCopy
118 *
119 * Make a copy of a non-NULL datum.
120 *
121 * If the datatype is pass-by-reference, memory is obtained with palloc().
122 *
123 * If the value is a reference to an expanded object, we flatten into memory
124 * obtained with palloc(). We need to copy because one of the main uses of
125 * this function is to copy a datum out of a transient memory context that's
126 * about to be destroyed, and the expanded object is probably in a child
127 * context that will also go away. Moreover, many callers assume that the
128 * result is a single pfree-able chunk.
129 *-------------------------------------------------------------------------
130 */
131 Datum
132 datumCopy(Datum value, bool typByVal, int typLen)
133 {
134 Datum res;
135
136 if (typByVal)
137 res = value;
138 else if (typLen == -1)
139 {
140 /* It is a varlena datatype */
141 struct varlena *vl = (struct varlena *) DatumGetPointer(value);
142
143 if (VARATT_IS_EXTERNAL_EXPANDED(vl))
144 {
145 /* Flatten into the caller's memory context */
146 ExpandedObjectHeader *eoh = DatumGetEOHP(value);
147 Size resultsize;
148 char *resultptr;
149
150 resultsize = EOH_get_flat_size(eoh);
151 resultptr = (char *) palloc(resultsize);
152 EOH_flatten_into(eoh, resultptr, resultsize);
153 res = PointerGetDatum(resultptr);
154 }
155 else
156 {
157 /* Otherwise, just copy the varlena datum verbatim */
158 Size realSize;
159 char *resultptr;
160
161 realSize = (Size) VARSIZE_ANY(vl);
162 resultptr = (char *) palloc(realSize);
163 memcpy(resultptr, vl, realSize);
164 res = PointerGetDatum(resultptr);
165 }
166 }
167 else
168 {
169 /* Pass by reference, but not varlena, so not toasted */
170 Size realSize;
171 char *resultptr;
172
173 realSize = datumGetSize(value, typByVal, typLen);
174
175 resultptr = (char *) palloc(realSize);
176 memcpy(resultptr, DatumGetPointer(value), realSize);
177 res = PointerGetDatum(resultptr);
178 }
179 return res;
180 }
181
182 /*-------------------------------------------------------------------------
183 * datumTransfer
184 *
185 * Transfer a non-NULL datum into the current memory context.
186 *
187 * This is equivalent to datumCopy() except when the datum is a read-write
188 * pointer to an expanded object. In that case we merely reparent the object
189 * into the current context, and return its standard R/W pointer (in case the
190 * given one is a transient pointer of shorter lifespan).
191 *-------------------------------------------------------------------------
192 */
193 Datum
194 datumTransfer(Datum value, bool typByVal, int typLen)
195 {
196 if (!typByVal && typLen == -1 &&
197 VARATT_IS_EXTERNAL_EXPANDED_RW(DatumGetPointer(value)))
198 value = TransferExpandedObject(value, CurrentMemoryContext);
199 else
200 value = datumCopy(value, typByVal, typLen);
201 return value;
202 }
203
204 /*-------------------------------------------------------------------------
205 * datumIsEqual
206 *
207 * Return true if two datums are equal, false otherwise
208 *
209 * NOTE: XXX!
210 * We just compare the bytes of the two values, one by one.
211 * This routine will return false if there are 2 different
212 * representations of the same value (something along the lines
213 * of say the representation of zero in one's complement arithmetic).
214 * Also, it will probably not give the answer you want if either
215 * datum has been "toasted".
216 *
217 * Do not try to make this any smarter than it currently is with respect
218 * to "toasted" datums, because some of the callers could be working in the
219 * context of an aborted transaction.
220 *-------------------------------------------------------------------------
221 */
222 bool
223 datumIsEqual(Datum value1, Datum value2, bool typByVal, int typLen)
224 {
225 bool res;
226
227 if (typByVal)
228 {
229 /*
230 * just compare the two datums. NOTE: just comparing "len" bytes will
231 * not do the work, because we do not know how these bytes are aligned
232 * inside the "Datum". We assume instead that any given datatype is
233 * consistent about how it fills extraneous bits in the Datum.
234 */
235 res = (value1 == value2);
236 }
237 else
238 {
239 Size size1,
240 size2;
241 char *s1,
242 *s2;
243
244 /*
245 * Compare the bytes pointed by the pointers stored in the datums.
246 */
247 size1 = datumGetSize(value1, typByVal, typLen);
248 size2 = datumGetSize(value2, typByVal, typLen);
249 if (size1 != size2)
250 return false;
251 s1 = (char *) DatumGetPointer(value1);
252 s2 = (char *) DatumGetPointer(value2);
253 res = (memcmp(s1, s2, size1) == 0);
254 }
255 return res;
256 }
257
258 /*-------------------------------------------------------------------------
259 * datum_image_eq
260 *
261 * Compares two datums for identical contents when coerced to a signed integer
262 * of typLen bytes. Return true if the two datums are equal, false otherwise.
263 *
264 * The coercion is required as we're not always careful to use the correct
265 * PG_RETURN_* macro. If we didn't do this, a Datum that's been formed and
266 * deformed into a tuple may not have the same signed representation as the
267 * other datum value.
268 *-------------------------------------------------------------------------
269 */
270 bool
271 datum_image_eq(Datum value1, Datum value2, bool typByVal, int typLen)
272 {
273 Size len1,
274 len2;
275 bool result = true;
276
277 if (typByVal)
278 {
279 switch (typLen)
280 {
281 case sizeof(char):
282 result = (DatumGetChar(value1) == DatumGetChar(value2));
283 break;
284 case sizeof(int16):
285 result = (DatumGetInt16(value1) == DatumGetInt16(value2));
286 break;
287 case sizeof(int32):
288 result = (DatumGetInt32(value1) == DatumGetInt32(value2));
289 break;
290 default:
291 result = (value1 == value2);
292 break;
293 }
294 }
295 else if (typLen > 0)
296 {
297 result = (memcmp(DatumGetPointer(value1),
298 DatumGetPointer(value2),
299 typLen) == 0);
300 }
301 else if (typLen == -1)
302 {
303 len1 = toast_raw_datum_size(value1);
304 len2 = toast_raw_datum_size(value2);
305 /* No need to de-toast if lengths don't match. */
306 if (len1 != len2)
307 result = false;
308 else
309 {
310 struct varlena *arg1val;
311 struct varlena *arg2val;
312
313 arg1val = PG_DETOAST_DATUM_PACKED(value1);
314 arg2val = PG_DETOAST_DATUM_PACKED(value2);
315
316 result = (memcmp(VARDATA_ANY(arg1val),
317 VARDATA_ANY(arg2val),
318 len1 - VARHDRSZ) == 0);
319
320 /* Only free memory if it's a copy made here. */
321 if ((Pointer) arg1val != (Pointer) value1)
322 pfree(arg1val);
323 if ((Pointer) arg2val != (Pointer) value2)
324 pfree(arg2val);
325 }
326 }
327 else if (typLen == -2)
328 {
329 char *s1,
330 *s2;
331
332 /* Compare cstring datums */
333 s1 = DatumGetCString(value1);
334 s2 = DatumGetCString(value2);
335 len1 = strlen(s1) + 1;
336 len2 = strlen(s2) + 1;
337 if (len1 != len2)
338 return false;
339 result = (memcmp(s1, s2, len1) == 0);
340 }
341 else
342 elog(ERROR, "unexpected typLen: %d", typLen);
343
344 return result;
345 }
346
347 /*-------------------------------------------------------------------------
348 * datum_image_hash
349 *
350 * Generate a hash value based on the binary representation of 'value' when
351 * represented as a signed integer of typLen bytes. Most use cases will want
352 * to use the hash function specific to the Datum's type, however, some corner
353 * cases require generating a hash value based on the actual bits rather than
354 * the logical value.
355 *-------------------------------------------------------------------------
356 */
357 uint32
358 datum_image_hash(Datum value, bool typByVal, int typLen)
359 {
360 Size len;
361 uint32 result;
362
363 if (typByVal)
364 {
365 switch (typLen)
366 {
367 case sizeof(char):
368 value = CharGetDatum(DatumGetChar(value));
369 break;
370 case sizeof(int16):
371 value = Int16GetDatum(DatumGetInt16(value));
372 break;
373 case sizeof(int32):
374 value = Int32GetDatum(DatumGetInt32(value));
375 break;
376 /* Nothing needs done for 64-bit types */
377 }
378
379 result = hash_bytes((unsigned char *) &value, sizeof(Datum));
380 }
381 else if (typLen > 0)
382 result = hash_bytes((unsigned char *) DatumGetPointer(value), typLen);
383 else if (typLen == -1)
384 {
385 struct varlena *val;
386
387 len = toast_raw_datum_size(value);
388
389 val = PG_DETOAST_DATUM_PACKED(value);
390
391 result = hash_bytes((unsigned char *) VARDATA_ANY(val), len - VARHDRSZ);
392
393 /* Only free memory if it's a copy made here. */
394 if ((Pointer) val != (Pointer) value)
395 pfree(val);
396 }
397 else if (typLen == -2)
398 {
399 char *s;
400
401 s = DatumGetCString(value);
402 len = strlen(s) + 1;
403
404 result = hash_bytes((unsigned char *) s, len);
405 }
406 else
407 {
408 elog(ERROR, "unexpected typLen: %d", typLen);
409 result = 0; /* keep compiler quiet */
410 }
411
412 return result;
413 }
414
415 /*-------------------------------------------------------------------------
416 * btequalimage
417 *
418 * Generic "equalimage" support function.
419 *
420 * B-Tree operator classes whose equality function could safely be replaced by
421 * datum_image_eq() in all cases can use this as their "equalimage" support
422 * function.
423 *
424 * Currently, we unconditionally assume that any B-Tree operator class that
425 * registers btequalimage as its support function 4 must be able to safely use
426 * optimizations like deduplication (i.e. we return true unconditionally). If
427 * it ever proved necessary to rescind support for an operator class, we could
428 * do that in a targeted fashion by doing something with the opcintype
429 * argument.
430 *-------------------------------------------------------------------------
431 */
432 Datum
433 btequalimage(PG_FUNCTION_ARGS)
434 {
435 /* Oid opcintype = PG_GETARG_OID(0); */
436
437 PG_RETURN_BOOL(true);
438 }
439
440 /*-------------------------------------------------------------------------
441 * datumEstimateSpace
442 *
443 * Compute the amount of space that datumSerialize will require for a
444 * particular Datum.
445 *-------------------------------------------------------------------------
446 */
447 Size
448 datumEstimateSpace(Datum value, bool isnull, bool typByVal, int typLen)
449 {
450 Size sz = sizeof(int);
451
452 if (!isnull)
453 {
454 /* no need to use add_size, can't overflow */
455 if (typByVal)
456 sz += sizeof(Datum);
457 else if (typLen == -1 &&
458 VARATT_IS_EXTERNAL_EXPANDED(DatumGetPointer(value)))
459 {
460 /* Expanded objects need to be flattened, see comment below */
461 sz += EOH_get_flat_size(DatumGetEOHP(value));
462 }
463 else
464 sz += datumGetSize(value, typByVal, typLen);
465 }
466
467 return sz;
468 }
469
470 /*-------------------------------------------------------------------------
471 * datumSerialize
472 *
473 * Serialize a possibly-NULL datum into caller-provided storage.
474 *
475 * Note: "expanded" objects are flattened so as to produce a self-contained
476 * representation, but other sorts of toast pointers are transferred as-is.
477 * This is because the intended use of this function is to pass the value
478 * to another process within the same database server. The other process
479 * could not access an "expanded" object within this process's memory, but
480 * we assume it can dereference the same TOAST pointers this one can.
481 *
482 * The format is as follows: first, we write a 4-byte header word, which
483 * is either the length of a pass-by-reference datum, -1 for a
484 * pass-by-value datum, or -2 for a NULL. If the value is NULL, nothing
485 * further is written. If it is pass-by-value, sizeof(Datum) bytes
486 * follow. Otherwise, the number of bytes indicated by the header word
487 * follow. The caller is responsible for ensuring that there is enough
488 * storage to store the number of bytes that will be written; use
489 * datumEstimateSpace() to find out how many will be needed.
490 * *start_address is updated to point to the byte immediately following
491 * those written.
492 *-------------------------------------------------------------------------
493 */
494 void
495 datumSerialize(Datum value, bool isnull, bool typByVal, int typLen,
496 char **start_address)
497 {
498 ExpandedObjectHeader *eoh = NULL;
499 int header;
500
501 /* Write header word. */
502 if (isnull)
503 header = -2;
504 else if (typByVal)
505 header = -1;
506 else if (typLen == -1 &&
507 VARATT_IS_EXTERNAL_EXPANDED(DatumGetPointer(value)))
508 {
509 eoh = DatumGetEOHP(value);
510 header = EOH_get_flat_size(eoh);
511 }
512 else
513 header = datumGetSize(value, typByVal, typLen);
514 memcpy(*start_address, &header, sizeof(int));
515 *start_address += sizeof(int);
516
517 /* If not null, write payload bytes. */
518 if (!isnull)
519 {
520 if (typByVal)
521 {
522 memcpy(*start_address, &value, sizeof(Datum));
523 *start_address += sizeof(Datum);
524 }
525 else if (eoh)
526 {
527 char *tmp;
528
529 /*
530 * EOH_flatten_into expects the target address to be maxaligned,
531 * so we can't store directly to *start_address.
532 */
533 tmp = (char *) palloc(header);
534 EOH_flatten_into(eoh, tmp, header);
535 memcpy(*start_address, tmp, header);
536 *start_address += header;
537
538 /* be tidy. */
539 pfree(tmp);
540 }
541 else
542 {
543 memcpy(*start_address, DatumGetPointer(value), header);
544 *start_address += header;
545 }
546 }
547 }
548
549 /*-------------------------------------------------------------------------
550 * datumRestore
551 *
552 * Restore a possibly-NULL datum previously serialized by datumSerialize.
553 * *start_address is updated according to the number of bytes consumed.
554 *-------------------------------------------------------------------------
555 */
556 Datum
557 datumRestore(char **start_address, bool *isnull)
558 {
559 int header;
560 void *d;
561
562 /* Read header word. */
563 memcpy(&header, *start_address, sizeof(int));
564 *start_address += sizeof(int);
565
566 /* If this datum is NULL, we can stop here. */
567 if (header == -2)
568 {
569 *isnull = true;
570 return (Datum) 0;
571 }
572
573 /* OK, datum is not null. */
574 *isnull = false;
575
576 /* If this datum is pass-by-value, sizeof(Datum) bytes follow. */
577 if (header == -1)
578 {
579 Datum val;
580
581 memcpy(&val, *start_address, sizeof(Datum));
582 *start_address += sizeof(Datum);
583 return val;
584 }
585
586 /* Pass-by-reference case; copy indicated number of bytes. */
587 Assert(header > 0);
588 d = palloc(header);
589 memcpy(d, *start_address, header);
590 *start_address += header;
591 return PointerGetDatum(d);
592 }