summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/xfunc-overload.html
blob: 82a07e5ddccc5fda997d96e02d44cc171337b5a8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>38.6. Function Overloading</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions" /><link rel="next" href="xfunc-volatility.html" title="38.7. Function Volatility Categories" /></head><body id="docContent" class="container-fluid col-10"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">38.6. Function Overloading</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 38. Extending <acronym xmlns="http://www.w3.org/1999/xhtml" class="acronym">SQL</acronym></th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 14.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xfunc-volatility.html" title="38.7. Function Volatility Categories">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="XFUNC-OVERLOAD"><div class="titlepage"><div><div><h2 class="title" style="clear: both">38.6. Function Overloading</h2></div></div></div><a id="id-1.8.3.9.2" class="indexterm"></a><p>
    More than one function can be defined with the same SQL name, so long
    as the arguments they take are different.  In other words,
    function names can be <em class="firstterm">overloaded</em>.  Whether or not
    you use it, this capability entails security precautions when calling
    functions in databases where some users mistrust other users; see
    <a class="xref" href="typeconv-func.html" title="10.3. Functions">Section 10.3</a>.  When a query is executed, the server
    will determine which function to call from the data types and the number
    of the provided arguments.  Overloading can also be used to simulate
    functions with a variable number of arguments, up to a finite maximum
    number.
   </p><p>
    When creating a family of overloaded functions, one should be
    careful not to create ambiguities.  For instance, given the
    functions:
</p><pre class="programlisting">
CREATE FUNCTION test(int, real) RETURNS ...
CREATE FUNCTION test(smallint, double precision) RETURNS ...
</pre><p>
    it is not immediately clear which function would be called with
    some trivial input like <code class="literal">test(1, 1.5)</code>.  The
    currently implemented resolution rules are described in
    <a class="xref" href="typeconv.html" title="Chapter 10. Type Conversion">Chapter 10</a>, but it is unwise to design a system that subtly
    relies on this behavior.
   </p><p>
    A function that takes a single argument of a composite type should
    generally not have the same name as any attribute (field) of that type.
    Recall that <code class="literal"><em class="replaceable"><code>attribute</code></em>(<em class="replaceable"><code>table</code></em>)</code>
    is considered equivalent
    to <code class="literal"><em class="replaceable"><code>table</code></em>.<em class="replaceable"><code>attribute</code></em></code>.
    In the case that there is an
    ambiguity between a function on a composite type and an attribute of
    the composite type, the attribute will always be used.  It is possible
    to override that choice by schema-qualifying the function name
    (that is, <code class="literal"><em class="replaceable"><code>schema</code></em>.<em class="replaceable"><code>func</code></em>(<em class="replaceable"><code>table</code></em>)
    </code>) but it's better to
    avoid the problem by not choosing conflicting names.
   </p><p>
    Another possible conflict is between variadic and non-variadic functions.
    For instance, it is possible to create both <code class="literal">foo(numeric)</code> and
    <code class="literal">foo(VARIADIC numeric[])</code>.  In this case it is unclear which one
    should be matched to a call providing a single numeric argument, such as
    <code class="literal">foo(10.1)</code>.  The rule is that the function appearing
    earlier in the search path is used, or if the two functions are in the
    same schema, the non-variadic one is preferred.
   </p><p>
    When overloading C-language functions, there is an additional
    constraint: The C name of each function in the family of
    overloaded functions must be different from the C names of all
    other functions, either internal or dynamically loaded.  If this
    rule is violated, the behavior is not portable.  You might get a
    run-time linker error, or one of the functions will get called
    (usually the internal one).  The alternative form of the
    <code class="literal">AS</code> clause for the SQL <code class="command">CREATE
    FUNCTION</code> command decouples the SQL function name from
    the function name in the C source code.  For instance:
</p><pre class="programlisting">
CREATE FUNCTION test(int) RETURNS int
    AS '<em class="replaceable"><code>filename</code></em>', 'test_1arg'
    LANGUAGE C;
CREATE FUNCTION test(int, int) RETURNS int
    AS '<em class="replaceable"><code>filename</code></em>', 'test_2arg'
    LANGUAGE C;
</pre><p>
    The names of the C functions here reflect one of many possible conventions.
   </p></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xfunc-sql.html" title="38.5. Query Language (SQL) Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 38. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xfunc-volatility.html" title="38.7. Function Volatility Categories">Next</a></td></tr><tr><td width="40%" align="left" valign="top">38.5. Query Language (<acronym xmlns="http://www.w3.org/1999/xhtml" class="acronym">SQL</acronym>) Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 14.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 38.7. Function Volatility Categories</td></tr></table></div></body></html>