????
Your IP : 3.148.252.155
<?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.3 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://datatracker.ietf.org/doc/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.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.6. Bit String Functions and Operators</td></tr></table></div></body></html>