mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-27 14:28:56 +00:00
ed67b3c502
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@283839 c90b9560-bf6c-de11-be94-00142212c4b1
343 lines
11 KiB
XML
343 lines
11 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.money-format">
|
|
<refnamediv>
|
|
<refname>money_format</refname>
|
|
<refpurpose>Formats a number as a currency string</refpurpose>
|
|
</refnamediv>
|
|
|
|
<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> returns a formatted version of
|
|
<parameter>number</parameter>. This function wraps the C library
|
|
function <function>strfmon</function>, with the difference that
|
|
this implementation converts only one number at a time.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>format</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The format specification consists of the following sequence:
|
|
<itemizedlist>
|
|
<listitem><para>a <literal>%</literal> character</para></listitem>
|
|
<listitem><para>optional flags</para></listitem>
|
|
<listitem><para>optional field width</para></listitem>
|
|
<listitem><para>optional left precision</para></listitem>
|
|
<listitem><para>optional right precision</para></listitem>
|
|
<listitem><para>a required conversion character</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<formalpara>
|
|
<title>Flags</title>
|
|
<para>
|
|
One or more of the optional flags below can be used:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>=</literal><replaceable>f</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The character <literal>=</literal> followed by a (single byte)
|
|
character <replaceable>f</replaceable> to be used as the numeric fill
|
|
character. The default fill character is space.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>^</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Disable the use of grouping characters (as defined
|
|
by the current locale).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>+</literal> or <literal>(</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Specify the formatting style for positive and negative numbers.
|
|
If <literal>+</literal> is used, the locale's equivalent for
|
|
<literal>+</literal> and <literal>-</literal> will be used. If
|
|
<literal>(</literal> is used, negative amounts are enclosed in
|
|
parenthesis. If no specification is given, the default is
|
|
<literal>+</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>!</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Suppress the currency symbol from the output string.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>-</literal></term>
|
|
<listitem>
|
|
<para>
|
|
If present, it will make all fields left-justified (padded to the
|
|
right), as opposed to the default which is for the fields to be
|
|
right-justified (padded to the left).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</formalpara>
|
|
<formalpara>
|
|
<title>Field width</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable>w</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A decimal digit string specifying a minimum field width. Field will
|
|
be right-justified unless the flag <literal>-</literal> is used.
|
|
Default value is 0 (zero).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</formalpara>
|
|
<formalpara>
|
|
<title>Left precision</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>#</literal><replaceable>n</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The maximum number of digits (<replaceable>n</replaceable>) expected
|
|
to the left of the decimal character (e.g. the decimal point). It is
|
|
used usually to keep formatted output aligned in the same columns,
|
|
using the fill character if the number of digits is less than
|
|
<replaceable>n</replaceable>. If the number of actual digits is
|
|
bigger than <replaceable>n</replaceable>, then this specification is
|
|
ignored.
|
|
</para>
|
|
<para>
|
|
If grouping has not been suppressed using the <literal>^</literal>
|
|
flag, grouping separators will be inserted before the fill
|
|
characters (if any) are added. Grouping separators will not be
|
|
applied to fill characters, even if the fill character is a digit.
|
|
</para>
|
|
<para>
|
|
To ensure alignment, any characters appearing before or after the
|
|
number in the formatted output such as currency or sign symbols are
|
|
padded as necessary with space characters to make their positive and
|
|
negative formats an equal length.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</formalpara>
|
|
<formalpara>
|
|
<title>
|
|
Right precision
|
|
</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>.</literal><replaceable>p</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
A period followed by the number of digits
|
|
(<replaceable>p</replaceable>) after the decimal character. If the
|
|
value of <replaceable>p</replaceable> is 0 (zero), the decimal
|
|
character and the digits to its right will be omitted. If no right
|
|
precision is included, the default will dictated by the current
|
|
local in use. The amount being formatted is rounded to the specified
|
|
number of digits prior to formatting.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</formalpara>
|
|
<formalpara>
|
|
<title>
|
|
Conversion characters
|
|
</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal>i</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The number is formatted according to the locale's international
|
|
currency format (e.g. for the USA locale: USD 1,234.56).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>n</literal></term>
|
|
<listitem>
|
|
<para>
|
|
The number is formatted according to the locale's national
|
|
currency format (e.g. for the de_DE locale: DM1.234,56).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>%</literal></term>
|
|
<listitem>
|
|
<para>
|
|
Returns the <literal>%</literal> character.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>number</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The number to be formatted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
Returns the formatted string. Characters before and after the formatting
|
|
string will be returned unchanged.
|
|
Non-numeric <parameter>number</parameter> causes returning &null; and
|
|
emitting <constant>E_WARNING</constant>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
<note>
|
|
<para>
|
|
The function <function>money_format</function> is only defined if
|
|
the system has strfmon capabilities. For example, Windows does
|
|
not, so <function>money_format</function> is undefined in Windows.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
The <constant>LC_MONETARY</constant> category of the locale settings,
|
|
affects the behavior of this function. Use <function>setlocale</function>
|
|
to set to the appropriate default locale before using this function.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title><function>money_format</function> Example</title>
|
|
<para>
|
|
We will use different locales and format specifications to
|
|
illustrate the use of this function.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$number = 1234.56;
|
|
|
|
// let's print the international format for the en_US locale
|
|
setlocale(LC_MONETARY, 'en_US');
|
|
echo money_format('%i', $number) . "\n";
|
|
// USD 1,234.56
|
|
|
|
// Italian national format with 2 decimals`
|
|
setlocale(LC_MONETARY, 'it_IT');
|
|
echo money_format('%.2n', $number) . "\n";
|
|
// L. 1.234,56
|
|
|
|
// Using a negative number
|
|
$number = -1234.5672;
|
|
|
|
// US national format, using () for negative numbers
|
|
// and 10 digits for left precision
|
|
setlocale(LC_MONETARY, 'en_US');
|
|
echo money_format('%(#10n', $number) . "\n";
|
|
// ($ 1,234.57)
|
|
|
|
// Similar format as above, adding the use of 2 digits of right
|
|
// precision and '*' as a fill character
|
|
echo money_format('%=*(#10.2n', $number) . "\n";
|
|
// ($********1,234.57)
|
|
|
|
// Let's justify to the left, with 14 positions of width, 8 digits of
|
|
// left precision, 2 of right precision, withouth grouping character
|
|
// and using the international format for the de_DE locale.
|
|
setlocale(LC_MONETARY, 'de_DE');
|
|
echo money_format('%=*^-14#8.2i', 1234.56) . "\n";
|
|
// DEM 1234,56****
|
|
|
|
// Let's add some blurb before and after the conversion specification
|
|
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="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:"../../../../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
|
|
-->
|