archived-doc-ru/reference/bc/bcmath/number/round.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: c142be811735a5542c8a2e4c4ed2f81e8cc3acc6 Maintainer: malferov Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="bcmath-number.round" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
 <refnamediv>
  <refname>BcMath\Number::round</refname>
  <refpurpose>Округляет число произвольной точности</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis role="BcMath\\Number">
   <modifier>public</modifier> <type>BcMath\Number</type><methodname>BcMath\Number::round</methodname>
   <methodparam choice="opt"><type>int</type><parameter>precision</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>RoundingMode</type><parameter>mode</parameter><initializer><constant>RoundingMode::HalfAwayFromZero</constant></initializer></methodparam>
  </methodsynopsis>
  <simpara>
   Метод возвращает значение переменной <varname>$this</varname>, которое округлил
   с точностью <parameter>precision</parameter> —
   количество знаков после десятичной точки.
   Параметр <parameter>precision</parameter> принимает также отрицательные значения или ноль — значение по умолчанию.
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <!-- precision parameter -->
   <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.round')/db:refsect1[@role='parameters']/descendant::db:varlistentry[2])" />
   <varlistentry xml:id="bcmath-number.round..parameters.mode">
    <term><parameter>mode</parameter></term>
    <listitem>
     <simpara>
      Режим округления. Подробнее о режимах рассказывет описание перечисления <enumname>RoundingMode</enumname>.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   Метод возвращает результат в виде нового объекта <classname>BcMath\Number</classname>.
  </simpara>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   При передаче недопустимого режима в параметр <parameter>mode</parameter> метод выбрасывает ошибку <exceptionname>ValueError</exceptionname>.
  </simpara>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
   <example>
   <title>Пример округления числа произвольной точности методом <methodname>BcMath\Number::round</methodname></title>
   <programlisting role="php">
<![CDATA[
<?php

var_dump(
    new BcMath\Number('3.4')->round(),
    new BcMath\Number('3.5')->round(),
    new BcMath\Number('3.6')->round(),
    new BcMath\Number('3.6')->round(0),
    new BcMath\Number('5.045')->round(2),
    new BcMath\Number('5.055')->round(2),
    new BcMath\Number('345')->round(-2),
    new BcMath\Number('345')->round(-3),
    new BcMath\Number('678')->round(-2),
    new BcMath\Number('678')->round(-3),
);

?>
]]>
   </programlisting>
   &example.outputs;
   <screen role="php">
<![CDATA[
object(BcMath\Number)#2 (2) {
  ["value"]=>
  string(1) "3"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#3 (2) {
  ["value"]=>
  string(1) "4"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(1) "4"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#5 (2) {
  ["value"]=>
  string(1) "4"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#6 (2) {
  ["value"]=>
  string(4) "5.05"
  ["scale"]=>
  int(2)
}
object(BcMath\Number)#7 (2) {
  ["value"]=>
  string(4) "5.06"
  ["scale"]=>
  int(2)
}
object(BcMath\Number)#8 (2) {
  ["value"]=>
  string(3) "300"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#9 (2) {
  ["value"]=>
  string(1) "0"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#10 (2) {
  ["value"]=>
  string(3) "700"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#11 (2) {
  ["value"]=>
  string(4) "1000"
  ["scale"]=>
  int(0)
}
]]>
   </screen>
  </example>
  <example>
   <title>
    Пример округления числа произвольной точности методом <methodname>BcMath\Number::round</methodname>
    с разными значениями точности <parameter>precision</parameter>
   </title>
   <programlisting role="php">
<![CDATA[
<?php

$number = new BcMath\Number('123.45');

var_dump(
    $number->round(3),
    $number->round(2),
    $number->round(1),
    $number->round(0),
    $number->round(-1),
    $number->round(-2),
    $number->round(-3),
);

?>
]]>
   </programlisting>
   &example.outputs;
   <screen role="php">
<![CDATA[
object(BcMath\Number)#2 (2) {
  ["value"]=>
  string(7) "123.450"
  ["scale"]=>
  int(2)
}
object(BcMath\Number)#3 (2) {
  ["value"]=>
  string(6) "123.45"
  ["scale"]=>
  int(3)
}
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(5) "123.5"
  ["scale"]=>
  int(1)
}
object(BcMath\Number)#5 (2) {
  ["value"]=>
  string(3) "123"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#6 (2) {
  ["value"]=>
  string(3) "120"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#7 (2) {
  ["value"]=>
  string(3) "100"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#8 (2) {
  ["value"]=>
  string(1) "0"
  ["scale"]=>
  int(0)
}
]]>
   </screen>
  </example>
  <example>
   <title>
    Пример округления числа произвольной точности методом <methodname>BcMath\Number::round</methodname>
    в разных режимах <parameter>mode</parameter>
   </title>
   <programlisting role="php">
<![CDATA[
<?php

echo 'Округление числа 9.5 в разных режимах', PHP_EOL;
$number = new BcMath\Number('9.5');
var_dump(
    $number->round(0, RoundingMode::HalfAwayFromZero),
    $number->round(0, RoundingMode::HalfTowardsZero),
    $number->round(0, RoundingMode::HalfEven),
    $number->round(0, RoundingMode::HalfOdd),
    $number->round(0, RoundingMode::TowardsZero),
    $number->round(0, RoundingMode::AwayFromZero),
    $number->round(0, RoundingMode::NegativeInfinity),
    $number->round(0, RoundingMode::PositiveInfinity),
);

echo PHP_EOL;
echo 'Округление числа 8.5 в разных режимах', PHP_EOL;
$number = new BcMath\Number('8.5');
var_dump(
    $number->round(0, RoundingMode::HalfAwayFromZero),
    $number->round(0, RoundingMode::HalfTowardsZero),
    $number->round(0, RoundingMode::HalfEven),
    $number->round(0, RoundingMode::HalfOdd),
    $number->round(0, RoundingMode::TowardsZero),
    $number->round(0, RoundingMode::AwayFromZero),
    $number->round(0, RoundingMode::NegativeInfinity),
    $number->round(0, RoundingMode::PositiveInfinity),
);

?>
]]>
   </programlisting>
   &example.outputs;
   <screen role="php">
<![CDATA[
Rounding modes with 9.5
object(BcMath\Number)#3 (2) {
  ["value"]=>
  string(2) "10"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#5 (2) {
  ["value"]=>
  string(1) "9"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#7 (2) {
  ["value"]=>
  string(2) "10"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#9 (2) {
  ["value"]=>
  string(1) "9"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#11 (2) {
  ["value"]=>
  string(1) "9"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#13 (2) {
  ["value"]=>
  string(2) "10"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#15 (2) {
  ["value"]=>
  string(1) "9"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#17 (2) {
  ["value"]=>
  string(2) "10"
  ["scale"]=>
  int(0)
}

Rounding modes with 8.5
object(BcMath\Number)#1 (2) {
  ["value"]=>
  string(1) "9"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#15 (2) {
  ["value"]=>
  string(1) "8"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#13 (2) {
  ["value"]=>
  string(1) "8"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#11 (2) {
  ["value"]=>
  string(1) "9"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#9 (2) {
  ["value"]=>
  string(1) "8"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#7 (2) {
  ["value"]=>
  string(1) "9"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#5 (2) {
  ["value"]=>
  string(1) "8"
  ["scale"]=>
  int(0)
}
object(BcMath\Number)#3 (2) {
  ["value"]=>
  string(1) "9"
  ["scale"]=>
  int(0)
}
]]>
   </screen>
  </example>
  <example>
   <title>
    Пример округления числа произвольной точности методом <methodname>BcMath\Number::round</methodname>
    в разных режимах <parameter>mode</parameter>
    до точности <parameter>precision</parameter>
   </title>
   <programlisting role="php">
<![CDATA[
<?php

$positive = new BcMath\Number('1.55');
$negative = new BcMath\Number('-1.55');

echo 'Режим округления RoundingMode::HalfAwayFromZero с точностью до 1 десятичного знака', PHP_EOL;
var_dump(
    $positive->round(1, RoundingMode::HalfAwayFromZero),
    $negative->round(1, RoundingMode::HalfAwayFromZero),
);

echo PHP_EOL;
echo 'Режим округления RoundingMode::HalfTowardsZero с точностью до 1 десятичного знака', PHP_EOL;
var_dump(
    $positive->round(1, RoundingMode::HalfTowardsZero),
    $negative->round(1, RoundingMode::HalfTowardsZero),
);

echo PHP_EOL;
echo 'Режим округления RoundingMode::HalfEven с точностью до 1 десятичного знака', PHP_EOL;
var_dump(
    $positive->round(1, RoundingMode::HalfEven),
    $negative->round(1, RoundingMode::HalfEven),
);

echo PHP_EOL;
echo 'Режим округления RoundingMode::HalfOdd с точностью до 1 десятичного знака', PHP_EOL;
var_dump(
    $positive->round(1, RoundingMode::HalfOdd),
    $negative->round(1, RoundingMode::HalfOdd),
);

echo PHP_EOL;
echo 'Режим округления RoundingMode::TowardsZero с точностью до 1 десятичного знака', PHP_EOL;
var_dump(
    $positive->round(1, RoundingMode::TowardsZero),
    $negative->round(1, RoundingMode::TowardsZero),
);

echo PHP_EOL;
echo 'Режим округления RoundingMode::AwayFromZero с точностью до 1 десятичного знака', PHP_EOL;
var_dump(
    $positive->round(1, RoundingMode::AwayFromZero),
    $negative->round(1, RoundingMode::AwayFromZero),
);

echo PHP_EOL;
echo 'Режим округления RoundingMode::NegativeInfinity с точностью до 1 десятичного знака', PHP_EOL;
var_dump(
    $positive->round(1, RoundingMode::NegativeInfinity),
    $negative->round(1, RoundingMode::NegativeInfinity),
);

echo PHP_EOL;
echo 'Режим округления RoundingMode::PositiveInfinity с точностью до 1 десятичного знака', PHP_EOL;
var_dump(
    $positive->round(1, RoundingMode::PositiveInfinity),
    $negative->round(1, RoundingMode::PositiveInfinity),
);

?>
]]>
   </programlisting>
   &example.outputs;
   <screen role="php">
<![CDATA[
Режим округления RoundingMode::HalfAwayFromZero с точностью до 1 десятичного знака
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(3) "1.6"
  ["scale"]=>
  int(1)
}
object(BcMath\Number)#5 (2) {
  ["value"]=>
  string(4) "-1.6"
  ["scale"]=>
  int(1)
}

Режим округления RoundingMode::HalfTowardsZero с точностью до 1 десятичного знака
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(3) "1.5"
  ["scale"]=>
  int(1)
}
object(BcMath\Number)#6 (2) {
  ["value"]=>
  string(4) "-1.5"
  ["scale"]=>
  int(1)
}

Режим округления RoundingMode::HalfEven с точностью до 1 десятичного знака
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(3) "1.6"
  ["scale"]=>
  int(1)
}
object(BcMath\Number)#7 (2) {
  ["value"]=>
  string(4) "-1.6"
  ["scale"]=>
  int(1)
}

Режим округления RoundingMode::HalfOdd с точностью до 1 десятичного знака
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(3) "1.5"
  ["scale"]=>
  int(1)
}
object(BcMath\Number)#8 (2) {
  ["value"]=>
  string(4) "-1.5"
  ["scale"]=>
  int(1)
}

Режим округления RoundingMode::TowardsZero с точностью до 1 десятичного знака
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(3) "1.5"
  ["scale"]=>
  int(1)
}
object(BcMath\Number)#9 (2) {
  ["value"]=>
  string(4) "-1.5"
  ["scale"]=>
  int(1)
}

Режим округления RoundingMode::AwayFromZero с точностью до 1 десятичного знака
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(3) "1.6"
  ["scale"]=>
  int(1)
}
object(BcMath\Number)#10 (2) {
  ["value"]=>
  string(4) "-1.6"
  ["scale"]=>
  int(1)
}

Режим округления RoundingMode::NegativeInfinity с точностью до 1 десятичного знака
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(3) "1.5"
  ["scale"]=>
  int(1)
}
object(BcMath\Number)#11 (2) {
  ["value"]=>
  string(4) "-1.6"
  ["scale"]=>
  int(1)
}

Режим округления RoundingMode::PositiveInfinity с точностью до 1 десятичного знака
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(3) "1.6"
  ["scale"]=>
  int(1)
}
object(BcMath\Number)#12 (2) {
  ["value"]=>
  string(4) "-1.5"
  ["scale"]=>
  int(1)
}
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>bcround</function></member>
   <member><methodname>BcMath\Number::ceil</methodname></member>
   <member><methodname>BcMath\Number::floor</methodname></member>
  </simplelist>
 </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
-->