<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="collator.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>Collator::__construct</refname>
  <refpurpose>Create a collator</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <constructorsynopsis>
   <modifier>public</modifier> <methodname>Collator::__construct</methodname>
   <methodparam><type>string</type><parameter>locale</parameter></methodparam>
  </constructorsynopsis>
  <para>
   Creates a new instance of Collator.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>locale</parameter></term>
     <listitem>
      <para>
       The locale whose collation rules should be used. Special values for
       locales can be passed in - if null is passed for the locale, the
       default locale collation rules will be used. If empty string ("") or
       "root" are passed, UCA rules will be used.
      </para>
      <para>
       The Locale attribute is typically the most important attribute for
       correct sorting and matching, according to the user expectations in
       different countries and regions. The default
       <link xlink:href="&url.icu.uca;">UCA</link>
       ordering will only sort a few languages such as Dutch and Portuguese
       correctly ("correctly" meaning according to the normal expectations for
       users of the languages). Otherwise, you need to supply the locale to
       UCA in order to properly collate text for a given language. Thus a
       locale needs to be supplied so as to choose a collator that is
       correctly tailored for that locale. The choice of a locale will
       automatically preset the values for all of the attributes to something
       that is reasonable for that locale. Thus most of the time the other
       attributes do not need to be explicitly set. In some cases, the choice
       of locale will make a difference in string comparison performance
       and/or sort key length.
       <!--
        In short attribute names,
        &lt;language&gt;_&lt;script&gt;_&lt;region&gt;_&lt;keyword&gt;
        is represented by:
        L&lt;language&gt;_Z&lt;script&gt;_R&lt;region&gt;_V&lt;variant&gt;_K&lt;keyword&gt;.
        for <emphasis>RFC4646</emphasis> locale naming.
        
        <example><title>Locale format</title>
        Example:
        Locale="sv" (Swedish) "Kypper" &lt; "Köpfe"
        Locale="de" (German) "Köpfe" &lt; "Kypper"
        </example>
       -->
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns Collator instance.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Returns an "empty" object on error. You can use
   <function>intl_get_error_code</function>
   and/or
   <function>intl_get_error_message</function>
   to know what happened.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>Collator::__construct</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$coll = new Collator( 'en_CA' );
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>Collator::create</function></member>
    <member><function>collator_create</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-omittag:t
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
 sgml-indent-step:1
 sgml-indent-data:t
 indent-tabs-mode:nil
 sgml-parent-document:nil
 sgml-default-dtd-file:"~/.phpdoc/manual.ced"
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
 vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
-->