diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 6aaf454b4c8..ca91c7f9154 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. - - -