Patch applied. Thanks.
---------------------------------------------------------------------------
> Here's my first attempt at a documentation patch :-)
>
> I've created a new section to func.sgml, "Binary String Functions and
> Operators", plagiarized shamelessly from the "String Functions and
> Operators" section. There were enough differences that it made sense (at
> least to me) to give this its own section instead of cramming it in with
> normal string functions. This way I could also make the examples
> relevant, which is particularly important for bytea.
>
> One thing I think worth mentioning: while documenting the trim()
> function I realized that I never implemented the bytea equivalent of
> rtrim and ltrim. Therefore, the 'leading' and 'trailing' forms of trim,
> available with text, are not available with bytea (I'd be happy to
> correct this, but since it would require an initdb, I guess not until
> 7.3) -- the submitted doc accurately reflects this.
>
> I will look for other areas of the docs that need mention of bytea, but
> any guidance would be much appreciated.
>
>
> regards,
>
> -- Joe
[ text/html is unsupported, treating like TEXT/PLAIN ]
> *** sgml.orig/func.sgml Mon Nov 19 01:05:01 2001
> --- sgml/func.sgml Mon Nov 19 20:00:36 2001
> ***************
> *** 1133,1139 ****
> <entry><type>text</type></entry>
> <entry>
> Encodes binary data to <acronym>ASCII</acronym>-only representation. Supported
> ! types are: 'base64', 'hex'.
> </entry>
> <entry><literal>encode('123\\000\\001', 'base64')</literal></entry>
> <entry><literal>MTIzAAE=</literal></entry>
> --- 1133,1139 ----
> <entry><type>text</type></entry>
> <entry>
> Encodes binary data to <acronym>ASCII</acronym>-only representation. Supported
> ! types are: 'base64', 'hex', 'escape'.
> </entry>
> <entry><literal>encode('123\\000\\001', 'base64')</literal></entry>
> <entry><literal>MTIzAAE=</literal></entry>
> ***************
> *** 1164,1169 ****
> --- 1164,1349 ----
> </sect1>
>
>
> + <sect1 id="functions-binarystring">
> + <title>Binary String Functions and Operators</title>
> +
> + <para>
> + This section describes functions and operators for examining and
> + manipulating binary string values. Strings in this context include
> + values of the type <type>BYTEA</type>.
> + </para>
> +
> + <para>
> + <acronym>SQL</acronym> defines some string functions with a special syntax where
> + certain keywords rather than commas are used to separate the
> + arguments. Details are in <xref linkend="functions-binarystring-sql">.
> + Some functions are also implemented using the regular syntax for
> + function invocation. (See <xref linkend="functions-binarystring-other">.)
> + </para>
> +
> + <table id="functions-binarystring-sql">
> + <title><acronym>SQL</acronym> Binary String Functions and Operators</title>
> + <tgroup cols="5">
> + <thead>
> + <row>
> + <entry>Function</entry>
> + <entry>Return Type</entry>
> + <entry>Description</entry>
> + <entry>Example</entry>
> + <entry>Result</entry>
> + </row>
> + </thead>
> +
> + <tbody>
> + <row>
> + <entry> <parameter>string</parameter> <literal>||</literal> <parameter>string</parameter> </entry>
> + <entry> <type>bytea</type> </entry>
> + <entry>
> + string concatenation
> + <indexterm>
> + <primary>binary strings</primary>
> + <secondary>concatenation</secondary>
> + </indexterm>
> + </entry>
> + <entry><literal>'\\\\Postgre'::bytea || '\\047SQL\\000'::bytea</></entry>
> + <entry><literal>\\Postgre'SQL\000</></entry>
> + </row>
> +
> + <row>
> + <entry><function>octet_length</function>(<parameter>string</parameter>)</entry>
> + <entry><type>integer</type></entry>
> + <entry>number of bytes in binary string</entry>
> + <entry><literal>octet_length('jo\\000se'::bytea)</literal></entry>
> + <entry><literal>5</literal></entry>
> + </row>
> +
> + <row>
> + <entry><function>position</function>(<parameter>substring</parameter> in
<parameter>string</parameter>)</entry>
> + <entry><type>integer</type></entry>
> + <entry>location of specified substring</entry>
> + <entry><literal>position('\\000om'::bytea in 'Th\\000omas'::bytea)</literal></entry>
> + <entry><literal>3</literal></entry>
> + </row>
> +
> + <row>
> + <entry><function>substring</function>(<parameter>string</parameter> <optional>from
<type>integer</type></optional><optional>for <type>integer</type></optional>)</entry>
> + <entry><type>bytea</type></entry>
> + <entry>
> + extract substring
> + <indexterm>
> + <primary>substring</primary>
> + </indexterm>
> + </entry>
> + <entry><literal>substring('Th\\000omas'::bytea from 2 for 3)</literal></entry>
> + <entry><literal>h\000o</literal></entry>
> + </row>
> +
> + <row>
> + <entry>
> + <function>trim</function>(<optional>both</optional>
> + <parameter>characters</parameter> from
> + <parameter>string</parameter>)
> + </entry>
> + <entry><type>bytea</type></entry>
> + <entry>
> + Removes the longest string containing only the
> + <parameter>characters</parameter> from the
> + beginning/end/both ends of the <parameter>string</parameter>.
> + </entry>
> + <entry><literal>trim('\\000'::bytea from '\\000Tom\\000'::bytea)</literal></entry>
> + <entry><literal>Tom</literal></entry>
> + </row>
> +
> + </tbody>
> + </tgroup>
> + </table>
> +
> + <para>
> + Additional binary string manipulation functions are available and are
> + listed below. Some of them are used internally to implement the
> + <acronym>SQL</acronym>-standard string functions listed above.
> + </para>
> +
> + <table id="functions-binarystring-other">
> + <title>Other Binary String Functions</title>
> + <tgroup cols="5">
> + <thead>
> + <row>
> + <entry>Function</entry>
> + <entry>Return Type</entry>
> + <entry>Description</entry>
> + <entry>Example</entry>
> + <entry>Result</entry>
> + </row>
> + </thead>
> +
> + <tbody>
> + <row>
> + <entry><function>btrim</function>(<parameter>string</parameter> <type>bytea</type>,
<parameter>trim</parameter><type>bytea</type>)</entry>
> + <entry><type>bytea</type></entry>
> + <entry>
> + Remove (trim) the longest string consisting only of characters
> + in <parameter>trim</parameter> from the start and end of
> + <parameter>string</parameter>.
> + </entry>
> + <entry><literal>btrim('\\000trim\\000'::bytea,'\\000'::bytea)</literal></entry>
> + <entry><literal>trim</literal></entry>
> + </row>
> +
> + <row>
> + <entry><function>length</function>(<parameter>string</parameter>)</entry>
> + <entry><type>integer</type></entry>
> + <entry>
> + length of binary string
> + <indexterm>
> + <primary>binary strings</primary>
> + <secondary>length</secondary>
> + </indexterm>
> + <indexterm>
> + <primary>length</primary>
> + <secondary>binary strings</secondary>
> + <see>binary strings, length</see>
> + </indexterm>
> + </entry>
> + <entry><literal>length('jo\\000se'::bytea)</></entry>
> + <entry><literal>5</></entry>
> + </row>
> +
> + <row>
> + <entry>
> + <function>encode</function>(<parameter>string</parameter> <type>bytea</type>,
> + <parameter>type</parameter> <type>text</type>)
> + </entry>
> + <entry><type>text</type></entry>
> + <entry>
> + Encodes binary string to <acronym>ASCII</acronym>-only representation. Supported
> + types are: 'base64', 'hex', 'escape'.
> + </entry>
> + <entry><literal>encode('123\\000456'::bytea, 'escape')</literal></entry>
> + <entry><literal>123\000456</literal></entry>
> + </row>
> +
> + <row>
> + <entry>
> + <function>decode</function>(<parameter>string</parameter> <type>text</type>,
> + <parameter>type</parameter> <type>text</type>)
> + </entry>
> + <entry><type>bytea</type></entry>
> + <entry>
> + Decodes binary string from <parameter>string</parameter> previously
> + encoded with encode(). Parameter type is same as in encode().
> + </entry>
> + <entry><literal>decode('123\\000456', 'escape')</literal></entry>
> + <entry><literal>123\000456</literal></entry>
> + </row>
> +
> + </tbody>
> + </tgroup>
> + </table>
> +
> + </sect1>
> +
> +
> <sect1 id="functions-matching">
> <title>Pattern Matching</title>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 2: you can get off all lists at once with the unregister command
> (send "unregister YourEmailAddressHere" to majordomo@postgresql.org)
--
Bruce Momjian | http://candle.pha.pa.us
pgman@candle.pha.pa.us | (610) 853-3000
+ If your life is a hard drive, | 830 Blythe Avenue
+ Christ can be your backup. | Drexel Hill, Pennsylvania 19026
