diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index a25c122ac8..131a63b36c 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1795,48 +1795,6 @@ - convert - - convert(string bytea, - src_encoding name, - dest_encoding name) - - bytea - - Convert string to dest_encoding. The - original encoding is specified by - src_encoding. The - string must be valid in this encoding. - Conversions can be defined by CREATE CONVERSION. - Also there are some predefined conversions. See for available conversions. - - convert('text_in_utf8', 'UTF8', 'LATIN1') - text_in_utf8 represented in Latin-1 - encoding (ISO 8859-1) - - - - - - convert_from - - convert_from(string bytea, - src_encoding name) - - text - - Convert string to the database encoding. The original encoding - is specified by src_encoding. The - string must be valid in this encoding. - - convert_from('text_in_utf8', 'UTF8') - text_in_utf8 represented in the current database encoding - - - - - convert_to convert_to(string text, @@ -1844,7 +1802,8 @@ bytea - Convert string to dest_encoding. + Convert string to dest_encoding. See for available conversions. convert_to('some text', 'UTF8') some text represented in the UTF8 encoding @@ -1855,39 +1814,24 @@ decode + + base64 encoding + decode(string text, format text) bytea Decode binary data from textual representation in string. - Options for format are same as in encode. + Options + for format are same as + in encode. decode('MTIzAAE=', 'base64') \x3132330001 - - - encode - - encode(data bytea, - format text) - - text - - Encode binary data into a textual representation. Supported - formats are: base64, hex, escape. - escape converts zero bytes and high-bit-set bytes to - octal sequences (\nnn) and - doubles backslashes. - - encode('123\000\001', 'base64') - MTIzAAE= - - - format @@ -1955,19 +1899,6 @@ - length(string bytea, - encoding name ) - int - - Number of characters in string in the given - encoding. The string - must be valid in this encoding. - - length('jose', 'UTF8') - 4 - - - lpad @@ -2133,18 +2064,6 @@ - quote_nullable(value anyelement) - text - - Coerce the given value to text and then quote it as a literal; - or, if the argument is null, return NULL. - Embedded single-quotes and backslashes are properly doubled. - - quote_nullable(42.5) - '42.5' - - - regexp_match @@ -2417,22 +2336,6 @@ - to_hex - - to_hex(number int - or bigint) - - text - Convert number to its equivalent hexadecimal - representation - - to_hex(2147483647) - 7fffffff - - - - - translate translate(string text, @@ -2468,6 +2371,89 @@ format treats a NULL as a zero-element array. + + encode + + + decode + + + base64 encoding + + + hex encoding + + + escape encoding + + + + The encode and decode functions + support the following encodings: + + + + base64 + + + The base64 encoding is that + of RFC + 2045 Section 6.8. As per the RFC, encoded lines are + broken at 76 characters. However instead of the MIME CRLF + end-of-line marker, only a newline is used for end-of-line. + + + The decode function ignores carriage-return, + newline, space, and tab characters. Otherwise, an error is + raised when decode is supplied invalid + base64 data — including when trailing padding is incorrect. + + + + + + escape + + + The escape encoding converts zero bytes and + high-bit-set bytes to octal sequences + (\nnn) and doubles + backslashes. Encoding always produces 4 characters for each + high-bit-set input byte. + + + The decode function accepts fewer than three + octal digits after a \ character. An error is + raised when decode is supplied a + single \ not followed by an octal digit. + + + + + + hex + + + The hex encoding represents each 4 bits of + data as a single hexadecimal digit, 0 + through f. Encoding outputs + the a-f hex digits in lower + case. Because the smallest unit of data is 8 bits there are + always an even number of characters returned + by encode. + + + The decode function + accepts a-f characters in + either upper or lower case. An error is raised + when decode is supplied invalid hex data + — including when given an odd number of characters. + + + + + + See also the aggregate function string_agg in . @@ -3466,7 +3452,8 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); This section describes functions and operators for examining and - manipulating values of type bytea. + manipulating values of type bytea, and a few functions + which produce strings from other binary inputs. @@ -3629,47 +3616,81 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); Remove the longest string containing only bytes appearing in bytes from the start and end of string - + btrim('\000trim\001'::bytea, '\000\001'::bytea) trim - - + + - decode + convert - decode(string text, - format text) - - bytea - - Decode binary data from textual representation in string. - Options for format are same as in encode. - - decode('123\000456', 'escape') - 123\000456 - + convert(string bytea, + src_encoding name, + dest_encoding name) + + bytea + + Convert string from src_encoding + to dest_encoding, or raise an error. See + for the predefined conversions. + The string must be valid + in src_encoding. New conversions may be + defined with CREATE CONVERSION. + + convert('text_in_utf8', 'UTF8', 'LATIN1') + text_in_utf8 represented in Latin-1 + encoding (ISO 8859-1) + - - + + + + convert_from + + convert_from(string bytea, + src_encoding name) + + text + + Convert string to the database encoding. The original encoding + is specified by src_encoding. The + string must be valid in this encoding. See + for available conversions. + + convert_from('text_in_utf8', 'UTF8') + text_in_utf8 represented in the current database encoding + + + + encode - encode(data bytea, - format text) - - text - - Encode binary data into a textual representation. Supported - formats are: base64, hex, escape. - escape converts zero bytes and high-bit-set bytes to - octal sequences (\nnn) and - doubles backslashes. - - encode('123\000456'::bytea, 'escape') - 123\000456 - + + base64 encoding + + + hex encoding + + + escape encoding + + encode(data bytea, + format text) + + text + + Encode binary data into a textual representation. Supported + formats are: + base64, + escape, + hex. + + encode('123\000\001', 'base64') + MTIzAAE= + @@ -3701,45 +3722,70 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); 109 - - - - length - - length(string) - - int - - Length of binary string - - binary string - length - - - length - of a binary string - binary strings, length - - - length('jo\000se'::bytea) - 5 - + + + + length + + length(string) + + int + + Length of binary string + + binary string + length + + + length + of a binary string + binary strings, length + + + length('jo\000se'::bytea) + 5 + - - - - md5 - - md5(string) - - text - - Calculates the MD5 hash of string, - returning the result in hexadecimal - - md5('Th\000omas'::bytea) - 8ab2d3c9689aaf18​b4958c334c82d8b1 - + + length(string bytea, + encoding name ) + int + + Number of characters in string in the given + encoding. The string + must be valid in this encoding. + + length('jose', 'UTF8') + 4 + + + + + + md5 + + md5(string) + + text + + Calculates the MD5 hash of string, + returning the result in hexadecimal + + md5('Th\000omas'::bytea) + 8ab2d3c9689aaf18​b4958c334c82d8b1 + + + + quote_nullable(value anyelement) + text + + Coerce the given value to text and then quote it as a literal; + or, if the argument is null, return NULL. + Embedded single-quotes and backslashes are properly doubled. + + quote_nullable(42.5) + '42.5' + @@ -3832,6 +3878,22 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); sha512('abc') \xddaf35a193617abacc417349ae204131​12e6fa4e89a97ea20a9eeee64b55d39a​2192992a274fc1a836ba3c23a3feebbd​454d4423643ce80e2a9ac94fa54ca49f + + + + + to_hex + + to_hex(number int + or bigint) + + text + Convert number to its equivalent hexadecimal + representation + + to_hex(2147483647) + 7fffffff +