Skip site navigation (1) Skip section navigation (2)

Re: bytea functions documentation

From: Bruce Momjian <pgman(at)candle(dot)pha(dot)pa(dot)us>
To: Joe Conway <joseph(dot)conway(at)home(dot)com>
Cc: "pgsql-patches(at)postgresql(dot)org" <pgsql-patches(at)postgresql(dot)org>
Subject: Re: bytea functions documentation
Date: 2001-11-20 15:42:33
Message-ID: 200111201542.fAKFgXr09234@candle.pha.pa.us (view raw or flat)
Thread:
Lists: 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(at)postgresql(dot)org)

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman(at)candle(dot)pha(dot)pa(dot)us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

In response to

pgsql-patches by date

Next:From: Bruce MomjianDate: 2001-11-20 15:42:41
Subject: Re: bytea datatype documentation patch
Previous:From: Marko KreenDate: 2001-11-20 15:25:14
Subject: fix pgcrypto usage of uint

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group