codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * subscripting.h4 *		API for generic type subscripting5 *6 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group7 * Portions Copyright (c) 1994, Regents of the University of California8 *9 * src/include/nodes/subscripting.h10 *11 *-------------------------------------------------------------------------12 */13#ifndef SUBSCRIPTING_H14#define SUBSCRIPTING_H15 16#include "nodes/primnodes.h"17 18/* Forward declarations, to avoid including other headers */19struct ParseState;20struct SubscriptingRefState;21struct SubscriptExecSteps;22 23/*24 * The SQL-visible function that defines a subscripting method is declared25 *		subscripting_function(internal) returns internal26 * but it actually is not passed any parameter.  It must return a pointer27 * to a "struct SubscriptRoutines" that provides pointers to the individual28 * subscript parsing and execution methods.  Typically the pointer will point29 * 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 expression31 * of a subscripting construct determines which subscripting function is32 * called for that construct.33 *34 * In addition to the method pointers, struct SubscriptRoutines includes35 * several bool flags that specify properties of the subscripting actions36 * this data type can perform:37 *38 * fetch_strict indicates that a fetch SubscriptRef is strict, i.e., returns39 * 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 requires43 * silently returning NULL for invalid subscripts.44 *45 * store_leakproof similarly indicates whether an assignment SubscriptRef is46 * leakproof.  (It is common to prefer throwing errors for invalid subscripts47 * 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 be51 * undesirable, since for example a null subscript in an assignment would52 * 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 subscripting61 * construct.  The SubscriptingRef node has been constructed, but some of62 * 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 doing64 * parse analysis of each subscript expression (using transformExpr),65 * coercing the subscripts to whatever type it needs, and building the66 * refupperindexpr and reflowerindexpr lists from those results.  The67 * reflowerindexpr list must be empty for an element operation, or the68 * same length as refupperindexpr for a slice operation.  Insert NULLs69 * (that is, an empty parse tree, not a null Const node) for any omitted70 * subscripts in a slice operation.  (Of course, if the transform method71 * 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 type75 * of the subscripting operation.  At call, refcontainertype and reftypmod76 * describe the container type (this will be a base type not a domain), and77 * refelemtype is set to the container type's pg_type.typelem value.  The78 * transform method must set refrestype and reftypmod to describe the result79 * of subscripting.  For arrays, refrestype is set to refelemtype for an80 * element operation or refcontainertype for a slice, while reftypmod stays81 * the same in either case; but other types might use other rules.  The82 * transform method should ignore refcollid, as that's determined later on83 * during parsing.84 *85 * At call, refassgnexpr has not been filled in, so the SubscriptingRef node86 * always looks like a fetch; refrestype should be set as though for a87 * fetch, too.  (The isAssignment parameter is typically only useful if the88 * transform method wishes to throw an error for not supporting assignment.)89 * To complete processing of an assignment, the core parser will coerce the90 * element/slice source expression to the returned refrestype and reftypmod91 * before putting it into refassgnexpr.  It will then set refrestype and92 * reftypmod to again describe the container type, since that's what an93 * assignment must return.94 */95typedef 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 a103 * SubscriptingRef node in an expression.  It must fill *methods with pointers104 * to functions that can be called for execution of the node.  Optionally,105 * exec_setup can initialize sbsrefstate->workspace to point to some palloc'd106 * workspace for execution.  (Typically, such workspace is used to hold107 * looked-up catalog data and/or provide space for the check_subscripts step108 * to pass data forward to the other step functions.)  See executor/execExpr.h109 * for the definitions of these structs and other ones used in expression110 * execution.111 *112 * The methods to be provided are:113 *114 * sbs_check_subscripts: examine the just-computed subscript values available115 * in sbsrefstate's arrays, and possibly convert them into another form116 * (stored in sbsrefstate->workspace).  Return TRUE to continue with117 * evaluation of the subscripting construct, or FALSE to skip it and return an118 * overall NULL result.  If this is a fetch and the data type's fetch_strict119 * flag is true, then sbs_check_subscripts must return FALSE if there are any120 * NULL subscripts.  Otherwise it can choose to throw an error, or return121 * 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 in124 * *op->resvalue and the subscripts from sbs_check_subscripts.  If125 * 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 in127 * *op->resvalue / *op->resnull.128 *129 * sbs_assign: perform a subscripting assignment, using the original130 * container value in *op->resvalue / *op->resnull, the subscripts from131 * sbs_check_subscripts, and the new element/slice value in132 * sbsrefstate->replacevalue/replacenull.  Any of these inputs might be NULL133 * (unless sbs_check_subscripts rejected null subscripts).  Place the result134 * (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 slice137 * assignment involves an assignment to a sub-field or sub-element138 * (i.e., nested containers are involved).  It must fetch the existing139 * value of the target element or slice.  This is exactly the same as140 * sbs_fetch except that (a) it must cope with a NULL container, and141 * with NULL subscripts if sbs_check_subscripts allows them (typically,142 * returning NULL is good enough); and (b) the result must be placed in143 * sbsrefstate->prevvalue/prevnull, without overwriting *op->resvalue.144 *145 * Subscripting implementations that do not support assignment need not146 * provide sbs_assign or sbs_fetch_old methods.  It might be reasonable147 * to also omit sbs_check_subscripts, in which case the sbs_fetch method must148 * combine the functionality of sbs_check_subscripts and sbs_fetch.  (The149 * main reason to have a separate sbs_check_subscripts method is so that150 * sbs_fetch_old and sbs_assign need not duplicate subscript processing.)151 * Set the relevant pointers to NULL for any omitted methods.152 */153typedef void (*SubscriptExecSetup) (const SubscriptingRef *sbsref,154									struct SubscriptingRefState *sbsrefstate,155									struct SubscriptExecSteps *methods);156 157/* Struct returned by the SQL-visible subscript handler function */158typedef struct SubscriptRoutines159{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 */168