From a003bd07f3f88c9d72e6f07205b78771f24eeb97 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 21 Oct 2006 17:12:07 +0000 Subject: [PATCH] Rewrite discussion of string constant syntax to bring it into line with the politically correct view that backslash escapes are deprecated. --- doc/src/sgml/syntax.sgml | 111 +++++++++++++++++++++++++++++------------------ 1 file changed, 69 insertions(+), 42 deletions(-) diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 8fd54089e3..3a7b5d9ea1 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1,4 +1,4 @@ - + SQL Syntax @@ -240,49 +240,12 @@ UPDATE "my_table" SET "a" = 5; A string constant in SQL is an arbitrary sequence of characters bounded by single quotes ('), for example - 'This is a string'. The standard-compliant way of - writing a single-quote character within a string constant is to + 'This is a string'. To include + a single-quote character within a string constant, write two adjacent single quotes, e.g. 'Dianne''s horse'. - PostgreSQL also allows single quotes - to be escaped with a backslash (\'). However, - future versions of PostgreSQL will not - allow this, so applications using backslashes should convert to the - standard-compliant method outlined above. - - - - Another PostgreSQL extension is that - C-style backslash escapes are available: \b is a - backspace, \f is a form feed, - \n is a newline, \r is a - carriage return, \t is a tab. Also supported is - \digits, where - digits represents an octal byte value, and - \xhexdigits, where - hexdigits represents a hexadecimal byte value. - (It is your responsibility that the byte sequences you create are - valid characters in the server character set encoding.) Any other - character following a backslash is taken literally. Thus, to - include a backslash in a string constant, write two backslashes. - - - - - While ordinary strings now support C-style backslash escapes, - future versions will generate warnings for such usage and - eventually treat backslashes as literal characters to be - standard-conforming. The proper way to specify escape processing is - to use the escape string syntax to indicate that escape - processing is desired. Escape string syntax is specified by writing - the letter E (upper or lower case) just before - the string, e.g. E'\041'. This method will work in all - future versions of PostgreSQL. - - - - - The character with the code zero cannot be in a string constant. + Note that this is not the same as a double-quote + character ("). @@ -306,6 +269,70 @@ SELECT 'foo' 'bar'; by SQL; PostgreSQL is following the standard.) + + + + escape string syntax + + + backslash escapes + + PostgreSQL also accepts escape + string constants, which are an extension to the SQL standard. + An escape string constant is specified by writing the letter + E (upper or lower case) just before the opening single + quote, e.g. E'foo'. (When continuing an escape string + constant across lines, write E only before the first opening + quote.) + Within an escape string, a backslash character (\) begins a + C-like backslash escape sequence, in which the combination + of backslash and following character(s) represents a special byte value. + \b is a backspace, + \f is a form feed, + \n is a newline, + \r is a carriage return, + \t is a tab. + Also supported are + \digits, where + digits represents an octal byte value, and + \xhexdigits, where + hexdigits represents a hexadecimal byte value. + (It is your responsibility that the byte sequences you create are + valid characters in the server character set encoding.) Any other + character following a backslash is taken literally. Thus, to + include a backslash character, write two backslashes (\\). + Also, a single quote can be included in an escape string by writing + \', in addition to the normal way of ''. + + + + + If the configuration parameter + is off, + then PostgreSQL recognizes backslash escapes + in both regular and escape string constants. This is for backward + compatibility with the historical behavior, in which backslash escapes + were always recognized. + Although standard_conforming_strings currently defaults to + off, the default will change to on in a future + release for improved standards compliance. Applications are therefore + encouraged to migrate away from using backslash escapes. If you need + to use a backslash escape to represent a special character, write the + constant with an E to be sure it will be handled the same + way in future releases. + + + + In addition to standard_conforming_strings, the configuration + parameters and + govern treatment of backslashes + in string constants. + + + + + The character with the code zero cannot be in a string constant. + -- 2.11.0