Date: Thu, 7 Nov 2019 12:28:30 -0500
From: Bruce Momjian <bruce@momjian.us>
To: brian.williams@mayalane.com, pgsql-docs@lists.postgresql.org
Subject: Re: Nit: "Immutable" should be "pure"
Message-ID: <20191107172830.GD12478@momjian.us>
References: <157313627814.14272.6307248648194149757@wrigleys.postgresql.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <157313627814.14272.6307248648194149757@wrigleys.postgresql.org>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk

On Thu, Nov  7, 2019 at 02:17:58PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/12/sql-createindex.html
> Description:
> 
> The adjective "immutable" describing the functions and operators used in an
> index (see two occurrences in doc snippet below) is incorrect and should be
> replaced with "pure". Both "pure" and "immutable" are in popular lexicon now
> because of the interest in functional programming, so conflating the two can
> happen, but the word immutable applies to data and pure applies to
> functions. See https://en.wikipedia.org/wiki/Pure_function. 
> 
> From the CREATE INDEX doc:
> All functions and operators used in an index definition must be “immutable”,
> that is, their results must depend only on their arguments and never on any
> outside influence (such as the contents of another table or the current
> time). This restriction ensures that the behavior of the index is
> well-defined. To use a user-defined function in an index expression or WHERE
> clause, remember to mark the function immutable when you create it.

Well, we use IMMUTABLE as an option to CREATE FUNCTION so I don't see
how we can realign to the new word meanings without a lot of confusion:

       CREATE [ OR REPLACE ] FUNCTION
           name ( [ [ argmode ] [ argname ] argtype [ { DEFAULT | = } default_expr ] [, ...] ] )
           [ RETURNS rettype
             | RETURNS TABLE ( column_name column_type [, ...] ) ]
         { LANGUAGE lang_name
           | TRANSFORM { FOR TYPE type_name } [, ... ]
           | WINDOW
           | IMMUTABLE | STABLE | VOLATILE | [ NOT ] LEAKPROOF
             ^^^^^^^^^

I think the best we can do is to mention that IMMUTABLE functions mean
pure, but I am not sure there is even enough demand for that, vs.
confusing people.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +