I686LINUX/util/I686LINUX/doc/postgresql/html/sql-createcast.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >CREATE CAST</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="SQL Commands"
  16 HREF="sql-commands.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="CREATE AGGREGATE"
  19 HREF="sql-createaggregate.html"><LINK
  20 REL="NEXT"
  21 TITLE="CREATE CONSTRAINT TRIGGER"
  22 HREF="sql-createconstraint.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="sql-createaggregate.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="sql-createaggregate.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 ></TD
  68 ><TD
  69 WIDTH="10%"
  70 ALIGN="right"
  71 VALIGN="top"
  72 ><A
  73 HREF="sql-createconstraint.html"
  74 >Fast Forward</A
  75 ></TD
  76 ><TD
  77 WIDTH="10%"
  78 ALIGN="right"
  79 VALIGN="top"
  80 ><A
  81 HREF="sql-createconstraint.html"
  82 ACCESSKEY="N"
  83 >Next</A
  84 ></TD
  85 ></TR
  86 ></TABLE
  87 ><HR
  88 ALIGN="LEFT"
  89 WIDTH="100%"></DIV
  90 ><H1
  91 ><A
  92 NAME="SQL-CREATECAST"
  93 ></A
  94 >CREATE CAST</H1
  95 ><DIV
  96 CLASS="REFNAMEDIV"
  97 ><A
  98 NAME="AEN36496"
  99 ></A
 100 ><H2
 101 >Name</H2
 102 >CREATE CAST&nbsp;--&nbsp;define a new cast</DIV
 103 ><A
 104 NAME="AEN36499"
 105 ></A
 106 ><DIV
 107 CLASS="REFSYNOPSISDIV"
 108 ><A
 109 NAME="AEN36501"
 110 ></A
 111 ><H2
 112 >Synopsis</H2
 113 ><PRE
 114 CLASS="SYNOPSIS"
 115 >CREATE CAST (<VAR
 116 CLASS="REPLACEABLE"
 117 >sourcetype</VAR
 118 > AS <VAR
 119 CLASS="REPLACEABLE"
 120 >targettype</VAR
 121 >)
 122     WITH FUNCTION <VAR
 123 CLASS="REPLACEABLE"
 124 >funcname</VAR
 125 > (<VAR
 126 CLASS="REPLACEABLE"
 127 >argtype</VAR
 128 >)
 129     [ AS ASSIGNMENT | AS IMPLICIT ]
 130
 131 CREATE CAST (<VAR
 132 CLASS="REPLACEABLE"
 133 >sourcetype</VAR
 134 > AS <VAR
 135 CLASS="REPLACEABLE"
 136 >targettype</VAR
 137 >)
 138     WITHOUT FUNCTION
 139     [ AS ASSIGNMENT | AS IMPLICIT ]</PRE
 140 ></DIV
 141 ><DIV
 142 CLASS="REFSECT1"
 143 ><A
 144 NAME="SQL-CREATECAST-DESCRIPTION"
 145 ></A
 146 ><H2
 147 >Description</H2
 148 ><P
 149 >   <TT
 150 CLASS="COMMAND"
 151 >CREATE CAST</TT
 152 > defines a new cast.  A cast
 153    specifies how to perform a conversion between
 154    two data types.  For example,
 155 </P><PRE
 156 CLASS="PROGRAMLISTING"
 157 >SELECT CAST(42 AS text);</PRE
 158 ><P>
 159    converts the integer constant 42 to type <TT
 160 CLASS="TYPE"
 161 >text</TT
 162 > by
 163    invoking a previously specified function, in this case
 164    <TT
 165 CLASS="LITERAL"
 166 >text(int4)</TT
 167 >. (If no suitable cast has been defined, the
 168    conversion fails.)
 169   </P
 170 ><P
 171 >   Two types may be <I
 172 CLASS="FIRSTTERM"
 173 >binary compatible</I
 174 >, which
 175    means that they can be converted into one another <SPAN
 176 CLASS="QUOTE"
 177 >"for
 178    free"</SPAN
 179 > without invoking any function.  This requires that
 180    corresponding values use the same internal representation.  For
 181    instance, the types <TT
 182 CLASS="TYPE"
 183 >text</TT
 184 > and <TT
 185 CLASS="TYPE"
 186 >varchar</TT
 187 > are
 188    binary compatible.
 189   </P
 190 ><P
 191 >   By default, a cast can be invoked only by an explicit cast request,
 192    that is an explicit <TT
 193 CLASS="LITERAL"
 194 >CAST(<VAR
 195 CLASS="REPLACEABLE"
 196 >x</VAR
 197 > AS
 198    <VAR
 199 CLASS="REPLACEABLE"
 200 >typename</VAR
 201 >)</TT
 202 >,
 203    <VAR
 204 CLASS="REPLACEABLE"
 205 >x</VAR
 206 ><TT
 207 CLASS="LITERAL"
 208 >::</TT
 209 ><VAR
 210 CLASS="REPLACEABLE"
 211 >typename</VAR
 212 >, or
 213    <VAR
 214 CLASS="REPLACEABLE"
 215 >typename</VAR
 216 >(<VAR
 217 CLASS="REPLACEABLE"
 218 >x</VAR
 219 >) construct.
 220   </P
 221 ><P
 222 >   If the cast is marked <TT
 223 CLASS="LITERAL"
 224 >AS ASSIGNMENT</TT
 225 > then it can be invoked
 226    implicitly when assigning a value to a column of the target data type.
 227    For example, supposing that <TT
 228 CLASS="LITERAL"
 229 >foo.f1</TT
 230 > is a column of
 231    type <TT
 232 CLASS="TYPE"
 233 >text</TT
 234 >, then
 235 </P><PRE
 236 CLASS="PROGRAMLISTING"
 237 >INSERT INTO foo (f1) VALUES (42);</PRE
 238 ><P>
 239    will be allowed if the cast from type <TT
 240 CLASS="TYPE"
 241 >integer</TT
 242 > to type
 243    <TT
 244 CLASS="TYPE"
 245 >text</TT
 246 > is marked <TT
 247 CLASS="LITERAL"
 248 >AS ASSIGNMENT</TT
 249 >, otherwise
 250    not.
 251    (We generally use the term <I
 252 CLASS="FIRSTTERM"
 253 >assignment
 254    cast</I
 255 > to describe this kind of cast.)
 256   </P
 257 ><P
 258 >   If the cast is marked <TT
 259 CLASS="LITERAL"
 260 >AS IMPLICIT</TT
 261 > then it can be invoked
 262    implicitly in any context, whether assignment or internally in an
 263    expression.  For example, since <TT
 264 CLASS="LITERAL"
 265 >||</TT
 266 > takes <TT
 267 CLASS="TYPE"
 268 >text</TT
 269 >
 270    operands,
 271 </P><PRE
 272 CLASS="PROGRAMLISTING"
 273 >SELECT 'The time is ' || now();</PRE
 274 ><P>
 275    will be allowed only if the cast from type <TT
 276 CLASS="TYPE"
 277 >timestamp</TT
 278 > to
 279    <TT
 280 CLASS="TYPE"
 281 >text</TT
 282 > is marked <TT
 283 CLASS="LITERAL"
 284 >AS IMPLICIT</TT
 285 >.  Otherwise it
 286    will be necessary to write the cast explicitly, for example
 287 </P><PRE
 288 CLASS="PROGRAMLISTING"
 289 >SELECT 'The time is ' || CAST(now() AS text);</PRE
 290 ><P>
 291    (We generally use the term <I
 292 CLASS="FIRSTTERM"
 293 >implicit
 294    cast</I
 295 > to describe this kind of cast.)
 296   </P
 297 ><P
 298 >   It is wise to be conservative about marking casts as implicit.  An
 299    overabundance of implicit casting paths can cause
 300    <SPAN
 301 CLASS="PRODUCTNAME"
 302 >PostgreSQL</SPAN
 303 > to choose surprising
 304    interpretations of commands, or to be unable to resolve commands at
 305    all because there are multiple possible interpretations.  A good
 306    rule of thumb is to make a cast implicitly invokable only for
 307    information-preserving transformations between types in the same
 308    general type category.  For example, the cast from <TT
 309 CLASS="TYPE"
 310 >int2</TT
 311 > to
 312    <TT
 313 CLASS="TYPE"
 314 >int4</TT
 315 > can reasonably be implicit, but the cast from
 316    <TT
 317 CLASS="TYPE"
 318 >float8</TT
 319 > to <TT
 320 CLASS="TYPE"
 321 >int4</TT
 322 > should probably be
 323    assignment-only.  Cross-type-category casts, such as <TT
 324 CLASS="TYPE"
 325 >text</TT
 326 >
 327    to <TT
 328 CLASS="TYPE"
 329 >int4</TT
 330 >, are best made explicit-only.
 331   </P
 332 ><P
 333 >   To be able to create a cast, you must own the source or the target
 334    data type.  To create a binary-compatible cast, you must be superuser.
 335    (This restriction is made because an erroneous binary-compatible cast
 336    conversion can easily crash the server.)
 337   </P
 338 ></DIV
 339 ><DIV
 340 CLASS="REFSECT1"
 341 ><A
 342 NAME="AEN36558"
 343 ></A
 344 ><H2
 345 >Parameters</H2
 346 ><P
 347 ></P
 348 ><DIV
 349 CLASS="VARIABLELIST"
 350 ><DL
 351 ><DT
 352 ><VAR
 353 CLASS="REPLACEABLE"
 354 >sourcetype</VAR
 355 ></DT
 356 ><DD
 357 ><P
 358 >       The name of the source data type of the cast.
 359       </P
 360 ></DD
 361 ><DT
 362 ><VAR
 363 CLASS="REPLACEABLE"
 364 >targettype</VAR
 365 ></DT
 366 ><DD
 367 ><P
 368 >       The name of the target data type of the cast.
 369       </P
 370 ></DD
 371 ><DT
 372 ><VAR
 373 CLASS="REPLACEABLE"
 374 >funcname</VAR
 375 >(<VAR
 376 CLASS="REPLACEABLE"
 377 >argtype</VAR
 378 >)</DT
 379 ><DD
 380 ><P
 381 >       The function used to perform the cast.  The function name may
 382        be schema-qualified.  If it is not, the function will be looked
 383        up in the path.  The argument type must be identical to the
 384        source type, the result data type must match the target type of
 385        the cast.
 386       </P
 387 ></DD
 388 ><DT
 389 ><TT
 390 CLASS="LITERAL"
 391 >WITHOUT FUNCTION</TT
 392 ></DT
 393 ><DD
 394 ><P
 395 >       Indicates that the source type and the target type are binary
 396        compatible, so no function is required to perform the cast.
 397       </P
 398 ></DD
 399 ><DT
 400 ><TT
 401 CLASS="LITERAL"
 402 >AS ASSIGNMENT</TT
 403 ></DT
 404 ><DD
 405 ><P
 406 >       Indicates that the cast may be invoked implicitly in assignment
 407        contexts.
 408       </P
 409 ></DD
 410 ><DT
 411 ><TT
 412 CLASS="LITERAL"
 413 >AS IMPLICIT</TT
 414 ></DT
 415 ><DD
 416 ><P
 417 >       Indicates that the cast may be invoked implicitly in any context.
 418       </P
 419 ></DD
 420 ></DL
 421 ></DIV
 422 ></DIV
 423 ><DIV
 424 CLASS="REFSECT1"
 425 ><A
 426 NAME="SQL-CREATECAST-NOTES"
 427 ></A
 428 ><H2
 429 >Notes</H2
 430 ><P
 431 >   Use <TT
 432 CLASS="COMMAND"
 433 >DROP CAST</TT
 434 > to remove user-defined casts.
 435   </P
 436 ><P
 437 >   Remember that if you want to be able to convert types both ways you
 438    need to declare casts both ways explicitly.
 439   </P
 440 ><P
 441 >   Prior to <SPAN
 442 CLASS="PRODUCTNAME"
 443 >PostgreSQL</SPAN
 444 > 7.3, every function that had
 445    the same name as a data type, returned that data type, and took one
 446    argument of a different type was automatically a cast function.
 447    This convention has been abandoned in face of the introduction of
 448    schemas and to be able to represent binary compatible casts in the
 449    system catalogs.  (The built-in cast functions still follow this naming
 450    scheme, but they have to be shown as casts in the system catalog <TT
 451 CLASS="LITERAL"
 452 >pg_cast</TT
 453 >
 454    now.)
 455   </P
 456 ></DIV
 457 ><DIV
 458 CLASS="REFSECT1"
 459 ><A
 460 NAME="SQL-CREATECAST-EXAMPLES"
 461 ></A
 462 ><H2
 463 >Examples</H2
 464 ><P
 465 >   To create a cast from type <TT
 466 CLASS="TYPE"
 467 >text</TT
 468 > to type
 469    <TT
 470 CLASS="TYPE"
 471 >int4</TT
 472 > using the function <TT
 473 CLASS="LITERAL"
 474 >int4(text)</TT
 475 >:
 476 </P><PRE
 477 CLASS="PROGRAMLISTING"
 478 >CREATE CAST (text AS int4) WITH FUNCTION int4(text);</PRE
 479 ><P>
 480    (This cast is already predefined in the system.)
 481   </P
 482 ></DIV
 483 ><DIV
 484 CLASS="REFSECT1"
 485 ><A
 486 NAME="SQL-CREATECAST-COMPAT"
 487 ></A
 488 ><H2
 489 >Compatibility</H2
 490 ><P
 491 >   The <TT
 492 CLASS="COMMAND"
 493 >CREATE CAST</TT
 494 > command conforms to SQL99,
 495    except that SQL99 does not make provisions for binary-compatible
 496    types.  <TT
 497 CLASS="LITERAL"
 498 >AS IMPLICIT</TT
 499 > is a <SPAN
 500 CLASS="PRODUCTNAME"
 501 >PostgreSQL</SPAN
 502 >
 503    extension, too.
 504   </P
 505 ></DIV
 506 ><DIV
 507 CLASS="REFSECT1"
 508 ><A
 509 NAME="SQL-CREATECAST-SEEALSO"
 510 ></A
 511 ><H2
 512 >See Also</H2
 513 ><P
 514 >   <A
 515 HREF="sql-createfunction.html"
 516 ><I
 517 >CREATE FUNCTION</I
 518 ></A
 519 >,
 520    <A
 521 HREF="sql-createtype.html"
 522 ><I
 523 >CREATE TYPE</I
 524 ></A
 525 >,
 526    <A
 527 HREF="sql-dropcast.html"
 528 ><I
 529 >DROP CAST</I
 530 ></A
 531 >
 532   </P
 533 ></DIV
 534 ><DIV
 535 CLASS="NAVFOOTER"
 536 ><HR
 537 ALIGN="LEFT"
 538 WIDTH="100%"><TABLE
 539 SUMMARY="Footer navigation table"
 540 WIDTH="100%"
 541 BORDER="0"
 542 CELLPADDING="0"
 543 CELLSPACING="0"
 544 ><TR
 545 ><TD
 546 WIDTH="33%"
 547 ALIGN="left"
 548 VALIGN="top"
 549 ><A
 550 HREF="sql-createaggregate.html"
 551 ACCESSKEY="P"
 552 >Prev</A
 553 ></TD
 554 ><TD
 555 WIDTH="34%"
 556 ALIGN="center"
 557 VALIGN="top"
 558 ><A
 559 HREF="index.html"
 560 ACCESSKEY="H"
 561 >Home</A
 562 ></TD
 563 ><TD
 564 WIDTH="33%"
 565 ALIGN="right"
 566 VALIGN="top"
 567 ><A
 568 HREF="sql-createconstraint.html"
 569 ACCESSKEY="N"
 570 >Next</A
 571 ></TD
 572 ></TR
 573 ><TR
 574 ><TD
 575 WIDTH="33%"
 576 ALIGN="left"
 577 VALIGN="top"
 578 >CREATE AGGREGATE</TD
 579 ><TD
 580 WIDTH="34%"
 581 ALIGN="center"
 582 VALIGN="top"
 583 ><A
 584 HREF="sql-commands.html"
 585 ACCESSKEY="U"
 586 >Up</A
 587 ></TD
 588 ><TD
 589 WIDTH="33%"
 590 ALIGN="right"
 591 VALIGN="top"
 592 >CREATE CONSTRAINT TRIGGER</TD
 593 ></TR
 594 ></TABLE
 595 ></DIV
 596 ></BODY
 597 ></HTML
 598 >