diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/json.sgml | 19 | ||||
| -rw-r--r-- | doc/src/sgml/syntax.sgml | 100 |
2 files changed, 55 insertions, 64 deletions
diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml index 1b6aaf0a558..a9c68c78ea5 100644 --- a/doc/src/sgml/json.sgml +++ b/doc/src/sgml/json.sgml @@ -61,8 +61,8 @@ </para> <para> - <productname>PostgreSQL</productname> allows only one character set - encoding per database. It is therefore not possible for the JSON + RFC 7159 specifies that JSON strings should be encoded in UTF8. + It is therefore not possible for the JSON types to conform rigidly to the JSON specification unless the database encoding is UTF8. Attempts to directly include characters that cannot be represented in the database encoding will fail; conversely, @@ -77,13 +77,13 @@ regardless of the database encoding, and are checked only for syntactic correctness (that is, that four hex digits follow <literal>\u</literal>). However, the input function for <type>jsonb</type> is stricter: it disallows - Unicode escapes for non-ASCII characters (those above <literal>U+007F</literal>) - unless the database encoding is UTF8. The <type>jsonb</type> type also + Unicode escapes for characters that cannot be represented in the database + encoding. The <type>jsonb</type> type also rejects <literal>\u0000</literal> (because that cannot be represented in <productname>PostgreSQL</productname>'s <type>text</type> type), and it insists that any use of Unicode surrogate pairs to designate characters outside the Unicode Basic Multilingual Plane be correct. Valid Unicode escapes - are converted to the equivalent ASCII or UTF8 character for storage; + are converted to the equivalent single character for storage; this includes folding surrogate pairs into a single character. </para> @@ -96,9 +96,8 @@ not <type>jsonb</type>. The fact that the <type>json</type> input function does not make these checks may be considered a historical artifact, although it does allow for simple storage (without processing) of JSON Unicode - escapes in a non-UTF8 database encoding. In general, it is best to - avoid mixing Unicode escapes in JSON with a non-UTF8 database encoding, - if possible. + escapes in a database encoding that does not support the represented + characters. </para> </note> @@ -144,8 +143,8 @@ <row> <entry><type>string</type></entry> <entry><type>text</type></entry> - <entry><literal>\u0000</literal> is disallowed, as are non-ASCII Unicode - escapes if database encoding is not UTF8</entry> + <entry><literal>\u0000</literal> is disallowed, as are Unicode escapes + representing characters not available in the database encoding</entry> </row> <row> <entry><type>number</type></entry> diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index c908e0bc399..e1348777982 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -189,6 +189,23 @@ UPDATE "my_table" SET "a" = 5; ampersands. The length limitation still applies. </para> + <para> + Quoting an identifier also makes it case-sensitive, whereas + unquoted names are always folded to lower case. For example, the + identifiers <literal>FOO</literal>, <literal>foo</literal>, and + <literal>"foo"</literal> are considered the same by + <productname>PostgreSQL</productname>, but + <literal>"Foo"</literal> and <literal>"FOO"</literal> are + different from these three and each other. (The folding of + unquoted names to lower case in <productname>PostgreSQL</productname> is + incompatible with the SQL standard, which says that unquoted names + should be folded to upper case. Thus, <literal>foo</literal> + should be equivalent to <literal>"FOO"</literal> not + <literal>"foo"</literal> according to the standard. If you want + to write portable applications you are advised to always quote a + particular name or never quote it.) + </para> + <indexterm> <primary>Unicode escape</primary> <secondary>in identifiers</secondary> @@ -230,7 +247,8 @@ U&"d!0061t!+000061" UESCAPE '!' The escape character can be any single character other than a hexadecimal digit, the plus sign, a single quote, a double quote, or a whitespace character. Note that the escape character is - written in single quotes, not double quotes. + written in single quotes, not double quotes, + after <literal>UESCAPE</literal>. </para> <para> @@ -239,32 +257,18 @@ U&"d!0061t!+000061" UESCAPE '!' </para> <para> - The Unicode escape syntax works only when the server encoding is - <literal>UTF8</literal>. When other server encodings are used, only code - points in the ASCII range (up to <literal>\007F</literal>) can be - specified. Both the 4-digit and the 6-digit form can be used to + Either the 4-digit or the 6-digit escape form can be used to specify UTF-16 surrogate pairs to compose characters with code points larger than U+FFFF, although the availability of the 6-digit form technically makes this unnecessary. (Surrogate - pairs are not stored directly, but combined into a single - code point that is then encoded in UTF-8.) + pairs are not stored directly, but are combined into a single + code point.) </para> <para> - Quoting an identifier also makes it case-sensitive, whereas - unquoted names are always folded to lower case. For example, the - identifiers <literal>FOO</literal>, <literal>foo</literal>, and - <literal>"foo"</literal> are considered the same by - <productname>PostgreSQL</productname>, but - <literal>"Foo"</literal> and <literal>"FOO"</literal> are - different from these three and each other. (The folding of - unquoted names to lower case in <productname>PostgreSQL</productname> is - incompatible with the SQL standard, which says that unquoted names - should be folded to upper case. Thus, <literal>foo</literal> - should be equivalent to <literal>"FOO"</literal> not - <literal>"foo"</literal> according to the standard. If you want - to write portable applications you are advised to always quote a - particular name or never quote it.) + If the server encoding is not UTF-8, the Unicode code point identified + by one of these escape sequences is converted to the actual server + encoding; an error is reported if that's not possible. </para> </sect2> @@ -427,25 +431,11 @@ SELECT 'foo' 'bar'; <para> It is your responsibility that the byte sequences you create, especially when using the octal or hexadecimal escapes, compose - valid characters in the server character set encoding. When the - server encoding is UTF-8, then the Unicode escapes or the + valid characters in the server character set encoding. + A useful alternative is to use Unicode escapes or the alternative Unicode escape syntax, explained - in <xref linkend="sql-syntax-strings-uescape"/>, should be used - instead. (The alternative would be doing the UTF-8 encoding by - hand and writing out the bytes, which would be very cumbersome.) - </para> - - <para> - The Unicode escape syntax works fully only when the server - encoding is <literal>UTF8</literal>. When other server encodings are - used, only code points in the ASCII range (up - to <literal>\u007F</literal>) can be specified. Both the 4-digit and - the 8-digit form can be used to specify UTF-16 surrogate pairs to - compose characters with code points larger than U+FFFF, although - the availability of the 8-digit form technically makes this - unnecessary. (When surrogate pairs are used when the server - encoding is <literal>UTF8</literal>, they are first combined into a - single code point that is then encoded in UTF-8.) + in <xref linkend="sql-syntax-strings-uescape"/>; then the server + will check that the character conversion is possible. </para> <caution> @@ -524,16 +514,23 @@ U&'d!0061t!+000061' UESCAPE '!' </para> <para> - The Unicode escape syntax works only when the server encoding is - <literal>UTF8</literal>. When other server encodings are used, only - code points in the ASCII range (up to <literal>\007F</literal>) - can be specified. Both the 4-digit and the 6-digit form can be - used to specify UTF-16 surrogate pairs to compose characters with - code points larger than U+FFFF, although the availability of the - 6-digit form technically makes this unnecessary. (When surrogate - pairs are used when the server encoding is <literal>UTF8</literal>, they - are first combined into a single code point that is then encoded - in UTF-8.) + To include the escape character in the string literally, write + it twice. + </para> + + <para> + Either the 4-digit or the 6-digit escape form can be used to + specify UTF-16 surrogate pairs to compose characters with code + points larger than U+FFFF, although the availability of the + 6-digit form technically makes this unnecessary. (Surrogate + pairs are not stored directly, but are combined into a single + code point.) + </para> + + <para> + If the server encoding is not UTF-8, the Unicode code point identified + by one of these escape sequences is converted to the actual server + encoding; an error is reported if that's not possible. </para> <para> @@ -546,11 +543,6 @@ U&'d!0061t!+000061' UESCAPE '!' parameter is set to off, this syntax will be rejected with an error message. </para> - - <para> - To include the escape character in the string literally, write it - twice. - </para> </sect3> <sect3 id="sql-syntax-dollar-quoting"> |