From 4284002d355b6eaf5eea004cbe25b7fc48956512 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sat, 15 Sep 2001 00:48:59 +0000 Subject: [PATCH] Markup examples as examples. Fix formatting of examples. --- doc/src/sgml/stylesheet.css | 3 +- doc/src/sgml/stylesheet.dsl | 38 +++++- doc/src/sgml/typeconv.sgml | 254 +++++++++++++++++++----------------- 3 files changed, 170 insertions(+), 125 deletions(-) diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css index 77b4fd90fe..d792db7700 100644 --- a/doc/src/sgml/stylesheet.css +++ b/doc/src/sgml/stylesheet.css @@ -1,4 +1,4 @@ -/* $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.css,v 1.1 2001/09/14 20:37:55 petere Exp $ */ +/* $Header: /cvsroot/pgsql/doc/src/sgml/stylesheet.css,v 1.2 2001/09/15 00:48:59 petere Exp $ */ /* color scheme similar to www.postgresql.org */ @@ -38,6 +38,7 @@ DIV.example { border-width: 0px; border-left-width: 2px; border-color: black; + margin: 0.5ex; } /* less dense spacing of TOC */ diff --git a/doc/src/sgml/stylesheet.dsl b/doc/src/sgml/stylesheet.dsl index 4c65604420..5ba9550731 100644 --- a/doc/src/sgml/stylesheet.dsl +++ b/doc/src/sgml/stylesheet.dsl @@ -1,4 +1,4 @@ - + @@ -68,6 +68,42 @@ (define html-index #t) +;; Block elements are allowed in PARA in DocBook, but not in P in +;; HTML. With %fix-para-wrappers% turned on, the stylesheets attempt +;; to avoid putting block elements in HTML P tags by outputting +;; additional end/begin P pairs around them. +(define %fix-para-wrappers% #t) + +;; ...but we need to do some extra work to make the above apply to PRE +;; as well. (mostly pasted from dbverb.dsl) +(define ($verbatim-display$ indent line-numbers?) + (let ((content (make element gi: "PRE" + attributes: (list + (list "CLASS" (gi))) + (if (or indent line-numbers?) + ($verbatim-line-by-line$ indent line-numbers?) + (process-children))))) + (if %shade-verbatim% + (make element gi: "TABLE" + attributes: ($shade-verbatim-attr$) + (make element gi: "TR" + (make element gi: "TD" + content))) + (make sequence + (para-check) + content + (para-check 'restart))))) + +;; ...and for notes. +(element note + (make sequence + (para-check) + ($admonition$) + (para-check 'restart))) + +;;; XXX The above is very ugly. It might be better to run 'tidy' on +;;; the resulting *.html files. + ]]> Type Conversion + + Introduction + SQL queries can, intentionally or not, require mixing of different data types in the same expression. -Postgres has extensive facilities for +PostgreSQL has extensive facilities for evaluating mixed-type expressions. In many cases a user will not need to understand the details of the type conversion mechanism. -However, the implicit conversions done by Postgres +However, the implicit conversions done by PostgreSQL can affect the results of a query. When necessary, these results can be tailored by a user or programmer using explicit type coercion. -This chapter introduces the Postgres +This chapter introduces the PostgreSQL type conversion mechanisms and conventions. -Refer to the relevant sections in the User's Guide and Programmer's Guide +Refer to the relevant sections in the and for more information on specific data types and allowed functions and operators. -The Programmer's Guide has more details on the exact algorithms used for +The Programmer's Guide has more details on the exact algorithms used for implicit type conversion and coercion. + Overview @@ -36,29 +40,29 @@ implicit type conversion and coercion. SQL is a strongly typed language. That is, every data item has an associated data type which determines its behavior and allowed usage. -Postgres has an extensible type system that is +PostgreSQL has an extensible type system that is much more general and flexible than other RDBMS implementations. -Hence, most type conversion behavior in Postgres +Hence, most type conversion behavior in PostgreSQL should be governed by general rules rather than by ad-hoc heuristics to allow mixed-type expressions to be meaningful, even with user-defined types. -The Postgres scanner/parser decodes lexical +The PostgreSQL scanner/parser decodes lexical elements into only five fundamental categories: integers, floats, strings, names, and keywords. Most extended types are first tokenized into strings. The SQL language definition allows specifying type names with strings, and this mechanism can be used in -Postgres to start the parser down the correct +PostgreSQL to start the parser down the correct path. For example, the query - + tgl=> SELECT text 'Origin' AS "Label", point '(0,0)' AS "Value"; Label | Value --------+------- Origin | (0,0) (1 row) - + has two strings, of type text and point. If a type is not specified for a string, then the placeholder type @@ -68,7 +72,7 @@ stages as described below. There are four fundamental SQL constructs requiring -distinct type conversion rules in the Postgres +distinct type conversion rules in the PostgreSQL parser: @@ -79,8 +83,8 @@ Operators -Postgres allows expressions with -left- and right-unary (one argument) operators, +PostgreSQL allows expressions with +prefix and postfix unary (one argument) operators, as well as binary (two argument) operators. @@ -91,12 +95,12 @@ Function calls -Much of the Postgres type system is built around a +Much of the PostgreSQL type system is built around a rich set of functions. Function calls have one or more arguments which, for any specific query, must be matched to the functions available in the system -catalog. Since Postgres permits function +catalog. Since PostgreSQL permits function overloading, the function name alone does not uniquely identify the function -to be called --- the parser must select the right function based on the data +to be called; the parser must select the right function based on the data types of the supplied arguments. @@ -107,7 +111,7 @@ Query targets -SQL INSERT and UPDATE statements place the results of +SQL INSERT and UPDATE statements place the results of expressions into a table. The expressions in the query must be matched up with, and perhaps converted to, the types of the target columns. @@ -115,15 +119,15 @@ with, and perhaps converted to, the types of the target columns. -UNION and CASE constructs +UNION and CASE constructs -Since all select results from a UNION SELECT statement must appear in a single +Since all select results from a unionized SELECT statement must appear in a single set of columns, the types of the results -of each SELECT clause must be matched up and converted to a uniform set. -Similarly, the result expressions of a CASE construct must be coerced to -a common type so that the CASE expression as a whole has a known output type. +of each SELECT clause must be matched up and converted to a uniform set. +Similarly, the result expressions of a CASE construct must be coerced to +a common type so that the CASE expression as a whole has a known output type. @@ -131,14 +135,14 @@ a common type so that the CASE expression as a whole has a known output type. Many of the general type conversion rules use simple conventions built on -the Postgres function and operator system tables. +the PostgreSQL function and operator system tables. There are some heuristics included in the conversion rules to better support -conventions for the SQL92 standard native types such as -smallint, integer, and float. +conventions for the SQL standard native types such as +smallint, integer, and real. -The Postgres parser uses the convention that all +The PostgreSQL parser uses the convention that all type conversion functions take a single argument of the source type and are named with the same name as the target type. Any function meeting these criteria is considered to be a valid conversion function, and may be used @@ -162,9 +166,6 @@ they will raise an error when there are multiple choices for user-defined types. - -Guidelines - All type conversion rules are designed with several principles in mind: @@ -185,7 +186,7 @@ be converted to a user-defined type (of course, only if conversion is necessary) -User-defined types are not related. Currently, Postgres +User-defined types are not related. Currently, PostgreSQL does not have information available to it on relationships between types, other than hardcoded heuristics for built-in types and implicit relationships based on available functions in the catalog. @@ -209,18 +210,25 @@ should use this new function and will no longer do the implicit conversion using - + Operators + + The operand types of an operator invocation are resolved following + to the procedure below. Note that this procedure is indirectly affected + by the precedence of the involved operators. See for more information. + + -Operator Type Resolution +Operand Type Resolution -Check for an exact match in the pg_operator system catalog. +Check for an exact match in the pg_operator system catalog. @@ -299,46 +307,45 @@ then fail. - -Examples +Examples - -Exponentiation Operator + +Exponentiation Operator Type Resolution There is only one exponentiation operator defined in the catalog, and it takes arguments of type double precision. -The scanner assigns an initial type of int4 to both arguments +The scanner assigns an initial type of integer to both arguments of this query expression: - + tgl=> select 2 ^ 3 AS "Exp"; Exp ----- 8 (1 row) - + So the parser does a type conversion on both operands and the query is equivalent to - + tgl=> select CAST(2 AS double precision) ^ CAST(3 AS double precision) AS "Exp"; Exp ----- 8 (1 row) - + or - + tgl=> select 2.0 ^ 3.0 AS "Exp"; Exp ----- 8 (1 row) - + @@ -348,10 +355,10 @@ have an impact on the performance of queries involving large tables. - + - -String Concatenation + +String Concatenation Operator Type Resolution A string-like syntax is used for working with string types as well as for @@ -361,13 +368,13 @@ Strings with unspecified type are matched with likely operator candidates. One unspecified argument: - + tgl=> SELECT text 'abc' || 'def' AS "Text and Unknown"; Text and Unknown ------------------ abcdef (1 row) - + @@ -378,13 +385,13 @@ be interpreted as of type text. Concatenation on unspecified types: - + tgl=> SELECT 'abc' || 'def' AS "Unspecified"; Unspecified ------------- abcdef (1 row) - + @@ -396,26 +403,26 @@ that category is selected, and then the preferred type for strings, text, is used as the specific type to resolve the unknown literals to. - + - -Factorial + +Factorial Operator Type Resolution This example illustrates an interesting result. Traditionally, the -factorial operator is defined for integers only. The Postgres +factorial operator is defined for integers only. The PostgreSQL operator catalog has only one entry for factorial, taking an integer operand. -If given a non-integer numeric argument, Postgres +If given a non-integer numeric argument, PostgreSQL will try to convert that argument to an integer for evaluation of the factorial. - + tgl=> select (4.3 !); ?column? ---------- 24 (1 row) - + @@ -423,20 +430,25 @@ Of course, this leads to a mathematically suspect result, since in principle the factorial of a non-integer is not defined. However, the role of a database is not to teach mathematics, but to be a tool for data manipulation. If a user chooses to take the -factorial of a floating point number, Postgres +factorial of a floating point number, PostgreSQL will try to oblige. - - + + Functions + + The argument types of function calls are resolved according to the + following steps. + + -Function Call Type Resolution +Function Argument Type Resolution @@ -520,38 +532,37 @@ to the named data type. - -Examples +Examples - -Factorial Function + +Factorial Function Argument Type Resolution There is only one factorial function defined in the pg_proc catalog. So the following query automatically converts the int2 argument to int4: - + tgl=> select int4fac(int2 '4'); int4fac --------- 24 (1 row) - + and is actually transformed by the parser to - + tgl=> select int4fac(int4(int2 '4')); int4fac --------- 24 (1 row) - + - + - -Substring Function + +Substring Function Type Resolution There are two substr functions declared in pg_proc. However, @@ -561,34 +572,35 @@ only one takes two arguments, of types text and int4. If called with a string constant of unspecified type, the type is matched up directly with the only candidate function type: - + tgl=> select substr('1234', 3); substr -------- 34 (1 row) - + If the string is declared to be of type varchar, as might be the case if it comes from a table, then the parser will try to coerce it to become text: - + tgl=> select substr(varchar '1234', 3); substr -------- 34 (1 row) - + which is transformed by the parser to become - + tgl=> select substr(text(varchar '1234'), 3); substr -------- 34 (1 row) - + + Actually, the parser is aware that text and varchar @@ -597,30 +609,31 @@ accepts the other without doing any physical conversion. Therefore, no explicit type conversion call is really inserted in this case. + And, if the function is called with an int4, the parser will try to convert that to text: - + tgl=> select substr(1234, 3); substr -------- 34 (1 row) - + actually executes as - + tgl=> select substr(text(1234), 3); substr -------- 34 (1 row) - + This succeeds because there is a conversion function text(int4) in the system catalog. - - + + @@ -654,17 +667,14 @@ passing the column's declared length as the second parameter. - -Examples - - -<type>varchar</type> Storage + +<type>varchar</type> Storage Type Conversion For a target column declared as varchar(4) the following query ensures that the target is sized correctly: - + tgl=> CREATE TABLE vv (v varchar(4)); CREATE tgl=> INSERT INTO vv SELECT 'abc' || 'def'; @@ -674,33 +684,32 @@ tgl=> SELECT * FROM vv; ------ abcd (1 row) - + -What's really happened here is that the two unknown literals are resolved -to text by default, allowing the || operator to be -resolved as text concatenation. Then the text result of the operator +What has really happened here is that the two unknown literals are resolved +to text by default, allowing the || operator to be +resolved as text concatenation. Then the text result of the operator is coerced to varchar to match the target column type. (But, since the -parser knows that text and varchar are binary-compatible, this coercion +parser knows that text and varchar are binary-compatible, this coercion is implicit and does not insert any real function call.) Finally, the -sizing function varchar(varchar,int4) is found in the system +sizing function varchar(varchar, integer) is found in the system catalogs and applied to the operator's result and the stored column length. This type-specific function performs the desired truncation. - - + -UNION and CASE Constructs +<literal>UNION</> and <literal>CASE</> Constructs -The UNION and CASE constructs must match up possibly dissimilar types to +The UNION and CASE constructs must match up possibly dissimilar types to become a single result set. The resolution algorithm is applied separately to -each output column of a UNION. CASE uses the identical algorithm to match +each output column of a union. CASE uses the identical algorithm to match up its result expressions. -UNION and CASE Type Resolution +<literal>UNION</> and <literal>CASE</> Type Resolution @@ -731,48 +740,47 @@ Coerce all inputs to the selected type. - -Examples +Examples - -Underspecified Types + +Underspecified Types in a Union - + tgl=> SELECT text 'a' AS "Text" UNION SELECT 'b'; Text ------ a b (2 rows) - + Here, the unknown-type literal 'b' will be resolved as type text. - + - -Simple UNION + +Type Conversion in a Simple Union - + tgl=> SELECT 1.2 AS "Double" UNION SELECT 1; Double -------- 1 1.2 (2 rows) - + - + - -Transposed UNION + +Type Conversion in a Transposed Union Here the output type of the union is forced to match the type of the first/top clause in the union: - + tgl=> SELECT 1 AS "All integers" tgl-> UNION SELECT CAST('2.2' AS REAL); All integers @@ -780,7 +788,7 @@ tgl-> UNION SELECT CAST('2.2' AS REAL); 1 2 (2 rows) - + Since REAL is not a preferred type, the parser sees no reason @@ -788,11 +796,11 @@ to select it over INTEGER (which is what the 1 is), and instead falls back on the use-the-first-alternative rule. This example demonstrates that the preferred-type mechanism doesn't encode as much information as we'd like. Future versions of -Postgres may support a more general notion of +PostgreSQL may support a more general notion of type preferences. - - + +