granicus.if.org Git - postgresql/blob - 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-2014, PostgreSQL Global Development Group
  50  * Portions Copyright (c) 1994, Regents of the University of California
  51  *
  52  * src/include/utils/array.h
  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 /* ArrayIteratorData is private in arrayfuncs.c */
 118 typedef struct ArrayIteratorData *ArrayIterator;
 119
 120 /*
 121  * fmgr macros for array objects
 122  */
 123 #define DatumGetArrayTypeP(X)             ((ArrayType *) PG_DETOAST_DATUM(X))
 124 #define DatumGetArrayTypePCopy(X)         ((ArrayType *) PG_DETOAST_DATUM_COPY(X))
 125 #define PG_GETARG_ARRAYTYPE_P(n)          DatumGetArrayTypeP(PG_GETARG_DATUM(n))
 126 #define PG_GETARG_ARRAYTYPE_P_COPY(n) DatumGetArrayTypePCopy(PG_GETARG_DATUM(n))
 127 #define PG_RETURN_ARRAYTYPE_P(x)          PG_RETURN_POINTER(x)
 128
 129 /*
 130  * Access macros for array header fields.
 131  *
 132  * ARR_DIMS returns a pointer to an array of array dimensions (number of
 133  * elements along the various array axes).
 134  *
 135  * ARR_LBOUND returns a pointer to an array of array lower bounds.
 136  *
 137  * That is: if the third axis of an array has elements 5 through 8, then
 138  * ARR_DIMS(a)[2] == 4 and ARR_LBOUND(a)[2] == 5.
 139  *
 140  * Unlike C, the default lower bound is 1.
 141  */
 142 #define ARR_SIZE(a)                             VARSIZE(a)
 143 #define ARR_NDIM(a)                             ((a)->ndim)
 144 #define ARR_HASNULL(a)                  ((a)->dataoffset != 0)
 145 #define ARR_ELEMTYPE(a)                 ((a)->elemtype)
 146
 147 #define ARR_DIMS(a) \
 148                 ((int *) (((char *) (a)) + sizeof(ArrayType)))
 149 #define ARR_LBOUND(a) \
 150                 ((int *) (((char *) (a)) + sizeof(ArrayType) + \
 151                                   sizeof(int) * ARR_NDIM(a)))
 152
 153 #define ARR_NULLBITMAP(a) \
 154                 (ARR_HASNULL(a) ? \
 155                  (bits8 *) (((char *) (a)) + sizeof(ArrayType) + \
 156                                         2 * sizeof(int) * ARR_NDIM(a)) \
 157                  : (bits8 *) NULL)
 158
 159 /*
 160  * The total array header size (in bytes) for an array with the specified
 161  * number of dimensions and total number of items.
 162  */
 163 #define ARR_OVERHEAD_NONULLS(ndims) \
 164                 MAXALIGN(sizeof(ArrayType) + 2 * sizeof(int) * (ndims))
 165 #define ARR_OVERHEAD_WITHNULLS(ndims, nitems) \
 166                 MAXALIGN(sizeof(ArrayType) + 2 * sizeof(int) * (ndims) + \
 167                                  ((nitems) + 7) / 8)
 168
 169 #define ARR_DATA_OFFSET(a) \
 170                 (ARR_HASNULL(a) ? (a)->dataoffset : ARR_OVERHEAD_NONULLS(ARR_NDIM(a)))
 171
 172 /*
 173  * Returns a pointer to the actual array data.
 174  */
 175 #define ARR_DATA_PTR(a) \
 176                 (((char *) (a)) + ARR_DATA_OFFSET(a))
 177
 178
 179 /*
 180  * GUC parameter
 181  */
 182 extern bool Array_nulls;
 183
 184 /*
 185  * prototypes for functions defined in arrayfuncs.c
 186  */
 187 extern Datum array_in(PG_FUNCTION_ARGS);
 188 extern Datum array_out(PG_FUNCTION_ARGS);
 189 extern Datum array_recv(PG_FUNCTION_ARGS);
 190 extern Datum array_send(PG_FUNCTION_ARGS);
 191 extern Datum array_eq(PG_FUNCTION_ARGS);
 192 extern Datum array_ne(PG_FUNCTION_ARGS);
 193 extern Datum array_lt(PG_FUNCTION_ARGS);
 194 extern Datum array_gt(PG_FUNCTION_ARGS);
 195 extern Datum array_le(PG_FUNCTION_ARGS);
 196 extern Datum array_ge(PG_FUNCTION_ARGS);
 197 extern Datum btarraycmp(PG_FUNCTION_ARGS);
 198 extern Datum hash_array(PG_FUNCTION_ARGS);
 199 extern Datum arrayoverlap(PG_FUNCTION_ARGS);
 200 extern Datum arraycontains(PG_FUNCTION_ARGS);
 201 extern Datum arraycontained(PG_FUNCTION_ARGS);
 202 extern Datum array_ndims(PG_FUNCTION_ARGS);
 203 extern Datum array_dims(PG_FUNCTION_ARGS);
 204 extern Datum array_lower(PG_FUNCTION_ARGS);
 205 extern Datum array_upper(PG_FUNCTION_ARGS);
 206 extern Datum array_length(PG_FUNCTION_ARGS);
 207 extern Datum array_cardinality(PG_FUNCTION_ARGS);
 208 extern Datum array_larger(PG_FUNCTION_ARGS);
 209 extern Datum array_smaller(PG_FUNCTION_ARGS);
 210 extern Datum generate_subscripts(PG_FUNCTION_ARGS);
 211 extern Datum generate_subscripts_nodir(PG_FUNCTION_ARGS);
 212 extern Datum array_fill(PG_FUNCTION_ARGS);
 213 extern Datum array_fill_with_lower_bounds(PG_FUNCTION_ARGS);
 214 extern Datum array_unnest(PG_FUNCTION_ARGS);
 215 extern Datum array_remove(PG_FUNCTION_ARGS);
 216 extern Datum array_replace(PG_FUNCTION_ARGS);
 217
 218 extern Datum array_ref(ArrayType *array, int nSubscripts, int *indx,
 219                   int arraytyplen, int elmlen, bool elmbyval, char elmalign,
 220                   bool *isNull);
 221 extern ArrayType *array_set(ArrayType *array, int nSubscripts, int *indx,
 222                   Datum dataValue, bool isNull,
 223                   int arraytyplen, int elmlen, bool elmbyval, char elmalign);
 224 extern ArrayType *array_get_slice(ArrayType *array, int nSubscripts,
 225                                 int *upperIndx, int *lowerIndx,
 226                                 int arraytyplen, int elmlen, bool elmbyval, char elmalign);
 227 extern ArrayType *array_set_slice(ArrayType *array, int nSubscripts,
 228                                 int *upperIndx, int *lowerIndx,
 229                                 ArrayType *srcArray, bool isNull,
 230                                 int arraytyplen, int elmlen, bool elmbyval, char elmalign);
 231
 232 extern Datum array_map(FunctionCallInfo fcinfo, Oid inpType, Oid retType,
 233                   ArrayMapState *amstate);
 234
 235 extern void array_bitmap_copy(bits8 *destbitmap, int destoffset,
 236                                   const bits8 *srcbitmap, int srcoffset,
 237                                   int nitems);
 238
 239 extern ArrayType *construct_array(Datum *elems, int nelems,
 240                                 Oid elmtype,
 241                                 int elmlen, bool elmbyval, char elmalign);
 242 extern ArrayType *construct_md_array(Datum *elems,
 243                                    bool *nulls,
 244                                    int ndims,
 245                                    int *dims,
 246                                    int *lbs,
 247                                    Oid elmtype, int elmlen, bool elmbyval, char elmalign);
 248 extern ArrayType *construct_empty_array(Oid elmtype);
 249 extern void deconstruct_array(ArrayType *array,
 250                                   Oid elmtype,
 251                                   int elmlen, bool elmbyval, char elmalign,
 252                                   Datum **elemsp, bool **nullsp, int *nelemsp);
 253 extern bool array_contains_nulls(ArrayType *array);
 254 extern ArrayBuildState *accumArrayResult(ArrayBuildState *astate,
 255                                  Datum dvalue, bool disnull,
 256                                  Oid element_type,
 257                                  MemoryContext rcontext);
 258 extern Datum makeArrayResult(ArrayBuildState *astate,
 259                                 MemoryContext rcontext);
 260 extern Datum makeMdArrayResult(ArrayBuildState *astate, int ndims,
 261                                   int *dims, int *lbs, MemoryContext rcontext, bool release);
 262
 263 extern ArrayIterator array_create_iterator(ArrayType *arr, int slice_ndim);
 264 extern bool array_iterate(ArrayIterator iterator, Datum *value, bool *isnull);
 265 extern void array_free_iterator(ArrayIterator iterator);
 266
 267 /*
 268  * prototypes for functions defined in arrayutils.c
 269  */
 270
 271 extern int      ArrayGetOffset(int n, const int *dim, const int *lb, const int *indx);
 272 extern int      ArrayGetOffset0(int n, const int *tup, const int *scale);
 273 extern int      ArrayGetNItems(int ndim, const int *dims);
 274 extern void mda_get_range(int n, int *span, const int *st, const int *endp);
 275 extern void mda_get_prod(int n, const int *range, int *prod);
 276 extern void mda_get_offset_values(int n, int *dist, const int *prod, const int *span);
 277 extern int      mda_next_tuple(int n, int *curr, const int *span);
 278 extern int32 *ArrayGetIntegerTypmods(ArrayType *arr, int *n);
 279
 280 /*
 281  * prototypes for functions defined in array_userfuncs.c
 282  */
 283 extern Datum array_push(PG_FUNCTION_ARGS);
 284 extern Datum array_cat(PG_FUNCTION_ARGS);
 285
 286 extern ArrayType *create_singleton_array(FunctionCallInfo fcinfo,
 287                                            Oid element_type,
 288                                            Datum element,
 289                                            bool isNull,
 290                                            int ndims);
 291
 292 extern Datum array_agg_transfn(PG_FUNCTION_ARGS);
 293 extern Datum array_agg_finalfn(PG_FUNCTION_ARGS);
 294
 295 /*
 296  * prototypes for functions defined in array_typanalyze.c
 297  */
 298 extern Datum array_typanalyze(PG_FUNCTION_ARGS);
 299
 300 #endif   /* ARRAY_H */