money-format.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 06313c3bb195d974aeba8f4364a6739833b18768 Maintainer: takagi Status: ready -->
<!-- Credits: mumumu -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.money-format">
 <refnamediv>
  <refname>money_format</refname>
  <refpurpose>数値を金額文字列にフォーマットする</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
   &warn.deprecated.function-7-4-0.removed-8-0-0;
 </refsynopsisdiv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>money_format</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam><type>float</type><parameter>number</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>money_format</function> は、<parameter>number</parameter>
   をフォーマットして返します。この関数は C のライブラリ関数
   <function>strfmon</function> をラップしたものですが、一度に
   変換できる数値がひとつだけであるという点が異なります。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       フォーマット指定の書式は以下の順になります。
       <itemizedlist>
        <listitem><para><literal>%</literal> 文字</para></listitem>
        <listitem><para>フラグ(オプション)</para></listitem>
        <listitem><para>フィールドの幅(オプション)</para></listitem>
        <listitem><para>左精度(オプション)</para></listitem>
        <listitem><para>右精度(オプション)</para></listitem>
        <listitem><para>変換文字(必須)</para></listitem>
       </itemizedlist>
      </para>
      <formalpara>
       <title>フラグ</title>
       <para>
       以下のフラグのうちひとつあるいは複数が使用可能です。
        <variablelist>
         <varlistentry>
          <term><literal>=</literal><replaceable>f</replaceable></term>
          <listitem>
           <para>
            文字 <literal>=</literal> の後に続く(シングルバイトの)文字
            <replaceable>f</replaceable> が、数値埋め文字として使用されます。
            デフォルトはスペース文字です。
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>^</literal></term>
          <listitem>
           <para>
            グループ化文字(現在のロケールで定義されている)を使用しないようにします。
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>+</literal> あるいは <literal>(</literal></term>
          <listitem>
           <para>
            正の数、負の数の書式を指定します。<literal>+</literal> が使用された場合、
            <literal>+</literal> および <literal>-</literal> に該当する
            そのロケールの符号マークが使用されます。<literal>(</literal>
            が使用された場合、負の数は括弧で囲まれます。何も指定しなかった場合、
            デフォルトは <literal>+</literal> です。
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>!</literal></term>
          <listitem>
           <para>
            出力文字列から通貨記号を除きます。
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>-</literal></term>
          <listitem>
           <para>
            指定した場合、すべてのフィールドを左詰め(右側に数値埋め文字が追加される)
            にします。デフォルトはこれと反対で、すべてのフィールドを右詰め
            (左側に数値埋め文字が追加される)にします。
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
      <formalpara>
       <title>フィールドの幅</title>
       <para>
        <variablelist>
         <varlistentry>
          <term><replaceable>w</replaceable></term>
          <listitem>
           <para>
            10 進の数値形式の文字列で、フィールドの幅の最小値を指定します。フラグ
            <literal>-</literal> が使用されていない限り、フィールドは
            右詰めとなります。デフォルト値は 0(ゼロ) です。
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
      <formalpara>
       <title>左精度</title>
       <para>
        <variablelist>
         <varlistentry>
          <term><literal>#</literal><replaceable>n</replaceable></term>
          <listitem>
           <para>
            10 進の基準文字(例: 小数点)より左側の最大の桁数
            (<replaceable>n</replaceable>) を指定します。これは通常、
            <replaceable>n</replaceable> より少ない桁数の数値に対して
            数値埋め文字を使用することで、出力の桁位置をそろえるために
            使用されます。実際の桁数が <replaceable>n</replaceable> より
            大きい場合、この設定は無視されます。
           </para>
           <para>
            <literal>^</literal> フラグでグループ化文字が抑止されていない場合、
            (もし存在するなら)数値埋め文字が追加される前にグループ化文字が
            挿入されます。グループ化文字は数値埋め文字には適用されません。
            たとえ数値埋め文字が数字であったとしても同様です。
           </para>
           <para>
            位置あわせを確実にするため、出力中の数値の前後に表れる文字(たとえば
            通貨記号や符号など)は、必要に応じて(正の数と負の数の長さをそろえるなど
            の理由で)スペース文字が付加されることがあります。
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
      <formalpara>
       <title>
        右精度
       </title>
       <para>
        <variablelist>
         <varlistentry>
          <term><literal>.</literal><replaceable>p</replaceable></term>
          <listitem>
           <para>
            ピリオドに続く数値(<replaceable>p</replaceable>)
            で、10 進の基準文字以降の桁数を指定します。
            <replaceable>p</replaceable> の値が 0(ゼロ)であった場合、基準文字と
            それ以降の数値は省略されます。右精度が指定されていない場合、
            使用中の現在のロケールからデフォルト値を検出します。
            フォーマットされる数値は、フォーマット前にこの桁数に丸められます。
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
      <formalpara>
       <title>
        変換文字
       </title>
       <para>
        <variablelist>
         <varlistentry>
          <term><literal>i</literal></term>
          <listitem>
           <para>
            ロケールの国際通貨フォーマット(例: USA ロケールでは
            USD 1,234.56)によってフォーマットします。
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>n</literal></term>
          <listitem>
           <para>
            ロケールの国内通貨フォーマット(例: de_DE ロケールでは
            EU1.234,56) によってフォーマットします。
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>%</literal></term>
          <listitem>
           <para>
            <literal>%</literal> 文字を返します。
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>number</parameter></term>
     <listitem>
      <para>
       フォーマットする数値。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   フォーマットした文字列を返します。
   フォーマット文字列の前後の文字は、そのまま返されます。
   <parameter>number</parameter> が非数値の場合は &null; を返し、
   <constant>E_WARNING</constant> を発行します。
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.0.0</entry>
       <entry>
        &removed.function;
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        &deprecated.function;
        代わりに、<methodname>NumberFormatter::formatCurrency</methodname> を使ってください。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>money_format</function> の例</title>
    <para>
     この関数の使用法を詳しく説明するために、
     さまざまなロケールおよびフォーマット指定を使用します。
    </para>
    <programlisting role="php">
<![CDATA[
<?php

$number = 1234.56;

// en_US ロケールの国際フォーマットで表示します
setlocale(LC_MONETARY, 'en_US');
echo money_format('%i', $number) . "\n";
// USD 1,234.56

// イタリアの国内フォーマットで小数点以下 2 桁で表示します
setlocale(LC_MONETARY, 'it_IT');
echo money_format('%.2n', $number) . "\n";
// Eu 1.234,56

// 負の数を使用します
$number = -1234.5672;

// US の国際フォーマットで、負の数には () を使用して
// 左精度を 10 桁にします
setlocale(LC_MONETARY, 'en_US');
echo money_format('%(#10n', $number) . "\n";
// ($        1,234.57)

// 上と同じですが、それに加えて右精度を 2 桁
// 数値埋め文字として '*' を使用します
echo money_format('%=*(#10.2n', $number) . "\n";
// ($********1,234.57)

// 左詰め、幅 14 桁、左精度 8 桁、右精度 2 桁、グループ化文字なしで
// de_DE ロケールの国際フォーマットを使用します。
setlocale(LC_MONETARY, 'de_DE');
echo money_format('%=*^-14#8.2i', 1234.56) . "\n";
// Eu 1234,56****

// 変換指定の前後に宣伝文句を追加します
setlocale(LC_MONETARY, 'en_GB');
$fmt = 'The final value is %i (after a 10%% discount)';
echo money_format($fmt, 1234.56) . "\n";
// The final value is  GBP 1,234.56 (after a 10% discount)

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    システムで strfmon が使用可能な場合のみ <function>money_format</function>
    関数が定義されます。例えば、Windows では strfmon は使用できません。
    そのため <function>money_format</function> は Windows では
    定義されていません。
   </para>
  </note>
  <note>
   <para>
    ロケール設定のうち、<constant>LC_MONETARY</constant> カテゴリの内容が
    この関数の振る舞いに影響します。この関数を使用する前に、
    <function>setlocale</function> で適切なデフォルトロケールを
    設定してください。
   </para>
  </note>   
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>setlocale</function></member>
    <member><function>sscanf</function></member>
    <member><function>sprintf</function></member>
    <member><function>printf</function></member>
    <member><function>number_format</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
-->