Thread: Nit: "Immutable" should be "pure"

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.

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 +

Bruce Momjian <bruce@momjian.us> writes:
> On Thu, Nov  7, 2019 at 02:17:58PM +0000, PG Doc comments form wrote:
>> 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".

> 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.

Yeah.  I don't think this terminology is nearly as universal
as the OP believes, so I don't feel a need to change anything.

If we adopt Corey's proposal to create a glossary [1], there'd be
room for a parenthetical comment like "(In some circles, "pure" is the
preferred term for this function property.)" in the glossary entry for
"immutable".  I suspect it won't be the only entry that needs
cross-references to other terminology.

            regards, tom lane

[1] https://commitfest.postgresql.org/25/2305/

Thanks for the feedback folks. I had not seen the IMMUTABLE argument to CREATE FUNCTION and realize this change is too
expensive.

This probably will not be the last you hear on this since pureness and immutability are all the rage in development
circles.   

> On Nov 7, 2019, at 12:38 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Bruce Momjian <bruce@momjian.us> writes:
>> On Thu, Nov  7, 2019 at 02:17:58PM +0000, PG Doc comments form wrote:
>>> 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".
>
>> 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.
>
> Yeah.  I don't think this terminology is nearly as universal
> as the OP believes, so I don't feel a need to change anything.
>
> If we adopt Corey's proposal to create a glossary [1], there'd be
> room for a parenthetical comment like "(In some circles, "pure" is the
> preferred term for this function property.)" in the glossary entry for
> "immutable".  I suspect it won't be the only entry that needs
> cross-references to other terminology.
>
>             regards, tom lane
>
> [1] https://commitfest.postgresql.org/25/2305/