From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 6 Sep 2011 16:14:51 +0000 (-0400)
Subject: Update type-conversion documentation for long-ago changes.
X-Git-Tag: REL9_2_BETA1~1136
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=b7f83e70d9758c5dd480c9dbba1668ddeec37916;p=postgresql

Update type-conversion documentation for long-ago changes.

This example wasn't updated when we changed the behavior of bpcharlen()
in 8.0, nor when we changed the number of parameters taken by the bpchar()
cast function in 7.3.  Per report from lsliang.
---

diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index f233e9d712..cca45eb569 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -758,9 +758,11 @@ cast is a cast from that type to itself.  If one is found in the
 <structname>pg_cast</> catalog, apply it to the expression before storing
 into the destination column.  The implementation function for such a cast
 always takes an extra parameter of type <type>integer</type>, which receives
-the destination column's declared length (actually, its
-<structfield>atttypmod</> value; the interpretation of
-<structfield>atttypmod</> varies for different data types).  The cast function
+the destination column's <structfield>atttypmod</> value (typically its
+declared length, although the interpretation of <structfield>atttypmod</>
+varies for different data types), and it may take a third <type>boolean</>
+parameter that says whether the cast is explicit or implicit.  The cast
+function
 is responsible for applying any length-dependent semantics such as size
 checking or truncation.
 </para>
@@ -772,17 +774,17 @@ checking or truncation.
 <title><type>character</type> Storage Type Conversion</title>
 
 <para>
-For a target column declared as <type>character(20)</type> the following statement
-ensures that the stored value is sized correctly:
+For a target column declared as <type>character(20)</type> the following
+statement shows that the stored value is sized correctly:
 
 <screen>
 CREATE TABLE vv (v character(20));
 INSERT INTO vv SELECT 'abc' || 'def';
-SELECT v, length(v) FROM vv;
+SELECT v, octet_length(v) FROM vv;
 
-          v           | length
-----------------------+--------
- abcdef               |     20
+          v           | octet_length
+----------------------+--------------
+ abcdef               |           20
 (1 row)
 </screen>
 </para>
@@ -796,7 +798,7 @@ char</>, the internal name of the <type>character</type> data type) to match the
 column type.  (Since the conversion from <type>text</type> to
 <type>bpchar</type> is binary-coercible, this conversion does
 not insert any real function call.)  Finally, the sizing function
-<literal>bpchar(bpchar, integer)</literal> is found in the system catalog
+<literal>bpchar(bpchar, integer, boolean)</> is found in the system catalog
 and applied to the operator's result and the stored column length.  This
 type-specific function performs the required length check and addition of
 padding spaces.