Adding upstream version 16.2.upstream/16.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 13:44:03 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 13:44:03 +0000
commit: 293913568e6a7a86fd1479e1cff8e2ecb58d6568 (patch)
tree: fc3b469a3ec5ab71b36ea97cc7aaddb838423a0c /doc/src/sgml/html/functions-binarystring.html
parent: Initial commit. (diff)
download: postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.tar.xz
postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.zip
1 files changed, 510 insertions, 0 deletions
diff --git a/doc/src/sgml/html/functions-binarystring.html b/doc/src/sgml/html/functions-binarystring.html
new file mode 100644
index 0000000..64f479e
--- /dev/null
+++ b/doc/src/sgml/html/functions-binarystring.html
@@ -0,0 +1,510 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.5. Binary String Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-string.html" title="9.4. String Functions and Operators" /><link rel="next" href="functions-bitstring.html" title="9.6. Bit String Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.5. Binary String Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-string.html" title="9.4. String Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-bitstring.html" title="9.6. Bit String Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-BINARYSTRING"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.5. Binary String Functions and Operators <a href="#FUNCTIONS-BINARYSTRING" class="id_link">#</a></h2></div></div></div><a id="id-1.5.8.11.2" class="indexterm"></a><p>
+    This section describes functions and operators for examining and
+    manipulating binary strings, that is values of type <code class="type">bytea</code>.
+    Many of these are equivalent, in purpose and syntax, to the
+    text-string functions described in the previous section.
+   </p><p>
+    <acronym class="acronym">SQL</acronym> defines some string functions that use
+    key words, rather than commas, to separate
+    arguments.  Details are in
+    <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-SQL" title="Table 9.11. SQL Binary String Functions and Operators">Table 9.11</a>.
+    <span class="productname">PostgreSQL</span> also provides versions of these functions
+    that use the regular function invocation syntax
+    (see <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-OTHER" title="Table 9.12. Other Binary String Functions">Table 9.12</a>).
+   </p><div class="table" id="FUNCTIONS-BINARYSTRING-SQL"><p class="title"><strong>Table 9.11. <acronym class="acronym">SQL</acronym> Binary String Functions and Operators</strong></p><div class="table-contents"><table class="table" summary="SQL Binary String Functions and Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+        Function/Operator
+       </p>
+       <p>
+        Description
+       </p>
+       <p>
+        Example(s)
+       </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.5.2.2.1.1.1.1" class="indexterm"></a>
+        <code class="type">bytea</code> <code class="literal">||</code> <code class="type">bytea</code>
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Concatenates the two binary strings.
+       </p>
+       <p>
+        <code class="literal">'\x123456'::bytea || '\x789a00bcde'::bytea</code>
+        → <code class="returnvalue">\x123456789a00bcde</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.5.2.2.2.1.1.1" class="indexterm"></a>
+        <code class="function">bit_length</code> ( <code class="type">bytea</code> )
+        → <code class="returnvalue">integer</code>
+       </p>
+       <p>
+        Returns number of bits in the binary string (8
+        times the <code class="function">octet_length</code>).
+       </p>
+       <p>
+        <code class="literal">bit_length('\x123456'::bytea)</code>
+        → <code class="returnvalue">24</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.5.2.2.3.1.1.1" class="indexterm"></a>
+        <code class="function">btrim</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+        <em class="parameter"><code>bytesremoved</code></em> <code class="type">bytea</code> )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Removes the longest string containing only bytes appearing in
+        <em class="parameter"><code>bytesremoved</code></em> from the start and end of
+        <em class="parameter"><code>bytes</code></em>.
+       </p>
+       <p>
+        <code class="literal">btrim('\x1234567890'::bytea, '\x9012'::bytea)</code>
+        → <code class="returnvalue">\x345678</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+         <a id="id-1.5.8.11.5.2.2.4.1.1.1" class="indexterm"></a>
+         <code class="function">ltrim</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+         <em class="parameter"><code>bytesremoved</code></em> <code class="type">bytea</code> )
+         → <code class="returnvalue">bytea</code>
+        </p>
+        <p>
+         Removes the longest string containing only bytes appearing in
+         <em class="parameter"><code>bytesremoved</code></em> from the start of
+         <em class="parameter"><code>bytes</code></em>.
+        </p>
+        <p>
+         <code class="literal">ltrim('\x1234567890'::bytea, '\x9012'::bytea)</code>
+         → <code class="returnvalue">\x34567890</code>
+        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.5.2.2.5.1.1.1" class="indexterm"></a>
+        <code class="function">octet_length</code> ( <code class="type">bytea</code> )
+        → <code class="returnvalue">integer</code>
+       </p>
+       <p>
+        Returns number of bytes in the binary string.
+       </p>
+       <p>
+        <code class="literal">octet_length('\x123456'::bytea)</code>
+        → <code class="returnvalue">3</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.5.2.2.6.1.1.1" class="indexterm"></a>
+        <code class="function">overlay</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code> <code class="literal">PLACING</code> <em class="parameter"><code>newsubstring</code></em> <code class="type">bytea</code> <code class="literal">FROM</code> <em class="parameter"><code>start</code></em> <code class="type">integer</code> [<span class="optional"> <code class="literal">FOR</code> <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Replaces the substring of <em class="parameter"><code>bytes</code></em> that starts at
+        the <em class="parameter"><code>start</code></em>'th byte and extends
+        for <em class="parameter"><code>count</code></em> bytes
+        with <em class="parameter"><code>newsubstring</code></em>.
+        If <em class="parameter"><code>count</code></em> is omitted, it defaults to the length
+        of <em class="parameter"><code>newsubstring</code></em>.
+       </p>
+       <p>
+        <code class="literal">overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3)</code>
+        → <code class="returnvalue">\x12020390</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.5.2.2.7.1.1.1" class="indexterm"></a>
+        <code class="function">position</code> ( <em class="parameter"><code>substring</code></em> <code class="type">bytea</code> <code class="literal">IN</code> <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code> )
+        → <code class="returnvalue">integer</code>
+       </p>
+       <p>
+        Returns first starting index of the specified
+        <em class="parameter"><code>substring</code></em> within
+        <em class="parameter"><code>bytes</code></em>, or zero if it's not present.
+       </p>
+       <p>
+        <code class="literal">position('\x5678'::bytea in '\x1234567890'::bytea)</code>
+        → <code class="returnvalue">3</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+         <a id="id-1.5.8.11.5.2.2.8.1.1.1" class="indexterm"></a>
+         <code class="function">rtrim</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+         <em class="parameter"><code>bytesremoved</code></em> <code class="type">bytea</code> )
+         → <code class="returnvalue">bytea</code>
+        </p>
+        <p>
+         Removes the longest string containing only bytes appearing in
+         <em class="parameter"><code>bytesremoved</code></em> from the end of
+         <em class="parameter"><code>bytes</code></em>.
+        </p>
+        <p>
+         <code class="literal">rtrim('\x1234567890'::bytea, '\x9012'::bytea)</code>
+         → <code class="returnvalue">\x12345678</code>
+        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.5.2.2.9.1.1.1" class="indexterm"></a>
+        <code class="function">substring</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code> [<span class="optional"> <code class="literal">FROM</code> <em class="parameter"><code>start</code></em> <code class="type">integer</code> </span>] [<span class="optional"> <code class="literal">FOR</code> <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Extracts the substring of <em class="parameter"><code>bytes</code></em> starting at
+        the <em class="parameter"><code>start</code></em>'th byte if that is specified,
+        and stopping after <em class="parameter"><code>count</code></em> bytes if that is
+        specified.  Provide at least one of <em class="parameter"><code>start</code></em>
+        and <em class="parameter"><code>count</code></em>.
+       </p>
+       <p>
+        <code class="literal">substring('\x1234567890'::bytea from 3 for 2)</code>
+        → <code class="returnvalue">\x5678</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.5.2.2.10.1.1.1" class="indexterm"></a>
+        <code class="function">trim</code> ( [<span class="optional"> <code class="literal">LEADING</code> | <code class="literal">TRAILING</code> | <code class="literal">BOTH</code> </span>]
+        <em class="parameter"><code>bytesremoved</code></em> <code class="type">bytea</code> <code class="literal">FROM</code>
+        <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code> )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Removes the longest string containing only bytes appearing in
+        <em class="parameter"><code>bytesremoved</code></em> from the start,
+        end, or both ends (<code class="literal">BOTH</code> is the default)
+        of <em class="parameter"><code>bytes</code></em>.
+       </p>
+       <p>
+        <code class="literal">trim('\x9012'::bytea from '\x1234567890'::bytea)</code>
+        → <code class="returnvalue">\x345678</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <code class="function">trim</code> ( [<span class="optional"> <code class="literal">LEADING</code> | <code class="literal">TRAILING</code> | <code class="literal">BOTH</code> </span>] [<span class="optional"> <code class="literal">FROM</code> </span>]
+        <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+        <em class="parameter"><code>bytesremoved</code></em> <code class="type">bytea</code> )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        This is a non-standard syntax for <code class="function">trim()</code>.
+       </p>
+       <p>
+        <code class="literal">trim(both from '\x1234567890'::bytea, '\x9012'::bytea)</code>
+        → <code class="returnvalue">\x345678</code>
+       </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+    Additional binary string manipulation functions are available and
+    are listed in <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-OTHER" title="Table 9.12. Other Binary String Functions">Table 9.12</a>.  Some
+    of them are used internally to implement the
+    <acronym class="acronym">SQL</acronym>-standard string functions listed in <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-SQL" title="Table 9.11. SQL Binary String Functions and Operators">Table 9.11</a>.
+   </p><div class="table" id="FUNCTIONS-BINARYSTRING-OTHER"><p class="title"><strong>Table 9.12. Other Binary String Functions</strong></p><div class="table-contents"><table class="table" summary="Other Binary String Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+        Function
+       </p>
+       <p>
+        Description
+       </p>
+       <p>
+        Example(s)
+       </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.1.1.1.1" class="indexterm"></a>
+        <a id="id-1.5.8.11.7.2.2.1.1.1.2" class="indexterm"></a>
+        <code class="function">bit_count</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code> )
+        → <code class="returnvalue">bigint</code>
+       </p>
+       <p>
+        Returns the number of bits set in the binary string (also known as
+        <span class="quote">“<span class="quote">popcount</span>”</span>).
+       </p>
+       <p>
+        <code class="literal">bit_count('\x1234567890'::bytea)</code>
+        → <code class="returnvalue">15</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.2.1.1.1" class="indexterm"></a>
+        <code class="function">get_bit</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+        <em class="parameter"><code>n</code></em> <code class="type">bigint</code> )
+        → <code class="returnvalue">integer</code>
+       </p>
+       <p>
+        Extracts <a class="link" href="functions-binarystring.html#FUNCTIONS-ZEROBASED-NOTE">n'th</a> bit
+        from binary string.
+       </p>
+       <p>
+        <code class="literal">get_bit('\x1234567890'::bytea, 30)</code>
+        → <code class="returnvalue">1</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.3.1.1.1" class="indexterm"></a>
+        <code class="function">get_byte</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+        <em class="parameter"><code>n</code></em> <code class="type">integer</code> )
+        → <code class="returnvalue">integer</code>
+       </p>
+       <p>
+        Extracts <a class="link" href="functions-binarystring.html#FUNCTIONS-ZEROBASED-NOTE">n'th</a> byte
+        from binary string.
+       </p>
+       <p>
+        <code class="literal">get_byte('\x1234567890'::bytea, 4)</code>
+        → <code class="returnvalue">144</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.4.1.1.1" class="indexterm"></a>
+        <a id="id-1.5.8.11.7.2.2.4.1.1.2" class="indexterm"></a>
+        <a id="id-1.5.8.11.7.2.2.4.1.1.3" class="indexterm"></a>
+        <code class="function">length</code> ( <code class="type">bytea</code> )
+        → <code class="returnvalue">integer</code>
+       </p>
+       <p>
+        Returns the number of bytes in the binary string.
+       </p>
+       <p>
+        <code class="literal">length('\x1234567890'::bytea)</code>
+        → <code class="returnvalue">5</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <code class="function">length</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+        <em class="parameter"><code>encoding</code></em> <code class="type">name</code> )
+        → <code class="returnvalue">integer</code>
+       </p>
+       <p>
+        Returns the number of characters in the binary string, assuming
+        that it is text in the given <em class="parameter"><code>encoding</code></em>.
+       </p>
+       <p>
+        <code class="literal">length('jose'::bytea, 'UTF8')</code>
+        → <code class="returnvalue">4</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.6.1.1.1" class="indexterm"></a>
+        <code class="function">md5</code> ( <code class="type">bytea</code> )
+        → <code class="returnvalue">text</code>
+       </p>
+       <p>
+        Computes the MD5 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a> of
+        the binary string, with the result written in hexadecimal.
+       </p>
+       <p>
+        <code class="literal">md5('Th\000omas'::bytea)</code>
+        → <code class="returnvalue">8ab2d3c9689aaf18b4958c334c82d8b1</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.7.1.1.1" class="indexterm"></a>
+        <code class="function">set_bit</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+        <em class="parameter"><code>n</code></em> <code class="type">bigint</code>,
+        <em class="parameter"><code>newvalue</code></em> <code class="type">integer</code> )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Sets <a class="link" href="functions-binarystring.html#FUNCTIONS-ZEROBASED-NOTE">n'th</a> bit in
+        binary string to <em class="parameter"><code>newvalue</code></em>.
+       </p>
+       <p>
+        <code class="literal">set_bit('\x1234567890'::bytea, 30, 0)</code>
+        → <code class="returnvalue">\x1234563890</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.8.1.1.1" class="indexterm"></a>
+        <code class="function">set_byte</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+        <em class="parameter"><code>n</code></em> <code class="type">integer</code>,
+        <em class="parameter"><code>newvalue</code></em> <code class="type">integer</code> )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Sets <a class="link" href="functions-binarystring.html#FUNCTIONS-ZEROBASED-NOTE">n'th</a> byte in
+        binary string to <em class="parameter"><code>newvalue</code></em>.
+       </p>
+       <p>
+        <code class="literal">set_byte('\x1234567890'::bytea, 4, 64)</code>
+        → <code class="returnvalue">\x1234567840</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.9.1.1.1" class="indexterm"></a>
+        <code class="function">sha224</code> ( <code class="type">bytea</code> )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Computes the SHA-224 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a>
+        of the binary string.
+       </p>
+       <p>
+        <code class="literal">sha224('abc'::bytea)</code>
+        → <code class="returnvalue">\x23097d223405d8228642a477bda255b32aadbce4bda0b3f7e36c9da7</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.10.1.1.1" class="indexterm"></a>
+        <code class="function">sha256</code> ( <code class="type">bytea</code> )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Computes the SHA-256 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a>
+        of the binary string.
+       </p>
+       <p>
+        <code class="literal">sha256('abc'::bytea)</code>
+        → <code class="returnvalue">\xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.11.1.1.1" class="indexterm"></a>
+        <code class="function">sha384</code> ( <code class="type">bytea</code> )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Computes the SHA-384 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a>
+        of the binary string.
+       </p>
+       <p>
+        <code class="literal">sha384('abc'::bytea)</code>
+        → <code class="returnvalue">\xcb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.12.1.1.1" class="indexterm"></a>
+        <code class="function">sha512</code> ( <code class="type">bytea</code> )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Computes the SHA-512 <a class="link" href="functions-binarystring.html#FUNCTIONS-HASH-NOTE">hash</a>
+        of the binary string.
+       </p>
+       <p>
+        <code class="literal">sha512('abc'::bytea)</code>
+        → <code class="returnvalue">\xddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f</code>
+       </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+        <a id="id-1.5.8.11.7.2.2.13.1.1.1" class="indexterm"></a>
+        <code class="function">substr</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>, <em class="parameter"><code>start</code></em> <code class="type">integer</code> [<span class="optional">, <em class="parameter"><code>count</code></em> <code class="type">integer</code> </span>] )
+        → <code class="returnvalue">bytea</code>
+       </p>
+       <p>
+        Extracts the substring of <em class="parameter"><code>bytes</code></em> starting at
+        the <em class="parameter"><code>start</code></em>'th byte,
+        and extending for <em class="parameter"><code>count</code></em> bytes if that is
+        specified.  (Same
+        as <code class="literal">substring(<em class="parameter"><code>bytes</code></em>
+        from <em class="parameter"><code>start</code></em>
+        for <em class="parameter"><code>count</code></em>)</code>.)
+       </p>
+       <p>
+        <code class="literal">substr('\x1234567890'::bytea, 3, 2)</code>
+        → <code class="returnvalue">\x5678</code>
+       </p></td></tr></tbody></table></div></div><br class="table-break" /><p id="FUNCTIONS-ZEROBASED-NOTE">
+   Functions <code class="function">get_byte</code> and <code class="function">set_byte</code>
+   number the first byte of a binary string as byte 0.
+   Functions <code class="function">get_bit</code> and <code class="function">set_bit</code>
+   number bits from the right within each byte; for example bit 0 is the least
+   significant bit of the first byte, and bit 15 is the most significant bit
+   of the second byte.
+  </p><p id="FUNCTIONS-HASH-NOTE">
+   For historical reasons, the function <code class="function">md5</code>
+   returns a hex-encoded value of type <code class="type">text</code> whereas the SHA-2
+   functions return type <code class="type">bytea</code>.  Use the functions
+   <a class="link" href="functions-binarystring.html#FUNCTION-ENCODE"><code class="function">encode</code></a>
+   and <a class="link" href="functions-binarystring.html#FUNCTION-DECODE"><code class="function">decode</code></a> to
+   convert between the two.  For example write <code class="literal">encode(sha256('abc'),
+   'hex')</code> to get a hex-encoded text representation,
+   or <code class="literal">decode(md5('abc'), 'hex')</code> to get
+   a <code class="type">bytea</code> value.
+  </p><p>
+   <a id="id-1.5.8.11.10.1" class="indexterm"></a>
+   <a id="id-1.5.8.11.10.2" class="indexterm"></a>
+   Functions for converting strings between different character sets
+   (encodings), and for representing arbitrary binary data in textual
+   form, are shown in
+   <a class="xref" href="functions-binarystring.html#FUNCTIONS-BINARYSTRING-CONVERSIONS" title="Table 9.13. Text/Binary String Conversion Functions">Table 9.13</a>.  For these
+   functions, an argument or result of type <code class="type">text</code> is expressed
+   in the database's default encoding, while arguments or results of
+   type <code class="type">bytea</code> are in an encoding named by another argument.
+  </p><div class="table" id="FUNCTIONS-BINARYSTRING-CONVERSIONS"><p class="title"><strong>Table 9.13. Text/Binary String Conversion Functions</strong></p><div class="table-contents"><table class="table" summary="Text/Binary String Conversion Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
+       Function
+      </p>
+      <p>
+       Description
+      </p>
+      <p>
+       Example(s)
+      </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
+       <a id="id-1.5.8.11.11.2.2.1.1.1.1" class="indexterm"></a>
+       <code class="function">convert</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+       <em class="parameter"><code>src_encoding</code></em> <code class="type">name</code>,
+       <em class="parameter"><code>dest_encoding</code></em> <code class="type">name</code> )
+       → <code class="returnvalue">bytea</code>
+      </p>
+      <p>
+       Converts a binary string representing text in
+       encoding <em class="parameter"><code>src_encoding</code></em>
+       to a binary string in encoding <em class="parameter"><code>dest_encoding</code></em>
+       (see <a class="xref" href="multibyte.html#MULTIBYTE-CONVERSIONS-SUPPORTED" title="24.3.4. Available Character Set Conversions">Section 24.3.4</a> for
+       available conversions).
+      </p>
+      <p>
+       <code class="literal">convert('text_in_utf8', 'UTF8', 'LATIN1')</code>
+       → <code class="returnvalue">\x746578745f696e5f75746638</code>
+      </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+       <a id="id-1.5.8.11.11.2.2.2.1.1.1" class="indexterm"></a>
+       <code class="function">convert_from</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+       <em class="parameter"><code>src_encoding</code></em> <code class="type">name</code> )
+       → <code class="returnvalue">text</code>
+      </p>
+      <p>
+       Converts a binary string representing text in
+       encoding <em class="parameter"><code>src_encoding</code></em>
+       to <code class="type">text</code> in the database encoding
+       (see <a class="xref" href="multibyte.html#MULTIBYTE-CONVERSIONS-SUPPORTED" title="24.3.4. Available Character Set Conversions">Section 24.3.4</a> for
+       available conversions).
+      </p>
+      <p>
+       <code class="literal">convert_from('text_in_utf8', 'UTF8')</code>
+       → <code class="returnvalue">text_in_utf8</code>
+      </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+       <a id="id-1.5.8.11.11.2.2.3.1.1.1" class="indexterm"></a>
+       <code class="function">convert_to</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+       <em class="parameter"><code>dest_encoding</code></em> <code class="type">name</code> )
+       → <code class="returnvalue">bytea</code>
+      </p>
+      <p>
+       Converts a <code class="type">text</code> string (in the database encoding) to a
+       binary string encoded in encoding <em class="parameter"><code>dest_encoding</code></em>
+       (see <a class="xref" href="multibyte.html#MULTIBYTE-CONVERSIONS-SUPPORTED" title="24.3.4. Available Character Set Conversions">Section 24.3.4</a> for
+       available conversions).
+      </p>
+      <p>
+       <code class="literal">convert_to('some_text', 'UTF8')</code>
+       → <code class="returnvalue">\x736f6d655f74657874</code>
+      </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+       <a id="FUNCTION-ENCODE" class="indexterm"></a>
+       <code class="function">encode</code> ( <em class="parameter"><code>bytes</code></em> <code class="type">bytea</code>,
+       <em class="parameter"><code>format</code></em> <code class="type">text</code> )
+       → <code class="returnvalue">text</code>
+      </p>
+      <p>
+       Encodes binary data into a textual representation; supported
+       <em class="parameter"><code>format</code></em> values are:
+       <a class="link" href="functions-binarystring.html#ENCODE-FORMAT-BASE64"><code class="literal">base64</code></a>,
+       <a class="link" href="functions-binarystring.html#ENCODE-FORMAT-ESCAPE"><code class="literal">escape</code></a>,
+       <a class="link" href="functions-binarystring.html#ENCODE-FORMAT-HEX"><code class="literal">hex</code></a>.
+      </p>
+      <p>
+       <code class="literal">encode('123\000\001', 'base64')</code>
+       → <code class="returnvalue">MTIzAAE=</code>
+      </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
+       <a id="FUNCTION-DECODE" class="indexterm"></a>
+       <code class="function">decode</code> ( <em class="parameter"><code>string</code></em> <code class="type">text</code>,
+       <em class="parameter"><code>format</code></em> <code class="type">text</code> )
+       → <code class="returnvalue">bytea</code>
+      </p>
+      <p>
+       Decodes binary data from a textual representation; supported
+       <em class="parameter"><code>format</code></em> values are the same as
+       for <code class="function">encode</code>.
+      </p>
+      <p>
+       <code class="literal">decode('MTIzAAE=', 'base64')</code>
+       → <code class="returnvalue">\x3132330001</code>
+      </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
+   The <code class="function">encode</code> and <code class="function">decode</code>
+   functions support the following textual formats:
+
+   </p><div class="variablelist"><dl class="variablelist"><dt id="ENCODE-FORMAT-BASE64"><span class="term">base64
+     <a id="id-1.5.8.11.12.3.1.1.1" class="indexterm"></a></span> <a href="#ENCODE-FORMAT-BASE64" class="id_link">#</a></dt><dd><p>
+       The <code class="literal">base64</code> format is that
+       of <a class="ulink" href="https://tools.ietf.org/html/rfc2045#section-6.8" target="_top">RFC
+       2045 Section 6.8</a>.  As per the <acronym class="acronym">RFC</acronym>, 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 <code class="function">decode</code> function ignores carriage-return,
+       newline, space, and tab characters.  Otherwise, an error is
+       raised when <code class="function">decode</code> is supplied invalid
+       base64 data — including when trailing padding is incorrect.
+      </p></dd><dt id="ENCODE-FORMAT-ESCAPE"><span class="term">escape
+     <a id="id-1.5.8.11.12.3.2.1.1" class="indexterm"></a></span> <a href="#ENCODE-FORMAT-ESCAPE" class="id_link">#</a></dt><dd><p>
+       The <code class="literal">escape</code> format converts zero bytes and
+       bytes with the high bit set into octal escape sequences
+       (<code class="literal">\</code><em class="replaceable"><code>nnn</code></em>), and it doubles
+       backslashes.  Other byte values are represented literally.
+       The <code class="function">decode</code> function will raise an error if a
+       backslash is not followed by either a second backslash or three
+       octal digits; it accepts other byte values unchanged.
+      </p></dd><dt id="ENCODE-FORMAT-HEX"><span class="term">hex
+     <a id="id-1.5.8.11.12.3.3.1.1" class="indexterm"></a></span> <a href="#ENCODE-FORMAT-HEX" class="id_link">#</a></dt><dd><p>
+       The <code class="literal">hex</code> format represents each 4 bits of
+       data as one hexadecimal digit, <code class="literal">0</code>
+       through <code class="literal">f</code>, writing the higher-order digit of
+       each byte first.  The <code class="function">encode</code> function outputs
+       the <code class="literal">a</code>-<code class="literal">f</code> hex digits in lower
+       case.  Because the smallest unit of data is 8 bits, there are
+       always an even number of characters returned
+       by <code class="function">encode</code>.
+       The <code class="function">decode</code> function
+       accepts the <code class="literal">a</code>-<code class="literal">f</code> characters in
+       either upper or lower case.  An error is raised
+       when <code class="function">decode</code> is given invalid hex data
+       — including when given an odd number of characters.
+      </p></dd></dl></div><p>
+  </p><p>
+   See also the aggregate function <code class="function">string_agg</code> in
+   <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a> and the large object functions
+   in <a class="xref" href="lo-funcs.html" title="35.4. Server-Side Functions">Section 35.4</a>.
+  </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-string.html" title="9.4. String Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-bitstring.html" title="9.6. Bit String Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.4. String Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.6. Bit String Functions and Operators</td></tr></table></div></body></html>
+\ No newline at end of file
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 13:44:03 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 13:44:03 +0000
commit	293913568e6a7a86fd1479e1cff8e2ecb58d6568 (patch)
tree	fc3b469a3ec5ab71b36ea97cc7aaddb838423a0c /doc/src/sgml/html/functions-binarystring.html
parent	Initial commit. (diff)
download	postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.tar.xz postgresql-16-293913568e6a7a86fd1479e1cff8e2ecb58d6568.zip