Re: [BUGS] BUG #2223: Misleading info in docs on volatility level of - Mailing list pgsql-patches

Jim C. Nasby wrote:
> This was recently discussed on -docs and I believe a patch was applied
> to at least HEAD.

Yep, patch attached.  Any improvements?

---------------------------------------------------------------------------


>
> On Mon, Jan 30, 2006 at 10:33:35AM +0000, dueyduey@freemail.hu wrote:
> >
> > The following bug has been logged online:
> >
> > Bug reference:      2223
> > Logged by:
> > Email address:      dueyduey@freemail.hu
> > PostgreSQL version: 8.1
> > Operating system:   linux
> > Description:        Misleading info in docs on volatility level of functions
> > Details:
> >
> > Hi, all!
> > The documentation on how to and why declare a function STABLE or IMMUTABLE
> > is very laconic. It makes clear what promises I make when determining the
> > volatility of my functions but it fails to point out what exactly I can
> > expect in turn for my promises.
> > See also the discussion on bug#2150 on the pgsql-bugs list.
> > Thanks for bothering.
> >
> > ---------------------------(end of broadcast)---------------------------
> > TIP 9: In versions below 8.0, the planner will ignore your desire to
> >        choose an index scan if your joining column's datatypes do not
> >        match
> >
>
> --
> Jim C. Nasby, Sr. Engineering Consultant      jnasby@pervasive.com
> Pervasive Software      http://pervasive.com    work: 512-231-6117
> vcard: http://jim.nasby.net/pervasive.vcf       cell: 512-569-9461
>
> ---------------------------(end of broadcast)---------------------------
> TIP 6: explain analyze is your friend
>

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073
Index: xfunc.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v
retrieving revision 1.109
retrieving revision 1.110
diff -c -c -r1.109 -r1.110
*** xfunc.sgml    29 Nov 2005 01:46:54 -0000    1.109
--- xfunc.sgml    19 Jan 2006 22:52:08 -0000    1.110
***************
*** 1,5 ****
  <!--
! $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.109 2005/11/29 01:46:54 alvherre Exp $
  -->

   <sect1 id="xfunc">
--- 1,5 ----
  <!--
! $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.110 2006/01/19 22:52:08 momjian Exp $
  -->

   <sect1 id="xfunc">
***************
*** 899,911 ****
       <para>
        A <literal>STABLE</> function cannot modify the database and is
        guaranteed to return the same results given the same arguments
!       for all calls within a single surrounding query.  This category
!       allows the optimizer to optimize away multiple calls of the function
!       within a single query.  In particular, it is safe to use an expression
!       containing such a function in an index scan condition.  (Since an
!       index scan will evaluate the comparison value only once, not once at
!       each row, it is not valid to use a <literal>VOLATILE</> function in
!       an index scan condition.)
       </para>
      </listitem>
      <listitem>
--- 899,911 ----
       <para>
        A <literal>STABLE</> function cannot modify the database and is
        guaranteed to return the same results given the same arguments
!       for all rows within a single statement. This category allows the
!       optimizer to optimize multiple calls of the function to a single
!       call. In particular, it is safe to use an expression containing
!       such a function in an index scan condition. (Since an index scan
!       will evaluate the comparison value only once, not once at each
!       row, it is not valid to use a <literal>VOLATILE</> function in an
!       index scan condition.)
       </para>
      </listitem>
      <listitem>