| 1 |
/*------------------------------------------------------------------------- |
| 2 |
* |
| 3 |
* subscripting.h |
| 4 |
* API for generic type subscripting |
| 5 |
* |
| 6 |
* Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group |
| 7 |
* Portions Copyright (c) 1994, Regents of the University of California |
| 8 |
* |
| 9 |
* src/include/nodes/subscripting.h |
| 10 |
* |
| 11 |
*------------------------------------------------------------------------- |
| 12 |
*/ |
| 13 |
#ifndef SUBSCRIPTING_H |
| 14 |
#define SUBSCRIPTING_H |
| 15 |
|
| 16 |
#include "nodes/primnodes.h" |
| 17 |
|
| 18 |
/* Forward declarations, to avoid including other headers */ |
| 19 |
struct ParseState; |
| 20 |
struct SubscriptingRefState; |
| 21 |
struct SubscriptExecSteps; |
| 22 |
|
| 23 |
/* |
| 24 |
* The SQL-visible function that defines a subscripting method is declared |
| 25 |
* subscripting_function(internal) returns internal |
| 26 |
* but it actually is not passed any parameter. It must return a pointer |
| 27 |
* to a "struct SubscriptRoutines" that provides pointers to the individual |
| 28 |
* subscript parsing and execution methods. Typically the pointer will point |
| 29 |
* to a "static const" variable, but at need it can point to palloc'd space. |
| 30 |
* The type (after domain-flattening) of the head variable or expression |
| 31 |
* of a subscripting construct determines which subscripting function is |
| 32 |
* called for that construct. |
| 33 |
* |
| 34 |
* In addition to the method pointers, struct SubscriptRoutines includes |
| 35 |
* several bool flags that specify properties of the subscripting actions |
| 36 |
* this data type can perform: |
| 37 |
* |
| 38 |
* fetch_strict indicates that a fetch SubscriptRef is strict, i.e., returns |
| 39 |
* NULL if any input (either the container or any subscript) is NULL. |
| 40 |
* |
| 41 |
* fetch_leakproof indicates that a fetch SubscriptRef is leakproof, i.e., |
| 42 |
* will not throw any data-value-dependent errors. Typically this requires |
| 43 |
* silently returning NULL for invalid subscripts. |
| 44 |
* |
| 45 |
* store_leakproof similarly indicates whether an assignment SubscriptRef is |
| 46 |
* leakproof. (It is common to prefer throwing errors for invalid subscripts |
| 47 |
* in assignments; that's fine, but it makes the operation not leakproof. |
| 48 |
* In current usage there is no advantage in making assignments leakproof.) |
| 49 |
* |
| 50 |
* There is no store_strict flag. Such behavior would generally be |
| 51 |
* undesirable, since for example a null subscript in an assignment would |
| 52 |
* cause the entire container to become NULL. |
| 53 |
* |
| 54 |
* Regardless of these flags, all SubscriptRefs are expected to be immutable, |
| 55 |
* that is they must always give the same results for the same inputs. |
| 56 |
* They are expected to always be parallel-safe, as well. |
| 57 |
*/ |
| 58 |
|
| 59 |
/* |
| 60 |
* The transform method is called during parse analysis of a subscripting |
| 61 |
* construct. The SubscriptingRef node has been constructed, but some of |
| 62 |
* its fields still need to be filled in, and the subscript expression(s) |
| 63 |
* are still in raw form. The transform method is responsible for doing |
| 64 |
* parse analysis of each subscript expression (using transformExpr), |
| 65 |
* coercing the subscripts to whatever type it needs, and building the |
| 66 |
* refupperindexpr and reflowerindexpr lists from those results. The |
| 67 |
* reflowerindexpr list must be empty for an element operation, or the |
| 68 |
* same length as refupperindexpr for a slice operation. Insert NULLs |
| 69 |
* (that is, an empty parse tree, not a null Const node) for any omitted |
| 70 |
* subscripts in a slice operation. (Of course, if the transform method |
| 71 |
* does not care to support slicing, it can just throw an error if isSlice.) |
| 72 |
* See array_subscript_transform() for sample code. |
| 73 |
* |
| 74 |
* The transform method is also responsible for identifying the result type |
| 75 |
* of the subscripting operation. At call, refcontainertype and reftypmod |
| 76 |
* describe the container type (this will be a base type not a domain), and |
| 77 |
* refelemtype is set to the container type's pg_type.typelem value. The |
| 78 |
* transform method must set refrestype and reftypmod to describe the result |
| 79 |
* of subscripting. For arrays, refrestype is set to refelemtype for an |
| 80 |
* element operation or refcontainertype for a slice, while reftypmod stays |
| 81 |
* the same in either case; but other types might use other rules. The |
| 82 |
* transform method should ignore refcollid, as that's determined later on |
| 83 |
* during parsing. |
| 84 |
* |
| 85 |
* At call, refassgnexpr has not been filled in, so the SubscriptingRef node |
| 86 |
* always looks like a fetch; refrestype should be set as though for a |
| 87 |
* fetch, too. (The isAssignment parameter is typically only useful if the |
| 88 |
* transform method wishes to throw an error for not supporting assignment.) |
| 89 |
* To complete processing of an assignment, the core parser will coerce the |
| 90 |
* element/slice source expression to the returned refrestype and reftypmod |
| 91 |
* before putting it into refassgnexpr. It will then set refrestype and |
| 92 |
* reftypmod to again describe the container type, since that's what an |
| 93 |
* assignment must return. |
| 94 |
*/ |
| 95 |
typedef void (*SubscriptTransform) (SubscriptingRef *sbsref, |
| 96 |
List *indirection, |
| 97 |
struct ParseState *pstate, |
| 98 |
bool isSlice, |
| 99 |
bool isAssignment); |
| 100 |
|
| 101 |
/* |
| 102 |
* The exec_setup method is called during executor-startup compilation of a |
| 103 |
* SubscriptingRef node in an expression. It must fill *methods with pointers |
| 104 |
* to functions that can be called for execution of the node. Optionally, |
| 105 |
* exec_setup can initialize sbsrefstate->workspace to point to some palloc'd |
| 106 |
* workspace for execution. (Typically, such workspace is used to hold |
| 107 |
* looked-up catalog data and/or provide space for the check_subscripts step |
| 108 |
* to pass data forward to the other step functions.) See executor/execExpr.h |
| 109 |
* for the definitions of these structs and other ones used in expression |
| 110 |
* execution. |
| 111 |
* |
| 112 |
* The methods to be provided are: |
| 113 |
* |
| 114 |
* sbs_check_subscripts: examine the just-computed subscript values available |
| 115 |
* in sbsrefstate's arrays, and possibly convert them into another form |
| 116 |
* (stored in sbsrefstate->workspace). Return TRUE to continue with |
| 117 |
* evaluation of the subscripting construct, or FALSE to skip it and return an |
| 118 |
* overall NULL result. If this is a fetch and the data type's fetch_strict |
| 119 |
* flag is true, then sbs_check_subscripts must return FALSE if there are any |
| 120 |
* NULL subscripts. Otherwise it can choose to throw an error, or return |
| 121 |
* FALSE, or let sbs_fetch or sbs_assign deal with the null subscripts. |
| 122 |
* |
| 123 |
* sbs_fetch: perform a subscripting fetch, using the container value in |
| 124 |
* *op->resvalue and the subscripts from sbs_check_subscripts. If |
| 125 |
* fetch_strict is true then all these inputs can be assumed non-NULL, |
| 126 |
* otherwise sbs_fetch must check for null inputs. Place the result in |
| 127 |
* *op->resvalue / *op->resnull. |
| 128 |
* |
| 129 |
* sbs_assign: perform a subscripting assignment, using the original |
| 130 |
* container value in *op->resvalue / *op->resnull, the subscripts from |
| 131 |
* sbs_check_subscripts, and the new element/slice value in |
| 132 |
* sbsrefstate->replacevalue/replacenull. Any of these inputs might be NULL |
| 133 |
* (unless sbs_check_subscripts rejected null subscripts). Place the result |
| 134 |
* (an entire new container value) in *op->resvalue / *op->resnull. |
| 135 |
* |
| 136 |
* sbs_fetch_old: this is only used in cases where an element or slice |
| 137 |
* assignment involves an assignment to a sub-field or sub-element |
| 138 |
* (i.e., nested containers are involved). It must fetch the existing |
| 139 |
* value of the target element or slice. This is exactly the same as |
| 140 |
* sbs_fetch except that (a) it must cope with a NULL container, and |
| 141 |
* with NULL subscripts if sbs_check_subscripts allows them (typically, |
| 142 |
* returning NULL is good enough); and (b) the result must be placed in |
| 143 |
* sbsrefstate->prevvalue/prevnull, without overwriting *op->resvalue. |
| 144 |
* |
| 145 |
* Subscripting implementations that do not support assignment need not |
| 146 |
* provide sbs_assign or sbs_fetch_old methods. It might be reasonable |
| 147 |
* to also omit sbs_check_subscripts, in which case the sbs_fetch method must |
| 148 |
* combine the functionality of sbs_check_subscripts and sbs_fetch. (The |
| 149 |
* main reason to have a separate sbs_check_subscripts method is so that |
| 150 |
* sbs_fetch_old and sbs_assign need not duplicate subscript processing.) |
| 151 |
* Set the relevant pointers to NULL for any omitted methods. |
| 152 |
*/ |
| 153 |
typedef void (*SubscriptExecSetup) (const SubscriptingRef *sbsref, |
| 154 |
struct SubscriptingRefState *sbsrefstate, |
| 155 |
struct SubscriptExecSteps *methods); |
| 156 |
|
| 157 |
/* Struct returned by the SQL-visible subscript handler function */ |
| 158 |
typedef struct SubscriptRoutines |
| 159 |
{ |
| 160 |
SubscriptTransform transform; /* parse analysis function */ |
| 161 |
SubscriptExecSetup exec_setup; /* expression compilation function */ |
| 162 |
bool fetch_strict; /* is fetch SubscriptRef strict? */ |
| 163 |
bool fetch_leakproof; /* is fetch SubscriptRef leakproof? */ |
| 164 |
bool store_leakproof; /* is assignment SubscriptRef leakproof? */ |
| 165 |
} SubscriptRoutines; |
| 166 |
|
| 167 |
#endif /* SUBSCRIPTING_H */ |