Hi Fabien,
On Tue, 5 Mar 2019 07:09:01 +0100 (CET)
Fabien COELHO <coe...@cri.ensmp.fr> wrote:
> > Doc patch, against master. Documents encode() and decode() base64
> > format.
>
> It is already documented. Enhance documentation, though.
Right. I was thinking that there are various implementations
of the base64 data format and so it needed more than
just to be named.
> > Attached: doc_base64_v1.patch
> >
> > References RFC2045 section 6.8 to define base64.
>
> Did you consider referencing RFC 4648 instead?
Not really. What drew me to document was the line
breaks every 76 characters. So I pretty much went
straight to the MIME RFC which says there should
be breaks at 76 characters.
I can see advantages and disadvantages either way.
More or less extraneous information either semi
or not base64 related in either RFC.
Which RFC do you think should be referenced?
Attached: doc_base64_v2.patch
This new version adds a phrase clarifying that
decode errors are raised when trailing padding
is wrong. Seemed like I may as well be explicit.
(I am not entirely pleased with the double dash
but can't come up with anything better. And
can't make an emdash entity work either.)
Thanks for taking a look.
Regards,
Karl <k...@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6765b0d584..95b8f5cd5a 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1752,6 +1752,9 @@
<indexterm>
<primary>decode</primary>
</indexterm>
+ <indexterm>
+ <primary>base64</primary>
+ </indexterm>
<literal><function>decode(<parameter>string</parameter> <type>text</type>,
<parameter>format</parameter> <type>text</type>)</function></literal>
</entry>
@@ -1769,13 +1772,16 @@
<indexterm>
<primary>encode</primary>
</indexterm>
+ <indexterm>
+ <primary>base64</primary>
+ </indexterm>
<literal><function>encode(<parameter>data</parameter> <type>bytea</type>,
<parameter>format</parameter> <type>text</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Encode binary data into a textual representation. Supported
- formats are: <literal>base64</literal>, <literal>hex</literal>, <literal>escape</literal>.
+ formats are: <link linkend="base64-encoding"><literal>base64</literal></link>, <literal>hex</literal>, <literal>escape</literal>.
<literal>escape</literal> converts zero bytes and high-bit-set bytes to
octal sequences (<literal>\</literal><replaceable>nnn</replaceable>) and
doubles backslashes.
@@ -2365,6 +2371,21 @@
<function>format</function> treats a NULL as a zero-element array.
</para>
+ <indexterm>
+ <primary>base64</primary>
+ </indexterm>
+
+ <para id="base64-encoding">
+ The base64 encoding of the <function>encode</function>
+ and <function>decode</function> functions is that of RFC2045 section 6.8.
+ As per the RFC, 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 carriage-return, newline, space, and tab characters are
+ ignored by <function>decode</function>. Otherwise, an error is raised
+ when <function>decode</function> is supplied invalid base64 data --
+ including when trailing padding is incorrect.
+ </para>
+
<para>
See also the aggregate function <function>string_agg</function> in
<xref linkend="functions-aggregate"/>.
@@ -3577,13 +3598,16 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
<indexterm>
<primary>encode</primary>
</indexterm>
+ <indexterm>
+ <primary>base64</primary>
+ </indexterm>
<literal><function>encode(<parameter>data</parameter> <type>bytea</type>,
<parameter>format</parameter> <type>text</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Encode binary data into a textual representation. Supported
- formats are: <literal>base64</literal>, <literal>hex</literal>, <literal>escape</literal>.
+ formats are: <link linkend="base64-encoding"><literal>base64</literal></link>, <literal>hex</literal>, <literal>escape</literal>.
<literal>escape</literal> converts zero bytes and high-bit-set bytes to
octal sequences (<literal>\</literal><replaceable>nnn</replaceable>) and
doubles backslashes.
