Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 717fa27

Browse files
tglsfdctglsfdc
committed
Support use of function argument names to identify which actual arguments
match which function parameters. The syntax uses AS, for example funcname(value AS arg1, anothervalue AS arg2) Pavel Stehule
1 parent 2eda8df commit 717fa27

34 files changed

+1925
-274
lines changed

‎doc/src/sgml/ref/create_function.sgml

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.87 2009/10/02 18:13:04 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.88 2009/10/08 02:39:14 tgl Exp $
33
-->
44

55
<refentry id="SQL-CREATEFUNCTION">
@@ -65,7 +65,7 @@ CREATE [ OR REPLACE ] FUNCTION
6565
Also, <command>CREATE OR REPLACE FUNCTION</command> will not let
6666
you change the return type of an existing function. To do that,
6767
you must drop and recreate the function. (When using <literal>OUT</>
68-
parameters, that means you cannot change the names or types of any
68+
parameters, that means you cannot change the types of any
6969
<literal>OUT</> parameters except by dropping the function.)
7070
</para>
7171

@@ -121,8 +121,11 @@ CREATE [ OR REPLACE ] FUNCTION
121121
<para>
122122
The name of an argument. Some languages (currently only PL/pgSQL) let
123123
you use the name in the function body. For other languages the
124-
name of an input argument is just extra documentation. But the name
125-
of an output argument is significant, since it defines the column
124+
name of an input argument is just extra documentation, so far as
125+
the function itself is concerned; but you can use input argument names
126+
when calling a function to improve readability (see <xref
127+
linkend="sql-syntax-calling-funcs">). In any case, the name
128+
of an output argument is significant, because it defines the column
126129
name in the result row type. (If you omit the name for an output
127130
argument, the system will choose a default column name.)
128131
</para>
@@ -570,6 +573,18 @@ CREATE FUNCTION foo(int, int default 42) ...
570573
to replace it (this includes being a member of the owning role).
571574
</para>
572575

576+
<para>
577+
When replacing an existing function with <command>CREATE OR REPLACE
578+
FUNCTION</>, there are restrictions on changing parameter names.
579+
You cannot change the name already assigned to any input parameter
580+
(although you can add names to parameters that had none before).
581+
If there is more than one output parameter, you cannot change the
582+
names of the output parameters, because that would change the
583+
column names of the anonymous composite type that describes the
584+
function's result. These restrictions are made to ensure that
585+
existing calls of the function do not stop working when it is replaced.
586+
</para>
587+
573588
</refsect1>
574589

575590
<refsect1 id="sql-createfunction-examples">

‎doc/src/sgml/sources.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/sources.sgml,v 2.34 2009/06/04 18:33:06 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/sources.sgml,v 2.35 2009/10/08 02:39:16 tgl Exp $ -->
22

33
<chapter id="source">
44
<title>PostgreSQL Coding Conventions</title>
@@ -125,7 +125,7 @@ ereport(ERROR,
125125
(errcode(ERRCODE_AMBIGUOUS_FUNCTION),
126126
errmsg("function %s is not unique",
127127
func_signature_string(funcname, nargs,
128-
actual_arg_types)),
128+
NIL, actual_arg_types)),
129129
errhint("Unable to choose a best candidate function. "
130130
"You might need to add explicit typecasts.")));
131131
</programlisting>

‎doc/src/sgml/syntax.sgml

Lines changed: 170 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.136 2009/09/22 23:52:53 petere Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.137 2009/10/08 02:39:16 tgl Exp $ -->
22

33
<chapter id="sql-syntax">
44
<title>SQL Syntax</title>
@@ -1505,6 +1505,11 @@ sqrt(2)
15051505
The list of built-in functions is in <xref linkend="functions">.
15061506
Other functions can be added by the user.
15071507
</para>
1508+
1509+
<para>
1510+
The arguments can optionally have names attached.
1511+
See <xref linkend="sql-syntax-calling-funcs"> for details.
1512+
</para>
15081513
</sect2>
15091514

15101515
<sect2 id="syntax-aggregates">
@@ -2123,4 +2128,168 @@ SELECT ... WHERE CASE WHEN x &gt; 0 THEN y/x &gt; 1.5 ELSE false END;
21232128
</sect2>
21242129
</sect1>
21252130

2131+
<sect1 id="sql-syntax-calling-funcs">
2132+
<title>Calling Functions</title>
2133+
2134+
<indexterm zone="sql-syntax-calling-funcs">
2135+
<primary>notation</primary>
2136+
<secondary>functions</secondary>
2137+
</indexterm>
2138+
2139+
<para>
2140+
<productname>PostgreSQL</productname> allows functions that have named
2141+
parameters to be called using either <firstterm>positional</firstterm> or
2142+
<firstterm>named</firstterm> notation. Named notation is especially
2143+
useful for functions that have a large number of parameters, since it
2144+
makes the associations between parameters and actual arguments more
2145+
explicit and reliable.
2146+
In positional notation, a function call is written with
2147+
its argument values in the same order as they are defined in the function
2148+
declaration. In named notation, the arguments are matched to the
2149+
function parameters by name and can be written in any order.
2150+
</para>
2151+
2152+
<para>
2153+
In either notation, parameters that have default values given in the
2154+
function declaration need not be written in the call at all. But this
2155+
is particularly useful in named notation, since any combination of
2156+
parameters can be omitted; while in positional notation parameters can
2157+
only be omitted from right to left.
2158+
</para>
2159+
2160+
<para>
2161+
<productname>PostgreSQL</productname> also supports
2162+
<firstterm>mixed</firstterm> notation, which combines positional and
2163+
named notation. In this case, positional parameters are written first
2164+
and named parameters appear after them.
2165+
</para>
2166+
2167+
<para>
2168+
The following examples will illustrate the usage of all three
2169+
notations, using the following function definition:
2170+
<programlisting>
2171+
CREATE FUNCTION concat_lower_or_upper(a text, b text, uppercase boolean DEFAULT false)
2172+
RETURNS text
2173+
AS
2174+
$$
2175+
SELECT CASE
2176+
WHEN $3 THEN UPPER($1 || ' ' || $2)
2177+
ELSE LOWER($1 || ' ' || $2)
2178+
END;
2179+
$$
2180+
LANGUAGE SQL IMMUTABLE STRICT;
2181+
</programlisting>
2182+
Function <function>concat_lower_or_upper</function> has two mandatory
2183+
parameters, <literal>a</literal> and <literal>b</literal>. Additionally
2184+
there is one optional parameter <literal>uppercase</literal> which defaults
2185+
to <literal>false</literal>. The <literal>a</literal> and
2186+
<literal>b</literal> inputs will be concatenated, and forced to either
2187+
upper or lower case depending on the <literal>uppercase</literal>
2188+
parameter. The remaining details of this function
2189+
definition are not important here (see <xref linkend="extend"> for
2190+
more information).
2191+
</para>
2192+
2193+
<sect2 id="sql-syntax-calling-funcs-positional">
2194+
<title>Using positional notation</title>
2195+
2196+
<indexterm>
2197+
<primary>function</primary>
2198+
<secondary>positional notation</secondary>
2199+
</indexterm>
2200+
2201+
<para>
2202+
Positional notation is the traditional mechanism for passing arguments
2203+
to functions in <productname>PostgreSQL</productname>. An example is:
2204+
<screen>
2205+
SELECT concat_lower_or_upper('Hello', 'World', true);
2206+
concat_lower_or_upper
2207+
-----------------------
2208+
HELLO WORLD
2209+
(1 row)
2210+
</screen>
2211+
All arguments are specified in order. The result is upper case since
2212+
<literal>uppercase</literal> is specified as <literal>true</literal>.
2213+
Another example is:
2214+
<screen>
2215+
SELECT concat_lower_or_upper('Hello', 'World');
2216+
concat_lower_or_upper
2217+
-----------------------
2218+
hello world
2219+
(1 row)
2220+
</screen>
2221+
Here, the <literal>uppercase</literal> parameter is omitted, so it
2222+
receives its default value of <literal>false</literal>, resulting in
2223+
lower case output. In positional notation, arguments can be omitted
2224+
from right to left so long as they have defaults.
2225+
</para>
2226+
</sect2>
2227+
2228+
<sect2 id="sql-syntax-calling-funcs-named">
2229+
<title>Using named notation</title>
2230+
2231+
<indexterm>
2232+
<primary>function</primary>
2233+
<secondary>named notation</secondary>
2234+
</indexterm>
2235+
2236+
<para>
2237+
In named notation, each argument's name is specified using the
2238+
<literal>AS</literal> keyword. For example:
2239+
<screen>
2240+
SELECT concat_lower_or_upper('Hello' AS a, 'World' AS b);
2241+
concat_lower_or_upper
2242+
-----------------------
2243+
hello world
2244+
(1 row)
2245+
</screen>
2246+
Again, the argument <literal>uppercase</literal> was omitted
2247+
so it is set to <literal>false</literal> implicitly. One advantage of
2248+
using named notation is that the arguments may be specified in any
2249+
order, for example:
2250+
<screen>
2251+
SELECT concat_lower_or_upper('Hello' AS a, 'World' AS b, true AS uppercase);
2252+
concat_lower_or_upper
2253+
-----------------------
2254+
HELLO WORLD
2255+
(1 row)
2256+
2257+
SELECT concat_lower_or_upper('Hello' AS a, true AS uppercase, 'World' AS b);
2258+
concat_lower_or_upper
2259+
-----------------------
2260+
HELLO WORLD
2261+
(1 row)
2262+
</screen>
2263+
</para>
2264+
</sect2>
2265+
2266+
<sect2 id="sql-syntax-calling-funcs-mixed">
2267+
<title>Using mixed notation</title>
2268+
2269+
<indexterm>
2270+
<primary>function</primary>
2271+
<secondary>mixed notation</secondary>
2272+
</indexterm>
2273+
2274+
<para>
2275+
The mixed notation combines positional and named notation. However, as
2276+
already mentioned, named arguments cannot precede positional arguments.
2277+
For example:
2278+
<screen>
2279+
SELECT concat_lower_or_upper('Hello', 'World', true AS uppercase);
2280+
concat_lower_or_upper
2281+
-----------------------
2282+
HELLO WORLD
2283+
(1 row)
2284+
</screen>
2285+
In the above query, the arguments <literal>a</literal> and
2286+
<literal>b</literal> are specified positionally, while
2287+
<literal>uppercase</> is specified by name. In this example,
2288+
that adds little except documentation. With a more complex function
2289+
having numerous parameters that have default values, named or mixed
2290+
notation can save a great deal of writing and reduce chances for error.
2291+
</para>
2292+
</sect2>
2293+
</sect1>
2294+
21262295
</chapter>

‎doc/src/sgml/xfunc.sgml

Lines changed: 62 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.139 2009/09/03 22:11:07 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.140 2009/10/08 02:39:16 tgl Exp $ -->
22

33
<sect1 id="xfunc">
44
<title>User-Defined Functions</title>
@@ -517,6 +517,39 @@ SELECT getname(new_emp());
517517
</para>
518518
</sect2>
519519

520+
<sect2 id="xfunc-named-parameters">
521+
<title><acronym>SQL</> Functions with Parameter Names</title>
522+
523+
<indexterm>
524+
<primary>function</primary>
525+
<secondary>named parameter</secondary>
526+
</indexterm>
527+
528+
<para>
529+
It is possible to attach names to a function's parameters, for example
530+
531+
<programlisting>
532+
CREATE FUNCTION tf1 (acct_no integer, debit numeric) RETURNS numeric AS $$
533+
UPDATE bank
534+
SET balance = balance - $2
535+
WHERE accountno = $1
536+
RETURNING balance;
537+
$$ LANGUAGE SQL;
538+
</programlisting>
539+
540+
Here the first parameter has been given the name <literal>acct_no</>,
541+
and the second parameter the name <literal>debit</>.
542+
So far as the SQL function itself is concerned, these names are just
543+
decoration; you must still refer to the parameters as <literal>$1</>,
544+
<literal>$2</>, etc within the function body. (Some procedural
545+
languages let you use the parameter names instead.) However,
546+
attaching names to the parameters is useful for documentation purposes.
547+
When a function has many parameters, it is also useful to use the names
548+
while calling the function, as described in
549+
<xref linkend="sql-syntax-calling-funcs">.
550+
</para>
551+
</sect2>
552+
520553
<sect2 id="xfunc-output-parameters">
521554
<title><acronym>SQL</> Functions with Output Parameters</title>
522555

@@ -571,7 +604,10 @@ LANGUAGE SQL;
571604
</screen>
572605

573606
but not having to bother with the separate composite type definition
574-
is often handy.
607+
is often handy. Notice that the names attached to the output parameters
608+
are not just decoration, but determine the column names of the anonymous
609+
composite type. (If you omit a name for an output parameter, the
610+
system will choose a name on its own.)
575611
</para>
576612

577613
<para>
@@ -621,7 +657,7 @@ DROP FUNCTION sum_n_product (int, int);
621657
must be declared as being of an array type. For example:
622658

623659
<screen>
624-
CREATE FUNCTION mleast(VARIADIC numeric[]) RETURNS numeric AS $$
660+
CREATE FUNCTION mleast(VARIADIC arr numeric[]) RETURNS numeric AS $$
625661
SELECT min($1[i]) FROM generate_subscripts($1, 1) g(i);
626662
$$ LANGUAGE SQL;
627663

@@ -661,6 +697,25 @@ SELECT mleast(VARIADIC ARRAY[10, -1, 5, 4.4]);
661697
normally. <literal>VARIADIC</> can only be attached to the last
662698
actual argument of a function call.
663699
</para>
700+
701+
<para>
702+
The array element parameters generated from a variadic parameter are
703+
treated as not having any names of their own. This means it is not
704+
possible to call a variadic function using named arguments (<xref
705+
linkend="sql-syntax-calling-funcs">), except when you specify
706+
<literal>VARIADIC</>. For example, this will work:
707+
708+
<screen>
709+
SELECT mleast(VARIADIC ARRAY[10, -1, 5, 4.4] AS arr);
710+
</screen>
711+
712+
but not these:
713+
714+
<screen>
715+
SELECT mleast(10 AS arr);
716+
SELECT mleast(ARRAY[10, -1, 5, 4.4] AS arr);
717+
</screen>
718+
</para>
664719
</sect2>
665720

666721
<sect2 id="xfunc-sql-parameter-defaults">
@@ -677,7 +732,9 @@ SELECT mleast(VARIADIC ARRAY[10, -1, 5, 4.4]);
677732
called with insufficiently many actual arguments. Since arguments
678733
can only be omitted from the end of the actual argument list, all
679734
parameters after a parameter with a default value have to have
680-
default values as well.
735+
default values as well. (Although the use of named argument notation
736+
could allow this restriction to be relaxed, it's still enforced so that
737+
positional argument notation works sensibly.)
681738
</para>
682739

683740
<para>
@@ -712,7 +769,7 @@ SELECT foo(); -- fails since there is no default for the first argument
712769
ERROR: function foo() does not exist
713770
</screen>
714771
The <literal>=</literal> sign can also be used in place of the
715-
key word <literal>DEFAULT</literal>,
772+
key word <literal>DEFAULT</literal>.
716773
</para>
717774
</sect2>
718775

0 commit comments

Comments
 (0)