compose-locale.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="locale.composelocale" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>Locale::composeLocale</refname>
  <refname>locale_compose</refname>
  <refpurpose>Returns a correctly ordered and delimited locale ID</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>
   &style.oop;
  </para>
  <methodsynopsis role="Locale">
   <modifier>public</modifier> <modifier>static</modifier> <type class="union"><type>string</type><type>false</type></type><methodname>Locale::composeLocale</methodname>
   <methodparam><type>array</type><parameter>subtags</parameter></methodparam>
  </methodsynopsis>
  <para>
   &style.procedural;
  </para>
  <methodsynopsis>
   <type class="union"><type>string</type><type>false</type></type><methodname>locale_compose</methodname>
   <methodparam><type>array</type><parameter>subtags</parameter></methodparam>
  </methodsynopsis>
  <para>
   Returns a correctly ordered and delimited locale ID the keys identify the
   particular locale ID subtags, and the values are the associated subtag
   values.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>subtags</parameter></term>
     <listitem>
      <para>
       An &array; containing a list of key-value pairs, where the keys identify
       the particular locale ID subtags, and the values are the associated
       subtag values.
       <note>
        <para>
         The <literal>'variant'</literal> and <literal>'private'</literal> subtags can take maximum 15 values
         whereas <literal>'extlang'</literal> can take maximum 3 values. For instance, variants are allowed
         with the suffix ranging from 0-14. Hence the keys for the input array
         can be <literal>variant0</literal>, <literal>variant1</literal>, …,<literal>variant14</literal>. In the returned locale id,
         the subtag is ordered by suffix resulting in <literal>variant0</literal> followed by
         <literal>variant1</literal> followed by <literal>variant2</literal> and so on.
        </para>
        <para>
         Alternatively, the <literal>'variant'</literal>, <literal>'private'</literal> and <literal>'extlang'</literal> values can be specified
         as array under specific key (e.g. <literal>'variant'</literal>).
         In this case no limits on the number of recognized subtags apply.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>


 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   The corresponding locale identifier, or &false; when <parameter>subtags</parameter> is empty.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>locale_compose</function> example</title>
   <programlisting role="php">
    <![CDATA[
<?php
$arr = array(
    'language'=>'en',
    'script'  =>'Hans',
    'region'  =>'CN',
    'variant2'=>'rozaj',
    'variant1'=>'nedis',
    'private1'=>'prv1',
    'private2'=>'prv2',
);
echo locale_compose($arr);
?>
]]>
   </programlisting>
  </example>
  <example>
   <title>OO example</title>
   <programlisting role="php">
<![CDATA[
<?php
$arr = array(
    'language'=>'en' ,
    'script'  =>'Hans',
    'region'  =>'CN',
    'variant2'=>'rozaj',
    'variant1'=>'nedis',
    'private1'=>'prv1',
    'private2'=>'prv2',
);
echo Locale::composeLocale($arr);
?>
]]>
   </programlisting>
  </example>
  &example.outputs;
  <screen>
<![CDATA[
Locale: en_Hans_CN_nedis_rozaj_x_prv1_prv2
]]>
  </screen>

  <example xml:id="locale.composelocale.example.limits">
   <title>Subtag limits</title>
   <para>
    If <parameter>subtags</parameter> are given as separate keys with numeric suffix,
    unsupported keys are silently ignored (in this case <literal>'extlang3'</literal>),
    and ordered in the result by numeric suffix.
    There are no limits, if subtags are given as &array;; the order is as given.
   </para>
   <programlisting role="php">
    <![CDATA[
<?php
$arr = array(
    'language' => 'en',
    'script'   => 'Hans',
    'region'   => 'CN',
    'extlang3' => 'd',
    'extlang2' => 'c',
    'extlang1' => 'b',
    'extlang0' => 'a',
);
echo locale_compose($arr), PHP_EOL;

$arr = array(
    'language' => 'en',
    'script'   => 'Hans',
    'region'   => 'CN',
    'extlang'  => ['a', 'b', 'c', 'd'],
);
echo locale_compose($arr), PHP_EOL;
?>
]]>
   </programlisting>
  </example>
  &example.outputs;
  <screen>
<![CDATA[
en_a_b_c_Hans_CN
en_a_b_c_d_Hans_CN
]]>
  </screen>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>locale_parse</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
-->