From 3d2849820b03f18199f0253fa21a1d31e5670c4f Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 26 Oct 2004 22:16:12 +0000
Subject: [PATCH] Document IS DISTINCT FROM in a more obvious place, and add
some more index entries for IS-foo constructs.
---
doc/src/sgml/func.sgml | 81 +++++++++++++++++++++++++++++++++++++---
doc/src/sgml/syntax.sgml | 14 +++++--
2 files changed, 86 insertions(+), 9 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7e1b488bae7..fb55b1bff72 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.220 2004/10/04 08:15:41 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.221 2004/10/26 22:16:11 tgl Exp $
PostgreSQL documentation
-->
@@ -283,6 +283,18 @@ PostgreSQL documentation
</para>
<para>
+ <indexterm>
+ <primary>IS NULL</primary>
+ </indexterm>
+ <indexterm>
+ <primary>IS NOT NULL</primary>
+ </indexterm>
+ <indexterm>
+ <primary>ISNULL</primary>
+ </indexterm>
+ <indexterm>
+ <primary>NOTNULL</primary>
+ </indexterm>
To check whether a value is or is not null, use the constructs
<synopsis>
<replaceable>expression</replaceable> IS NULL
@@ -305,6 +317,7 @@ PostgreSQL documentation
behavior conforms to the SQL standard.
</para>
+ <tip>
<para>
Some applications may expect that
<literal><replaceable>expression</replaceable> = NULL</literal>
@@ -318,8 +331,43 @@ PostgreSQL documentation
the default behavior in <productname>PostgreSQL</productname>
releases 6.5 through 7.1.
</para>
+ </tip>
+
+ <para>
+ <indexterm>
+ <primary>IS DISTINCT FROM</primary>
+ </indexterm>
+ The ordinary comparison operators yield null (signifying <quote>unknown</>)
+ when either input is null. Another way to do comparisons is with the
+ <literal>IS DISTINCT FROM</literal> construct:
+<synopsis>
+<replaceable>expression</replaceable> IS DISTINCT FROM <replaceable>expression</replaceable>
+</synopsis>
+ For non-null inputs this is the same as the <literal><></> operator.
+ However, when both inputs are null it will return false, and when just
+ one input is null it will return true. Thus it effectively acts as though
+ null were a normal data value, rather than <quote>unknown</>.
+ </para>
<para>
+ <indexterm>
+ <primary>IS TRUE</primary>
+ </indexterm>
+ <indexterm>
+ <primary>IS NOT TRUE</primary>
+ </indexterm>
+ <indexterm>
+ <primary>IS FALSE</primary>
+ </indexterm>
+ <indexterm>
+ <primary>IS NOT FALSE</primary>
+ </indexterm>
+ <indexterm>
+ <primary>IS UNKNOWN</primary>
+ </indexterm>
+ <indexterm>
+ <primary>IS NOT UNKNOWN</primary>
+ </indexterm>
Boolean values can also be tested using the constructs
<synopsis>
<replaceable>expression</replaceable> IS TRUE
@@ -329,9 +377,13 @@ PostgreSQL documentation
<replaceable>expression</replaceable> IS UNKNOWN
<replaceable>expression</replaceable> IS NOT UNKNOWN
</synopsis>
- These are similar to <literal>IS NULL</literal> in that they will
- always return true or false, never a null value, even when the operand is null.
+ These will always return true or false, never a null value, even when the
+ operand is null.
A null input is treated as the logical value <quote>unknown</>.
+ Notice that <literal>IS UNKNOWN</> and <literal>IS NOT UNKNOWN</> are
+ effectively the same as <literal>IS NULL</literal> and
+ <literal>IS NOT NULL</literal>, respectively, except that the input
+ expression must be of Boolean type.
</para>
</sect1>
@@ -7344,7 +7396,7 @@ SELECT col1 FROM tab1
</sect2>
<sect2>
- <title><literal>NOT IN </literal></title>
+ <title><literal>NOT IN</literal></title>
<synopsis>
<replaceable>expression</replaceable> NOT IN (<replaceable>subquery</replaceable>)
@@ -7538,9 +7590,9 @@ SELECT col1 FROM tab1
<sect2>
<title>Row-wise Comparison</title>
- <indexterm>
+ <indexterm zone="functions-subquery">
<primary>comparison</primary>
- <secondary>of rows</secondary>
+ <secondary>subquery result row</secondary>
</indexterm>
<synopsis>
@@ -7594,6 +7646,23 @@ SELECT col1 FROM tab1
<primary>SOME</primary>
</indexterm>
+ <indexterm>
+ <primary>comparison</primary>
+ <secondary>row-wise</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>IS DISTINCT FROM</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>IS NULL</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>IS NOT NULL</primary>
+ </indexterm>
+
<para>
This section describes several specialized constructs for making
multiple comparisons between groups of values. These forms are
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 98deceb8957..99038b42692 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.95 2004/09/20 22:48:25 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.96 2004/10/26 22:16:12 tgl Exp $
-->
<chapter id="sql-syntax">
@@ -1421,6 +1421,10 @@ SELECT name, (SELECT max(pop) FROM cities WHERE cities.state = states.name)
<secondary>constructor</secondary>
</indexterm>
+ <indexterm>
+ <primary>ARRAY</primary>
+ </indexterm>
+
<para>
An array constructor is an expression that builds an
array value from values for its member elements. A simple array
@@ -1521,13 +1525,17 @@ SELECT ARRAY(SELECT oid FROM pg_proc WHERE proname LIKE 'bytea%');
<secondary>constructor</secondary>
</indexterm>
+ <indexterm>
+ <primary>ROW</primary>
+ </indexterm>
+
<para>
A row constructor is an expression that builds a row value (also
called a composite value) from values
for its member fields. A row constructor consists of the key word
- <literal>ROW</literal>, a left parenthesis <literal>(</>, zero or more
+ <literal>ROW</literal>, a left parenthesis, zero or more
expressions (separated by commas) for the row field values, and finally
- a right parenthesis <literal>)</>. For example,
+ a right parenthesis. For example,
<programlisting>
SELECT ROW(1,2.5,'this is a test');
</programlisting>
--
GitLab