Hi, Doc patch, against master. Documents encode() and decode() base64 format.
Builds for me. Attached: doc_base64_v1.patch References RFC2045 section 6.8 to define base64. Because encode() and decode() show up in both the string functions section and the binary string functions section I documented in only the string functions section and hyperlinked "base64" in both sections to the new text. Note that XML output can also generate base64 data. I suspect this is done via the (different, src/common/base64.c) pg_b64_encode() function which does not limit line length. In any case this patch does not touch the XML documentation. 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..f6b4b2c5a0 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,20 @@ <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. + </para> + <para> See also the aggregate function <function>string_agg</function> in <xref linkend="functions-aggregate"/>. @@ -3577,13 +3597,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.