From 4157f73b4ba7fa0c6fb117cb9b5a771875850c83 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 20 Apr 2020 12:29:28 -0400 Subject: [PATCH] Doc: update sections 9.5 and 9.6 for new function table layout. Along the way, update the older examples for bytea to use "hex" output format. That lets us get rid of the lame disclaimer about how the examples assume bytea_output = escape, which was only half true anyway because none of the more-recently-added examples had paid any attention to that. --- doc/src/sgml/func.sgml | 835 +++++++++++++++++++++++++---------------- 1 file changed, 508 insertions(+), 327 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 6aaf454b4c..ca91c7f915 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -2978,7 +2978,6 @@ repeat('Pg', 4) PgPgPgPg substr substr ( string text, start integer , count integer ) - ) text Extracts the substring of string starting at @@ -3335,146 +3334,151 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); (see ). - - - The sample results shown on this page assume that the server parameter - bytea_output is set - to escape (the traditional PostgreSQL format). - The output will look different when using the default setting - (hex). - - - <acronym>SQL</acronym> Binary String Functions and Operators - + - Function - Return Type - Description - Example - Result + + Function/OperatorDescriptionExample(s) + - bytes || - bytes - bytea - - Binary string concatenation + binary string concatenation + bytea || bytea + bytea + + Concatenates the two binary strings. + + '\x123456'::bytea || '\x789a00bcde'::bytea + \x123456789a00bcde - '\\Post'::bytea || '\047gres\000'::bytea - \\Post'gres\000 - + bit_length - bit_length(bytes) + bit_length ( bytea ) + integer + + Returns number of bits in the binary string (8 + times the octet_length). + + bit_length('\x123456'::bytea) + 24 - int - Number of bits in binary string - bit_length('jo\000se':bytea) - 40 - + octet_length - octet_length(bytes) + octet_length ( bytea ) + integer + + Returns number of bytes in the binary string. + + octet_length('\x123456'::bytea) + 3 - int - Number of bytes in binary string - octet_length('jo\000se'::bytea) - 5 - + overlay - overlay(bytes placing bytes from int for int) + overlay ( bytes bytea PLACING newsubstring bytea FROM start integer FOR count integer ) + bytea + + Replaces the substring of bytes that starts at + the start'th byte and extends + for count bytes + with newsubstring. + If count is omitted, it defaults to the length + of newsubstring. + + overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3) + \x12020390 - bytea - - Replace substring - - overlay('Th\000omas'::bytea placing '\002\003'::bytea from 2 for 3) - T\\002\\003mas - + position - position(bytesubstring in bytes) + position ( substring bytea IN bytes bytea ) + integer + + Returns starting index of specified substring + within bytes, or zero if it's not present. + + position('\x5678'::bytea in '\x1234567890'::bytea) + 3 - int - Location of specified substring - position('\000om'::bytea in 'Th\000omas'::bytea) - 3 - + substring - substring(bytes from int for int) + substring ( bytes bytea FROM start integer FOR count integer ) + bytea + + Extracts the substring of bytes starting at + the start'th byte if that is specified, + and stopping after count bytes if that is + specified. Provide at least one of start + and count. + + substring('\x1234567890'::bytea from 3 for 2) + \x5678 - bytea - - Extract substring (provide at least one of from - and for) - - substring('Th\000omas'::bytea from 2 for 3) - h\000o - + trim - trim(both - bytesremoved from - bytes) - - bytea - - Remove the longest string containing only bytes appearing in + trim ( BOTH + bytesremoved bytea FROM + bytes bytea ) + bytea + + Removes the longest string containing only bytes appearing in bytesremoved from the start - and end of bytes + and end of bytes. + + trim('\x9012'::bytea from '\x1234567890'::bytea) + \x345678 - trim('\000\001'::bytea from '\000Tom\001'::bytea) - Tom - - trim(both from - bytes, - bytesremoved) + + trim ( BOTH FROM + bytes bytea, + bytesremoved bytea ) + bytea + + This is a non-standard syntax for trim(). + + trim(both from '\x1234567890'::bytea, '\x9012'::bytea) + \x345678 - bytea - - Non-standard syntax for trim() - - trim(both from 'yxTomxx'::bytea, 'xyz'::bytea) - Tom @@ -3490,78 +3494,73 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
Other Binary String Functions - + - Function - Return Type - Description - Example - Result + + FunctionDescriptionExample(s) + - + btrim - btrim(bytes - bytea, bytesremoved bytea) - - bytea - - Remove the longest string containing only bytes appearing in + btrim ( bytes bytea, + bytesremoved bytea ) + bytea + + Removes the longest string containing only bytes appearing in bytesremoved from the start and end of - bytes - - btrim('\000trim\001'::bytea, '\000\001'::bytea) - trim + bytes. + + btrim('\x1234567890'::bytea, '\x9012'::bytea) + \x345678 + - + get_bit - get_bit(bytes bytea, offset bigint) + get_bit ( bytes bytea, + n bigint ) + integer + + Extracts n'th bit + from binary string. + + get_bit('\x1234567890'::bytea, 30) + 1 - int - - Extract n'th bit - from binary string - - get_bit('Th\000omas'::bytea, 45) - 1 - + get_byte - get_byte(bytes bytea, offset int) + get_byte ( bytes bytea, + n integer ) + integer + + Extracts n'th byte + from binary string. + + get_byte('\x1234567890'::bytea, 4) + 144 - int - - Extract n'th byte - from binary string - - get_byte('Th\000omas'::bytea, 4) - 109 - + length - length(bytes bytea) - - int - - Number of bytes in binary string binary string length @@ -3571,149 +3570,165 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); of a binary string binary strings, length + length ( bytea ) + integer + + Returns the number of bytes in the binary string. + + length('\x1234567890'::bytea) + 5 - length('jo\000se'::bytea) - 5 - length(bytes bytea, - encoding name) - int - - Number of characters in bytes, assuming - that it is text in the given encoding + + length ( bytes bytea, + encoding name ) + integer + + Returns the number of characters in the binary string, assuming + that it is text in the given encoding. + + length('jose'::bytea, 'UTF8') + 4 - length('jose'::bytea, 'UTF8') - 4 - + md5 - md5(bytes bytea) + md5 ( bytea ) + text + + Computes the MD5 hash of + the binary string, with the result written in hexadecimal. + + md5('Th\000omas'::bytea) + 8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1 - text - - MD5 hash, with - the result written in hexadecimal - - md5('Th\000omas'::bytea) - 8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1 - + set_bit - set_bit(bytes bytea, - offset bigint, - newvalue int) + set_bit ( bytes bytea, + n bigint, + newvalue integer ) + bytea + + Sets n'th bit in + binary string to newvalue. + + set_bit('\x1234567890'::bytea, 30, 0) + \x1234563890 - bytea - - Set n'th bit in - binary string - - set_bit('Th\000omas'::bytea, 45, 0) - Th\000omAs - + set_byte - set_byte(bytes bytea, - offset int, - newvalue int) + set_byte ( bytes bytea, + n integer, + newvalue integer ) + bytea + + Sets n'th byte in + binary string to newvalue. + + set_byte('\x1234567890'::bytea, 4, 64) + \x1234567840 - bytea - - Set n'th byte in - binary string - - set_byte('Th\000omas'::bytea, 4, 64) - Th\000o@as - + sha224 - sha224(bytes bytea) + sha224 ( bytea ) + bytea + + Computes the SHA-224 hash + of the binary string. + + sha224('abc'::bytea) + \x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7 - bytea - - SHA-224 hash - - sha224('abc'::bytea) - \x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7 - + sha256 - sha256(bytes bytea) + sha256 ( bytea ) + bytea + + Computes the SHA-256 hash + of the binary string. + + sha256('abc'::bytea) + \xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad - bytea - - SHA-256 hash - - sha256('abc'::bytea) - \xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad - + sha384 - sha384(bytes bytea) + sha384 ( bytea ) + bytea + + Computes the SHA-384 hash + of the binary string. + + sha384('abc'::bytea) + \xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;8086072ba1e7cc2358baeca134c825a7 - bytea - - SHA-384 hash - - sha384('abc'::bytea) - \xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;8086072ba1e7cc2358baeca134c825a7 - + sha512 - sha512(bytes bytea) + sha512 ( bytea ) + bytea + + Computes the SHA-512 hash + of the binary string. + + sha512('abc'::bytea) + \xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;2192992a274fc1a836ba3c23a3feebbd&zwsp;454d4423643ce80e2a9ac94fa54ca49f - bytea - - SHA-512 hash - - sha512('abc'::bytea) - \xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;2192992a274fc1a836ba3c23a3feebbd&zwsp;454d4423643ce80e2a9ac94fa54ca49f - + substr - substr(bytes bytea, from int , count int) + substr ( bytes bytea, start integer , count integer ) + bytea + + Extracts the substring of bytes starting at + the start'th byte, + and extending for count bytes if that is + specified. (Same + as substring(bytes + from start + for count).) + + substr('\x1234567890'::bytea, 3, 2) + \x5678 - bytea - - Extract substring (same as - substring(bytea from from for count)) - - substr('alphabet', 3, 2) - ph @@ -3760,116 +3775,112 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
Text/Binary String Conversion Functions - + - Function - Return Type - Description - Example - Result + + FunctionDescriptionExample(s) + - + convert - convert(bytes bytea, + convert ( bytes bytea, src_encoding name, - dest_encoding name) - - bytea - - Convert binary string representing text in + dest_encoding name ) + bytea + + Converts a binary string representing text in encoding src_encoding to a binary string in encoding dest_encoding (see for - available conversions) + available conversions). + + convert('text_in_utf8', 'UTF8', 'LATIN1') + \x746578745f696e5f75746638 - convert('text_in_utf8', 'UTF8', 'LATIN1') - text_in_utf8 represented in Latin-1 encoding - + convert_from - convert_from(bytes bytea, - src_encoding name) - - text - - Convert binary string representing text in + convert_from ( bytes bytea, + src_encoding name ) + text + + Converts a binary string representing text in encoding src_encoding to text in the database encoding (see for - available conversions) + available conversions). + + convert_from('text_in_utf8', 'UTF8') + text_in_utf8 - convert_from('text_in_utf8', 'UTF8') - text_in_utf8 represented in the - database encoding - + convert_to - convert_to(string text, - dest_encoding name) - - bytea - - Convert text (in the database encoding) to a binary - string encoded in encoding dest_encoding + convert_to ( string text, + dest_encoding name ) + bytea + + Converts a text string (in the database encoding) to a + binary string encoded in encoding dest_encoding (see for - available conversions) + available conversions). + + convert_to('some_text', 'UTF8') + \x736f6d655f74657874 - convert_to('some text', 'UTF8') - some text represented in UTF8 encoding - + encode - encode(bytes bytea, - format text) - - text - - Encode binary data into a textual representation; supported + encode ( bytes bytea, + format text ) + text + + Encodes binary data into a textual representation; supported format values are: base64, escape, - hex + hex. + + encode('123\000\001', 'base64') + MTIzAAE= - encode('123\000\001', 'base64') - MTIzAAE= - + decode - decode(string text, - format text) - - bytea - - Decode binary data from a textual representation given - in string; allowed + decode ( string text, + format text ) + bytea + + Decodes binary data from a textual representation; supported format values are the same as - for encode + for encode. + + decode('MTIzAAE=', 'base64') + \x3132330001 - decode('MTIzAAE=', 'base64') - \x3132330001 @@ -3963,102 +3974,281 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); This section describes functions and operators for examining and manipulating bit strings, that is values of the types - bit and bit varying. Aside from the - usual comparison operators, the operators - shown in can be used. - Bit string operands of &, |, - and # must be of equal length. When bit - shifting, the original length of the string is preserved, as shown - in the examples. + bit and bit varying. (While only + type bit is mentioned in the tables, values of + type bit varying can be used interchangeably.) + Bit strings support the usual comparison operators shown in + , as well as the + operators shown in .
Bit String Operators - - + - Operator - Description - Example - Result + + OperatorDescriptionExample(s) + - || - concatenation - B'10001' || B'011' - 10001011 + + bit || bit + bit + + Concatenation + + B'10001' || B'011' + 10001011 + - & - bitwise AND - B'10001' & B'01101' - 00001 + + bit & bit + bit + + Bitwise AND (inputs must be of equal length) + + B'10001' & B'01101' + 00001 + - | - bitwise OR - B'10001' | B'01101' - 11101 + + bit | bit + bit + + Bitwise OR (inputs must be of equal length) + + B'10001' | B'01101' + 11101 + - # - bitwise XOR - B'10001' # B'01101' - 11100 + + bit # bit + bit + + Bitwise exclusive OR (inputs must be of equal length) + + B'10001' # B'01101' + 11100 + - ~ - bitwise NOT - ~ B'10001' - 01110 + + ~ bit + bit + + Bitwise NOT + + ~ B'10001' + 01110 + - << - bitwise shift left - B'10001' << 3 - 01000 + + bit << integer + bit + + Bitwise shift left + (string length is preserved) + + B'10001' << 3 + 01000 + - >> - bitwise shift right - B'10001' >> 2 - 00100 + + bit >> integer + bit + + Bitwise shift right + (string length is preserved) + + B'10001' >> 2 + 00100 +
- Some of the binary-string functions shown in - and - are also available - for bit strings, specifically: - length, - bit_length, - octet_length, - position, - substring, - overlay, - get_bit, - set_bit. - When working with a bit string, get_bit - and set_bit number the first - (leftmost) bit of the string as bit 0. + Some of the functions available for binary strings are also available + for bit strings, as shown in . + + Bit String Functions + + + + + FunctionDescriptionExample(s) + + + + + + + + + bit_length + + bit_length ( bit ) + integer + + Returns number of bits in the bit string. + + bit_length(B'10111') + 5 + + + + + + + length + + + bit string + length + + length ( bit ) + integer + + Returns number of bits in the bit string. + + length(B'10111') + 5 + + + + + + + octet_length + + octet_length ( bit ) + integer + + Returns number of bytes in the bit string. + + octet_length(B'1011111011') + 2 + + + + + + + overlay + + overlay ( bits bit PLACING newsubstring bit FROM start integer FOR count integer ) + bit + + Replaces the substring of bits that starts at + the start'th bit and extends + for count bits + with newsubstring. + If count is omitted, it defaults to the length + of newsubstring. + + overlay(B'01010101010101010' placing B'11111' from 2 for 3) + 0111110101010101010 + + + + + + + position + + position ( substring bit IN bits bit ) + integer + + Returns starting index of specified substring + within bits, or zero if it's not present. + + position(B'010' in B'000001101011') + 8 + + + + + + + substring + + substring ( bits bit FROM start integer FOR count integer ) + bit + + Extracts the substring of bits starting at + the start'th bit if that is specified, + and stopping after count bits if that is + specified. Provide at least one of start + and count. + + substring(B'110010111111' from 3 for 2) + 00 + + + + + + + get_bit + + get_bit ( bits bit, + n integer ) + integer + + Extracts n'th bit + from bit string; the first (leftmost) bit is bit 0. + + get_bit(B'101010101010101010', 6) + 1 + + + + + + + set_bit + + set_bit ( bits bit, + n integer, + newvalue integer ) + bit + + Sets n'th bit in + bit string to newvalue; + the first (leftmost) bit is bit 0. + + set_bit(B'101010101010101010', 6, 0) + 101010001010101010 + + + + +
+ In addition, it is possible to cast integral values to and from type bit. + Casting an integer to bit(n) copies the rightmost + n bits. Casting an integer to a bit string width wider + than the integer itself will sign-extend on the left. Some examples: 44::bit(10) 0000101100 @@ -4070,15 +4260,6 @@ cast(-44 as bit(12)) 111111010100 bit(1), and so will deliver only the least significant bit of the integer. - - - - Casting an integer to bit(n) copies the rightmost - n bits. Casting an integer to a bit string width wider - than the integer itself will sign-extend on the left. - - -