diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index af7864a1b5b..9f22dacac7d 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -2384,6 +2384,56 @@ PG_FUNCTION_INFO_V1(funcname);
takes as its argument the actual value to return.
+
+ To call another version-1 function, you can use
+ DirectFunctionCalln(func,
+ arg1, ..., argn). This is particularly useful when you want
+ to call functions defined in the standard internal library, by using an
+ interface similar to their SQL signature.
+
+
+
+ These convenience functions and similar ones can be found
+ in fmgr.h.
+ The DirectFunctionCalln
+ family expect a C function name as their first argument. There are also
+ OidFunctionCalln which
+ take the OID of the target function, and some other variants. All of
+ these expect the function's arguments to be supplied
+ as Datums, and likewise they return Datum.
+ Note that neither arguments nor result are allowed to be NULL when
+ using these convenience functions.
+
+
+
+ For example, to call the starts_with(text, text)
+ function from C, you can search through the catalog and find out that
+ its C implementation is the
+ Datum text_starts_with(PG_FUNCTION_ARGS)
+ function. Typically you would
+ use DirectFunctionCall2(text_starts_with, ...) to
+ call such a function. However, starts_with(text,
+ text) requires collation information, so it will fail
+ with could not determine which collation to use for string
+ comparison
if called that way. Instead you must
+ use DirectFunctionCall2Coll(text_starts_with, ...)
+ and provide the desired collation, which typically is just passed
+ through from PG_GET_COLLATION(), as shown in the
+ example below.
+
+
+
+ fmgr.h also supplies macros that facilitate
+ conversions between C types and Datum. For example to
+ turn Datum into text*, you can
+ use DatumGetTextPP(X). While some types have macros
+ named like TypeGetDatum(X) for the reverse
+ conversion, text* does not; it's sufficient to use the
+ generic macro PointerGetDatum(X) for that.
+ If your extension defines additional types, it is usually convenient to
+ define similar macros for your types too.
+
+
Here are some examples using the version-1 calling convention:
@@ -2482,6 +2532,25 @@ concat_text(PG_FUNCTION_ARGS)
memcpy(VARDATA(new_text) + arg1_size, VARDATA_ANY(arg2), arg2_size);
PG_RETURN_TEXT_P(new_text);
}
+
+/* A wrapper around starts_with(text, text) */
+
+PG_FUNCTION_INFO_V1(t_starts_with);
+
+Datum
+t_starts_with(PG_FUNCTION_ARGS)
+{
+ text *t1 = PG_GETARG_TEXT_PP(0);
+ text *t2 = PG_GETARG_TEXT_PP(1);
+ Oid collid = PG_GET_COLLATION();
+ bool result;
+
+ result = DatumGetBool(DirectFunctionCall2Coll(text_starts_with,
+ collid,
+ PointerGetDatum(t1),
+ PointerGetDatum(t2)));
+ PG_RETURN_BOOL(result);
+}
]]>
@@ -2513,6 +2582,10 @@ CREATE FUNCTION copytext(text) RETURNS text
CREATE FUNCTION concat_text(text, text) RETURNS text
AS 'DIRECTORY/funcs', 'concat_text'
LANGUAGE C STRICT;
+
+CREATE FUNCTION t_starts_with(text, text) RETURNS boolean
+ AS 'DIRECTORY/funcs', 't_starts_with'
+ LANGUAGE C STRICT;
diff --git a/src/tutorial/funcs.c b/src/tutorial/funcs.c
index f597777a1ff..4a61177567c 100644
--- a/src/tutorial/funcs.c
+++ b/src/tutorial/funcs.c
@@ -11,6 +11,7 @@
#include "postgres.h" /* general Postgres declarations */
#include "executor/executor.h" /* for GetAttributeByName() */
+#include "utils/fmgrprotos.h" /* for text_starts_with() */
#include "utils/geo_decls.h" /* for point type */
PG_MODULE_MAGIC;
@@ -102,6 +103,25 @@ concat_text(PG_FUNCTION_ARGS)
PG_RETURN_TEXT_P(new_text);
}
+/* A wrapper around starts_with(text, text) */
+
+PG_FUNCTION_INFO_V1(t_starts_with);
+
+Datum
+t_starts_with(PG_FUNCTION_ARGS)
+{
+ text *t1 = PG_GETARG_TEXT_PP(0);
+ text *t2 = PG_GETARG_TEXT_PP(1);
+ Oid collid = PG_GET_COLLATION();
+ bool result;
+
+ result = DatumGetBool(DirectFunctionCall2Coll(text_starts_with,
+ collid,
+ PointerGetDatum(t1),
+ PointerGetDatum(t2)));
+ PG_RETURN_BOOL(result);
+}
+
/* Composite types */
PG_FUNCTION_INFO_V1(c_overpaid);
diff --git a/src/tutorial/funcs.source b/src/tutorial/funcs.source
index 542b5c81ec9..eb561537542 100644
--- a/src/tutorial/funcs.source
+++ b/src/tutorial/funcs.source
@@ -123,16 +123,25 @@ SELECT * FROM EMP;
-----------------------------
CREATE FUNCTION add_one(integer) RETURNS integer
- AS '_OBJWD_/funcs' LANGUAGE C;
+ AS '_OBJWD_/funcs' LANGUAGE C STRICT;
+
+CREATE FUNCTION add_one(double precision) RETURNS double precision
+ AS '_OBJWD_/funcs' LANGUAGE C STRICT;
CREATE FUNCTION makepoint(point, point) RETURNS point
- AS '_OBJWD_/funcs' LANGUAGE C;
+ AS '_OBJWD_/funcs' LANGUAGE C STRICT;
CREATE FUNCTION copytext(text) RETURNS text
- AS '_OBJWD_/funcs' LANGUAGE C;
+ AS '_OBJWD_/funcs' LANGUAGE C STRICT;
+
+CREATE FUNCTION concat_text(text, text) RETURNS text
+ AS '_OBJWD_/funcs' LANGUAGE C STRICT;
+
+CREATE FUNCTION t_starts_with(text, text) RETURNS boolean
+ AS '_OBJWD_/funcs' LANGUAGE C STRICT;
CREATE FUNCTION c_overpaid(EMP, integer) RETURNS boolean
- AS '_OBJWD_/funcs' LANGUAGE C;
+ AS '_OBJWD_/funcs' LANGUAGE C STRICT;
SELECT add_one(3) AS four;
@@ -140,6 +149,8 @@ SELECT makepoint('(1,2)'::point, '(3,4)'::point ) AS newpoint;
SELECT copytext('hello world!');
+SELECT t_starts_with('foobar', 'foo');
+
SELECT name, c_overpaid(EMP, 1500) AS overpaid
FROM EMP
WHERE name = 'Bill' or name = 'Sam';
@@ -147,10 +158,13 @@ WHERE name = 'Bill' or name = 'Sam';
-- remove functions that were created in this file
DROP FUNCTION c_overpaid(EMP, integer);
+DROP FUNCTION t_starts_with(text, text);
+DROP FUNCTION concat_text(text, text);
DROP FUNCTION copytext(text);
DROP FUNCTION makepoint(point, point);
+DROP FUNCTION add_one(double precision);
DROP FUNCTION add_one(integer);
---DROP FUNCTION clean_EMP();
+DROP FUNCTION clean_EMP();
DROP FUNCTION high_pay();
DROP FUNCTION new_emp();
DROP FUNCTION add_em(integer, integer);