begriffs open source - ai-pg/blob - full-docs/txt/xfunc-overload.txt

   1
   2 36.6. Function Overloading #
   3
   4    More than one function can be defined with the same SQL name, so long
   5    as the arguments they take are different. In other words, function
   6    names can be overloaded. Whether or not you use it, this capability
   7    entails security precautions when calling functions in databases where
   8    some users mistrust other users; see Section 10.3. When a query is
   9    executed, the server will determine which function to call from the
  10    data types and the number of the provided arguments. Overloading can
  11    also be used to simulate functions with a variable number of arguments,
  12    up to a finite maximum number.
  13
  14    When creating a family of overloaded functions, one should be careful
  15    not to create ambiguities. For instance, given the functions:
  16 CREATE FUNCTION test(int, real) RETURNS ...
  17 CREATE FUNCTION test(smallint, double precision) RETURNS ...
  18
  19    it is not immediately clear which function would be called with some
  20    trivial input like test(1, 1.5). The currently implemented resolution
  21    rules are described in Chapter 10, but it is unwise to design a system
  22    that subtly relies on this behavior.
  23
  24    A function that takes a single argument of a composite type should
  25    generally not have the same name as any attribute (field) of that type.
  26    Recall that attribute(table) is considered equivalent to
  27    table.attribute. In the case that there is an ambiguity between a
  28    function on a composite type and an attribute of the composite type,
  29    the attribute will always be used. It is possible to override that
  30    choice by schema-qualifying the function name (that is,
  31    schema.func(table) ) but it's better to avoid the problem by not
  32    choosing conflicting names.
  33
  34    Another possible conflict is between variadic and non-variadic
  35    functions. For instance, it is possible to create both foo(numeric) and
  36    foo(VARIADIC numeric[]). In this case it is unclear which one should be
  37    matched to a call providing a single numeric argument, such as
  38    foo(10.1). The rule is that the function appearing earlier in the
  39    search path is used, or if the two functions are in the same schema,
  40    the non-variadic one is preferred.
  41
  42    When overloading C-language functions, there is an additional
  43    constraint: The C name of each function in the family of overloaded
  44    functions must be different from the C names of all other functions,
  45    either internal or dynamically loaded. If this rule is violated, the
  46    behavior is not portable. You might get a run-time linker error, or one
  47    of the functions will get called (usually the internal one). The
  48    alternative form of the AS clause for the SQL CREATE FUNCTION command
  49    decouples the SQL function name from the function name in the C source
  50    code. For instance:
  51 CREATE FUNCTION test(int) RETURNS int
  52     AS 'filename', 'test_1arg'
  53     LANGUAGE C;
  54 CREATE FUNCTION test(int, int) RETURNS int
  55     AS 'filename', 'test_2arg'
  56     LANGUAGE C;
  57
  58    The names of the C functions here reflect one of many possible
  59    conventions.