Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit d70a42e

Browse files
tglsfdctglsfdc
committed
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.
1 parent 8e7349b commit d70a42e

23 files changed

+788
-465
lines changed

‎doc/src/sgml/catalogs.sgml

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<!--
22
Documentation of the system catalogs, directed toward PostgreSQL developers
3-
$PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.86 2004/06/07 04:04:47 tgl Exp $
3+
$PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.87 2004/06/16 01:26:33 tgl Exp $
44
-->
55

66
<chapter id="catalogs">
@@ -934,7 +934,7 @@
934934
<entry>
935935
Indicates what contexts the cast may be invoked in.
936936
<literal>e</> means only as an explicit cast (using
937-
<literal>CAST</>, <literal>::</>, or function-call syntax).
937+
<literal>CAST</> or <literal>::</> syntax).
938938
<literal>a</> means implicitly in assignment
939939
to a target column, as well as explicitly.
940940
<literal>i</> means implicitly in expressions, as well as the
@@ -944,6 +944,39 @@
944944
</tbody>
945945
</tgroup>
946946
</table>
947+
948+
<para>
949+
The cast functions listed in <structname>pg_cast</structname> must
950+
always take the cast source type as their first argument type, and
951+
return the cast destination type as their result type. A cast
952+
function can have up to three arguments. The second argument,
953+
if present, must be type <type>integer</>; it receives the type
954+
modifier associated with the destination type, or <literal>-1</>
955+
if there is none. The third argument,
956+
if present, must be type <type>boolean</>; it receives <literal>true</>
957+
if the cast is an explicit cast, <literal>false</> otherwise.
958+
</para>
959+
960+
<para>
961+
It is legitimate to create a <structname>pg_cast</structname> entry
962+
in which the source and target types are the same, if the associated
963+
function takes more than one argument. Such entries represent
964+
<quote>length coercion functions</> that coerce values of the type
965+
to be legal for a particular type modifier value. Note however that
966+
at present there is no support for associating non-default type
967+
modifiers with user-created data types, and so this facility is only
968+
of use for the small number of built-in types that have type modifier
969+
syntax built into the grammar.
970+
</para>
971+
972+
<para>
973+
When a <structname>pg_cast</structname> entry has different source and
974+
target types and a function that takes more than one argument, it
975+
represents converting from one type to another and applying a length
976+
coercion in a single step. When no such entry is available, coercion
977+
to a type that uses a type modifier involves two steps, one to
978+
convert between datatypes and a second to apply the modifier.
979+
</para>
947980
</sect1>
948981

949982
<sect1 id="catalog-pg-class">

‎doc/src/sgml/datatype.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.145 2004/06/07 04:04:47 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.146 2004/06/16 01:26:35 tgl Exp $
33
-->
44

55
<chapter id="datatype">
@@ -2851,7 +2851,7 @@ SELECT * FROM test1 WHERE a;
28512851
linkend="sql-syntax-bit-strings"> for information about the syntax
28522852
of bit string constants. Bit-logical operators and string
28532853
manipulation functions are available; see <xref
2854-
linkend="functions">.
2854+
linkend="functions-bitstring">.
28552855
</para>
28562856

28572857
<example>

‎doc/src/sgml/func.sgml

Lines changed: 139 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.208 2004/06/14 19:01:09 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.209 2004/06/16 01:26:36 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -488,55 +488,13 @@ PostgreSQL documentation
488488
</table>
489489

490490
<para>
491-
The bitwise operators are also available for the bit
491+
The bitwise operators work only on integral data types, whereas
492+
the others are available for all numeric data types. The bitwise
493+
operators are also available for the bit
492494
string types <type>bit</type> and <type>bit varying</type>, as
493-
shown in <xref linkend="functions-math-bit-table">.
494-
Bit string operands of <literal>&amp;</literal>, <literal>|</literal>,
495-
and <literal>#</literal> must be of equal length. When bit
496-
shifting, the original length of the string is preserved, as shown
497-
in the table.
495+
shown in <xref linkend="functions-bit-string-op-table">.
498496
</para>
499497

500-
<table id="functions-math-bit-table">
501-
<title>Bit String Bitwise Operators</title>
502-
503-
<tgroup cols="2">
504-
<thead>
505-
<row>
506-
<entry>Example</entry>
507-
<entry>Result</entry>
508-
</row>
509-
</thead>
510-
511-
<tbody>
512-
<row>
513-
<entry><literal>B'10001' &amp; B'01101'</literal></entry>
514-
<entry><literal>00001</literal></entry>
515-
</row>
516-
<row>
517-
<entry><literal>B'10001' | B'01101'</literal></entry>
518-
<entry><literal>11101</literal></entry>
519-
</row>
520-
<row>
521-
<entry><literal>B'10001' # B'01101'</literal></entry>
522-
<entry><literal>11110</literal></entry>
523-
</row>
524-
<row>
525-
<entry><literal>~ B'10001'</literal></entry>
526-
<entry><literal>01110</literal></entry>
527-
</row>
528-
<row>
529-
<entry><literal>B'10001' &lt;&lt; 3</literal></entry>
530-
<entry><literal>01000</literal></entry>
531-
</row>
532-
<row>
533-
<entry><literal>B'10001' &gt;&gt; 2</literal></entry>
534-
<entry><literal>00100</literal></entry>
535-
</row>
536-
</tbody>
537-
</tgroup>
538-
</table>
539-
540498
<para>
541499
<xref linkend="functions-math-func-table"> shows the available
542500
mathematical functions. In the table, <literal>dp</literal>
@@ -2337,6 +2295,130 @@ PostgreSQL documentation
23372295
</sect1>
23382296

23392297

2298+
<sect1 id="functions-bitstring">
2299+
<title>Bit String Functions and Operators</title>
2300+
2301+
<indexterm zone="functions-bitstring">
2302+
<primary>bit strings</primary>
2303+
<secondary>functions</secondary>
2304+
</indexterm>
2305+
2306+
<para>
2307+
This section describes functions and operators for examining and
2308+
manipulating bit strings, that is values of the types
2309+
<type>bit</type> and <type>bit varying</type>. Aside from the
2310+
usual comparison operators, the operators
2311+
shown in <xref linkend="functions-bit-string-op-table"> can be used.
2312+
Bit string operands of <literal>&amp;</literal>, <literal>|</literal>,
2313+
and <literal>#</literal> must be of equal length. When bit
2314+
shifting, the original length of the string is preserved, as shown
2315+
in the examples.
2316+
</para>
2317+
2318+
<table id="functions-bit-string-op-table">
2319+
<title>Bit String Operators</title>
2320+
2321+
<tgroup cols="4">
2322+
<thead>
2323+
<row>
2324+
<entry>Operator</entry>
2325+
<entry>Description</entry>
2326+
<entry>Example</entry>
2327+
<entry>Result</entry>
2328+
</row>
2329+
</thead>
2330+
2331+
<tbody>
2332+
<row>
2333+
<entry> <literal>||</literal> </entry>
2334+
<entry>concatenation</entry>
2335+
<entry><literal>B'10001' || B'011'</literal></entry>
2336+
<entry><literal>10001011</literal></entry>
2337+
</row>
2338+
2339+
<row>
2340+
<entry> <literal>&amp;</literal> </entry>
2341+
<entry>bitwise AND</entry>
2342+
<entry><literal>B'10001' &amp; B'01101'</literal></entry>
2343+
<entry><literal>00001</literal></entry>
2344+
</row>
2345+
2346+
<row>
2347+
<entry> <literal>|</literal> </entry>
2348+
<entry>bitwise OR</entry>
2349+
<entry><literal>B'10001' | B'01101'</literal></entry>
2350+
<entry><literal>11101</literal></entry>
2351+
</row>
2352+
2353+
<row>
2354+
<entry> <literal>#</literal> </entry>
2355+
<entry>bitwise XOR</entry>
2356+
<entry><literal>B'10001' # B'01101'</literal></entry>
2357+
<entry><literal>11100</literal></entry>
2358+
</row>
2359+
2360+
<row>
2361+
<entry> <literal>~</literal> </entry>
2362+
<entry>bitwise NOT</entry>
2363+
<entry><literal>~ B'10001'</literal></entry>
2364+
<entry><literal>01110</literal></entry>
2365+
</row>
2366+
2367+
<row>
2368+
<entry> <literal>&lt;&lt;</literal> </entry>
2369+
<entry>bitwise shift left</entry>
2370+
<entry><literal>B'10001' &lt;&lt; 3</literal></entry>
2371+
<entry><literal>01000</literal></entry>
2372+
</row>
2373+
2374+
<row>
2375+
<entry> <literal>&gt;&gt;</literal> </entry>
2376+
<entry>bitwise shift right</entry>
2377+
<entry><literal>B'10001' &gt;&gt; 2</literal></entry>
2378+
<entry><literal>00100</literal></entry>
2379+
</row>
2380+
</tbody>
2381+
</tgroup>
2382+
</table>
2383+
2384+
<para>
2385+
The following <acronym>SQL</acronym>-standard functions work on bit
2386+
strings as well as character strings:
2387+
<literal><function>length</function></literal>,
2388+
<literal><function>bit_length</function></literal>,
2389+
<literal><function>octet_length</function></literal>,
2390+
<literal><function>position</function></literal>,
2391+
<literal><function>substring</function></literal>.
2392+
</para>
2393+
2394+
<para>
2395+
In addition, it is possible to cast integral values to and from type
2396+
<type>bit</>.
2397+
Some examples:
2398+
<programlisting>
2399+
44::bit(10) <lineannotation>0000101100</lineannotation>
2400+
44::bit(3) <lineannotation>100</lineannotation>
2401+
cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
2402+
'1110'::bit(4)::integer <lineannotation>14</lineannotation>
2403+
</programlisting>
2404+
Note that casting to just <quote>bit</> means casting to
2405+
<literal>bit(1)</>, and so it will deliver only the least significant
2406+
bit of the integer.
2407+
</para>
2408+
2409+
<note>
2410+
<para>
2411+
Prior to <productname>PostgreSQL</productname> 7.5, casting an
2412+
integer to <type>bit(n)</> would copy the leftmost <literal>n</>
2413+
bits of the integer, whereas now it copies the rightmost <literal>n</>
2414+
bits. Also, casting an integer to a bit string width wider than
2415+
the integer itself will sign-extend on the left.
2416+
</para>
2417+
</note>
2418+
2419+
</sect1>
2420+
2421+
23402422
<sect1 id="functions-matching">
23412423
<title>Pattern Matching</title>
23422424

@@ -7628,14 +7710,13 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
76287710
<function>bit_and(<replaceable class="parameter">expression</replaceable>)</function>
76297711
</entry>
76307712
<entry>
7631-
<type>smallint</type>, <type>integer</type>, <type>bigint</type> or
7632-
<type>bit</type>,
7713+
<type>smallint</type>, <type>integer</type>, <type>bigint</type>, or
7714+
<type>bit</type>
76337715
</entry>
76347716
<entry>
7635-
same as argument data type.
7636-
</entry>
7637-
<entry>the bitwise-and of all non-null input values, or null if empty
7717+
same as argument data type
76387718
</entry>
7719+
<entry>the bitwise AND of all non-null input values, or null if none</entry>
76397720
</row>
76407721

76417722
<row>
@@ -7646,14 +7727,13 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
76467727
<function>bit_or(<replaceable class="parameter">expression</replaceable>)</function>
76477728
</entry>
76487729
<entry>
7649-
<type>smallint</type>, <type>integer</type>, <type>bigint</type> or
7650-
<type>bit</type>,
7730+
<type>smallint</type>, <type>integer</type>, <type>bigint</type>, or
7731+
<type>bit</type>
76517732
</entry>
76527733
<entry>
7653-
same as argument data type.
7654-
</entry>
7655-
<entry>the bitwise-or of all non-null input values, or null if empty.
7734+
same as argument data type
76567735
</entry>
7736+
<entry>the bitwise OR of all non-null input values, or null if none</entry>
76577737
</row>
76587738

76597739
<row>
@@ -7669,9 +7749,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
76697749
<entry>
76707750
<type>bool</type>
76717751
</entry>
7672-
<entry>true if all input values are true, otherwise false.
7673-
Also known as <function>bool_and</function>.
7674-
</entry>
7752+
<entry>true if all input values are true, otherwise false</entry>
76757753
</row>
76767754

76777755
<row>
@@ -7720,9 +7798,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
77207798
<entry>
77217799
<type>bool</type>
77227800
</entry>
7723-
<entry>true if all input values are true, otherwise false.
7724-
Also known as <function>bool_and</function>.
7725-
</entry>
7801+
<entry>equivalent to <function>bool_and</function></entry>
77267802
</row>
77277803

77287804
<row>

0 commit comments

Comments
 (0)