pg_unescape_bytea — Unescape a string returned by an SQL query on a bytea (byte array) column, recovering the original binary string.
pg_unescape_bytea string
pg_unescape_bytea
recovers a binary string from the
escaped data returned by PostgreSQL when
a bytea (byte array) column is queries.
This command returns the original data from a bytea column which was
inserted (for example) after being escaped with
pg_escape_bytea.
(An alternative to escaping and unescaping binary data is to use binary
mode prepared queries. See pg_exec_prepared.)
string
The string to unescape. This should be the result of a query on a bytea column. Other uses are undefined (see notes).
The unescaped binary data string. This is a regular Tcl string, which can contain arbitrary byte values.
This command uses or emulates the PostgreSQL
libpq
function PQunescapeBytea
.
See also pg_escape_bytea.
Note that pg_escape_bytea
and
pg_unescape_bytea
are not inverses of each other.
For example, pg_escape_bytea
turns the byte value
1 into the 5 character sequence \\001
.
pg_unescape_bytea
turns the 4 character
sequence \001
into the byte value 1. This asymmetry
is due to the fact that SQL statements undergo an extra level of parsing
with bytea columns.
The pgin.tcl implementation of this
command is not an accurate emulation of the libpq
function. This was done for performance reasons. Correct results will
always be returned for data that results from a query on a bytea column
(that is, any data output by the byteaout
backend
function). Results are undefined for other uses. For example, give the
two byte sequence \a (which will never be output by PostgreSQL for a bytea
column), PQunescapeBytea
will return the single
character 'a', but pg_unescape_bytea
will return the
byte value 7 (because Tcl unescapes \a to ASCII bell).
This command was added in pgtclng-1.5.2 and in pgintcl-2.2.0.
See Section 5.10, “Example - Bytea Escaping - Picture Viewer, Part 2 - View Pictures” for an example.