🌐 AI搜索 & 代理 主页
Skip to content

Commit a003bd0

Browse files
tglsfdctglsfdc
committed
Rewrite discussion of string constant syntax to bring it into line with
the politically correct view that backslash escapes are deprecated.
1 parent c9c1c4e commit a003bd0

File tree

1 file changed

+69
-42
lines changed

1 file changed

+69
-42
lines changed

‎doc/src/sgml/syntax.sgml‎

Lines changed: 69 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.109 2006/09/16 00:30:16 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.110 2006/10/21 17:12:07 tgl Exp $ -->
22

33
<chapter id="sql-syntax">
44
<title>SQL Syntax</title>
@@ -240,49 +240,12 @@ UPDATE "my_table" SET "a" = 5;
240240
</indexterm>
241241
A string constant in SQL is an arbitrary sequence of characters
242242
bounded by single quotes (<literal>'</literal>), for example
243-
<literal>'This is a string'</literal>. The standard-compliant way of
244-
writing a single-quote character within a string constant is to
243+
<literal>'This is a string'</literal>. To include
244+
a single-quote character within a string constant,
245245
write two adjacent single quotes, e.g.
246246
<literal>'Dianne''s horse'</literal>.
247-
<productname>PostgreSQL</productname> also allows single quotes
248-
to be escaped with a backslash (<literal>\'</literal>). However,
249-
future versions of <productname>PostgreSQL</productname> will not
250-
allow this, so applications using backslashes should convert to the
251-
standard-compliant method outlined above.
252-
</para>
253-
254-
<para>
255-
Another <productname>PostgreSQL</productname> extension is that
256-
C-style backslash escapes are available: <literal>\b</literal> is a
257-
backspace, <literal>\f</literal> is a form feed,
258-
<literal>\n</literal> is a newline, <literal>\r</literal> is a
259-
carriage return, <literal>\t</literal> is a tab. Also supported is
260-
<literal>\<replaceable>digits</replaceable></literal>, where
261-
<replaceable>digits</replaceable> represents an octal byte value, and
262-
<literal>\x<replaceable>hexdigits</replaceable></literal>, where
263-
<replaceable>hexdigits</replaceable> represents a hexadecimal byte value.
264-
(It is your responsibility that the byte sequences you create are
265-
valid characters in the server character set encoding.) Any other
266-
character following a backslash is taken literally. Thus, to
267-
include a backslash in a string constant, write two backslashes.
268-
</para>
269-
270-
<note>
271-
<para>
272-
While ordinary strings now support C-style backslash escapes,
273-
future versions will generate warnings for such usage and
274-
eventually treat backslashes as literal characters to be
275-
standard-conforming. The proper way to specify escape processing is
276-
to use the escape string syntax to indicate that escape
277-
processing is desired. Escape string syntax is specified by writing
278-
the letter <literal>E</literal> (upper or lower case) just before
279-
the string, e.g. <literal>E'\041'</>. This method will work in all
280-
future versions of <productname>PostgreSQL</productname>.
281-
</para>
282-
</note>
283-
284-
<para>
285-
The character with the code zero cannot be in a string constant.
247+
Note that this is <emphasis>not</> the same as a double-quote
248+
character (<literal>"</>).
286249
</para>
287250

288251
<para>
@@ -306,6 +269,70 @@ SELECT 'foo' 'bar';
306269
by <acronym>SQL</acronym>; <productname>PostgreSQL</productname> is
307270
following the standard.)
308271
</para>
272+
273+
<para>
274+
<indexterm>
275+
<primary>escape string syntax</primary>
276+
</indexterm>
277+
<indexterm>
278+
<primary>backslash escapes</primary>
279+
</indexterm>
280+
<productname>PostgreSQL</productname> also accepts <quote>escape</>
281+
string constants, which are an extension to the SQL standard.
282+
An escape string constant is specified by writing the letter
283+
<literal>E</literal> (upper or lower case) just before the opening single
284+
quote, e.g. <literal>E'foo'</>. (When continuing an escape string
285+
constant across lines, write <literal>E</> only before the first opening
286+
quote.)
287+
Within an escape string, a backslash character (<literal>\</>) begins a
288+
C-like <firstterm>backslash escape</> sequence, in which the combination
289+
of backslash and following character(s) represents a special byte value.
290+
<literal>\b</literal> is a backspace,
291+
<literal>\f</literal> is a form feed,
292+
<literal>\n</literal> is a newline,
293+
<literal>\r</literal> is a carriage return,
294+
<literal>\t</literal> is a tab.
295+
Also supported are
296+
<literal>\<replaceable>digits</replaceable></literal>, where
297+
<replaceable>digits</replaceable> represents an octal byte value, and
298+
<literal>\x<replaceable>hexdigits</replaceable></literal>, where
299+
<replaceable>hexdigits</replaceable> represents a hexadecimal byte value.
300+
(It is your responsibility that the byte sequences you create are
301+
valid characters in the server character set encoding.) Any other
302+
character following a backslash is taken literally. Thus, to
303+
include a backslash character, write two backslashes (<literal>\\</>).
304+
Also, a single quote can be included in an escape string by writing
305+
<literal>\'</literal>, in addition to the normal way of <literal>''</>.
306+
</para>
307+
308+
<caution>
309+
<para>
310+
If the configuration parameter
311+
<xref linkend="guc-standard-conforming-strings"> is <literal>off</>,
312+
then <productname>PostgreSQL</productname> recognizes backslash escapes
313+
in both regular and escape string constants. This is for backward
314+
compatibility with the historical behavior, in which backslash escapes
315+
were always recognized.
316+
Although <varname>standard_conforming_strings</> currently defaults to
317+
<literal>off</>, the default will change to <literal>on</> in a future
318+
release for improved standards compliance. Applications are therefore
319+
encouraged to migrate away from using backslash escapes. If you need
320+
to use a backslash escape to represent a special character, write the
321+
constant with an <literal>E</> to be sure it will be handled the same
322+
way in future releases.
323+
</para>
324+
325+
<para>
326+
In addition to <varname>standard_conforming_strings</>, the configuration
327+
parameters <xref linkend="guc-escape-string-warning"> and
328+
<xref linkend="guc-backslash-quote"> govern treatment of backslashes
329+
in string constants.
330+
</para>
331+
</caution>
332+
333+
<para>
334+
The character with the code zero cannot be in a string constant.
335+
</para>
309336
</sect3>
310337

311338
<sect3 id="sql-syntax-dollar-quoting">

0 commit comments

Comments
 (0)