← Back to branch summary

~ubuntu-branches/debian/sid/postgresql-9.3/sid

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/typeconv-func.html

  • Committer: Package Import Robot
  • Author(s): Martin Pitt
  • Date: 2013-05-08 05:39:52 UTC
  • Revision ID: package-import@ubuntu.com-20130508053952-1j7uilp7mjtrvq8q
Tags: upstream-9.3~beta1
Import upstream version 9.3~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/typeconv-func.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>Functions</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.3beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="Type Conversion"
 
16
HREF="typeconv.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Operators"
 
19
HREF="typeconv-oper.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="Value Storage"
 
22
HREF="typeconv-query.html"><LINK
 
23
REL="STYLESHEET"
 
24
TYPE="text/css"
 
25
HREF="stylesheet.css"><META
 
26
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2013-05-06T21:00:50"></HEAD
 
30
><BODY
 
31
CLASS="SECT1"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.3beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="Operators"
 
57
HREF="typeconv-oper.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
HREF="typeconv.html"
 
67
ACCESSKEY="U"
 
68
>Up</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
>Chapter 10. Type Conversion</TD
 
75
><TD
 
76
WIDTH="20%"
 
77
ALIGN="right"
 
78
VALIGN="top"
 
79
><A
 
80
TITLE="Value Storage"
 
81
HREF="typeconv-query.html"
 
82
ACCESSKEY="N"
 
83
>Next</A
 
84
></TD
 
85
></TR
 
86
></TABLE
 
87
><HR
 
88
ALIGN="LEFT"
 
89
WIDTH="100%"></DIV
 
90
><DIV
 
91
CLASS="SECT1"
 
92
><H1
 
93
CLASS="SECT1"
 
94
><A
 
95
NAME="TYPECONV-FUNC"
 
96
>10.3. Functions</A
 
97
></H1
 
98
><P
 
99
>   The specific function that is referenced by a function call
 
100
   is determined using the following procedure.
 
101
  </P
 
102
><DIV
 
103
CLASS="PROCEDURE"
 
104
><P
 
105
><B
 
106
>Function Type Resolution</B
 
107
></P
 
108
><OL
 
109
TYPE="1"
 
110
><LI
 
111
CLASS="STEP"
 
112
><P
 
113
>Select the functions to be considered from the
 
114
<CODE
 
115
CLASS="CLASSNAME"
 
116
>pg_proc</CODE
 
117
> system catalog.  If a non-schema-qualified
 
118
function name was used, the functions
 
119
considered are those with the matching name and argument count that are
 
120
visible in the current search path (see <A
 
121
HREF="ddl-schemas.html#DDL-SCHEMAS-PATH"
 
122
>Section 5.7.3</A
 
123
>).
 
124
If a qualified function name was given, only functions in the specified
 
125
schema are considered.</P
 
126
><OL
 
127
CLASS="SUBSTEPS"
 
128
TYPE="a"
 
129
><LI
 
130
CLASS="STEP"
 
131
><P
 
132
>If the search path finds multiple functions of identical argument types,
 
133
only the one appearing earliest in the path is considered.  Functions of
 
134
different argument types are considered on an equal footing regardless of
 
135
search path position.</P
 
136
></LI
 
137
><LI
 
138
CLASS="STEP"
 
139
><P
 
140
>If a function is declared with a <TT
 
141
CLASS="LITERAL"
 
142
>VARIADIC</TT
 
143
> array parameter, and
 
144
the call does not use the <TT
 
145
CLASS="LITERAL"
 
146
>VARIADIC</TT
 
147
> keyword, then the function
 
148
is treated as if the array parameter were replaced by one or more occurrences
 
149
of its element type, as needed to match the call.  After such expansion the
 
150
function might have effective argument types identical to some non-variadic
 
151
function.  In that case the function appearing earlier in the search path is
 
152
used, or if the two functions are in the same schema, the non-variadic one is
 
153
preferred.</P
 
154
></LI
 
155
><LI
 
156
CLASS="STEP"
 
157
><P
 
158
>Functions that have default values for parameters are considered to match any
 
159
call that omits zero or more of the defaultable parameter positions.  If more
 
160
than one such function matches a call, the one appearing earliest in the
 
161
search path is used.  If there are two or more such functions in the same
 
162
schema with identical parameter types in the non-defaulted positions (which is
 
163
possible if they have different sets of defaultable parameters), the system
 
164
will not be able to determine which to prefer, and so an <SPAN
 
165
CLASS="QUOTE"
 
166
>"ambiguous
 
167
function call"</SPAN
 
168
> error will result if no better match to the call can be
 
169
found.</P
 
170
></LI
 
171
></OL
 
172
></LI
 
173
><LI
 
174
CLASS="STEP"
 
175
><P
 
176
>Check for a function accepting exactly the input argument types.
 
177
If one exists (there can be only one exact match in the set of
 
178
functions considered), use it.
 
179
(Cases involving <TT
 
180
CLASS="TYPE"
 
181
>unknown</TT
 
182
> will never find a match at
 
183
this step.)</P
 
184
></LI
 
185
><LI
 
186
CLASS="STEP"
 
187
><P
 
188
>If no exact match is found, see if the function call appears
 
189
to be a special type conversion request.  This happens if the function call
 
190
has just one argument and the function name is the same as the (internal)
 
191
name of some data type.  Furthermore, the function argument must be either
 
192
an unknown-type literal, or a type that is binary-coercible to the named
 
193
data type, or a type that could be converted to the named data type by
 
194
applying that type's I/O functions (that is, the conversion is either to or
 
195
from one of the standard string types).  When these conditions are met,
 
196
the function call is treated as a form of <TT
 
197
CLASS="LITERAL"
 
198
>CAST</TT
 
199
> specification.
 
200
  <A
 
201
NAME="AEN21298"
 
202
HREF="#FTN.AEN21298"
 
203
><SPAN
 
204
CLASS="footnote"
 
205
>[1]</SPAN
 
206
></A
 
207
></P
 
208
></LI
 
209
><LI
 
210
CLASS="STEP"
 
211
><P
 
212
>Look for the best match.</P
 
213
><OL
 
214
CLASS="SUBSTEPS"
 
215
TYPE="a"
 
216
><LI
 
217
CLASS="STEP"
 
218
><P
 
219
>Discard candidate functions for which the input types do not match
 
220
and cannot be converted (using an implicit conversion) to match.
 
221
<TT
 
222
CLASS="TYPE"
 
223
>unknown</TT
 
224
> literals are
 
225
assumed to be convertible to anything for this purpose.  If only one
 
226
candidate remains, use it; else continue to the next step.</P
 
227
></LI
 
228
><LI
 
229
CLASS="STEP"
 
230
><P
 
231
>Run through all candidates and keep those with the most exact matches
 
232
on input types.  (Domains are considered the same as their base type
 
233
for this purpose.)  Keep all candidates if none have exact matches.
 
234
If only one candidate remains, use it; else continue to the next step.</P
 
235
></LI
 
236
><LI
 
237
CLASS="STEP"
 
238
><P
 
239
>Run through all candidates and keep those that accept preferred types (of the
 
240
input data type's type category) at the most positions where type conversion
 
241
will be required.
 
242
Keep all candidates if none accept preferred types.
 
243
If only one candidate remains, use it; else continue to the next step.</P
 
244
></LI
 
245
><LI
 
246
CLASS="STEP"
 
247
><P
 
248
>If any input arguments are <TT
 
249
CLASS="TYPE"
 
250
>unknown</TT
 
251
>, check the type categories
 
252
accepted
 
253
at those argument positions by the remaining candidates.  At each position,
 
254
select the <TT
 
255
CLASS="TYPE"
 
256
>string</TT
 
257
> category if any candidate accepts that category.
 
258
(This bias towards string
 
259
is appropriate since an unknown-type literal looks like a string.)
 
260
Otherwise, if all the remaining candidates accept the same type category,
 
261
select that category; otherwise fail because
 
262
the correct choice cannot be deduced without more clues.
 
263
Now discard candidates that do not accept the selected type category.
 
264
Furthermore, if any candidate accepts a preferred type in that category,
 
265
discard candidates that accept non-preferred types for that argument.
 
266
Keep all candidates if none survive these tests.
 
267
If only one candidate remains, use it; else continue to the next step.</P
 
268
></LI
 
269
><LI
 
270
CLASS="STEP"
 
271
><P
 
272
>If there are both <TT
 
273
CLASS="TYPE"
 
274
>unknown</TT
 
275
> and known-type arguments, and all
 
276
the known-type arguments have the same type, assume that the
 
277
<TT
 
278
CLASS="TYPE"
 
279
>unknown</TT
 
280
> arguments are also of that type, and check which
 
281
candidates can accept that type at the <TT
 
282
CLASS="TYPE"
 
283
>unknown</TT
 
284
>-argument
 
285
positions.  If exactly one candidate passes this test, use it.
 
286
Otherwise, fail.</P
 
287
></LI
 
288
></OL
 
289
></LI
 
290
></OL
 
291
></DIV
 
292
><P
 
293
>Note that the <SPAN
 
294
CLASS="QUOTE"
 
295
>"best match"</SPAN
 
296
> rules are identical for operator and
 
297
function type resolution.
 
298
Some examples follow.</P
 
299
><DIV
 
300
CLASS="EXAMPLE"
 
301
><A
 
302
NAME="AEN21322"
 
303
></A
 
304
><P
 
305
><B
 
306
>Example 10-5. Rounding Function Argument Type Resolution</B
 
307
></P
 
308
><P
 
309
>There is only one <CODE
 
310
CLASS="FUNCTION"
 
311
>round</CODE
 
312
> function that takes two
 
313
arguments; it takes a first argument of type <TT
 
314
CLASS="TYPE"
 
315
>numeric</TT
 
316
> and
 
317
a second argument of type <TT
 
318
CLASS="TYPE"
 
319
>integer</TT
 
320
>.
 
321
So the following query automatically converts
 
322
the first argument of type <TT
 
323
CLASS="TYPE"
 
324
>integer</TT
 
325
> to
 
326
<TT
 
327
CLASS="TYPE"
 
328
>numeric</TT
 
329
>:
 
330
 
 
331
</P><PRE
 
332
CLASS="SCREEN"
 
333
>SELECT round(4, 4);
 
334
 
 
335
 round
 
336
--------
 
337
 4.0000
 
338
(1 row)</PRE
 
339
><P>
 
340
 
 
341
That query is actually transformed by the parser to:
 
342
</P><PRE
 
343
CLASS="SCREEN"
 
344
>SELECT round(CAST (4 AS numeric), 4);</PRE
 
345
><P></P
 
346
><P
 
347
>Since numeric constants with decimal points are initially assigned the
 
348
type <TT
 
349
CLASS="TYPE"
 
350
>numeric</TT
 
351
>, the following query will require no type
 
352
conversion and therefore might be slightly more efficient:
 
353
</P><PRE
 
354
CLASS="SCREEN"
 
355
>SELECT round(4.0, 4);</PRE
 
356
><P></P
 
357
></DIV
 
358
><DIV
 
359
CLASS="EXAMPLE"
 
360
><A
 
361
NAME="AEN21335"
 
362
></A
 
363
><P
 
364
><B
 
365
>Example 10-6. Substring Function Type Resolution</B
 
366
></P
 
367
><P
 
368
>There are several <CODE
 
369
CLASS="FUNCTION"
 
370
>substr</CODE
 
371
> functions, one of which
 
372
takes types <TT
 
373
CLASS="TYPE"
 
374
>text</TT
 
375
> and <TT
 
376
CLASS="TYPE"
 
377
>integer</TT
 
378
>.  If called
 
379
with a string constant of unspecified type, the system chooses the
 
380
candidate function that accepts an argument of the preferred category
 
381
<TT
 
382
CLASS="LITERAL"
 
383
>string</TT
 
384
> (namely of type <TT
 
385
CLASS="TYPE"
 
386
>text</TT
 
387
>).
 
388
 
 
389
</P><PRE
 
390
CLASS="SCREEN"
 
391
>SELECT substr('1234', 3);
 
392
 
 
393
 substr
 
394
--------
 
395
     34
 
396
(1 row)</PRE
 
397
><P></P
 
398
><P
 
399
>If the string is declared to be of type <TT
 
400
CLASS="TYPE"
 
401
>varchar</TT
 
402
>, as might be the case
 
403
if it comes from a table, then the parser will try to convert it to become <TT
 
404
CLASS="TYPE"
 
405
>text</TT
 
406
>:
 
407
</P><PRE
 
408
CLASS="SCREEN"
 
409
>SELECT substr(varchar '1234', 3);
 
410
 
 
411
 substr
 
412
--------
 
413
     34
 
414
(1 row)</PRE
 
415
><P>
 
416
 
 
417
This is transformed by the parser to effectively become:
 
418
</P><PRE
 
419
CLASS="SCREEN"
 
420
>SELECT substr(CAST (varchar '1234' AS text), 3);</PRE
 
421
><P></P
 
422
><P
 
423
></P><DIV
 
424
CLASS="NOTE"
 
425
><BLOCKQUOTE
 
426
CLASS="NOTE"
 
427
><P
 
428
><B
 
429
>Note: </B
 
430
>The parser learns from the <TT
 
431
CLASS="STRUCTNAME"
 
432
>pg_cast</TT
 
433
> catalog that
 
434
<TT
 
435
CLASS="TYPE"
 
436
>text</TT
 
437
> and <TT
 
438
CLASS="TYPE"
 
439
>varchar</TT
 
440
>
 
441
are binary-compatible, meaning that one can be passed to a function that
 
442
accepts the other without doing any physical conversion.  Therefore, no
 
443
type conversion call is really inserted in this case.</P
 
444
></BLOCKQUOTE
 
445
></DIV
 
446
><P></P
 
447
><P
 
448
>And, if the function is called with an argument of type <TT
 
449
CLASS="TYPE"
 
450
>integer</TT
 
451
>,
 
452
the parser will try to convert that to <TT
 
453
CLASS="TYPE"
 
454
>text</TT
 
455
>:
 
456
</P><PRE
 
457
CLASS="SCREEN"
 
458
>SELECT substr(1234, 3);
 
459
ERROR:  function substr(integer, integer) does not exist
 
460
HINT:  No function matches the given name and argument types. You might need
 
461
to add explicit type casts.</PRE
 
462
><P>
 
463
 
 
464
This does not work because <TT
 
465
CLASS="TYPE"
 
466
>integer</TT
 
467
> does not have an implicit cast
 
468
to <TT
 
469
CLASS="TYPE"
 
470
>text</TT
 
471
>.  An explicit cast will work, however:
 
472
</P><PRE
 
473
CLASS="SCREEN"
 
474
>SELECT substr(CAST (1234 AS text), 3);
 
475
 
 
476
 substr
 
477
--------
 
478
     34
 
479
(1 row)</PRE
 
480
><P></P
 
481
></DIV
 
482
></DIV
 
483
><H3
 
484
CLASS="FOOTNOTES"
 
485
>Notes</H3
 
486
><TABLE
 
487
BORDER="0"
 
488
CLASS="FOOTNOTES"
 
489
WIDTH="100%"
 
490
><TR
 
491
><TD
 
492
ALIGN="LEFT"
 
493
VALIGN="TOP"
 
494
WIDTH="5%"
 
495
><A
 
496
NAME="FTN.AEN21298"
 
497
HREF="typeconv-func.html#AEN21298"
 
498
><SPAN
 
499
CLASS="footnote"
 
500
>[1]</SPAN
 
501
></A
 
502
></TD
 
503
><TD
 
504
ALIGN="LEFT"
 
505
VALIGN="TOP"
 
506
WIDTH="95%"
 
507
><P
 
508
>    The reason for this step is to support function-style cast specifications
 
509
    in cases where there is not an actual cast function.  If there is a cast
 
510
    function, it is conventionally named after its output type, and so there
 
511
    is no need to have a special case.  See
 
512
    <A
 
513
HREF="sql-createcast.html"
 
514
>CREATE CAST</A
 
515
>
 
516
    for additional commentary.
 
517
   </P
 
518
></TD
 
519
></TR
 
520
></TABLE
 
521
><DIV
 
522
CLASS="NAVFOOTER"
 
523
><HR
 
524
ALIGN="LEFT"
 
525
WIDTH="100%"><TABLE
 
526
SUMMARY="Footer navigation table"
 
527
WIDTH="100%"
 
528
BORDER="0"
 
529
CELLPADDING="0"
 
530
CELLSPACING="0"
 
531
><TR
 
532
><TD
 
533
WIDTH="33%"
 
534
ALIGN="left"
 
535
VALIGN="top"
 
536
><A
 
537
HREF="typeconv-oper.html"
 
538
ACCESSKEY="P"
 
539
>Prev</A
 
540
></TD
 
541
><TD
 
542
WIDTH="34%"
 
543
ALIGN="center"
 
544
VALIGN="top"
 
545
><A
 
546
HREF="index.html"
 
547
ACCESSKEY="H"
 
548
>Home</A
 
549
></TD
 
550
><TD
 
551
WIDTH="33%"
 
552
ALIGN="right"
 
553
VALIGN="top"
 
554
><A
 
555
HREF="typeconv-query.html"
 
556
ACCESSKEY="N"
 
557
>Next</A
 
558
></TD
 
559
></TR
 
560
><TR
 
561
><TD
 
562
WIDTH="33%"
 
563
ALIGN="left"
 
564
VALIGN="top"
 
565
>Operators</TD
 
566
><TD
 
567
WIDTH="34%"
 
568
ALIGN="center"
 
569
VALIGN="top"
 
570
><A
 
571
HREF="typeconv.html"
 
572
ACCESSKEY="U"
 
573
>Up</A
 
574
></TD
 
575
><TD
 
576
WIDTH="33%"
 
577
ALIGN="right"
 
578
VALIGN="top"
 
579
>Value Storage</TD
 
580
></TR
 
581
></TABLE
 
582
></DIV
 
583
></BODY
 
584
></HTML
 
585
>
 
 
b'\\ No newline at end of file'