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

74
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"> <sect1 id="citext">
<title>citext</title> <title>citext</title>
@ -96,31 +96,23 @@
</sect2> </sect2>
<sect2> <sect2>
<title>Limitations</title> <title>String Comparison Behavior</title>
<itemizedlist>
<listitem>
<para> <para>
<type>citext</>'s behavior depends on In order to emulate a case-insensitive collation as closely as possible,
the <literal>LC_CTYPE</> setting of your database. How it compares there are <type>citext</>-specific versions of a number of the comparison
values is therefore determined when operators and functions. So, for example, the regular expression
<application>initdb</> is run to create the cluster. It is not truly operators <literal>~</> and <literal>~*</> exhibit the same behavior when
case-insensitive in the terms defined by the Unicode standard. applied to <type>citext</>: they both compare case-insensitively.
Effectively, what this means is that, as long as you're happy with your The same is true
collation, you should be happy with <type>citext</>'s comparisons. But for <literal>!~</> and <literal>!~*</>, as well as for the
if you have data in different languages stored in your database, users <literal>LIKE</> operators <literal>~~</> and <literal>~~*</>, and
of one language may find their query results are not as expected if the <literal>!~~</> and <literal>!~~*</>. If you'd like to match
collation is for another language. case-sensitively, you can always cast to <type>text</> before comparing.
</para> </para>
</listitem>
<listitem>
<para> <para>
The pattern-matching comparison operators, such as <literal>LIKE</>, Similarly, all of the following functions perform matching
<literal>~</>, <literal>~~</>, <literal>!~</>, <literal>!~~</>, etc., case-insensitively if their arguments are <type>citext</>:
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> </para>
<itemizedlist> <itemizedlist>
@ -162,9 +154,30 @@
</itemizedlist> </itemizedlist>
<para> <para>
Of course, for the regular expression functions, you can specify For the regexp functions, if you want to match case-sensitively, you can
case-insensitive comparisons in their <parameter>flags</> arguments, but specify the <quote>c</> flag to force a case-sensitive match. Otherwise,
the same cannot be done for the the non-regexp functions. you must cast to <type>text</> before using one of these functions if
you want case-sensitive behavior.
</para>
</sect2>
<sect2>
<title>Limitations</title>
<itemizedlist>
<listitem>
<para>
<type>citext</>'s behavior depends on
the <literal>LC_CTYPE</> setting of your database. How it compares
values is therefore determined when
<application>initdb</> is run to create the cluster. It is not truly
case-insensitive in the terms defined by the Unicode standard.
Effectively, what this means is that, as long as you're happy with your
collation, you should be happy with <type>citext</>'s comparisons. But
if you have data in different languages stored in your database, users
of one language may find their query results are not as expected if the
collation is for another language.
</para> </para>
</listitem> </listitem>
@ -178,17 +191,6 @@
</para> </para>
</listitem> </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> <listitem>
<para> <para>
<type>citext</> doesn't help much if you need data to compare <type>citext</> doesn't help much if you need data to compare