From 0add759825e746c76671badfcf38c329ee7f151a Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 23 Dec 2004 23:07:38 +0000
Subject: [PATCH] More minor updates and copy-editing.
---
doc/src/sgml/func.sgml | 111 +++++++++++++++----------------------
doc/src/sgml/indices.sgml | 6 +-
doc/src/sgml/mvcc.sgml | 10 ++--
doc/src/sgml/perform.sgml | 35 ++++++------
doc/src/sgml/typeconv.sgml | 60 +++++++++++---------
5 files changed, 103 insertions(+), 119 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 2de07c04ae8..96fc4ea6989 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.231 2004/12/21 01:02:28 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.232 2004/12/23 23:07:38 tgl Exp $
PostgreSQL documentation
-->
@@ -1347,7 +1347,8 @@ PostgreSQL documentation
<footnote>
<para>
The <function>to_ascii</function> function supports conversion from
- <literal>LATIN1</>, <literal>LATIN2</>, and <literal>WIN1250</> only.
+ <literal>LATIN1</>, <literal>LATIN2</>, <literal>LATIN9</>,
+ and <literal>WIN1250</> encodings only.
</para>
</footnote>
</entry>
@@ -2483,11 +2484,11 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
There are three separate approaches to pattern matching provided
by <productname>PostgreSQL</productname>: the traditional
<acronym>SQL</acronym> <function>LIKE</function> operator, the
- more recent <literal>>SIMILAR TO</literal> operator (since
+ more recent <function>SIMILAR TO</function> operator (added in
SQL:1999), and <acronym>POSIX</acronym>-style regular expressions.
Additionally, a pattern matching function,
<function>substring</function>, is available, using either
- <literal>SIMILAR TO</literal>-style or POSIX-style regular
+ <function>SIMILAR TO</function>-style or POSIX-style regular
expressions.
</para>
@@ -2544,7 +2545,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
<para>
<function>LIKE</function> pattern matches always cover the entire
- string. To match a pattern anywhere within a string, the
+ string. To match a sequence anywhere within a string, the
pattern must therefore start and end with a percent sign.
</para>
@@ -2578,7 +2579,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
<para>
The key word <token>ILIKE</token> can be used instead of
- <token>LIKE</token> to make the match case insensitive according
+ <token>LIKE</token> to make the match case-insensitive according
to the active locale. This is not in the <acronym>SQL</acronym> standard but is a
<productname>PostgreSQL</productname> extension.
</para>
@@ -2818,9 +2819,11 @@ substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotat
pattern. But if the pattern contains any parentheses, the portion
of the text that matched the first parenthesized subexpression (the
one whose left parenthesis comes first) is
- returned. You can always put parentheses around the whole expression
+ returned. You can put parentheses around the whole expression
if you want to use parentheses within it without triggering this
- exception. Also see the non-capturing parentheses described below.
+ exception. If you need parentheses in the pattern before the
+ subexpression you want to extract, see the non-capturing parentheses
+ described below.
</para>
<para>
@@ -3073,7 +3076,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
<para>
The forms using <literal>{</><replaceable>...</><literal>}</>
- are known as <firstterm>bound</>s.
+ are known as <firstterm>bounds</>.
The numbers <replaceable>m</> and <replaceable>n</> within a bound are
unsigned decimal integers with permissible values from 0 to 255 inclusive.
</para>
@@ -3603,9 +3606,10 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
Normally the flavor of RE being used is determined by
<varname>regex_flavor</>.
However, this can be overridden by a <firstterm>director</> prefix.
- If an RE of any flavor begins with <literal>***:</>,
- the rest of the RE is taken as an ARE.
- If an RE of any flavor begins with <literal>***=</>,
+ If an RE begins with <literal>***:</>,
+ the rest of the RE is taken as an ARE regardless of
+ <varname>regex_flavor</>.
+ If an RE begins with <literal>***=</>,
the rest of the RE is taken to be a literal string,
with all characters considered ordinary characters.
</para>
@@ -3703,8 +3707,8 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
<para>
Embedded options take effect at the <literal>)</> terminating the sequence.
- They are available only at the start of an ARE,
- and may not be used later within it.
+ They may appear only at the start of an ARE (after the
+ <literal>***:</> director if any).
</para>
<para>
@@ -3732,13 +3736,13 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
</listitem>
<listitem>
<para>
- white space and comments are illegal within multi-character symbols,
- like the ARE <literal>(?:</> or the BRE <literal>\(</>
+ white space and comments cannot appear within multi-character symbols,
+ such as <literal>(?:</>
</para>
</listitem>
</itemizedlist>
- Expanded-syntax white-space characters are blank, tab, newline, and
+ For this purpose, white-space characters are blank, tab, newline, and
any character that belongs to the <replaceable>space</> character class.
</para>
@@ -4330,7 +4334,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
</table>
<para>
- Usage notes for the date/time formatting:
+ Usage notes for date/time formatting:
<itemizedlist>
<listitem>
@@ -4506,7 +4510,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
</table>
<para>
- Usage notes for the numeric formatting:
+ Usage notes for numeric formatting:
<itemizedlist>
<listitem>
@@ -5068,10 +5072,10 @@ EXTRACT (<replaceable>field</replaceable> FROM <replaceable>source</replaceable>
<para>
The <function>extract</function> function retrieves subfields
- from date/time values, such as year or hour.
- <replaceable>source</replaceable> is a value expression that
- evaluates to type <type>timestamp</type> or <type>interval</type>.
- (Expressions of type <type>date</type> or <type>time</type> will
+ such as year or hour from date/time values.
+ <replaceable>source</replaceable> must be a value expression of
+ type <type>timestamp</type>, <type>time</type>, or <type>interval</type>.
+ (Expressions of type <type>date</type> will
be cast to <type>timestamp</type> and can therefore be used as
well.) <replaceable>field</replaceable> is an identifier or
string that selects what field to extract from the source value.
@@ -5699,7 +5703,7 @@ SELECT TIMESTAMP 'now';
</programlisting>
</para>
- <note>
+ <tip>
<para>
You do not want to use the third form when specifying a <literal>DEFAULT</>
clause while creating a table. The system will convert <literal>now</literal>
@@ -5710,7 +5714,7 @@ SELECT TIMESTAMP 'now';
because they are function calls. Thus they will give the desired
behavior of defaulting to the time of row insertion.
</para>
- </note>
+ </tip>
</sect2>
</sect1>
@@ -6803,7 +6807,7 @@ SELECT NULLIF(value, '(none)') ...
<para>
<xref linkend="array-functions-table"> shows the functions
available for use with array types. See <xref linkend="arrays">
- for more discussion and examples for the use of these functions.
+ for more discussion and examples of the use of these functions.
</para>
<table id="array-functions-table">
@@ -6827,10 +6831,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>anyarray</type></entry>
- <entry>
- concatenate two arrays, returning <literal>NULL</literal>
- for <literal>NULL</literal> inputs
- </entry>
+ <entry>concatenate two arrays</entry>
<entry><literal>array_cat(ARRAY[1,2,3], ARRAY[4,5])</literal></entry>
<entry><literal>{1,2,3,4,5}</literal></entry>
</row>
@@ -6842,10 +6843,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>anyarray</type></entry>
- <entry>
- append an element to the end of an array, returning
- <literal>NULL</literal> for <literal>NULL</literal> inputs
- </entry>
+ <entry>append an element to the end of an array</entry>
<entry><literal>array_append(ARRAY[1,2], 3)</literal></entry>
<entry><literal>{1,2,3}</literal></entry>
</row>
@@ -6857,10 +6855,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>anyarray</type></entry>
- <entry>
- append an element to the beginning of an array, returning
- <literal>NULL</literal> for <literal>NULL</literal> inputs
- </entry>
+ <entry>append an element to the beginning of an array</entry>
<entry><literal>array_prepend(1, ARRAY[2,3])</literal></entry>
<entry><literal>{1,2,3}</literal></entry>
</row>
@@ -6872,10 +6867,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>text</type></entry>
- <entry>
- returns a text representation of array dimension lower and upper bounds,
- generating an ERROR for <literal>NULL</literal> inputs
- </entry>
+ <entry>returns a text representation of array's dimensions</entry>
<entry><literal>array_dims(array[[1,2,3], [4,5,6]])</literal></entry>
<entry><literal>[1:2][1:3]</literal></entry>
</row>
@@ -6887,10 +6879,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>integer</type></entry>
- <entry>
- returns lower bound of the requested array dimension, returning
- <literal>NULL</literal> for <literal>NULL</literal> inputs
- </entry>
+ <entry>returns lower bound of the requested array dimension</entry>
<entry><literal>array_lower(array_prepend(0, ARRAY[1,2,3]), 1)</literal></entry>
<entry><literal>0</literal></entry>
</row>
@@ -6902,10 +6891,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>integer</type></entry>
- <entry>
- returns upper bound of the requested array dimension, returning
- <literal>NULL</literal> for <literal>NULL</literal> inputs
- </entry>
+ <entry>returns upper bound of the requested array dimension</entry>
<entry><literal>array_upper(ARRAY[1,2,3,4], 1)</literal></entry>
<entry><literal>4</literal></entry>
</row>
@@ -6917,10 +6903,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>text</type></entry>
- <entry>
- concatenates array elements using provided delimiter, returning
- <literal>NULL</literal> for <literal>NULL</literal> inputs
- </entry>
+ <entry>concatenates array elements using provided delimiter</entry>
<entry><literal>array_to_string(array[1, 2, 3], '~^~')</literal></entry>
<entry><literal>1~^~2~^~3</literal></entry>
</row>
@@ -6932,10 +6915,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>text[]</type></entry>
- <entry>
- splits string into array elements using provided delimiter, returning
- <literal>NULL</literal> for <literal>NULL</literal> inputs
- </entry>
+ <entry>splits string into array elements using provided delimiter</entry>
<entry><literal>string_to_array( 'xx~^~yy~^~zz', '~^~')</literal></entry>
<entry><literal>{xx,yy,zz}</literal></entry>
</row>
@@ -7181,7 +7161,7 @@ SELECT NULLIF(value, '(none)') ...
It should be noted that except for <function>count</function>,
these functions return a null value when no rows are selected. In
particular, <function>sum</function> of no rows returns null, not
- zero as one might expect. The function <function>coalesce</function> may be
+ zero as one might expect. The <function>coalesce</function> function may be
used to substitute zero for null when necessary.
</para>
@@ -8045,9 +8025,10 @@ select current_date + s.a as dates from generate_series(0,14,7) as s(a);
</indexterm>
<para>
- The <function>session_user</function> is the user that initiated a
- database connection; it is fixed for the duration of that
- connection. The <function>current_user</function> is the user identifier
+ The <function>session_user</function> is normally the user who initiated
+ the current database connection; but superusers can change this setting
+ with <xref linkend="sql-set-session-authorization">.
+ The <function>current_user</function> is the user identifier
that is applicable for permission checking. Normally, it is equal
to the session user, but it changes during the execution of
functions with the attribute <literal>SECURITY DEFINER</literal>.
@@ -8106,8 +8087,8 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
<function>inet_server_addr</function> returns the IP address on which
the server accepted the current connection, and
<function>inet_server_port</function> returns the port number.
- All these functions return NULL if the connection is via a Unix-domain
- socket.
+ All these functions return NULL if the current connection is via a
+ Unix-domain socket.
</para>
<indexterm zone="functions-info">
@@ -8325,7 +8306,7 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
</para>
<para>
- To evaluate whether a user holds a grant option on the privilege,
+ To test whether a user holds a grant option on the privilege,
append <literal> WITH GRANT OPTION</literal> to the privilege key
word; for example <literal>'UPDATE WITH GRANT OPTION'</literal>.
</para>
diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index f35e65aba18..e37d2b85e82 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.47 2003/11/29 19:51:37 pgsql Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.48 2004/12/23 23:07:38 tgl Exp $ -->
<chapter id="indexes">
<title id="indexes-title">Indexes</title>
@@ -71,7 +71,7 @@ CREATE INDEX test1_id_index ON test1 (id);
</para>
<para>
- Once the index is created, no further intervention is required: the
+ Once an index is created, no further intervention is required: the
system will update the index when the table is modified, and it will
use the index in queries when it thinks this would be more efficient
than a sequential table scan. But you may have to run the
@@ -761,7 +761,7 @@ CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target)
</para>
<para>
- It is especially fatal to use proportionally reduced data sets.
+ It is especially fatal to use very small test data sets.
While selecting 1000 out of 100000 rows could be a candidate for
an index, selecting 1 out of 100 rows will hardly be, because the
100 rows will probably fit within a single disk page, and there
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 3b3b68a97fc..01f697d426a 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.45 2004/11/15 06:32:14 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.46 2004/12/23 23:07:38 tgl Exp $
-->
<chapter id="mvcc">
@@ -206,9 +206,9 @@ $PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.45 2004/11/15 06:32:14 neilc Exp $
</table>
<para>
- In <productname>PostgreSQL</productname>, you can use all four
- possible transaction isolation levels. Internally, there are only
- two distinct isolation levels, which correspond to the levels Read
+ In <productname>PostgreSQL</productname>, you can request any of the
+ four standard transaction isolation levels. But internally, there are
+ only two distinct isolation levels, which correspond to the levels Read
Committed and Serializable. When you select the level Read
Uncommitted you really get Read Committed, and when you select
Repeatable Read you really get Serializable, so the actual
@@ -217,7 +217,7 @@ $PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.45 2004/11/15 06:32:14 neilc Exp $
define which phenomena must not happen, they do not define which
phenomena must happen. The reason that <productname>PostgreSQL</>
only provides two isolation levels is that this is the only
- sensible way to map the isolation levels to the multiversion
+ sensible way to map the standard isolation levels to the multiversion
concurrency control architecture. The behavior of the available
isolation levels is detailed in the following subsections.
</para>
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 687d3228120..5448913586c 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.48 2004/12/01 19:00:27 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.49 2004/12/23 23:07:38 tgl Exp $
-->
<chapter id="performance-tips">
@@ -78,7 +78,7 @@ $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.48 2004/12/01 19:00:27 tgl Exp
estimates are converted into disk-page units using some
fairly arbitrary fudge factors. If you want to experiment with these
factors, see the list of run-time configuration parameters in
- <xref linkend="runtime-config-resource">.)
+ <xref linkend="runtime-config-query-constants">.)
</para>
<para>
@@ -657,16 +657,6 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
point would be rolled back, so you won't be stuck with partially
loaded data.
</para>
-
- <para>
- If you are issuing a large sequence of <command>INSERT</command>
- commands to bulk load some data, also consider using <xref
- linkend="sql-prepare" endterm="sql-prepare-title"> to create a
- prepared <command>INSERT</command> statement. Since you are
- executing the same command multiple times, it is more efficient to
- prepare the command once and then use <command>EXECUTE</command>
- as many times as required.
- </para>
</sect2>
<sect2 id="populate-copy-from">
@@ -683,12 +673,20 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
use this method to populate a table.
</para>
+ <para>
+ If you cannot use <command>COPY</command>, it may help to use <xref
+ linkend="sql-prepare" endterm="sql-prepare-title"> to create a
+ prepared <command>INSERT</command> statement, and then use
+ <command>EXECUTE</command> as many times as required. This avoids
+ some of the overhead of repeatedly parsing and planning
+ <command>INSERT</command>.
+ </para>
+
<para>
Note that loading a large number of rows using
<command>COPY</command> is almost always faster than using
- <command>INSERT</command>, even if multiple
- <command>INSERT</command> commands are batched into a single
- transaction.
+ <command>INSERT</command>, even if <command>PREPARE</> is used and
+ multiple insertions are batched into a single transaction.
</para>
</sect2>
@@ -719,10 +717,10 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<para>
Temporarily increasing the <xref linkend="guc-maintenance-work-mem">
- configuration variable when restoring large amounts of data can
+ configuration variable when loading large amounts of data can
lead to improved performance. This is because when a B-tree index
is created from scratch, the existing content of the table needs
- to be sorted. Allowing the external merge sort to use more memory
+ to be sorted. Allowing the merge sort to use more memory
means that fewer merge passes will be required. A larger setting for
<varname>maintenance_work_mem</varname> may also speed up validation
of foreign-key constraints.
@@ -754,8 +752,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
Whenever you have significantly altered the distribution of data
within a table, running <xref linkend="sql-analyze"
endterm="sql-analyze-title"> is strongly recommended. This
- includes when bulk loading large amounts of data into
- <productname>PostgreSQL</productname>. Running
+ includes bulk loading large amounts of data into the table. Running
<command>ANALYZE</command> (or <command>VACUUM ANALYZE</command>)
ensures that the planner has up-to-date statistics about the
table. With no statistics or obsolete statistics, the planner may
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index 05fb4f4a0cd..ae0e3aea4d7 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.42 2003/12/14 00:10:32 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.43 2004/12/23 23:07:38 tgl Exp $
-->
<chapter Id="typeconv">
@@ -22,8 +22,7 @@ In many cases a user will not need
to understand the details of the type conversion mechanism.
However, the implicit conversions done by <productname>PostgreSQL</productname>
can affect the results of a query. When necessary, these results
-can be tailored by a user or programmer
-using <emphasis>explicit</emphasis> type conversion.
+can be tailored by using <emphasis>explicit</emphasis> type conversion.
</para>
<para>
@@ -43,16 +42,17 @@ has an associated data type which determines its behavior and allowed usage.
<productname>PostgreSQL</productname> has an extensible type system that is
much more general and flexible than other <acronym>SQL</acronym> implementations.
Hence, most type conversion behavior in <productname>PostgreSQL</productname>
-should be governed by general rules rather than by <foreignphrase>ad hoc</> heuristics, to allow
+is governed by general rules rather than by <foreignphrase>ad hoc</>
+heuristics. This allows
mixed-type expressions to be meaningful even with user-defined types.
</para>
<para>
-The <productname>PostgreSQL</productname> scanner/parser decodes lexical
-elements into only five fundamental categories: integers, floating-point numbers, strings,
-names, and key words. Constants of most non-numeric types are first classified as
-strings. The <acronym>SQL</acronym> language definition allows specifying type
-names with strings, and this mechanism can be used in
+The <productname>PostgreSQL</productname> scanner/parser divides lexical
+elements into only five fundamental categories: integers, non-integer numbers,
+strings, identifiers, and key words. Constants of most non-numeric types are
+first classified as strings. The <acronym>SQL</acronym> language definition
+allows specifying type names with strings, and this mechanism can be used in
<productname>PostgreSQL</productname> to start the parser down the correct
path. For example, the query
@@ -79,28 +79,30 @@ parser:
<variablelist>
<varlistentry>
<term>
-Operators
+Function calls
</term>
<listitem>
<para>
-<productname>PostgreSQL</productname> allows expressions with
-prefix and postfix unary (one-argument) operators,
-as well as binary (two-argument) operators.
+Much of the <productname>PostgreSQL</productname> type system is built around a
+rich set of functions. Functions can have one or more arguments.
+Since <productname>PostgreSQL</productname> permits function
+overloading, the function name alone does not uniquely identify the function
+to be called; the parser must select the right function based on the data
+types of the supplied arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
-Function calls
+Operators
</term>
<listitem>
<para>
-Much of the <productname>PostgreSQL</productname> type system is built around a
-rich set of functions. Function calls can have one or more arguments.
-Since <productname>PostgreSQL</productname> permits function
-overloading, the function name alone does not uniquely identify the function
-to be called; the parser must select the right function based on the data
-types of the supplied arguments.
+<productname>PostgreSQL</productname> allows expressions with
+prefix and postfix unary (one-argument) operators,
+as well as binary (two-argument) operators. Like functions, operators can
+be overloaded, and so the same problem of selecting the right operator
+exists.
</para>
</listitem>
</varlistentry>
@@ -125,7 +127,7 @@ with, and perhaps converted to, the types of the target columns.
Since all query results from a unionized <command>SELECT</command> statement
must appear in a single set of columns, the types of the results of each
<command>SELECT</> clause must be matched up and converted to a uniform set.
-Similarly, the branch expressions of a <literal>CASE</> construct must be
+Similarly, the result expressions of a <literal>CASE</> construct must be
converted to a common type so that the <literal>CASE</> expression as a whole
has a known output type. The same holds for <literal>ARRAY</> constructs.
</para>
@@ -728,12 +730,16 @@ type.
<step performance="required">
<para>
-If the target is a fixed-length type (e.g., <type>char</type> or <type>varchar</type>
-declared with a length) then try to find a sizing function for the target
-type. A sizing function is a function of the same name as the type,
-taking two arguments of which the first is that type and the second is of type
-<type>integer</type>, and returning the same type. If one is found, it is applied,
-passing the column's declared length as the second parameter.
+Check to see if there is a sizing cast for the target type. A sizing
+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 datatypes). The cast function
+is responsible for applying any length-dependent semantics such as size
+checking or truncation.
</para>
</step>
--
GitLab