<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: c142be811735a5542c8a2e4c4ed2f81e8cc3acc6 Maintainer: hholzgra Status: ready -->

<!-- Reviewed: yes -->

<!-- Rev-Revision: 7973fd533364af4dd6282ca9e7bee2dffec39b1c Reviewer: samesch -->

<refentry xml:id="function.round" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>round</refname>

<refpurpose>Rundet einen Gleitkommawert</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>float</type><methodname>round</methodname>

<methodparam><type class="union"><type>int</type><type>float</type></type><parameter>num</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>precision</parameter><initializer>0</initializer></methodparam>

<methodparam choice="opt"><type class="union"><type>int</type><type>RoundingMode</type></type><parameter>mode</parameter><initializer><constant>RoundingMode::HalfAwayFromZero</constant></initializer></methodparam>

</methodsynopsis>

<para>

Rundet den Parameter <parameter>num</parameter> auf die mit

<parameter>precision</parameter> angegebene Anzahl von Nachkommastellen.

<parameter>precision</parameter> kann dabei auch Null (Vorgabewert) oder

negativ sein. So wird bei einer Stellenzahl von -1 &zb; auf volle Zehner

gerundet.

</para>

<!-- It's not true

<para>

<caution>

<simpara>

When rounding on exact halves <function>round</function> rounds down on

evens and up on odds. If you want to always force it in one direction on

a .5 (or .05 in your case) add or subtract a tiny fuzz factor. The reason

behind rounding half the values down and the other half up is to avoid

the classical banking problem where if you always rounded down you would

be stealing money from your customers, or if you always rounded up you

would end up over time losing money. By averaging it out through evens

and odds you statistically break even.

</simpara>

</caution>

</para>

-->

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>num</parameter></term>

<listitem>

<para>

Der zu rundende Wert.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>precision</parameter></term>

<listitem>

<para>

Auf wie viele Nachkommastellen gerundet werden soll.

</para>

<para>

Ist die Genauigkeit <parameter>precision</parameter> positiv, wird

<parameter>num</parameter> auf <parameter>precision</parameter>

signifikante Stellen nach dem Dezimalpunkt gerundet.

</para>

<para>

Ist die Genauigkeit <parameter>precision</parameter> negativ, wird

<parameter>num</parameter> auf <parameter>precision</parameter>

signifikante Stellen vor dem Dezimalpunkt gerundet, &dh; auf das

nächste Vielfache von <literal>pow(10, -precision)</literal>, &zb;

wird <parameter>num</parameter> mit einer

<parameter>precision</parameter> von -1 auf Zehner gerundet, mit einer

<parameter>precision</parameter> von -2 auf Hunderter usw.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>mode</parameter></term>

<listitem>

<para>

Um den Rundungsmodus festzulegen, kann <enumname>RoundingMode</enumname>

oder eine der folgenden Konstanten verwendet werden.

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Constants;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry><constant>PHP_ROUND_HALF_UP</constant></entry>

<entry>

Rundet <parameter>num</parameter> auf halber Strecke von Null weg,

womit 1.5 zu 2 wird und -1.5 zu -2.

</entry>

</row>

<row>

<entry><constant>PHP_ROUND_HALF_DOWN</constant></entry>

<entry>

Rundet <parameter>num</parameter> auf halber Strecke zu Null hin,

womit 1.5 zu 1 wird und -1.5 zu -1.

</entry>

</row>

<row>

<entry><constant>PHP_ROUND_HALF_EVEN</constant></entry>

<entry>

Rundet <parameter>num</parameter> auf halber Strecke auf den

nächsten geraden Wert, womit sowohl 1.5 als auch 2.5 zu 2 werden.

</entry>

</row>

<row>

<entry><constant>PHP_ROUND_HALF_ODD</constant></entry>

<entry>

Rundet <parameter>num</parameter> auf halber Strecke auf den

nächsten ungeraden Wert, womit 1.5 zu 1 wird und 2.5 zu 3.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

Es ist jedoch zu beachten, dass einige neu hinzugefügte Modi nur in

<link linkend="enum.roundingmode">RoundingMode</link> existieren.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Der auf die angegebene <parameter>precision</parameter> gerundete Wert als

&float;.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<simpara>

Wenn <parameter>mode</parameter> ungültig ist, löst die Funktion einen

<exceptionname>ValueError</exceptionname> aus.

Vor PHP 8.4.0 wurde bei einem ungültigen Modus automatisch

<constant>PHP_ROUND_HALF_UP</constant> verwendet.

</simpara>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.4.0</entry>

<entry>

Vier neue Rundungsmodi wurden hinzugefügt.

</entry>

</row>

<row>

<entry>8.4.0</entry>

<entry>

Es wird nun ein <exceptionname>ValueError</exceptionname> ausgelöst,

wenn <parameter>mode</parameter> ungültig ist.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>num</parameter> akzeptiert keine internen Objekte mehr, die

eine numerische Konvertierung unterstützen.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>round</function>-Beispiele</title>

<programlisting role="php">

<![CDATA[

<?php

var_dump(round(3.4));

var_dump(round(3.5));

var_dump(round(3.6));

var_dump(round(3.6, 0));

var_dump(round(5.045, 2));

var_dump(round(5.055, 2));

var_dump(round(345, -2));

var_dump(round(345, -3));

var_dump(round(678, -2));

var_dump(round(678, -3));

?>

]]>

</programlisting>

&example.outputs;

<screen role="php">

<![CDATA[

float(3)

float(4)

float(4)

float(4)

float(5.05)

float(5.06)

float(300)

float(0)

float(700)

float(1000)

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Wie <parameter>precision</parameter> eine Gleitkommazahl betrifft</title>

<programlisting role="php">

<![CDATA[

<?php

$number = 135.79;

var_dump(round($number, 3));

var_dump(round($number, 2));

var_dump(round($number, 1));

var_dump(round($number, 0));

var_dump(round($number, -1));

var_dump(round($number, -2));

var_dump(round($number, -3));

?>

]]>

</programlisting>

&example.outputs;

<screen role="php">

<![CDATA[

float(135.79)

float(135.79)

float(135.8)

float(136)

float(140)

float(100)

float(0)

]]>

</screen>

</example>

</para>

<para>

<example>

<title><parameter>mode</parameter>-Beispiele</title>

<programlisting role="php">

<![CDATA[

<?php

echo 'Rundundsmodi mit 9.5' . PHP_EOL;

var_dump(round(9.5, 0, PHP_ROUND_HALF_UP));

var_dump(round(9.5, 0, PHP_ROUND_HALF_DOWN));

var_dump(round(9.5, 0, PHP_ROUND_HALF_EVEN));

var_dump(round(9.5, 0, PHP_ROUND_HALF_ODD));

echo PHP_EOL;

echo 'Rundundsmodi mit 8.5' . PHP_EOL;

var_dump(round(8.5, 0, PHP_ROUND_HALF_UP));

var_dump(round(8.5, 0, PHP_ROUND_HALF_DOWN));

var_dump(round(8.5, 0, PHP_ROUND_HALF_EVEN));

var_dump(round(8.5, 0, PHP_ROUND_HALF_ODD));

?>

]]>

</programlisting>

&example.outputs;

<screen role="php">

<![CDATA[

Rundundsmodi mit 9.5

float(10)

float(9)

float(10)

float(9)

Rundundsmodi mit 8.5

float(9)

float(8)

float(8)

float(9)

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Beispiele für <parameter>mode</parameter> mit <parameter>precision</parameter></title>

<programlisting role="php">

<![CDATA[

<?php

echo 'Verwendung von PHP_ROUND_HALF_UP mit einer Dezimalstelle Genauigkeit' . PHP_EOL;

var_dump(round( 1.55, 1, PHP_ROUND_HALF_UP));

var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));

echo PHP_EOL;

echo 'Verwendung von PHP_ROUND_HALF_DOWN mit einer Dezimalstelle Genauigkeit' . PHP_EOL;

var_dump(round( 1.55, 1, PHP_ROUND_HALF_DOWN));

var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));

echo PHP_EOL;

echo 'Verwendung von PHP_ROUND_HALF_EVEN mit einer Dezimalstelle Genauigkeit' . PHP_EOL;

var_dump(round( 1.55, 1, PHP_ROUND_HALF_EVEN));

var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));

echo PHP_EOL;

echo 'Verwendung von PHP_ROUND_HALF_ODD mit einer Dezimalstelle Genauigkeit' . PHP_EOL;

var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));

var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));

?>

]]>

</programlisting>

&example.outputs;

<screen role="php">

<![CDATA[

Verwendung von PHP_ROUND_HALF_UP mit einer Dezimalstelle Genauigkeit

float(1.6)

float(-1.6)

Verwendung von PHP_ROUND_HALF_DOWN mit einer Dezimalstelle Genauigkeit

float(1.5)

float(-1.5)

Verwendung von PHP_ROUND_HALF_EVEN mit einer Dezimalstelle Genauigkeit

float(1.6)

float(-1.6)

Verwendung von PHP_ROUND_HALF_ODD mit einer Dezimalstelle Genauigkeit

float(1.5)

float(-1.5)

]]>

</screen>

</example>

<example>

<title>Beispiel für die Verwendung von <enumname>RoundingMode</enumname></title>

<programlisting role="php">

<![CDATA[

<?php

foreach (RoundingMode::cases() as $mode) {

foreach ([

8.5,

9.5,

-3.5,

] as $number) {

printf("%-17s: %+.17g -> %+.17g\n", $mode->name, $number, round($number, 0, $mode));

}

echo "\n";

}

?>

]]>

</programlisting>

&example.outputs;

<screen role="php">

<![CDATA[

HalfAwayFromZero : +8.5 -> +9

HalfAwayFromZero : +9.5 -> +10

HalfAwayFromZero : -3.5 -> -4

HalfTowardsZero : +8.5 -> +8

HalfTowardsZero : +9.5 -> +9

HalfTowardsZero : -3.5 -> -3

HalfEven : +8.5 -> +8

HalfEven : +9.5 -> +10

HalfEven : -3.5 -> -4

HalfOdd : +8.5 -> +9

HalfOdd : +9.5 -> +9

HalfOdd : -3.5 -> -3

TowardsZero : +8.5 -> +8

TowardsZero : +9.5 -> +9

TowardsZero : -3.5 -> -3

AwayFromZero : +8.5 -> +9

AwayFromZero : +9.5 -> +10

AwayFromZero : -3.5 -> -4

NegativeInfinity : +8.5 -> +8

NegativeInfinity : +9.5 -> +9

NegativeInfinity : -3.5 -> -4

PositiveInfinity : +8.5 -> +9

PositiveInfinity : +9.5 -> +10

PositiveInfinity : -3.5 -> -3

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>ceil</function></member>

<member><function>floor</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

-->