begriffs open source - ai-pg/blob - full-docs/txt/functions-binarystring.txt

   1
   2 9.5. Binary String Functions and Operators #
   3
   4    This section describes functions and operators for examining and
   5    manipulating binary strings, that is values of type bytea. Many of
   6    these are equivalent, in purpose and syntax, to the text-string
   7    functions described in the previous section.
   8
   9    SQL defines some string functions that use key words, rather than
  10    commas, to separate arguments. Details are in Table 9.11. PostgreSQL
  11    also provides versions of these functions that use the regular function
  12    invocation syntax (see Table 9.12).
  13
  14    Table 9.11. SQL Binary String Functions and Operators
  15
  16    Function/Operator
  17
  18    Description
  19
  20    Example(s)
  21
  22    bytea || bytea → bytea
  23
  24    Concatenates the two binary strings.
  25
  26    '\x123456'::bytea || '\x789a00bcde'::bytea → \x123456789a00bcde
  27
  28    bit_length ( bytea ) → integer
  29
  30    Returns number of bits in the binary string (8 times the octet_length).
  31
  32    bit_length('\x123456'::bytea) → 24
  33
  34    btrim ( bytes bytea, bytesremoved bytea ) → bytea
  35
  36    Removes the longest string containing only bytes appearing in
  37    bytesremoved from the start and end of bytes.
  38
  39    btrim('\x1234567890'::bytea, '\x9012'::bytea) → \x345678
  40
  41    ltrim ( bytes bytea, bytesremoved bytea ) → bytea
  42
  43    Removes the longest string containing only bytes appearing in
  44    bytesremoved from the start of bytes.
  45
  46    ltrim('\x1234567890'::bytea, '\x9012'::bytea) → \x34567890
  47
  48    octet_length ( bytea ) → integer
  49
  50    Returns number of bytes in the binary string.
  51
  52    octet_length('\x123456'::bytea) → 3
  53
  54    overlay ( bytes bytea PLACING newsubstring bytea FROM start integer [
  55    FOR count integer ] ) → bytea
  56
  57    Replaces the substring of bytes that starts at the start'th byte and
  58    extends for count bytes with newsubstring. If count is omitted, it
  59    defaults to the length of newsubstring.
  60
  61    overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3) →
  62    \x12020390
  63
  64    position ( substring bytea IN bytes bytea ) → integer
  65
  66    Returns first starting index of the specified substring within bytes,
  67    or zero if it's not present.
  68
  69    position('\x5678'::bytea in '\x1234567890'::bytea) → 3
  70
  71    rtrim ( bytes bytea, bytesremoved bytea ) → bytea
  72
  73    Removes the longest string containing only bytes appearing in
  74    bytesremoved from the end of bytes.
  75
  76    rtrim('\x1234567890'::bytea, '\x9012'::bytea) → \x12345678
  77
  78    substring ( bytes bytea [ FROM start integer ] [ FOR count integer ] )
  79    → bytea
  80
  81    Extracts the substring of bytes starting at the start'th byte if that
  82    is specified, and stopping after count bytes if that is specified.
  83    Provide at least one of start and count.
  84
  85    substring('\x1234567890'::bytea from 3 for 2) → \x5678
  86
  87    trim ( [ LEADING | TRAILING | BOTH ] bytesremoved bytea FROM bytes
  88    bytea ) → bytea
  89
  90    Removes the longest string containing only bytes appearing in
  91    bytesremoved from the start, end, or both ends (BOTH is the default) of
  92    bytes.
  93
  94    trim('\x9012'::bytea from '\x1234567890'::bytea) → \x345678
  95
  96    trim ( [ LEADING | TRAILING | BOTH ] [ FROM ] bytes bytea, bytesremoved
  97    bytea ) → bytea
  98
  99    This is a non-standard syntax for trim().
 100
 101    trim(both from '\x1234567890'::bytea, '\x9012'::bytea) → \x345678
 102
 103    Additional binary string manipulation functions are available and are
 104    listed in Table 9.12. Some of them are used internally to implement the
 105    SQL-standard string functions listed in Table 9.11.
 106
 107    Table 9.12. Other Binary String Functions
 108
 109    Function
 110
 111    Description
 112
 113    Example(s)
 114
 115    bit_count ( bytes bytea ) → bigint
 116
 117    Returns the number of bits set in the binary string (also known as
 118    “popcount”).
 119
 120    bit_count('\x1234567890'::bytea) → 15
 121
 122    crc32 ( bytea ) → bigint
 123
 124    Computes the CRC-32 value of the binary string.
 125
 126    crc32('abc'::bytea) → 891568578
 127
 128    crc32c ( bytea ) → bigint
 129
 130    Computes the CRC-32C value of the binary string.
 131
 132    crc32c('abc'::bytea) → 910901175
 133
 134    get_bit ( bytes bytea, n bigint ) → integer
 135
 136    Extracts n'th bit from binary string.
 137
 138    get_bit('\x1234567890'::bytea, 30) → 1
 139
 140    get_byte ( bytes bytea, n integer ) → integer
 141
 142    Extracts n'th byte from binary string.
 143
 144    get_byte('\x1234567890'::bytea, 4) → 144
 145
 146    length ( bytea ) → integer
 147
 148    Returns the number of bytes in the binary string.
 149
 150    length('\x1234567890'::bytea) → 5
 151
 152    length ( bytes bytea, encoding name ) → integer
 153
 154    Returns the number of characters in the binary string, assuming that it
 155    is text in the given encoding.
 156
 157    length('jose'::bytea, 'UTF8') → 4
 158
 159    md5 ( bytea ) → text
 160
 161    Computes the MD5 hash of the binary string, with the result written in
 162    hexadecimal.
 163
 164    md5('Th\000omas'::bytea) → 8ab2d3c9689aaf18b4958c334c82d8b1
 165
 166    reverse ( bytea ) → bytea
 167
 168    Reverses the order of the bytes in the binary string.
 169
 170    reverse('\xabcd'::bytea) → \xcdab
 171
 172    set_bit ( bytes bytea, n bigint, newvalue integer ) → bytea
 173
 174    Sets n'th bit in binary string to newvalue.
 175
 176    set_bit('\x1234567890'::bytea, 30, 0) → \x1234563890
 177
 178    set_byte ( bytes bytea, n integer, newvalue integer ) → bytea
 179
 180    Sets n'th byte in binary string to newvalue.
 181
 182    set_byte('\x1234567890'::bytea, 4, 64) → \x1234567840
 183
 184    sha224 ( bytea ) → bytea
 185
 186    Computes the SHA-224 hash of the binary string.
 187
 188    sha224('abc'::bytea) →
 189    \x23097d223405d8228642a477bda255b32aadbce4bda0b3f7e36c9da7
 190
 191    sha256 ( bytea ) → bytea
 192
 193    Computes the SHA-256 hash of the binary string.
 194
 195    sha256('abc'::bytea) →
 196    \xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
 197
 198    sha384 ( bytea ) → bytea
 199
 200    Computes the SHA-384 hash of the binary string.
 201
 202    sha384('abc'::bytea) →
 203    \xcb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed808
 204    6072ba1e7cc2358baeca134c825a7
 205
 206    sha512 ( bytea ) → bytea
 207
 208    Computes the SHA-512 hash of the binary string.
 209
 210    sha512('abc'::bytea) →
 211    \xddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a219
 212    2992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f
 213
 214    substr ( bytes bytea, start integer [, count integer ] ) → bytea
 215
 216    Extracts the substring of bytes starting at the start'th byte, and
 217    extending for count bytes if that is specified. (Same as
 218    substring(bytes from start for count).)
 219
 220    substr('\x1234567890'::bytea, 3, 2) → \x5678
 221
 222    Functions get_byte and set_byte number the first byte of a binary
 223    string as byte 0. Functions get_bit and set_bit number bits from the
 224    right within each byte; for example bit 0 is the least significant bit
 225    of the first byte, and bit 15 is the most significant bit of the second
 226    byte.
 227
 228    For historical reasons, the function md5 returns a hex-encoded value of
 229    type text whereas the SHA-2 functions return type bytea. Use the
 230    functions encode and decode to convert between the two. For example
 231    write encode(sha256('abc'), 'hex') to get a hex-encoded text
 232    representation, or decode(md5('abc'), 'hex') to get a bytea value.
 233
 234    Functions for converting strings between different character sets
 235    (encodings), and for representing arbitrary binary data in textual
 236    form, are shown in Table 9.13. For these functions, an argument or
 237    result of type text is expressed in the database's default encoding,
 238    while arguments or results of type bytea are in an encoding named by
 239    another argument.
 240
 241    Table 9.13. Text/Binary String Conversion Functions
 242
 243    Function
 244
 245    Description
 246
 247    Example(s)
 248
 249    convert ( bytes bytea, src_encoding name, dest_encoding name ) → bytea
 250
 251    Converts a binary string representing text in encoding src_encoding to
 252    a binary string in encoding dest_encoding (see Section 23.3.4 for
 253    available conversions).
 254
 255    convert('text_in_utf8', 'UTF8', 'LATIN1') → \x746578745f696e5f75746638
 256
 257    convert_from ( bytes bytea, src_encoding name ) → text
 258
 259    Converts a binary string representing text in encoding src_encoding to
 260    text in the database encoding (see Section 23.3.4 for available
 261    conversions).
 262
 263    convert_from('text_in_utf8', 'UTF8') → text_in_utf8
 264
 265    convert_to ( string text, dest_encoding name ) → bytea
 266
 267    Converts a text string (in the database encoding) to a binary string
 268    encoded in encoding dest_encoding (see Section 23.3.4 for available
 269    conversions).
 270
 271    convert_to('some_text', 'UTF8') → \x736f6d655f74657874
 272
 273    encode ( bytes bytea, format text ) → text
 274
 275    Encodes binary data into a textual representation; supported format
 276    values are: base64, escape, hex.
 277
 278    encode('123\000\001', 'base64') → MTIzAAE=
 279
 280    decode ( string text, format text ) → bytea
 281
 282    Decodes binary data from a textual representation; supported format
 283    values are the same as for encode.
 284
 285    decode('MTIzAAE=', 'base64') → \x3132330001
 286
 287    The encode and decode functions support the following textual formats:
 288
 289    base64 #
 290           The base64 format is that of RFC 2045 Section 6.8. As per the
 291           RFC, encoded lines are broken at 76 characters. However instead
 292           of the MIME CRLF end-of-line marker, only a newline is used for
 293           end-of-line. The decode function ignores carriage-return,
 294           newline, space, and tab characters. Otherwise, an error is
 295           raised when decode is supplied invalid base64 data — including
 296           when trailing padding is incorrect.
 297
 298    escape #
 299           The escape format converts zero bytes and bytes with the high
 300           bit set into octal escape sequences (\nnn), and it doubles
 301           backslashes. Other byte values are represented literally. The
 302           decode function will raise an error if a backslash is not
 303           followed by either a second backslash or three octal digits; it
 304           accepts other byte values unchanged.
 305
 306    hex #
 307           The hex format represents each 4 bits of data as one hexadecimal
 308           digit, 0 through f, writing the higher-order digit of each byte
 309           first. The encode function outputs the a-f hex digits in lower
 310           case. Because the smallest unit of data is 8 bits, there are
 311           always an even number of characters returned by encode. The
 312           decode function accepts the a-f characters in either upper or
 313           lower case. An error is raised when decode is given invalid hex
 314           data — including when given an odd number of characters.
 315
 316    In addition, it is possible to cast integral values to and from type
 317    bytea. Casting an integer to bytea produces 2, 4, or 8 bytes, depending
 318    on the width of the integer type. The result is the two's complement
 319    representation of the integer, with the most significant byte first.
 320    Some examples:
 321 1234::smallint::bytea          \x04d2
 322 cast(1234 as bytea)            \x000004d2
 323 cast(-1234 as bytea)           \xfffffb2e
 324 '\x8000'::bytea::smallint      -32768
 325 '\x8000'::bytea::integer       32768
 326
 327    Casting a bytea to an integer will raise an error if the length of the
 328    bytea exceeds the width of the integer type.
 329
 330    See also the aggregate function string_agg in Section 9.21 and the
 331    large object functions in Section 33.4.