Support assignment to subfields of composite columns in UPDATE and INSERT.

As a side effect, cause subscripts in INSERT targetlists to do something
more or less sensible; previously we evaluated such subscripts and then
effectively ignored them.  Another side effect is that UPDATE-ing an
element or slice of an array value that is NULL now produces a non-null
result, namely an array containing just the assigned-to positions.

Author: tglsfdc

doc/src/sgml/ref/insert.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.26 2003/11/29 19:51:39 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.27 2004/06/09 19:08:13 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -73,6 +73,9 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
     <listitem>
      <para>
       The name of a column in <replaceable class="PARAMETER">table</replaceable>.
+      The column name can be qualified with a subfield name or array
+      subscript, if needed.  (Inserting into only some fields of a
+      composite column leaves the other fields null.)
      </para>
     </listitem>
    </varlistentry>
@@ -184,13 +187,11 @@ INSERT INTO films SELECT * FROM tmp;
 
 <programlisting>
 -- Create an empty 3x3 gameboard for noughts-and-crosses
--- (all of these commands create the same board)
+-- (these commands create the same board)
 INSERT INTO tictactoe (game, board[1:3][1:3])
-    VALUES (1,'{{"","",""},{},{"",""}}');
-INSERT INTO tictactoe (game, board[3][3])
-    VALUES (2,'{}');
+    VALUES (1,'{{"","",""},{"","",""},{"","",""}}');
 INSERT INTO tictactoe (game, board)
-    VALUES (3,'{{,,},{,,},{,,}}');
+    VALUES (2,'{{,,},{,,},{,,}}');
 </programlisting>
   </para>
  </refsect1>

doc/src/sgml/ref/update.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/update.sgml,v 1.28 2004/03/03 22:22:24 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/update.sgml,v 1.29 2004/06/09 19:08:13 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -77,7 +77,10 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> SET <replacea
     <term><replaceable class="PARAMETER">column</replaceable></term>
     <listitem>
      <para>
-      The name of a column in <replaceable class="PARAMETER">table</replaceable>.
+      The name of a column in <replaceable
+      class="PARAMETER">table</replaceable>.
+      The column name can be qualified with a subfield name or array
+      subscript, if needed.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/rowtypes.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.1 2004/06/07 04:04:47 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.2 2004/06/09 19:08:14 tgl Exp $ -->
 
 <sect1 id="rowtypes">
  <title>Composite Types</title>
@@ -66,6 +66,27 @@ SELECT price_extension(item, 10) FROM on_hand;
 </programlisting>
 
  </para>
+
+ <para>
+  Whenever you create a table, a composite type is also automatically
+  created, with the same name as the table, to represent the table's
+  row type.  For example, had we said
+<programlisting>
+CREATE TABLE inventory_item (
+    name            text,
+    supplier_id     integer REFERENCES suppliers,
+    price           numeric CHECK (price > 0)
+);
+</programlisting>
+  then the same <literal>inventory_item</> composite type shown above would
+  come into being as a 
+  byproduct, and could be used just as above.  Note however an important
+  restriction of the current implementation: since no constraints are
+  associated with a composite type, the constraints shown in the table
+  definition <emphasis>do not apply</> to values of the composite type
+  outside the table.  (A partial workaround is to use domain
+  types as members of composite types.)
+ </para>
  </sect2>
 
  <sect2>
@@ -178,6 +199,49 @@ SELECT (my_func(...)).field FROM ...
  </para>
  </sect2>
 
+ <sect2>
+  <title>Modifying Composite Types</title>
+
+ <para>
+  Here are some examples of the proper syntax for inserting and updating
+  composite columns.
+  First, inserting or updating a whole column:
+
+<programlisting>
+INSERT INTO mytab (complex_col) VALUES((1.1,2.2));
+
+UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...;
+</programlisting>
+
+  The first example omits <literal>ROW</>, the second uses it; we
+  could have done it either way.
+ </para>
+
+ <para>
+  We can update an individual subfield of a composite column:
+
+<programlisting>
+UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...;
+</programlisting>
+
+  Notice here that we don't need to (and indeed cannot)
+  put parentheses around the column name appearing just after
+  <literal>SET</>, but we do need parentheses when referencing the same
+  column in the expression to the right of the equal sign.
+ </para>
+
+ <para>
+  And we can specify subfields as targets for <command>INSERT</>, too:
+
+<programlisting>
+INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2);
+</programlisting>
+
+  Had we not supplied values for all the subfields of the column, the
+  remaining subfields would have been filled with NULLs.
+ </para>
+ </sect2>
+
  <sect2>
   <title>Composite Type Input and Output Syntax</title>