diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 016ad36..df73bfd 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -1102,7 +1102,7 @@ CREATE FUNCTION test(int, int) RETURNS int - Positional and named notation + Calling Functions notation @@ -1110,23 +1110,24 @@ CREATE FUNCTION test(int, int) RETURNS int - Functions with named parameters can be called by positional - or named notation. Named notation makes it - easier to recognize the signature of a function. This - applies especially to overloaded functions with larger argument lists. This is also closer to - some other SQL dialects which should make porting applications easier. The positional - notation calls the function with its argument values in the same order as defined in the function declaration. - Using named notation allows to - pass arguments by its name to a function, the positional order doesn't need to be preserved. Both - named and positional notation can be mixed - (mixed notation). However, positional notation is - only allowed from the left to the right in the argument list. - As soon as a named argument appears in the list, named - notation have to be used for all following arguments. Arguments with default values can be omitted and - don't have to be specified. The default values of such arguments will then be used instead. The following - example will illustrate the usage of all three kinds of notation. - - + PostgreSQL supports calling functions with named + parameters using positional or + named notation. Named + notation makes it easier to recognize the signature of a function. This + applies especially to overloaded functions with larger argument lists. The + positional notation calls the function with its + argument values in the same order as they are defined in the function + declaration. Using named notation allows passing + arguments to a function by name, in any order. These + named and positional + notations can be mixed (mixed notation). However, + positional notation is only allowed from left to the + right in the argument list. As soon as a named + argument appears in the list, named notation must be + used for all remaining arguments. Arguments with default values can be + omitted. The default values of such arguments will then be used instead. + The following examples will illustrate the usage of all three kinds of + notation. CREATE OR REPLACE FUNCTION concat_lower_or_upper(a IN text, b IN text, uppercase boolean DEFAULT false) RETURNS text @@ -1139,12 +1140,14 @@ $$ $$ LANGUAGE SQL IMMUTABLE STRICT; - Function concat_lower_or_upper has two mandatory parameters: a and - b. Additionally there is one optional parameter uppercase which defaults to false. - This function can be called with positional, named or - mixed notation . See also for a more detailed explanation of calling - function with default values. + Function concat_lower_or_upper has two mandatory + parameters: a and b. Additionally + there is one optional parameter uppercase which defaults + to false. This function can be called with + positional, named or + mixed notation. See also for a more detailed explanation of + how to call a function with default values. @@ -1155,9 +1158,10 @@ LANGUAGE SQL IMMUTABLE STRICT; positional notation - -Positional notation is the traditional behavior how arguments are passed to functions in -PostgreSQL, for example: + + Positional notation is the traditional mechanism for + passing arguments to functions in PostgreSQL, + for example: SELECT concat_lower_or_upper('Hello', 'World'); concat_lower_or_upper @@ -1165,10 +1169,11 @@ SELECT concat_lower_or_upper('Hello', 'World'); hello world (1 row) -This calls the function concat_lower_or_upper with both mandatory arguments -a and b in positional notation -and omits all default arguments. The argument uppercase will get its -default value false assigned implicitely. Another example: + This calls the function concat_lower_or_upper with + both mandatory arguments a and b in + positional notation and omits all default arguments. + The argument uppercase will have its default value + false assigned implicitly. Another example: SELECT concat_lower_or_upper('Hello', 'World', true); concat_lower_or_upper @@ -1176,35 +1181,39 @@ SELECT concat_lower_or_upper('Hello', 'World', true); HELLO WORLD (1 row) -Now the function concat_lower_or_upper is called with all arguments in -positional notation. In this case the argument uppercase -will have true assigned explicitely and concat a and b -in uppercase. - + Now the function concat_lower_or_upper is called with + all arguments in positional notation. In this case + true will be assigned to the argument + uppercase explicitly, and the function wil concatenate + a and b in uppercase. + - Using named notation + Using named notation function named notation - -Using named notation this time, the mandatory arguments a and b -are specified with the AS keyword. + + Using named notation this time, the mandatory + arguments a and b are specified with + the AS keyword. -SELECT concat_lower_or_upper('Hello' AS a, 'World' As b); +SELECT concat_lower_or_upper('Hello' AS a, 'World' AS b); concat_lower_or_upper ----------------------- hello world (1 row) -Again, the default argument uppercase is omitted and set to false implicitly. Furthermore, -when using named notation the order of the arguments doesn't matter, for example: + Again, the default argument uppercase is omitted and set + to false implicitly. The advantage of using + named notation is that the arguments may be specified in + any order, for example: -SELECT concat_lower_or_upper('Hello' AS a, 'World' As b, true AS uppercase); +SELECT concat_lower_or_upper('Hello' AS a, 'World' AS b, true AS uppercase); concat_lower_or_upper ----------------------- HELLO WORLD @@ -1216,26 +1225,28 @@ SELECT concat_lower_or_upper('Hello' AS a, true AS uppercase, 'World' AS b); HELLO WORLD (1 row) -In the examples above, the named notation allows to specify the argument values out of -their original order as they would occur in positional notation. It isn't possible to use -named or mixed notation for variadic function. Variadic functions are based -on positions of every parameter and positions has no sense in these notations. + + + + Variadic functions cannot be called using named + or mixed notation. + - Using mixed notation + Using mixed notation function mixed notation - -The mixed notation combines positional and named -notation. However, as already mentioned, positional argument have to occur from left to right, named -arguments cannot precede positional arguments. This means that in mixed notation named -arguments cannot be defined before positional arguments. + + The mixed notation combines + positional and named + notation. However, as already mentioned, named arguments cannot precede + positional arguments. SELECT concat_lower_or_upper('Hello', 'World' AS b, true AS uppercase); concat_lower_or_upper @@ -1243,9 +1254,11 @@ SELECT concat_lower_or_upper('Hello', 'World' AS b, true AS uppercase); HELLO WORLD (1 row) -The first query above is correct, since the argument a is defined in -positional notation before any named arguments. However, the following example -isn't allowed to work, since a precedes the named argument b. + The above query is legal, since the argument a is + specified using positional notation, before any + named arguments. However, the following example will fail, since + 'Hello' is specified using positional notation after the + named argument b. SELECT concat_lower_or_upper('World' AS b, 'Hello', true AS uppercase); ERROR: expected named argument