archived-doc-ru/reference/strings/functions/money-format.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 715a125af5a86f0e6d6d5aa6cfa9c45257a433ac Maintainer: shein Status: ready -->
<!-- Reviewed: no -->
<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> как денежную величину.
   Эта функция вызывает функцию <function>strfmon</function> языка C,
   но позволяет преобразовать только одно число за один вызов.
  </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>
            Строка из десятичных цифр, задающая минимальную ширину поля.
            Поле будет выравнено вправо, если не указан флаг
            <literal>-</literal>. Значение по умолчанию - 0 (ноль).
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
      <formalpara>
       <title>Точность до запятой</title>
       <para>
        <variablelist>
         <varlistentry>
          <term><literal>#</literal><replaceable>n</replaceable></term>
          <listitem>
           <para>
            Максимальное количество цифр (<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>),
            выводимых после запятой.
            Если значение <replaceable>p</replaceable> равно нулю, десятичная
            точка и цифры после неё не будут выводиться.
            Если этот параметр отсутствует, число знаков после запятой
            определяется текущей локалью. Перед форматированием число
            округляется до указанного количества знаков.
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
      <formalpara>
       <title>
        Описатель преобразования
       </title>
       <para>
        <variablelist>
         <varlistentry>
          <term><literal>i</literal></term>
          <listitem>
           <para>
            Используется международный денежный формат из текущей локали
            (например, для американской локали: 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>7.4.0</entry>
       <entry>
        Функция устарела. Вместо неё используйте <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;

// национальный формат США, с использованием скобок для
// отрицательных чисел и 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 = 'Итоговая сумма: %i (после 10%% скидки)';
echo money_format($fmt, 1234.56) . "\n";
// Итоговая сумма: GBP 1,234.56 (после 10% скидки)

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

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Функция <function>money_format</function> определена только если
    в системе присутствует функция strfmon. Например, в Windows она
    отсутствует, поэтому <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
-->