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

Commit ffea8fd

Browse files
committed
Update citext's documentation to match the recently-applied patch,
per David Wheeler.
1 parent bf0b6ac commit ffea8fd

File tree

1 file changed

+68
-66
lines changed

1 file changed

+68
-66
lines changed

doc/src/sgml/citext.sgml

+68-66
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/citext.sgml,v 1.1 2008/07/29 18:31:20 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/citext.sgml,v 1.2 2008/09/12 18:29:49 tgl Exp $ -->
22

33
<sect1 id="citext">
44
<title>citext</title>
@@ -95,6 +95,73 @@
9595
</para>
9696
</sect2>
9797

98+
<sect2>
99+
<title>String Comparison Behavior</title>
100+
<para>
101+
In order to emulate a case-insensitive collation as closely as possible,
102+
there are <type>citext</>-specific versions of a number of the comparison
103+
operators and functions. So, for example, the regular expression
104+
operators <literal>~</> and <literal>~*</> exhibit the same behavior when
105+
applied to <type>citext</>: they both compare case-insensitively.
106+
The same is true
107+
for <literal>!~</> and <literal>!~*</>, as well as for the
108+
<literal>LIKE</> operators <literal>~~</> and <literal>~~*</>, and
109+
<literal>!~~</> and <literal>!~~*</>. If you'd like to match
110+
case-sensitively, you can always cast to <type>text</> before comparing.
111+
</para>
112+
113+
<para>
114+
Similarly, all of the following functions perform matching
115+
case-insensitively if their arguments are <type>citext</>:
116+
</para>
117+
118+
<itemizedlist>
119+
<listitem>
120+
<para>
121+
<function>regexp_replace()</>
122+
</para>
123+
</listitem>
124+
<listitem>
125+
<para>
126+
<function>regexp_split_to_array()</>
127+
</para>
128+
</listitem>
129+
<listitem>
130+
<para>
131+
<function>regexp_split_to_table()</>
132+
</para>
133+
</listitem>
134+
<listitem>
135+
<para>
136+
<function>replace()</>
137+
</para>
138+
</listitem>
139+
<listitem>
140+
<para>
141+
<function>split_part()</>
142+
</para>
143+
</listitem>
144+
<listitem>
145+
<para>
146+
<function>strpos()</>
147+
</para>
148+
</listitem>
149+
<listitem>
150+
<para>
151+
<function>translate()</>
152+
</para>
153+
</listitem>
154+
</itemizedlist>
155+
156+
<para>
157+
For the regexp functions, if you want to match case-sensitively, you can
158+
specify the <quote>c</> flag to force a case-sensitive match. Otherwise,
159+
you must cast to <type>text</> before using one of these functions if
160+
you want case-sensitive behavior.
161+
</para>
162+
163+
</sect2>
164+
98165
<sect2>
99166
<title>Limitations</title>
100167

@@ -114,60 +181,6 @@
114181
</para>
115182
</listitem>
116183

117-
<listitem>
118-
<para>
119-
The pattern-matching comparison operators, such as <literal>LIKE</>,
120-
<literal>~</>, <literal>~~</>, <literal>!~</>, <literal>!~~</>, etc.,
121-
have been overloaded to make case-insensitive comparisons when their
122-
left-hand argument is of type <type>citext</>. However, related
123-
functions have not been changed, including:
124-
</para>
125-
126-
<itemizedlist>
127-
<listitem>
128-
<para>
129-
<function>regexp_replace()</>
130-
</para>
131-
</listitem>
132-
<listitem>
133-
<para>
134-
<function>regexp_split_to_array()</>
135-
</para>
136-
</listitem>
137-
<listitem>
138-
<para>
139-
<function>regexp_split_to_table()</>
140-
</para>
141-
</listitem>
142-
<listitem>
143-
<para>
144-
<function>replace()</>
145-
</para>
146-
</listitem>
147-
<listitem>
148-
<para>
149-
<function>split_part()</>
150-
</para>
151-
</listitem>
152-
<listitem>
153-
<para>
154-
<function>strpos()</>
155-
</para>
156-
</listitem>
157-
<listitem>
158-
<para>
159-
<function>translate()</>
160-
</para>
161-
</listitem>
162-
</itemizedlist>
163-
164-
<para>
165-
Of course, for the regular expression functions, you can specify
166-
case-insensitive comparisons in their <parameter>flags</> arguments, but
167-
the same cannot be done for the the non-regexp functions.
168-
</para>
169-
</listitem>
170-
171184
<listitem>
172185
<para>
173186
<type>citext</> is not as efficient as <type>text</> because the
@@ -178,17 +191,6 @@
178191
</para>
179192
</listitem>
180193

181-
<listitem>
182-
<para>
183-
<productname>PostgreSQL</> supports casting between <type>text</>
184-
and any other type (even non-string types) by using the other type's
185-
I/O functions. This doesn't work with <type>citext</>. However,
186-
you can cast via I/O functions in two steps, for example
187-
<literal><replaceable>somevalue</>::text::citext</literal> or
188-
<literal><replaceable>citextvalue</>::text::<replaceable>sometype</></literal>.
189-
</para>
190-
</listitem>
191-
192194
<listitem>
193195
<para>
194196
<type>citext</> doesn't help much if you need data to compare

0 commit comments

Comments
 (0)