src/include/access/tupmacs.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * tupmacs.h
   4  *        Tuple macros used by both index tuples and heap tuples.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * src/include/access/tupmacs.h
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef TUPMACS_H
  15 #define TUPMACS_H
  16
  17 #include "catalog/pg_type_d.h"  /* for TYPALIGN macros */
  18
  19
  20 /*
  21  * Check a tuple's null bitmap to determine whether the attribute is null.
  22  * Note that a 0 in the null bitmap indicates a null, while 1 indicates
  23  * non-null.
  24  */
  25 static inline bool
  26 att_isnull(int ATT, const bits8 *BITS)
  27 {
  28         return !(BITS[ATT >> 3] & (1 << (ATT & 0x07)));
  29 }
  30
  31 #ifndef FRONTEND
  32 /*
  33  * Given an attbyval and an attlen from either a Form_pg_attribute or
  34  * CompactAttribute and a pointer into a tuple's data area, return the
  35  * correct value or pointer.
  36  *
  37  * We return a Datum value in all cases.  If attbyval is false,  we return the
  38  * same pointer into the tuple data area that we're passed.  Otherwise, we
  39  * return the correct number of bytes fetched from the data area and extended
  40  * to Datum form.
  41  *
  42  * On machines where Datum is 8 bytes, we support fetching 8-byte byval
  43  * attributes; otherwise, only 1, 2, and 4-byte values are supported.
  44  *
  45  * Note that T must already be properly aligned for this to work correctly.
  46  */
  47 #define fetchatt(A,T) fetch_att(T, (A)->attbyval, (A)->attlen)
  48
  49 /*
  50  * Same, but work from byval/len parameters rather than Form_pg_attribute.
  51  */
  52 static inline Datum
  53 fetch_att(const void *T, bool attbyval, int attlen)
  54 {
  55         if (attbyval)
  56         {
  57                 switch (attlen)
  58                 {
  59                         case sizeof(char):
  60                                 return CharGetDatum(*((const char *) T));
  61                         case sizeof(int16):
  62                                 return Int16GetDatum(*((const int16 *) T));
  63                         case sizeof(int32):
  64                                 return Int32GetDatum(*((const int32 *) T));
  65 #if SIZEOF_DATUM == 8
  66                         case sizeof(Datum):
  67                                 return *((const Datum *) T);
  68 #endif
  69                         default:
  70                                 elog(ERROR, "unsupported byval length: %d", attlen);
  71                                 return 0;
  72                 }
  73         }
  74         else
  75                 return PointerGetDatum(T);
  76 }
  77 #endif                                                  /* FRONTEND */
  78
  79 /*
  80  * att_align_datum aligns the given offset as needed for a datum of alignment
  81  * requirement attalign and typlen attlen.  attdatum is the Datum variable
  82  * we intend to pack into a tuple (it's only accessed if we are dealing with
  83  * a varlena type).  Note that this assumes the Datum will be stored as-is;
  84  * callers that are intending to convert non-short varlena datums to short
  85  * format have to account for that themselves.
  86  */
  87 #define att_align_datum(cur_offset, attalign, attlen, attdatum) \
  88 ( \
  89         ((attlen) == -1 && VARATT_IS_SHORT(DatumGetPointer(attdatum))) ? \
  90         (uintptr_t) (cur_offset) : \
  91         att_align_nominal(cur_offset, attalign) \
  92 )
  93
  94 /*
  95  * Similar to att_align_datum, but accepts a number of bytes, typically from
  96  * CompactAttribute.attalignby to align the Datum by.
  97  */
  98 #define att_datum_alignby(cur_offset, attalignby, attlen, attdatum) \
  99         ( \
 100         ((attlen) == -1 && VARATT_IS_SHORT(DatumGetPointer(attdatum))) ? \
 101         (uintptr_t) (cur_offset) : \
 102         TYPEALIGN(attalignby, cur_offset))
 103
 104 /*
 105  * att_align_pointer performs the same calculation as att_align_datum,
 106  * but is used when walking a tuple.  attptr is the current actual data
 107  * pointer; when accessing a varlena field we have to "peek" to see if we
 108  * are looking at a pad byte or the first byte of a 1-byte-header datum.
 109  * (A zero byte must be either a pad byte, or the first byte of a correctly
 110  * aligned 4-byte length word; in either case we can align safely.  A non-zero
 111  * byte must be either a 1-byte length word, or the first byte of a correctly
 112  * aligned 4-byte length word; in either case we need not align.)
 113  *
 114  * Note: some callers pass a "char *" pointer for cur_offset.  This is
 115  * a bit of a hack but should work all right as long as uintptr_t is the
 116  * correct width.
 117  */
 118 #define att_align_pointer(cur_offset, attalign, attlen, attptr) \
 119 ( \
 120         ((attlen) == -1 && VARATT_NOT_PAD_BYTE(attptr)) ? \
 121         (uintptr_t) (cur_offset) : \
 122         att_align_nominal(cur_offset, attalign) \
 123 )
 124
 125 /*
 126  * Similar to att_align_pointer, but accepts a number of bytes, typically from
 127  * CompactAttribute.attalignby to align the pointer by.
 128  */
 129 #define att_pointer_alignby(cur_offset, attalignby, attlen, attptr) \
 130         ( \
 131         ((attlen) == -1 && VARATT_NOT_PAD_BYTE(attptr)) ? \
 132         (uintptr_t) (cur_offset) : \
 133         TYPEALIGN(attalignby, cur_offset))
 134
 135 /*
 136  * att_align_nominal aligns the given offset as needed for a datum of alignment
 137  * requirement attalign, ignoring any consideration of packed varlena datums.
 138  * There are three main use cases for using this macro directly:
 139  *      * we know that the att in question is not varlena (attlen != -1);
 140  *        in this case it is cheaper than the above macros and just as good.
 141  *      * we need to estimate alignment padding cost abstractly, ie without
 142  *        reference to a real tuple.  We must assume the worst case that
 143  *        all varlenas are aligned.
 144  *      * within arrays and multiranges, we unconditionally align varlenas (XXX this
 145  *        should be revisited, probably).
 146  *
 147  * The attalign cases are tested in what is hopefully something like their
 148  * frequency of occurrence.
 149  */
 150 #define att_align_nominal(cur_offset, attalign) \
 151 ( \
 152         ((attalign) == TYPALIGN_INT) ? INTALIGN(cur_offset) : \
 153          (((attalign) == TYPALIGN_CHAR) ? (uintptr_t) (cur_offset) : \
 154           (((attalign) == TYPALIGN_DOUBLE) ? DOUBLEALIGN(cur_offset) : \
 155            ( \
 156                         AssertMacro((attalign) == TYPALIGN_SHORT), \
 157                         SHORTALIGN(cur_offset) \
 158            ))) \
 159 )
 160
 161 /*
 162  * Similar to att_align_nominal, but accepts a number of bytes, typically from
 163  * CompactAttribute.attalignby to align the offset by.
 164  */
 165 #define att_nominal_alignby(cur_offset, attalignby) \
 166         TYPEALIGN(attalignby, cur_offset)
 167
 168 /*
 169  * att_addlength_datum increments the given offset by the space needed for
 170  * the given Datum variable.  attdatum is only accessed if we are dealing
 171  * with a variable-length attribute.
 172  */
 173 #define att_addlength_datum(cur_offset, attlen, attdatum) \
 174         att_addlength_pointer(cur_offset, attlen, DatumGetPointer(attdatum))
 175
 176 /*
 177  * att_addlength_pointer performs the same calculation as att_addlength_datum,
 178  * but is used when walking a tuple --- attptr is the pointer to the field
 179  * within the tuple.
 180  *
 181  * Note: some callers pass a "char *" pointer for cur_offset.  This is
 182  * actually perfectly OK, but probably should be cleaned up along with
 183  * the same practice for att_align_pointer.
 184  */
 185 #define att_addlength_pointer(cur_offset, attlen, attptr) \
 186 ( \
 187         ((attlen) > 0) ? \
 188         ( \
 189                 (cur_offset) + (attlen) \
 190         ) \
 191         : (((attlen) == -1) ? \
 192         ( \
 193                 (cur_offset) + VARSIZE_ANY(attptr) \
 194         ) \
 195         : \
 196         ( \
 197                 AssertMacro((attlen) == -2), \
 198                 (cur_offset) + (strlen((char *) (attptr)) + 1) \
 199         )) \
 200 )
 201
 202 #ifndef FRONTEND
 203 /*
 204  * store_att_byval is a partial inverse of fetch_att: store a given Datum
 205  * value into a tuple data area at the specified address.  However, it only
 206  * handles the byval case, because in typical usage the caller needs to
 207  * distinguish by-val and by-ref cases anyway, and so a do-it-all function
 208  * wouldn't be convenient.
 209  */
 210 static inline void
 211 store_att_byval(void *T, Datum newdatum, int attlen)
 212 {
 213         switch (attlen)
 214         {
 215                 case sizeof(char):
 216                         *(char *) T = DatumGetChar(newdatum);
 217                         break;
 218                 case sizeof(int16):
 219                         *(int16 *) T = DatumGetInt16(newdatum);
 220                         break;
 221                 case sizeof(int32):
 222                         *(int32 *) T = DatumGetInt32(newdatum);
 223                         break;
 224 #if SIZEOF_DATUM == 8
 225                 case sizeof(Datum):
 226                         *(Datum *) T = newdatum;
 227                         break;
 228 #endif
 229                 default:
 230                         elog(ERROR, "unsupported byval length: %d", attlen);
 231         }
 232 }
 233 #endif                                                  /* FRONTEND */
 234
 235 #endif                                                  /* TUPMACS_H */