From d70a42e6424e1531355ce9d1d1aa59e329b3c0e6 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 16 Jun 2004 01:27:00 +0000 Subject: Represent type-specific length coercion functions as pg_cast entries, eliminating the former hard-wired convention about their names. Allow pg_cast entries to represent both type coercion and length coercion in a single step --- this is represented by a function that takes an extra typmod argument, just like a length coercion function. This nicely merges the type and length coercion mechanisms into something at least a little cleaner than we had before. Make use of the single- coercion-step behavior to fix integer-to-bit coercion so that coercing to bit(n) yields the rightmost n bits of the integer instead of the leftmost n bits. This should fix recurrent complaints about the odd behavior of this coercion. Clean up the documentation of the bit string functions, and try to put it where people might actually find it. Also, get rid of the unreliable heuristics in ruleutils.c about whether to display nested coercion steps; instead require parse_coerce.c to label them properly in the first place. --- doc/src/sgml/catalogs.sgml | 37 ++++++- doc/src/sgml/datatype.sgml | 4 +- doc/src/sgml/func.sgml | 202 ++++++++++++++++++++++++++------------ doc/src/sgml/ref/create_cast.sgml | 92 ++++++++++++++--- doc/src/sgml/syntax.sgml | 4 +- 5 files changed, 257 insertions(+), 82 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 226eef1c8da..84ae3cb205f 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1,6 +1,6 @@ @@ -934,7 +934,7 @@ Indicates what contexts the cast may be invoked in. e means only as an explicit cast (using - CAST, ::, or function-call syntax). + CAST or :: syntax). a means implicitly in assignment to a target column, as well as explicitly. i means implicitly in expressions, as well as the @@ -944,6 +944,39 @@ + + + The cast functions listed in pg_cast must + always take the cast source type as their first argument type, and + return the cast destination type as their result type. A cast + function can have up to three arguments. The second argument, + if present, must be type integer; it receives the type + modifier associated with the destination type, or -1 + if there is none. The third argument, + if present, must be type boolean; it receives true + if the cast is an explicit cast, false otherwise. + + + + It is legitimate to create a pg_cast entry + in which the source and target types are the same, if the associated + function takes more than one argument. Such entries represent + length coercion functions that coerce values of the type + to be legal for a particular type modifier value. Note however that + at present there is no support for associating non-default type + modifiers with user-created data types, and so this facility is only + of use for the small number of built-in types that have type modifier + syntax built into the grammar. + + + + When a pg_cast entry has different source and + target types and a function that takes more than one argument, it + represents converting from one type to another and applying a length + coercion in a single step. When no such entry is available, coercion + to a type that uses a type modifier involves two steps, one to + convert between datatypes and a second to apply the modifier. + diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 19feebe0b28..fdc63d8250a 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,5 +1,5 @@ @@ -2851,7 +2851,7 @@ SELECT * FROM test1 WHERE a; linkend="sql-syntax-bit-strings"> for information about the syntax of bit string constants. Bit-logical operators and string manipulation functions are available; see . + linkend="functions-bitstring">. diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 37cc1411f81..3de1adafc9a 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,5 +1,5 @@ @@ -488,55 +488,13 @@ PostgreSQL documentation - The bitwise operators are also available for the bit + The bitwise operators work only on integral data types, whereas + the others are available for all numeric data types. The bitwise + operators are also available for the bit string types bit and bit varying, as - shown in . - Bit string operands of &, |, - and # must be of equal length. When bit - shifting, the original length of the string is preserved, as shown - in the table. + shown in . - - Bit String Bitwise Operators - - - - - Example - Result - - - - - - B'10001' & B'01101' - 00001 - - - B'10001' | B'01101' - 11101 - - - B'10001' # B'01101' - 11110 - - - ~ B'10001' - 01110 - - - B'10001' << 3 - 01000 - - - B'10001' >> 2 - 00100 - - - -
- shows the available mathematical functions. In the table, dp @@ -2337,6 +2295,130 @@ PostgreSQL documentation + + Bit String Functions and Operators + + + bit strings + functions + + + + This section describes functions and operators for examining and + manipulating bit strings, that is values of the types + bit and bit varying. Aside from the + usual comparison operators, the operators + shown in can be used. + Bit string operands of &, |, + and # must be of equal length. When bit + shifting, the original length of the string is preserved, as shown + in the examples. + + + + Bit String Operators + + + + + Operator + Description + Example + Result + + + + + + || + concatenation + B'10001' || B'011' + 10001011 + + + + & + bitwise AND + B'10001' & B'01101' + 00001 + + + + | + bitwise OR + B'10001' | B'01101' + 11101 + + + + # + bitwise XOR + B'10001' # B'01101' + 11100 + + + + ~ + bitwise NOT + ~ B'10001' + 01110 + + + + << + bitwise shift left + B'10001' << 3 + 01000 + + + + >> + bitwise shift right + B'10001' >> 2 + 00100 + + + +
+ + + The following SQL-standard functions work on bit + strings as well as character strings: + length, + bit_length, + octet_length, + position, + substring. + + + + In addition, it is possible to cast integral values to and from type + bit. + Some examples: + +44::bit(10) 0000101100 +44::bit(3) 100 +cast(-44 as bit(12)) 111111010100 +'1110'::bit(4)::integer 14 + + Note that casting to just bit means casting to + bit(1), and so it will deliver only the least significant + bit of the integer. + + + + + Prior to PostgreSQL 7.5, casting an + integer to bit(n) would copy the leftmost n + bits of the integer, whereas now it copies the rightmost n + bits. Also, casting an integer to a bit string width wider than + the integer itself will sign-extend on the left. + + + + + + Pattern Matching @@ -7628,14 +7710,13 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); bit_and(expression) - smallint, integer, bigint or - bit, + smallint, integer, bigint, or + bit - same as argument data type. - - the bitwise-and of all non-null input values, or null if empty + same as argument data type + the bitwise AND of all non-null input values, or null if none @@ -7646,14 +7727,13 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); bit_or(expression) - smallint, integer, bigint or - bit, + smallint, integer, bigint, or + bit - same as argument data type. - - the bitwise-or of all non-null input values, or null if empty. + same as argument data type + the bitwise OR of all non-null input values, or null if none @@ -7669,9 +7749,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); bool - true if all input values are true, otherwise false. - Also known as bool_and. - + true if all input values are true, otherwise false @@ -7720,9 +7798,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); bool - true if all input values are true, otherwise false. - Also known as bool_and. - + equivalent to bool_and diff --git a/doc/src/sgml/ref/create_cast.sgml b/doc/src/sgml/ref/create_cast.sgml index a6f5e4aa19a..31d2473c350 100644 --- a/doc/src/sgml/ref/create_cast.sgml +++ b/doc/src/sgml/ref/create_cast.sgml @@ -1,4 +1,4 @@ - + @@ -18,7 +18,7 @@ CREATE CAST (sourcetype AS targettype) - WITH FUNCTION funcname (argtype) + WITH FUNCTION funcname (argtypes) [ AS ASSIGNMENT | AS IMPLICIT ] CREATE CAST (sourcetype AS targettype) @@ -55,9 +55,9 @@ SELECT CAST(42 AS text); By default, a cast can be invoked only by an explicit cast request, that is an explicit CAST(x AS - typename), - x::typename, or - typename(x) construct. + typename) or + x::typename + construct. @@ -141,15 +141,14 @@ SELECT 'The time is ' || CAST(now() AS text); - funcname(argtype) + funcname(argtypes) 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 schema search path. The argument type must be - identical to the source type and the result data type must - match the target type of the cast. + up in the schema search path. The function's result data type must + match the target type of the cast. Its arguments are discussed below. @@ -187,6 +186,42 @@ SELECT 'The time is ' || CAST(now() AS text); + + Cast implementation functions may have one to three arguments. + The first argument type must be identical to the cast's source type. + The second argument, + if present, must be type integer; it receives the type + modifier associated with the destination type, or -1 + if there is none. The third argument, + if present, must be type boolean; it receives true + if the cast is an explicit cast, false otherwise. + (Bizarrely, the SQL spec demands different behaviors for explicit and + implicit casts in some cases. This argument is supplied for functions + that must implement such casts. It is not recommended that you design + your own datatypes so that this matters.) + + + + Ordinarily a cast must have different source and target data types. + However, it is allowed to declare a cast with identical source and + target types if it has a cast implementation function with more than one + argument. This is used to represent type-specific length coercion + functions in the system catalogs. The named function is used to + coerce a value of the type to the type modifier value given by its + second argument. (Since the grammar presently permits only certain + built-in data types to have type modifiers, this feature is of no + use for user-defined target types, but we mention it for completeness.) + + + + When a cast has different source and + target types and a function that takes more than one argument, it + represents converting from one type to another and applying a length + coercion in a single step. When no such entry is available, coercion + to a type that uses a type modifier involves two steps, one to + convert between datatypes and a second to apply the modifier. + + @@ -207,10 +242,40 @@ SELECT 'The time is ' || CAST(now() AS text); argument of a different type was automatically a cast function. This convention has been abandoned in face of the introduction of schemas and to be able to represent binary compatible casts in the - system catalogs. (The built-in cast functions still follow this naming - scheme, but they have to be shown as casts in the system catalog pg_cast - now.) + system catalogs. The built-in cast functions still follow this naming + scheme, but they have to be shown as casts in the system catalog + pg_cast as well. + + + + While not required, it is recommended that you continue to follow this old + convention of naming cast implementation functions after the target data + type. Many users are used to being able to cast datatypes using a + function-style notation, that is + typename(x). This notation is in fact + nothing more nor less than a call of the cast implementation function; it + is not specially treated as a cast. If your conversion functions are not + named to support this convention then you will have surprised users. + Since PostgreSQL allows overloading of the same function + name with different argument types, there is no difficulty in having + multiple conversion functions from different types that all use the + target type's name. + + + + There is one small lie in the preceding paragraph: there is still one + case in which pg_cast will be used to resolve the + meaning of an apparent function call. If a + function call name(x) matches no + actual function, but name is the name of a data type + and pg_cast shows a binary-compatible cast to this + type from the type of x, then the call will be construed + as an explicit cast. This exception is made so that binary-compatible + casts can be invoked using functional syntax, even though they lack + any function. + + @@ -234,7 +299,8 @@ CREATE CAST (text AS int4) WITH FUNCTION int4(text); The CREATE CAST command conforms to SQL99, except that SQL99 does not make provisions for binary-compatible - types. AS IMPLICIT is a PostgreSQL + types or extra arguments to implementation functions. + AS IMPLICIT is a PostgreSQL extension, too. diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index 693f6380ef1..b1b5aa13248 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1,5 +1,5 @@ @@ -1319,7 +1319,7 @@ CAST ( expression AS type When a cast is applied to a value expression of a known type, it represents a run-time type conversion. The cast will succeed only - if a suitable type conversion function is available. Notice that this + if a suitable type conversion operation has been defined. Notice that this is subtly different from the use of casts with constants, as shown in . A cast applied to an unadorned string literal represents the initial assignment of a type -- cgit v1.2.3