From 97377048b460823a300b1d414203c5f09c8efc1b Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Thu, 18 Jul 2002 23:11:32 +0000 Subject: pg_cast table, and standards-compliant CREATE/DROP CAST commands, plus extension to create binary compatible casts. Includes dependency tracking as well. pg_proc.proimplicit is now defunct, but will be removed in a separate commit. pg_dump provides a migration path from the previous scheme to declare casts. Dumping binary compatible casts is currently impossible, though. --- doc/src/sgml/ref/allfiles.sgml | 4 +- doc/src/sgml/ref/create_cast.sgml | 232 ++++++++++++++++++++++++++++++++++ doc/src/sgml/ref/create_function.sgml | 72 +---------- doc/src/sgml/ref/drop_cast.sgml | 133 +++++++++++++++++++ doc/src/sgml/reference.sgml | 4 +- doc/src/sgml/release.sgml | 3 +- 6 files changed, 374 insertions(+), 74 deletions(-) create mode 100644 doc/src/sgml/ref/create_cast.sgml create mode 100644 doc/src/sgml/ref/drop_cast.sgml (limited to 'doc/src') diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index c9ece5af561..55b4fc5c9f0 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -1,5 +1,5 @@ @@ -51,6 +51,7 @@ Complete list of usable sgml source files in this directory. + @@ -71,6 +72,7 @@ Complete list of usable sgml source files in this directory. + diff --git a/doc/src/sgml/ref/create_cast.sgml b/doc/src/sgml/ref/create_cast.sgml new file mode 100644 index 00000000000..81259949f1e --- /dev/null +++ b/doc/src/sgml/ref/create_cast.sgml @@ -0,0 +1,232 @@ + + + + + CREATE CAST + SQL - Language Statements + + + + CREATE CAST + define a user-defined cast + + + + +CREATE CAST (sourcetype AS targettype) + WITH FUNCTION funcname (argtype) + [AS ASSIGNMENT] + +CREATE CAST (sourcetype AS targettype) + WITHOUT FUNCTION + [AS ASSIGNMENT] + + + + + Description + + + CREATE CAST defines a new cast. A cast + specifies which function can be invoked when a conversion between + two data types is requested. For example, + +SELECT CAST(42 AS text); + + converts the integer constant 42 to type text by + invoking a previously specified function, in this case + text(int4). (If no suitable cast has been defined, the + conversion fails.) + + + + Two types may be binary compatible, which + means that they can be converted into one another for + free without invoking any function. This requires that + corresponding values use the same internal representation. For + instance, the types text and varchar are + binary compatible. + + + + A cast can marked AS ASSIGNMENT, which means that it + can be invoked implicitly in any context where the conversion it + defines is required. Cast functions not so marked can be invoked + only by explicit CAST, + x::typename, or + typename(x) constructs. For + example, supposing that foo.f1 is a column of + type text, then + +INSERT INTO foo(f1) VALUES(42); + + will be allowed if the cast from type integer to type + text is marked AS ASSIGNMENT, otherwise + not. (We generally use the term implicit + cast to describe this kind of cast.) + + + + It is wise to be conservative about marking casts as implicit. An + overabundance of implicit casting paths can cause + PostgreSQL to choose surprising + interpretations of commands, or to be unable to resolve commands at + all because there are multiple possible interpretations. A good + rule of thumb is to make cast implicitly invokable only for + information-preserving transformations between types in the same + general type category. For example, int2 to + int4 casts can reasonably be implicit, but be wary of + marking int4 to text or + float8 to int4 as implicit casts. + + + + To be able to create a cast, you must own the underlying function. + To be able to create a binary compatible cast, you must own both + the source and the target data type. + + + + Parameters + + + sourcetype + + + + The name of the source data type of the cast. + + + + + + targettype + + + + The name of the target data type of the cast. + + + + + + funcname(argtype) + + + + The function used to perform the cast. The function name may + be schema-qualified. If it is not, the function will be looked + up in the path. The argument type must be identical to the + source type, the result data type must match the target type of + the cast. Cast functions must be marked immutable. + + + + + + WITHOUT FUNCTION + + + + Indicates that the source type and the target type are binary + compatible, so no function is required to perform the cast. + + + + + + AS ASSIGNMENT + + + + Indicates that the cast may be invoked implicitly. + + + + + + + + + Notes + + + Use DROP CAST to remove user-defined casts. + + + + The privileges required to create a cast may be changed in a future + release. + + + + Remember that if you want to be able to convert types both ways you + need to declare casts both ways explicitly. + + + + Prior to PostgreSQL 7.3, every function that had the same name as a + data type, returned that data type, and took one argument of a + different type was automatically a cast function. This system has + been abandoned in face of the introduction of schemas and to be + able to store binary compatible casts. The built-in cast functions + still follow this naming scheme, but they have to be declared as + casts explicitly now. + + + + + + Examples + + + To create a cast from type text to type + int using the function int4(text): + +CREATE CAST (text AS int4) WITH FUNCTION int4(text); + + (This cast is already predefined in the system.) + + + + + + Compatibility + + + The CREATE CAST command conforms to SQL99, + except that SQL99 does not make provisions for binary compatible + types. + + + + + + See Also + + + , + , + , + PostgreSQL Programmer's Guide + + + + + + diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index b2d2314a733..e2170dcc45d 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -1,5 +1,5 @@ @@ -20,7 +20,6 @@ CREATE [ OR REPLACE ] FUNCTION name { LANGUAGE langname | IMMUTABLE | STABLE | VOLATILE | CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT - | IMPLICIT CAST | [EXTERNAL] SECURITY INVOKER | [EXTERNAL] SECURITY DEFINER | AS 'definition' | AS 'obj_file', 'link_symbol' @@ -188,18 +187,6 @@ CREATE [ OR REPLACE ] FUNCTION name - - IMPLICIT CAST - - - - Indicates that the function may be used for implicit type - conversions. See for more detail. - - - - EXTERNAL SECURITY INVOKER EXTERNAL SECURITY DEFINER @@ -285,14 +272,6 @@ CREATE [ OR REPLACE ] FUNCTION name - - implicitCoercion - - - Same as IMPLICIT CAST - - - Attribute names are not case-sensitive. @@ -394,55 +373,6 @@ CREATE [ OR REPLACE ] FUNCTION name - - - Type Cast Functions - - - A function that has one argument and is named the same as its return - data type (including the schema name) is considered to be a type - casting function: it can be invoked to convert a value of its input - data type into a value - of its output datatype. For example, - -SELECT CAST(42 AS text); - - converts the integer constant 42 to text by invoking a function - text(int4), if such a function exists and returns type - text. (If no suitable conversion function can be found, the cast fails.) - - - - If a potential cast function is marked IMPLICIT CAST, - then it can be invoked implicitly in any context where the - conversion it defines is required. Cast functions not so marked - can be invoked only by explicit CAST, - x::typename, or - typename(x) constructs. For - example, supposing that foo.f1 is a column of - type text, then - -INSERT INTO foo(f1) VALUES(42); - - will be allowed if text(int4) is marked - IMPLICIT CAST, otherwise not. - - - - It is wise to be conservative about marking cast functions as - implicit casts. An overabundance of implicit casting paths can - cause PostgreSQL to choose surprising - interpretations of commands, or to be unable to resolve commands at - all because there are multiple possible interpretations. A good - rule of thumb is to make cast implicitly invokable only for - information-preserving transformations between types in the same - general type category. For example, int2 to - int4 casts can reasonably be implicit, but be wary of - marking int4 to text or - float8 to int4 as implicit casts. - - - Examples diff --git a/doc/src/sgml/ref/drop_cast.sgml b/doc/src/sgml/ref/drop_cast.sgml new file mode 100644 index 00000000000..37152114bca --- /dev/null +++ b/doc/src/sgml/ref/drop_cast.sgml @@ -0,0 +1,133 @@ + + + + + DROP CAST + SQL - Language Statements + + + + DROP CAST + remove a user-defined cast + + + + +DROP CAST (sourcetype AS targettype) + [ CASCADE | RESTRICT ] + + + + + Description + + + DROP CAST removes a previously defined cast. + + + + To be able to drop a cast, you must own the underlying function. + To be able to drop a binary compatible cast, you must own both the + source and the target data type. These are the same privileges + that are required to create a cast. + + + + Parameters + + + sourcetype + + + + The name of the source data type of the cast. + + + + + + targettype + + + + The name of the target data type of the cast. + + + + + + CASCADE + RESTRICT + + + + These key words do not have any effect, since there are no + dependencies on casts. + + + + + + + + + Notes + + + Use CREATE CAST to create user-defined casts. + + + + The privileges required to drop a cast may be changed in a future + release. + + + + + + Examples + + + To drop the cast from type text to type int: + +DROP CAST (text AS int4); + + + + + + + Compatibility + + + The DROP CAST command conforms to SQL99. + + + + + + See Also + + + + + + + + + diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 8249039826c..39fec262dd0 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -1,5 +1,5 @@ @@ -60,6 +60,7 @@ PostgreSQL Reference Manual &commit; ©Table; &createAggregate; + &createCast; &createConstraint; &createDatabase; &createDomain; @@ -80,6 +81,7 @@ PostgreSQL Reference Manual &declare; &delete; &dropAggregate; + &dropCast; &dropDatabase; &dropDomain; &dropFunction; diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml index f215c84b93e..4f7911ff4e1 100644 --- a/doc/src/sgml/release.sgml +++ b/doc/src/sgml/release.sgml @@ -1,5 +1,5 @@ @@ -24,6 +24,7 @@ CDATA means the content is "SGML-free", so you can write without worries about funny characters. -->