Improve commentary about ArrayRef and ResTarget nodes.

diff --git a/src/include/nodes/parsenodes.h b/src/include/nodes/parsenodes.h
index ef9f51c..ab22b73 100644 (file)
--- a/src/include/nodes/parsenodes.h
+++ b/src/include/nodes/parsenodes.h
@@ -6,7 +6,7 @@
  *
  * Copyright (c) 1994, Regents of the University of California
  *
- * $Id: parsenodes.h,v 1.76 1999/07/15 23:03:54 momjian Exp $
+ * $Id: parsenodes.h,v 1.77 1999/07/18 03:45:01 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -810,14 +810,23 @@ typedef struct A_Indices
 /*
  * ResTarget -
  *       result target (used in target list of pre-transformed Parse trees)
+ *
+ * In a SELECT or INSERT target list, 'name' is either NULL or
+ * the column name assigned to the value.  (If there is an 'AS ColumnLabel'
+ * clause, the grammar sets 'name' from it; otherwise 'name' is initially NULL
+ * and is filled in during the parse analysis phase.)
+ * The 'indirection' field is not used at all.
+ *
+ * In an UPDATE target list, 'name' is the name of the destination column,
+ * and 'indirection' stores any subscripts attached to the destination.
+ * That is, our representation is UPDATE table SET name [indirection] = val.
  */
 typedef struct ResTarget
 {
        NodeTag         type;
-       char       *name;                       /* name of the result column */
-       List       *indirection;        /* array references */
-       Node       *val;                        /* the value of the result (A_Expr or
-                                                                * Attr) (or A_Const) */
+       char       *name;                       /* column name or NULL */
+       List       *indirection;        /* subscripts for destination column, or NIL */
+       Node       *val;                        /* the value expression to compute or assign */
 } ResTarget;
 
 /*

diff --git a/src/include/nodes/primnodes.h b/src/include/nodes/primnodes.h
index 397575b..a4128a8 100644 (file)
--- a/src/include/nodes/primnodes.h
+++ b/src/include/nodes/primnodes.h
@@ -6,7 +6,7 @@
  *
  * Copyright (c) 1994, Regents of the University of California
  *
- * $Id: primnodes.h,v 1.31 1999/07/16 17:07:33 momjian Exp $
+ * $Id: primnodes.h,v 1.32 1999/07/18 03:45:01 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -302,13 +302,13 @@ typedef struct SubLink
 
 /* ----------------
  * Array
- *             arrayelemtype   - base type of the array's elements (homogenous!)
+ *             arrayelemtype   - type of the array's elements (homogenous!)
  *             arrayelemlength - length of that type
- *             arrayelembyval  - can you pass this element by value?
+ *             arrayelembyval  - is the element type pass-by-value?
  *             arrayndim               - number of dimensions of the array
  *             arraylow                - base for array indexing
  *             arrayhigh               - limit for array indexing
- *             arraylen                -
+ *             arraylen                - total length of array object
  * ----------------
  *
  *     memo from mao:  the array support we inherited from 3.1 is just
@@ -328,15 +328,39 @@ typedef struct Array
 } Array;
 
 /* ----------------
- *     ArrayRef:
- *             refelemtype             - type of the element referenced here
- *             refelemlength   - length of that type
- *             refelembyval    - can you pass this element type by value?
- *             refupperindexpr - expressions that evaluate to upper array index
- *             reflowerexpr- the expressions that evaluate to a lower array index
- *             refexpr                 - the expression that evaluates to an array
- *             refassignexpr- the expression that evaluates to the new value
- *     to be assigned to the array in case of replace.
+ *     ArrayRef: describes an array subscripting operation
+ *
+ * An ArrayRef can describe fetching a single element from an array,
+ * fetching a subarray (array slice), storing a single element into
+ * an array, or storing a slice.  The "store" cases work with an
+ * initial array value and a source value that is inserted into the
+ * appropriate part of the array.
+ *
+ *             refattrlength   - total length of array object
+ *             refelemtype             - type of the result of the subscript operation
+ *             refelemlength   - length of the array element type
+ *             refelembyval    - is the element type pass-by-value?
+ *             refupperindexpr - expressions that evaluate to upper array indexes
+ *             reflowerindexpr - expressions that evaluate to lower array indexes
+ *             refexpr                 - the expression that evaluates to an array value
+ *             refassgnexpr    - expression for the source value, or NULL if fetch
+ *
+ * If reflowerindexpr = NIL, then we are fetching or storing a single array
+ * element at the subscripts given by refupperindexpr.  Otherwise we are
+ * fetching or storing an array slice, that is a rectangular subarray
+ * with lower and upper bounds given by the index expressions.
+ * reflowerindexpr must be the same length as refupperindexpr when it
+ * is not NIL.
+ *
+ * Note: array types can be fixed-length (refattrlength > 0), but only
+ * when the element type is itself fixed-length.  Otherwise they are
+ * varlena structures and have refattrlength = -1.  In any case,
+ * an array type is never pass-by-value.
+ *
+ * Note: currently, refelemtype is NOT the element type, but the array type,
+ * when doing subarray fetch or either type of store.  It would be cleaner
+ * to add more fields so we can distinguish the array element type from the
+ * result type of the subscript operator...
  * ----------------
  */
 typedef struct ArrayRef