From 6a0f486a25a5a85fa973a99914fea8ae40a0b722 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 16 Dec 2000 19:33:23 +0000
Subject: [PATCH] A little wordsmithing in the pattern-matching section.
---
doc/src/sgml/func.sgml | 91 +++++++++++++++++++++++++-----------------
1 file changed, 54 insertions(+), 37 deletions(-)
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 48bdb2a5e1c..fdd1c34a3e1 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.42 2000/12/16 18:33:13 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.43 2000/12/16 19:33:23 tgl Exp $ -->
<chapter id="functions">
<title>Functions and Operators</title>
@@ -805,12 +805,12 @@
<para>
If <replaceable>pattern</replaceable> does not contain percent
- signs or underscore then the pattern only represents the string
+ signs or underscore, then the pattern only represents the string
itself; in that case <function>LIKE</function> acts like the
equals operator. An underscore (<literal>_</literal>) in
<replaceable>pattern</replaceable> stands for (matches) any single
- character, a percent sign (<literal>%</literal>) matches zero or
- more characters.
+ character; a percent sign (<literal>%</literal>) matches any string
+ of zero or more characters.
</para>
<informalexample>
@@ -827,33 +827,39 @@
<para>
<function>LIKE</function> pattern matches always cover the entire
- string. On order to match a pattern anywhere within a string, the
+ string. To match a pattern anywhere within a string, the
pattern must therefore start and end with a percent sign.
</para>
<para>
- In order to match a literal underscore or percent sign, the
- respective character in <replaceable>pattern</replaceable> must be
- preceded by the active escape character. The default escape
+ To match a literal underscore or percent sign without matching
+ other characters, the respective character in
+ <replaceable>pattern</replaceable> must be
+ preceded by the escape character. The default escape
character is the backslash but a different one may be selected by
- using the <literal>ESCAPE</literal> clause. When using the
- backslash as escape character in literal strings it must be
- doubled, because the backslash already has a special meaning in
- string literals.
+ using the <literal>ESCAPE</literal> clause. To match the escape
+ character itself, write two escape characters.
+ </para>
+
+ <para>
+ Note that the backslash already has a special meaning in string
+ literals, so to write a pattern constant that contains a backslash
+ you must write two backslashes in the query. You can avoid this by
+ selecting a different escape character with <literal>ESCAPE</literal>.
</para>
<para>
The keyword <token>ILIKE</token> can be used instead of
<token>LIKE</token> to make the match case insensitive according
- to the active locale. This is a
+ to the active locale. This is not in the SQL standard but is a
<productname>Postgres</productname> extension.
</para>
<para>
The operator <literal>~~</literal> is equivalent to
- <function>LIKE</function>, <literal>~~*</literal> corresponds to
- <literal>ILIKE</literal>. Finally, there are also
- <literal>!~~</literal> and <literal>!~~*</literal> operators to
+ <function>LIKE</function>, and <literal>~~*</literal> corresponds to
+ <function>ILIKE</function>. There are also
+ <literal>!~~</literal> and <literal>!~~*</literal> operators that
represent <function>NOT LIKE</function> and <function>NOT
ILIKE</function>. All of these are also
<productname>Postgres</productname>-specific.
@@ -864,25 +870,6 @@
<sect2 id="functions-regexp">
<title>POSIX Regular Expressions</title>
- <para>
- POSIX regular expressions provide a more powerful means for
- pattern matching than the <function>LIKE</function> function.
- Many Unix tools such as <command>egrep</command>,
- <command>sed</command>, or <command>awk</command> use a pattern
- matching language that is similar to the one described here.
- </para>
-
- <para>
- A regular expression is a character sequence that is an
- abbreviated definition of a set of strings (a <firstterm>regular
- set</firstterm>). A string is said to match a regular expression
- if it is a member of the regular set described by the regular
- expression. Unlike the <function>LIKE</function> operator, a
- regular expression also matches anywhere within a string, unless
- the regular expression is explicitly anchored to the beginning or
- end of the string.
- </para>
-
<table>
<title>Regular Expression Match Operators</title>
@@ -920,6 +907,29 @@
</tgroup>
</table>
+ <para>
+ POSIX regular expressions provide a more powerful means for
+ pattern matching than the <function>LIKE</function> function.
+ Many Unix tools such as <command>egrep</command>,
+ <command>sed</command>, or <command>awk</command> use a pattern
+ matching language that is similar to the one described here.
+ </para>
+
+ <para>
+ A regular expression is a character sequence that is an
+ abbreviated definition of a set of strings (a <firstterm>regular
+ set</firstterm>). A string is said to match a regular expression
+ if it is a member of the regular set described by the regular
+ expression. As with <function>LIKE</function>, pattern characters
+ match string characters exactly unless they are special characters
+ in the regular expression language --- but regular expressions use
+ different special characters than <function>LIKE</function> does.
+ Unlike <function>LIKE</function> patterns, a
+ regular expression is allowed to match anywhere within a string, unless
+ the regular expression is explicitly anchored to the beginning or
+ end of the string.
+ </para>
+
<!-- derived from the re_format.7 man page -->
<para>
@@ -927,8 +937,8 @@
1003.2, come in two forms: modern REs (roughly those of
<command>egrep</command>; 1003.2 calls these
<quote>extended</quote> REs) and obsolete REs (roughly those of
- <command>ed</command>; 1003.2 <quote>basic</quote> REs). Obsolete
- REs are not available in <productname>Postgres</productname>.
+ <command>ed</command>; 1003.2 <quote>basic</quote> REs).
+ <productname>Postgres</productname> implements the modern form.
</para>
<para>
@@ -1004,6 +1014,13 @@
<literal>\</literal>.
</para>
+ <para>
+ Note that the backslash (<literal>\</literal>) already has a special
+ meaning in string
+ literals, so to write a pattern constant that contains a backslash
+ you must write two backslashes in the query.
+ </para>
+
<para>
A <firstterm>bracket expression</firstterm> is a list of
characters enclosed in <literal>[]</literal>. It normally matches
--
GitLab