CREATE TABLE users (
    nick CITEXT PRIMARY KEY,
    pass TEXT   NOT NULL
);

INSERT INTO users VALUES ( 'larry',  sha256(random()::text::bytea) );
INSERT INTO users VALUES ( 'Tom',    sha256(random()::text::bytea) );
INSERT INTO users VALUES ( 'Damian', sha256(random()::text::bytea) );
INSERT INTO users VALUES ( 'NEAL',   sha256(random()::text::bytea) );
INSERT INTO users VALUES ( 'Bjørn',  sha256(random()::text::bytea) );

SELECT * FROM users WHERE nick = 'Larry';
</programlisting>

   The <command>SELECT</command> statement will return one tuple, even though
   the <structfield>nick</structfield> column was set to <literal>larry</literal> and the query
   was for <literal>Larry</literal>.
  </para>
 </sect2>

 <sect2 id="citext-string-comparison-behavior">
  <title>String Comparison Behavior</title>

  <para>
   <type>citext</type> performs comparisons by converting each string to lower
   case (as though <function>lower</function> were called) and then comparing the
   results normally.  Thus, for example, two strings are considered equal
   if <function>lower</function> would produce identical results for them.
  </para>

  <para>
   In order to emulate a case-insensitive collation as closely as possible,
   there are <type>citext</type>-specific versions of a number of string-processing
   operators and functions.  So, for example, the regular expression
   operators <literal>~</literal> and <literal>~*</literal> exhibit the same behavior when
   applied to <type>citext</type>: they both match case-insensitively.
   The same is true
   for <literal>!~</literal> and <literal>!~*</literal>, as well as for the
   <literal>LIKE</literal> operators <literal>~~</literal> and <literal>~~*</literal>, and
   <literal>!~~</literal> and <literal>!~~*</literal>. If you'd like to match
   case-sensitively, you can cast the operator's arguments to <type>text</type>.
  </para>

  <para>
   Similarly, all of the following functions perform matching
   case-insensitively if their arguments are <type>citext</type>:
  </para>

  <itemizedlist>
   <listitem>
    <para>
      <function>regexp_match()</function>
    </para>
   </listitem>
   <listitem>
    <para>
      <function>regexp_matches()</function>
    </para>
   </listitem>
   <listitem>
    <para>
      <function>regexp_replace()</function>
    </para>
   </listitem>
   <listitem>
    <para>
      <function>regexp_split_to_array()</function>
    </para>
   </listitem>
   <listitem>
    <para>
      <function>regexp_split_to_table()</function>
    </para>
   </listitem>
   <listitem>
    <para>
      <function>replace()</function>
    </para>
   </listitem>
   <listitem>
    <para>
      <function>split_part()</function>
    </para>
   </listitem>
   <listitem>
    <para>
      <function>strpos()</function>
    </para>
   </listitem>
   <listitem>
    <para>
      <function>translate()</function>
    </para>
   </listitem>
  </itemizedlist>

  <para>
   For the regexp functions, if you want to match case-sensitively, you can
   specify the <quote>c</quote> flag to force a case-sensitive match.  Otherwise,
   you must cast to <type>text</type> before using one of these functions if
   you want case-sensitive behavior.
  </para>

 </sect2>

 <sect2 id="citext-limitations">
  <title>Limitations</title>

   <itemizedlist>
    <listitem>
     <para>
      <type>citext</type>'s case-folding behavior depends on
      the <literal>LC_CTYPE</literal> setting of your database. How it compares
      values is therefore determined when the database is created.
      It is not truly