rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update citext's documentation to match the recently-applied patch, 

per David Wheeler.
This commit is contained in:
Tom Lane 2008-09-12 18:29:49 +00:00
parent bf0b6ac43c
commit ffea8fd381
1 changed files with 68 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
doc/src/sgml/citext.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/citext.sgml,v 1.1 2008/07/29 18:31:20 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/citext.sgml,v 1.2 2008/09/12 18:29:49 tgl Exp $ -->
<sect1 id="citext">
<title>citext</title>
@ -95,6 +95,73 @@
</para>
</sect2>
<sect2>
<title>String Comparison Behavior</title>
<para>
In order to emulate a case-insensitive collation as closely as possible,
there are <type>citext</>-specific versions of a number of the comparison
operators and functions. So, for example, the regular expression
operators <literal>~</> and <literal>~*</> exhibit the same behavior when
applied to <type>citext</>: they both compare case-insensitively.
The same is true
for <literal>!~</> and <literal>!~*</>, as well as for the
<literal>LIKE</> operators <literal>~~</> and <literal>~~*</>, and
<literal>!~~</> and <literal>!~~*</>. If you'd like to match
case-sensitively, you can always cast to <type>text</> before comparing.
</para>
<para>
Similarly, all of the following functions perform matching
case-insensitively if their arguments are <type>citext</>:
</para>
<itemizedlist>
<listitem>
<para>
<function>regexp_replace()</>
</para>
</listitem>
<listitem>
<para>
<function>regexp_split_to_array()</>
</para>
</listitem>
<listitem>
<para>
<function>regexp_split_to_table()</>
</para>
</listitem>
<listitem>
<para>
<function>replace()</>
</para>
</listitem>
<listitem>
<para>
<function>split_part()</>
</para>
</listitem>
<listitem>
<para>
<function>strpos()</>
</para>
</listitem>
<listitem>
<para>
<function>translate()</>
</para>
</listitem>
</itemizedlist>
<para>
For the regexp functions, if you want to match case-sensitively, you can
specify the <quote>c</> flag to force a case-sensitive match. Otherwise,
you must cast to <type>text</> before using one of these functions if
you want case-sensitive behavior.
</para>
</sect2>
<sect2>
<title>Limitations</title>
@ -114,60 +181,6 @@
</para>
</listitem>
<listitem>
<para>
The pattern-matching comparison operators, such as <literal>LIKE</>,
<literal>~</>, <literal>~~</>, <literal>!~</>, <literal>!~~</>, etc.,
have been overloaded to make case-insensitive comparisons when their
left-hand argument is of type <type>citext</>. However, related
functions have not been changed, including:
</para>
<itemizedlist>
<listitem>
<para>
<function>regexp_replace()</>
</para>
</listitem>
<listitem>
<para>
<function>regexp_split_to_array()</>
</para>
</listitem>
<listitem>
<para>
<function>regexp_split_to_table()</>
</para>
</listitem>
<listitem>
<para>
<function>replace()</>
</para>
</listitem>
<listitem>
<para>
<function>split_part()</>
</para>
</listitem>
<listitem>
<para>
<function>strpos()</>
</para>
</listitem>
<listitem>
<para>
<function>translate()</>
</para>
</listitem>
</itemizedlist>
<para>
Of course, for the regular expression functions, you can specify
case-insensitive comparisons in their <parameter>flags</> arguments, but
the same cannot be done for the the non-regexp functions.
</para>
</listitem>
<listitem>
<para>
<type>citext</> is not as efficient as <type>text</> because the
@ -178,17 +191,6 @@
</para>
</listitem>
<listitem>
<para>
<productname>PostgreSQL</> supports casting between <type>text</>
and any other type (even non-string types) by using the other type's
I/O functions. This doesn't work with <type>citext</>. However,
you can cast via I/O functions in two steps, for example
<literal><replaceable>somevalue</>::text::citext</literal> or
<literal><replaceable>citextvalue</>::text::<replaceable>sometype</></literal>.
</para>
</listitem>
<listitem>
<para>
<type>citext</> doesn't help much if you need data to compare