From 32edf732e8dc9eb3e7a923aeb67d49246744a20a Mon Sep 17 00:00:00 2001
From: Peter Eisentraut
Date: Mon, 2 Jun 2025 08:33:04 +0200
Subject: Rename gist stratnum support function

Commit 7406ab623fe added a gist support function that we internally
refer to by the symbol GIST_STRATNUM_PROC.  This translated from
"well-known" strategy numbers to opfamily-specific strategy numbers.
However, we later (commit 630f9a43cec) changed this to fit into
index-AM-level compare type mapping, so this function actually now
maps from compare type to opfamily-specific strategy numbers.  So this
name is no longer fitting.

Moreover, the index AM level also supports the opposite, a function to
map from strategy number to compare type.  This is currently not
supported in gist, but one might wonder what this function is supposed
to be called when it is added.

This patch changes the naming of the gist-level functionality to be
more in line with the index-AM-level functionality.  This makes sense
because these are essentially the same thing on different levels.
This also changes the names of the externally visible functions that
are provided for use as such a support function.

Reviewed-by: Paul A Jungwirth <pj@illuminatedcomputing.com>
Discussion: https://www.postgresql.org/message-id/37ebb1d9-9036-485f-a215-e55435689917%40eisentraut.org
---
 doc/src/sgml/gist.sgml   | 25 ++++++++++++++++++-------
 doc/src/sgml/xindex.sgml |  2 +-
 2 files changed, 19 insertions(+), 8 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml
index a373a8aa4b2..ee86e170055 100644
--- a/doc/src/sgml/gist.sgml
+++ b/doc/src/sgml/gist.sgml
@@ -1170,7 +1170,7 @@ my_sortsupport(PG_FUNCTION_ARGS)
     </varlistentry>
 
     <varlistentry>
-     <term><function>stratnum</function></term>
+     <term><function>translate_cmptype</function></term>
      <listitem>
       <para>
        Given a <literal>CompareType</literal> value from
@@ -1188,12 +1188,23 @@ my_sortsupport(PG_FUNCTION_ARGS)
        non-<literal>WITHOUT OVERLAPS</literal> part(s) of an index constraint.
       </para>
 
+      <para>
+       This support function corresponds to the index access method callback
+       function <structfield>amtranslatecmptype</structfield> (see <xref
+       linkend="index-functions"/>).  The
+       <structfield>amtranslatecmptype</structfield> callback function for
+       GiST indexes merely calls down to the
+       <function>translate_cmptype</function> support function of the
+       respective operator family, since the GiST index access method has no
+       fixed strategy numbers itself.
+      </para>
+
       <para>
        The <acronym>SQL</acronym> declaration of the function must look like
        this:
 
 <programlisting>
-CREATE OR REPLACE FUNCTION my_stratnum(integer)
+CREATE OR REPLACE FUNCTION my_translate_cmptype(integer)
 RETURNS smallint
 AS 'MODULE_PATHNAME'
 LANGUAGE C STRICT;
@@ -1202,7 +1213,7 @@ LANGUAGE C STRICT;
        And the operator family registration must look like this:
 <programlisting>
 ALTER OPERATOR FAMILY my_opfamily USING gist ADD
-    FUNCTION 12 ("any", "any") my_stratnum(int);
+    FUNCTION 12 ("any", "any") my_translate_cmptype(int);
 </programlisting>
       </para>
 
@@ -1210,10 +1221,10 @@ ALTER OPERATOR FAMILY my_opfamily USING gist ADD
         The matching code in the C module could then follow this skeleton:
 
 <programlisting>
-PG_FUNCTION_INFO_V1(my_stratnum);
+PG_FUNCTION_INFO_V1(my_translate_cmptype);
 
 Datum
-my_stratnum(PG_FUNCTION_ARGS)
+my_translate_cmptype(PG_FUNCTION_ARGS)
 {
     CompareType cmptype = PG_GETARG_INT32(0);
     StrategyNumber ret = InvalidStrategy;
@@ -1232,11 +1243,11 @@ my_stratnum(PG_FUNCTION_ARGS)
       <para>
        One translation function is provided by
        <productname>PostgreSQL</productname>:
-       <literal>gist_stratnum_common</literal> is for operator classes that
+       <literal>gist_translate_cmptype_common</literal> is for operator classes that
        use the <literal>RT*StrategyNumber</literal> constants.
        The <literal>btree_gist</literal>
        extension defines a second translation function,
-       <literal>gist_stratnum_btree</literal>, for operator classes that use
+       <literal>gist_translate_cmptype_btree</literal>, for operator classes that use
        the <literal>BT*StrategyNumber</literal> constants.
       </para>
      </listitem>
diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index 7e23a7b6e43..3d315df2f98 100644
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -598,7 +598,7 @@
        <entry>11</entry>
       </row>
       <row>
-       <entry><function>stratnum</function></entry>
+       <entry><function>translate_cmptype</function></entry>
        <entry>translate compare types to strategy numbers
         used by the operator class (optional)</entry>
        <entry>12</entry>
-- 
cgit v1.2.3