src/include/utils/array.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * array.h
   4  *        Declarations for Postgres arrays.
   5  *
   6  * A standard varlena array has the following internal structure:
   7  *        <vl_len_>             - standard varlena header word
   8  *        <ndim>                - number of dimensions of the array
   9  *        <dataoffset>  - offset to stored data, or 0 if no nulls bitmap
  10  *        <elemtype>    - element type OID
  11  *        <dimensions>  - length of each array axis (C array of int)
  12  *        <lower bnds>  - lower boundary of each dimension (C array of int)
  13  *        <null bitmap> - bitmap showing locations of nulls (OPTIONAL)
  14  *        <actual data> - whatever is the stored data
  15  *
  16  * The <dimensions> and <lower bnds> arrays each have ndim elements.
  17  *
  18  * The <null bitmap> may be omitted if the array contains no NULL elements.
  19  * If it is absent, the <dataoffset> field is zero and the offset to the
  20  * stored data must be computed on-the-fly.  If the bitmap is present,
  21  * <dataoffset> is nonzero and is equal to the offset from the array start
  22  * to the first data element (including any alignment padding).  The bitmap
  23  * follows the same conventions as tuple null bitmaps, ie, a 1 indicates
  24  * a non-null entry and the LSB of each bitmap byte is used first.
  25  *
  26  * The actual data starts on a MAXALIGN boundary.  Individual items in the
  27  * array are aligned as specified by the array element type.  They are
  28  * stored in row-major order (last subscript varies most rapidly).
  29  *
  30  * NOTE: it is important that array elements of toastable datatypes NOT be
  31  * toasted, since the tupletoaster won't know they are there.  (We could
  32  * support compressed toasted items; only out-of-line items are dangerous.
  33  * However, it seems preferable to store such items uncompressed and allow
  34  * the toaster to compress the whole array as one input.)
  35  *
  36  *
  37  * The OIDVECTOR and INT2VECTOR datatypes are storage-compatible with
  38  * generic arrays, but they support only one-dimensional arrays with no
  39  * nulls (and no null bitmap).
  40  *
  41  * There are also some "fixed-length array" datatypes, such as NAME and
  42  * POINT.  These are simply a sequence of a fixed number of items each
  43  * of a fixed-length datatype, with no overhead; the item size must be
  44  * a multiple of its alignment requirement, because we do no padding.
  45  * We support subscripting on these types, but array_in() and array_out()
  46  * only work with varlena arrays.
  47  *
  48  *
  49  * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
  50  * Portions Copyright (c) 1994, Regents of the University of California
  51  *
  52  * $PostgreSQL$
  53  *
  54  *-------------------------------------------------------------------------
  55  */
  56 #ifndef ARRAY_H
  57 #define ARRAY_H
  58
  59 #include "fmgr.h"
  60
  61 /*
  62  * Arrays are varlena objects, so must meet the varlena convention that
  63  * the first int32 of the object contains the total object size in bytes.
  64  * Be sure to use VARSIZE() and SET_VARSIZE() to access it, though!
  65  *
  66  * CAUTION: if you change the header for ordinary arrays you will also
  67  * need to change the headers for oidvector and int2vector!
  68  */
  69 typedef struct
  70 {
  71         int32           vl_len_;                /* varlena header (do not touch directly!) */
  72         int                     ndim;                   /* # of dimensions */
  73         int32           dataoffset;             /* offset to data, or 0 if no bitmap */
  74         Oid                     elemtype;               /* element type OID */
  75 } ArrayType;
  76
  77 /*
  78  * working state for accumArrayResult() and friends
  79  */
  80 typedef struct ArrayBuildState
  81 {
  82         MemoryContext mcontext;         /* where all the temp stuff is kept */
  83         Datum      *dvalues;            /* array of accumulated Datums */
  84         bool       *dnulls;                     /* array of is-null flags for Datums */
  85         int                     alen;                   /* allocated length of above arrays */
  86         int                     nelems;                 /* number of valid entries in above arrays */
  87         Oid                     element_type;   /* data type of the Datums */
  88         int16           typlen;                 /* needed info about datatype */
  89         bool            typbyval;
  90         char            typalign;
  91 } ArrayBuildState;
  92
  93 /*
  94  * structure to cache type metadata needed for array manipulation
  95  */
  96 typedef struct ArrayMetaState
  97 {
  98         Oid                     element_type;
  99         int16           typlen;
 100         bool            typbyval;
 101         char            typalign;
 102         char            typdelim;
 103         Oid                     typioparam;
 104         Oid                     typiofunc;
 105         FmgrInfo        proc;
 106 } ArrayMetaState;
 107
 108 /*
 109  * private state needed by array_map (here because caller must provide it)
 110  */
 111 typedef struct ArrayMapState
 112 {
 113         ArrayMetaState inp_extra;
 114         ArrayMetaState ret_extra;
 115 } ArrayMapState;
 116
 117 /*
 118  * fmgr macros for array objects
 119  */
 120 #define DatumGetArrayTypeP(X)             ((ArrayType *) PG_DETOAST_DATUM(X))
 121 #define DatumGetArrayTypePCopy(X)         ((ArrayType *) PG_DETOAST_DATUM_COPY(X))
 122 #define PG_GETARG_ARRAYTYPE_P(n)          DatumGetArrayTypeP(PG_GETARG_DATUM(n))
 123 #define PG_GETARG_ARRAYTYPE_P_COPY(n) DatumGetArrayTypePCopy(PG_GETARG_DATUM(n))
 124 #define PG_RETURN_ARRAYTYPE_P(x)          PG_RETURN_POINTER(x)
 125
 126 /*
 127  * Access macros for array header fields.
 128  *
 129  * ARR_DIMS returns a pointer to an array of array dimensions (number of
 130  * elements along the various array axes).
 131  *
 132  * ARR_LBOUND returns a pointer to an array of array lower bounds.
 133  *
 134  * That is: if the third axis of an array has elements 5 through 8, then
 135  * ARR_DIMS(a)[2] == 4 and ARR_LBOUND(a)[2] == 5.
 136  *
 137  * Unlike C, the default lower bound is 1.
 138  */
 139 #define ARR_SIZE(a)                             VARSIZE(a)
 140 #define ARR_NDIM(a)                             ((a)->ndim)
 141 #define ARR_HASNULL(a)                  ((a)->dataoffset != 0)
 142 #define ARR_ELEMTYPE(a)                 ((a)->elemtype)
 143
 144 #define ARR_DIMS(a) \
 145                 ((int *) (((char *) (a)) + sizeof(ArrayType)))
 146 #define ARR_LBOUND(a) \
 147                 ((int *) (((char *) (a)) + sizeof(ArrayType) + \
 148                                   sizeof(int) * ARR_NDIM(a)))
 149
 150 #define ARR_NULLBITMAP(a) \
 151                 (ARR_HASNULL(a) ? \
 152                  (bits8 *) (((char *) (a)) + sizeof(ArrayType) + \
 153                                         2 * sizeof(int) * ARR_NDIM(a)) \
 154                  : (bits8 *) NULL)
 155
 156 /*
 157  * The total array header size (in bytes) for an array with the specified
 158  * number of dimensions and total number of items.
 159  */
 160 #define ARR_OVERHEAD_NONULLS(ndims) \
 161                 MAXALIGN(sizeof(ArrayType) + 2 * sizeof(int) * (ndims))
 162 #define ARR_OVERHEAD_WITHNULLS(ndims, nitems) \
 163                 MAXALIGN(sizeof(ArrayType) + 2 * sizeof(int) * (ndims) + \
 164                                  ((nitems) + 7) / 8)
 165
 166 #define ARR_DATA_OFFSET(a) \
 167                 (ARR_HASNULL(a) ? (a)->dataoffset : ARR_OVERHEAD_NONULLS(ARR_NDIM(a)))
 168
 169 /*
 170  * Returns a pointer to the actual array data.
 171  */
 172 #define ARR_DATA_PTR(a) \
 173                 (((char *) (a)) + ARR_DATA_OFFSET(a))
 174
 175
 176 /*
 177  * GUC parameter
 178  */
 179 extern bool Array_nulls;
 180
 181 /*
 182  * prototypes for functions defined in arrayfuncs.c
 183  */
 184 extern Datum array_in(PG_FUNCTION_ARGS);
 185 extern Datum array_out(PG_FUNCTION_ARGS);
 186 extern Datum array_recv(PG_FUNCTION_ARGS);
 187 extern Datum array_send(PG_FUNCTION_ARGS);
 188 extern Datum array_eq(PG_FUNCTION_ARGS);
 189 extern Datum array_ne(PG_FUNCTION_ARGS);
 190 extern Datum array_lt(PG_FUNCTION_ARGS);
 191 extern Datum array_gt(PG_FUNCTION_ARGS);
 192 extern Datum array_le(PG_FUNCTION_ARGS);
 193 extern Datum array_ge(PG_FUNCTION_ARGS);
 194 extern Datum btarraycmp(PG_FUNCTION_ARGS);
 195 extern Datum arrayoverlap(PG_FUNCTION_ARGS);
 196 extern Datum arraycontains(PG_FUNCTION_ARGS);
 197 extern Datum arraycontained(PG_FUNCTION_ARGS);
 198 extern Datum array_dims(PG_FUNCTION_ARGS);
 199 extern Datum array_lower(PG_FUNCTION_ARGS);
 200 extern Datum array_upper(PG_FUNCTION_ARGS);
 201 extern Datum array_larger(PG_FUNCTION_ARGS);
 202 extern Datum array_smaller(PG_FUNCTION_ARGS);
 203 extern Datum generate_subscripts(PG_FUNCTION_ARGS);
 204 extern Datum generate_subscripts_nodir(PG_FUNCTION_ARGS);
 205 extern Datum array_fill(PG_FUNCTION_ARGS);
 206 extern Datum array_fill_with_lower_bounds(PG_FUNCTION_ARGS);
 207
 208 extern Datum array_ref(ArrayType *array, int nSubscripts, int *indx,
 209                   int arraytyplen, int elmlen, bool elmbyval, char elmalign,
 210                   bool *isNull);
 211 extern ArrayType *array_set(ArrayType *array, int nSubscripts, int *indx,
 212                   Datum dataValue, bool isNull,
 213                   int arraytyplen, int elmlen, bool elmbyval, char elmalign);
 214 extern ArrayType *array_get_slice(ArrayType *array, int nSubscripts,
 215                                 int *upperIndx, int *lowerIndx,
 216                                 int arraytyplen, int elmlen, bool elmbyval, char elmalign);
 217 extern ArrayType *array_set_slice(ArrayType *array, int nSubscripts,
 218                                 int *upperIndx, int *lowerIndx,
 219                                 ArrayType *srcArray, bool isNull,
 220                                 int arraytyplen, int elmlen, bool elmbyval, char elmalign);
 221
 222 extern Datum array_map(FunctionCallInfo fcinfo, Oid inpType, Oid retType,
 223                   ArrayMapState *amstate);
 224
 225 extern void array_bitmap_copy(bits8 *destbitmap, int destoffset,
 226                                   const bits8 *srcbitmap, int srcoffset,
 227                                   int nitems);
 228
 229 extern ArrayType *construct_array(Datum *elems, int nelems,
 230                                 Oid elmtype,
 231                                 int elmlen, bool elmbyval, char elmalign);
 232 extern ArrayType *construct_md_array(Datum *elems,
 233                                    bool *nulls,
 234                                    int ndims,
 235                                    int *dims,
 236                                    int *lbs,
 237                                    Oid elmtype, int elmlen, bool elmbyval, char elmalign);
 238 extern ArrayType *construct_empty_array(Oid elmtype);
 239 extern void deconstruct_array(ArrayType *array,
 240                                   Oid elmtype,
 241                                   int elmlen, bool elmbyval, char elmalign,
 242                                   Datum **elemsp, bool **nullsp, int *nelemsp);
 243 extern ArrayBuildState *accumArrayResult(ArrayBuildState *astate,
 244                                  Datum dvalue, bool disnull,
 245                                  Oid element_type,
 246                                  MemoryContext rcontext);
 247 extern Datum makeArrayResult(ArrayBuildState *astate,
 248                                 MemoryContext rcontext);
 249 extern Datum makeMdArrayResult(ArrayBuildState *astate, int ndims,
 250                                   int *dims, int *lbs, MemoryContext rcontext);
 251
 252 /*
 253  * prototypes for functions defined in arrayutils.c
 254  */
 255
 256 extern int      ArrayGetOffset(int n, const int *dim, const int *lb, const int *indx);
 257 extern int      ArrayGetOffset0(int n, const int *tup, const int *scale);
 258 extern int      ArrayGetNItems(int ndim, const int *dims);
 259 extern void mda_get_range(int n, int *span, const int *st, const int *endp);
 260 extern void mda_get_prod(int n, const int *range, int *prod);
 261 extern void mda_get_offset_values(int n, int *dist, const int *prod, const int *span);
 262 extern int      mda_next_tuple(int n, int *curr, const int *span);
 263 extern int32 *ArrayGetIntegerTypmods(ArrayType *arr, int *n);
 264
 265 /*
 266  * prototypes for functions defined in array_userfuncs.c
 267  */
 268 extern Datum array_push(PG_FUNCTION_ARGS);
 269 extern Datum array_cat(PG_FUNCTION_ARGS);
 270
 271 extern ArrayType *create_singleton_array(FunctionCallInfo fcinfo,
 272                                            Oid element_type,
 273                                            Datum element,
 274                                            int ndims);
 275
 276 #endif   /* ARRAY_H */