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

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

<!-- Reviewed: no -->

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

<refnamediv>

<refname>round</refname>

<refpurpose>Округляет число с плавающей точкой</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>

Функция возвращает значение числа <parameter>num</parameter>,

которое округлила с точностью <parameter>precision</parameter> —

количество цифр после запятой.

Значение точности <parameter>precision</parameter> принимает отрицательные значения и ноль —

значение по умолчанию.

</para>

<!-- It's not true

<para>

<caution>

<simpara>

При среднем значении <function>round</function> округляет в меньшую сторону чётные числа

и в большую - нечётные. Если необходимо всегда округлять в какую-либо одну сторону

на .5 (или .05 как в примере), следует указать параметр <parameter>mode</parameter>.

Причиной различного округления чётных и нечётных чисел является попытка

избежать классической проблемы банка, согласно которой, при постоянном округлении

в меньшую сторону банк крадёт деньги клиента, а при постоянном округлении

в большую сторону банк со временем разорится. Данная реализация округления

чётных и нечётных чисел равнозначна статистической безубыточности.

</simpara>

</caution>

</para>

-->

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

Значение, которое требуется округлить.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Необязательное количество десятичных знаков, до которых функция округлит число.

</para>

<para>

Функция округлит число <parameter>num</parameter> до такого количества

значащих цифр после десятичной точки, которое указали в параметре

<parameter>precision</parameter>,

если точность <parameter>precision</parameter> положительна.

</para>

<para>

Функция округлит число <parameter>num</parameter> до такого количества

значащих цифр перед десятичной точкой, которое указали в параметре

<parameter>precision</parameter>,

если точность <parameter>precision</parameter> отрицательна.

При отрицательном значении точности функция округляет число до следующего

кратного результата выражения <code>pow(10, -$precision)</code>.

Число <parameter>num</parameter> округляется до десятков,

если точность <parameter>precision</parameter> равна -1,

до сотен, если точность <parameter>precision</parameter> равна -2, и т. д.

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

Режим округления устанавливают перечислением <enumname>RoundingMode</enumname> или константой из следующего списка:

<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>

Округляет положительное число <parameter>num</parameter> в бо́льшую сторону,

а отрицательное в меньшую, превращая 1.5 в 2 и -1.5 в -2; стремится от нуля.

</entry>

</row>

<row>

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

<entry>

Округляет положительное число <parameter>num</parameter> в меньшую сторону,

а отрицательное в бо́льшую, превращая 1.5 в 1 и -1.5 в -1; стремится к нулю.

</entry>

</row>

<row>

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

<entry>

Округляет число <parameter>num</parameter> до ближайшего чётного значения,

превращая 1.5 и 2.5 в 2.

</entry>

</row>

<row>

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

<entry>

Округляет число <parameter>num</parameter> до ближайшего нечётного значения,

превращая 1.5 в 1 и 2.5 в 3.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

Обратите внимание, отдельные режимы, которые добавили недавно, доступны только в перечислении <link linkend="enum.roundingmode">RoundingMode</link>.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Функция возвращает число с плавающей точкой (&float;),

которое получила путём округления входного числа до точности,

которую установили в параметре <parameter>precision</parameter>.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<simpara>

При недопустимом режиме <parameter>mode</parameter> функция

выбрасывает ошибку <exceptionname>ValueError</exceptionname>.

До PHP 8.4.0 для недопустимого режима без предупреждения устанавливалось значение <constant>PHP_ROUND_HALF_UP</constant>.

</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>

Добавили четыре новые режима округления.

</entry>

</row>

<row>

<entry>8.4.0</entry>

<entry>

Функция теперь выбрасывает ошибку <exceptionname>ValueError</exceptionname>,

если в параметр <parameter>mode</parameter> передали недопустимый режим округления.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

Параметр <parameter>num</parameter> больше не принимает внутренние объекты,

которые поддерживают числовое преобразование.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Пример округления чисел функцией <function>round</function></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>Пример влияния параметра <parameter>precision</parameter> на числа с плавающей точкой</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> на округление чисел</title>

<programlisting role="php">

<![CDATA[

<?php

echo 'Режимы округления с 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 'Режимы округления с 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[

Режимы округления с 9.5

float(10)

float(9)

float(10)

float(9)

Режимы округления с 8.5

float(9)

float(8)

float(8)

float(9)

]]>

</screen>

</example>

</para>

<para>

<example>

<title>

Пример округления чисел с режимом <parameter>mode</parameter> и точностью <parameter>precision</parameter>

</title>

<programlisting role="php">

<![CDATA[

<?php

echo 'Округление с точностью до 1 знака в режиме PHP_ROUND_HALF_UP' . 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 'Округление с точностью до 1 знака в режиме PHP_ROUND_HALF_DOWN' . 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 'Округление с точностью до 1 знака в режиме PHP_ROUND_HALF_EVEN' . 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 'Округление с точностью до 1 знака в режиме PHP_ROUND_HALF_ODD' . 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[

Округление с точностью до 1 знака в режиме PHP_ROUND_HALF_UP

float(1.6)

float(-1.6)

Округление с точностью до 1 знака в режиме PHP_ROUND_HALF_DOWN

float(1.5)

float(-1.5)

Округление с точностью до 1 знака в режиме PHP_ROUND_HALF_EVEN

float(1.6)

float(-1.6)

Округление с точностью до 1 знака в режиме PHP_ROUND_HALF_ODD

float(1.5)

float(-1.5)

]]>

</screen>

</example>

<example>

<title>Пример установки режима округления перечислением <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

-->