Re: bytea functions documentation - Mailing list pgsql-patches

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