granicus.if.org Git - postgresql/blob - src/backend/utils/adt/datum.c

   1 /*-------------------------------------------------------------------------
   2  *
   3  * datum.c
   4  *        POSTGRES Datum (abstract data type) manipulation routines.
   5  *
   6  * Portions Copyright (c) 1996-2017, 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 "utils/datum.h"
  46 #include "utils/expandeddatum.h"
  47
  48
  49 /*-------------------------------------------------------------------------
  50  * datumGetSize
  51  *
  52  * Find the "real" size of a datum, given the datum value,
  53  * whether it is a "by value", and the declared type length.
  54  * (For TOAST pointer datums, this is the size of the pointer datum.)
  55  *
  56  * This is essentially an out-of-line version of the att_addlength_datum()
  57  * macro in access/tupmacs.h.  We do a tad more error checking though.
  58  *-------------------------------------------------------------------------
  59  */
  60 Size
  61 datumGetSize(Datum value, bool typByVal, int typLen)
  62 {
  63         Size            size;
  64
  65         if (typByVal)
  66         {
  67                 /* Pass-by-value types are always fixed-length */
  68                 Assert(typLen > 0 && typLen <= sizeof(Datum));
  69                 size = (Size) typLen;
  70         }
  71         else
  72         {
  73                 if (typLen > 0)
  74                 {
  75                         /* Fixed-length pass-by-ref type */
  76                         size = (Size) typLen;
  77                 }
  78                 else if (typLen == -1)
  79                 {
  80                         /* It is a varlena datatype */
  81                         struct varlena *s = (struct varlena *) DatumGetPointer(value);
  82
  83                         if (!PointerIsValid(s))
  84                                 ereport(ERROR,
  85                                                 (errcode(ERRCODE_DATA_EXCEPTION),
  86                                                  errmsg("invalid Datum pointer")));
  87
  88                         size = (Size) VARSIZE_ANY(s);
  89                 }
  90                 else if (typLen == -2)
  91                 {
  92                         /* It is a cstring datatype */
  93                         char       *s = (char *) DatumGetPointer(value);
  94
  95                         if (!PointerIsValid(s))
  96                                 ereport(ERROR,
  97                                                 (errcode(ERRCODE_DATA_EXCEPTION),
  98                                                  errmsg("invalid Datum pointer")));
  99
 100                         size = (Size) (strlen(s) + 1);
 101                 }
 102                 else
 103                 {
 104                         elog(ERROR, "invalid typLen: %d", typLen);
 105                         size = 0;                       /* keep compiler quiet */
 106                 }
 107         }
 108
 109         return size;
 110 }
 111
 112 /*-------------------------------------------------------------------------
 113  * datumCopy
 114  *
 115  * Make a copy of a non-NULL datum.
 116  *
 117  * If the datatype is pass-by-reference, memory is obtained with palloc().
 118  *
 119  * If the value is a reference to an expanded object, we flatten into memory
 120  * obtained with palloc().  We need to copy because one of the main uses of
 121  * this function is to copy a datum out of a transient memory context that's
 122  * about to be destroyed, and the expanded object is probably in a child
 123  * context that will also go away.  Moreover, many callers assume that the
 124  * result is a single pfree-able chunk.
 125  *-------------------------------------------------------------------------
 126  */
 127 Datum
 128 datumCopy(Datum value, bool typByVal, int typLen)
 129 {
 130         Datum           res;
 131
 132         if (typByVal)
 133                 res = value;
 134         else if (typLen == -1)
 135         {
 136                 /* It is a varlena datatype */
 137                 struct varlena *vl = (struct varlena *) DatumGetPointer(value);
 138
 139                 if (VARATT_IS_EXTERNAL_EXPANDED(vl))
 140                 {
 141                         /* Flatten into the caller's memory context */
 142                         ExpandedObjectHeader *eoh = DatumGetEOHP(value);
 143                         Size            resultsize;
 144                         char       *resultptr;
 145
 146                         resultsize = EOH_get_flat_size(eoh);
 147                         resultptr = (char *) palloc(resultsize);
 148                         EOH_flatten_into(eoh, (void *) resultptr, resultsize);
 149                         res = PointerGetDatum(resultptr);
 150                 }
 151                 else
 152                 {
 153                         /* Otherwise, just copy the varlena datum verbatim */
 154                         Size            realSize;
 155                         char       *resultptr;
 156
 157                         realSize = (Size) VARSIZE_ANY(vl);
 158                         resultptr = (char *) palloc(realSize);
 159                         memcpy(resultptr, vl, realSize);
 160                         res = PointerGetDatum(resultptr);
 161                 }
 162         }
 163         else
 164         {
 165                 /* Pass by reference, but not varlena, so not toasted */
 166                 Size            realSize;
 167                 char       *resultptr;
 168
 169                 realSize = datumGetSize(value, typByVal, typLen);
 170
 171                 resultptr = (char *) palloc(realSize);
 172                 memcpy(resultptr, DatumGetPointer(value), realSize);
 173                 res = PointerGetDatum(resultptr);
 174         }
 175         return res;
 176 }
 177
 178 /*-------------------------------------------------------------------------
 179  * datumTransfer
 180  *
 181  * Transfer a non-NULL datum into the current memory context.
 182  *
 183  * This is equivalent to datumCopy() except when the datum is a read-write
 184  * pointer to an expanded object.  In that case we merely reparent the object
 185  * into the current context, and return its standard R/W pointer (in case the
 186  * given one is a transient pointer of shorter lifespan).
 187  *-------------------------------------------------------------------------
 188  */
 189 Datum
 190 datumTransfer(Datum value, bool typByVal, int typLen)
 191 {
 192         if (!typByVal && typLen == -1 &&
 193                 VARATT_IS_EXTERNAL_EXPANDED_RW(DatumGetPointer(value)))
 194                 value = TransferExpandedObject(value, CurrentMemoryContext);
 195         else
 196                 value = datumCopy(value, typByVal, typLen);
 197         return value;
 198 }
 199
 200 /*-------------------------------------------------------------------------
 201  * datumIsEqual
 202  *
 203  * Return true if two datums are equal, false otherwise
 204  *
 205  * NOTE: XXX!
 206  * We just compare the bytes of the two values, one by one.
 207  * This routine will return false if there are 2 different
 208  * representations of the same value (something along the lines
 209  * of say the representation of zero in one's complement arithmetic).
 210  * Also, it will probably not give the answer you want if either
 211  * datum has been "toasted".
 212  *-------------------------------------------------------------------------
 213  */
 214 bool
 215 datumIsEqual(Datum value1, Datum value2, bool typByVal, int typLen)
 216 {
 217         bool            res;
 218
 219         if (typByVal)
 220         {
 221                 /*
 222                  * just compare the two datums. NOTE: just comparing "len" bytes will
 223                  * not do the work, because we do not know how these bytes are aligned
 224                  * inside the "Datum".  We assume instead that any given datatype is
 225                  * consistent about how it fills extraneous bits in the Datum.
 226                  */
 227                 res = (value1 == value2);
 228         }
 229         else
 230         {
 231                 Size            size1,
 232                                         size2;
 233                 char       *s1,
 234                                    *s2;
 235
 236                 /*
 237                  * Compare the bytes pointed by the pointers stored in the datums.
 238                  */
 239                 size1 = datumGetSize(value1, typByVal, typLen);
 240                 size2 = datumGetSize(value2, typByVal, typLen);
 241                 if (size1 != size2)
 242                         return false;
 243                 s1 = (char *) DatumGetPointer(value1);
 244                 s2 = (char *) DatumGetPointer(value2);
 245                 res = (memcmp(s1, s2, size1) == 0);
 246         }
 247         return res;
 248 }
 249
 250 /*-------------------------------------------------------------------------
 251  * datumEstimateSpace
 252  *
 253  * Compute the amount of space that datumSerialize will require for a
 254  * particular Datum.
 255  *-------------------------------------------------------------------------
 256  */
 257 Size
 258 datumEstimateSpace(Datum value, bool isnull, bool typByVal, int typLen)
 259 {
 260         Size            sz = sizeof(int);
 261
 262         if (!isnull)
 263         {
 264                 /* no need to use add_size, can't overflow */
 265                 if (typByVal)
 266                         sz += sizeof(Datum);
 267                 else if (VARATT_IS_EXTERNAL_EXPANDED(value))
 268                 {
 269                         ExpandedObjectHeader *eoh = DatumGetEOHP(value);
 270
 271                         sz += EOH_get_flat_size(eoh);
 272                 }
 273                 else
 274                         sz += datumGetSize(value, typByVal, typLen);
 275         }
 276
 277         return sz;
 278 }
 279
 280 /*-------------------------------------------------------------------------
 281  * datumSerialize
 282  *
 283  * Serialize a possibly-NULL datum into caller-provided storage.
 284  *
 285  * The format is as follows: first, we write a 4-byte header word, which
 286  * is either the length of a pass-by-reference datum, -1 for a
 287  * pass-by-value datum, or -2 for a NULL.  If the value is NULL, nothing
 288  * further is written.  If it is pass-by-value, sizeof(Datum) bytes
 289  * follow.  Otherwise, the number of bytes indicated by the header word
 290  * follow.  The caller is responsible for ensuring that there is enough
 291  * storage to store the number of bytes that will be written; use
 292  * datumEstimateSpace() to find out how many will be needed.
 293  * *start_address is updated to point to the byte immediately following
 294  * those written.
 295  *-------------------------------------------------------------------------
 296  */
 297 void
 298 datumSerialize(Datum value, bool isnull, bool typByVal, int typLen,
 299                            char **start_address)
 300 {
 301         ExpandedObjectHeader *eoh = NULL;
 302         int                     header;
 303
 304         /* Write header word. */
 305         if (isnull)
 306                 header = -2;
 307         else if (typByVal)
 308                 header = -1;
 309         else if (VARATT_IS_EXTERNAL_EXPANDED(value))
 310         {
 311                 eoh = DatumGetEOHP(value);
 312                 header = EOH_get_flat_size(eoh);
 313         }
 314         else
 315                 header = datumGetSize(value, typByVal, typLen);
 316         memcpy(*start_address, &header, sizeof(int));
 317         *start_address += sizeof(int);
 318
 319         /* If not null, write payload bytes. */
 320         if (!isnull)
 321         {
 322                 if (typByVal)
 323                 {
 324                         memcpy(*start_address, &value, sizeof(Datum));
 325                         *start_address += sizeof(Datum);
 326                 }
 327                 else if (eoh)
 328                 {
 329                         EOH_flatten_into(eoh, (void *) *start_address, header);
 330                         *start_address += header;
 331                 }
 332                 else
 333                 {
 334                         memcpy(*start_address, DatumGetPointer(value), header);
 335                         *start_address += header;
 336                 }
 337         }
 338 }
 339
 340 /*-------------------------------------------------------------------------
 341  * datumRestore
 342  *
 343  * Restore a possibly-NULL datum previously serialized by datumSerialize.
 344  * *start_address is updated according to the number of bytes consumed.
 345  *-------------------------------------------------------------------------
 346  */
 347 Datum
 348 datumRestore(char **start_address, bool *isnull)
 349 {
 350         int                     header;
 351         void       *d;
 352
 353         /* Read header word. */
 354         memcpy(&header, *start_address, sizeof(int));
 355         *start_address += sizeof(int);
 356
 357         /* If this datum is NULL, we can stop here. */
 358         if (header == -2)
 359         {
 360                 *isnull = true;
 361                 return (Datum) 0;
 362         }
 363
 364         /* OK, datum is not null. */
 365         *isnull = false;
 366
 367         /* If this datum is pass-by-value, sizeof(Datum) bytes follow. */
 368         if (header == -1)
 369         {
 370                 Datum           val;
 371
 372                 memcpy(&val, *start_address, sizeof(Datum));
 373                 *start_address += sizeof(Datum);
 374                 return val;
 375         }
 376
 377         /* Pass-by-reference case; copy indicated number of bytes. */
 378         Assert(header > 0);
 379         d = palloc(header);
 380         memcpy(d, *start_address, header);
 381         *start_address += header;
 382         return PointerGetDatum(d);
 383 }