archived-doc-es/reference/math/functions/round.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: c142be811735a5542c8a2e4c4ed2f81e8cc3acc6 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no Maintainer: Marqitos -->
<refentry xml:id="function.round" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>round</refname>
  <refpurpose>Redondea un número de punto flotante</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>
   Devuelve el valor redondeado de <parameter>num</parameter>
   a la precisión <parameter>precision</parameter> (número de
   dígitos después del punto decimal). El argumento <parameter>precision</parameter>
   puede ser negativo o &null; : es su valor por omisión.
  </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>
       El valor a redondear.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>precision</parameter></term>
     <listitem>
      <para>
       El número opcional de decimales a redondear.
      </para>
      <para>
       Si el argumento <parameter>precision</parameter> es positivo,
       <parameter>num</parameter> será redondeado utilizando el argumento
       <parameter>precision</parameter> para definir el número significativo
       de dígitos después del punto decimal.
      </para>
      <para>
       Si el argumento <parameter>precision</parameter> es negativo,
       <parameter>num</parameter> será redondeado utilizando el argumento
       <parameter>precision</parameter> para definir el número significativo
       de dígitos antes del punto decimal, i.e. el múltiplo más cercano
       de <code>pow(10, -$precision)</code>, i.e. para una
       <parameter>precision</parameter> de -1, <parameter>num</parameter>
       será redondeado a 10, para una <parameter>precision</parameter> de -2 a 100, etc.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       Utilice <enumname>RoundingMode</enumname> o una de las constantes siguientes para especificar el método de redondeo.
       <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>
            Redondea <parameter>num</parameter> alejándose de cero cuando
            está a mitad de camino, redondeando así 1.5 a 2, y -1.5 a -2.
           </entry>
          </row>
          <row>
           <entry><constant>PHP_ROUND_HALF_DOWN</constant></entry>
           <entry>
            Redondea <parameter>num</parameter> acercándose a cero cuando
            está a mitad de camino, redondeando así 1.5 a 1, y -1.5 a -1.
           </entry>
          </row>
          <row>
           <entry><constant>PHP_ROUND_HALF_EVEN</constant></entry>
           <entry>
            Redondea <parameter>num</parameter> al valor par más cercano
            cuando está a mitad de camino, redondeando así 1.5 y 2.5 a 2.
           </entry>
          </row>
          <row>
           <entry><constant>PHP_ROUND_HALF_ODD</constant></entry>
           <entry>
            Redondea <parameter>num</parameter> al valor impar más cercano
            cuando está a mitad de camino, redondeando así 1.5 a 1 y 2.5 a 3.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
       Sin embargo, tenga en cuenta que algunos métodos recién añadidos solo existen en <link linkend="enum.roundingmode">RoundingMode</link>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   El valor redondeado a la <parameter>precision</parameter> dada como &float;.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   La función lanza una <exceptionname>ValueError</exceptionname> si <parameter>mode</parameter> es inválido.
   Anterior a PHP 8.4.0, un modo inválido era silenciosamente convertido en <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>
       Cuatro nuevos métodos de redondeo han sido añadidos.
      </entry>
     </row>
     <row>
      <entry>8.4.0</entry>
      <entry>
       Ahora lanza una <exceptionname>ValueError</exceptionname> si
       <parameter>mode</parameter> es inválido.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>num</parameter> ya no acepta objetos internos que soporten
       las conversiones numéricas.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo con <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>Cómo <parameter>precision</parameter> afecta un flotante</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>Ejemplo con <parameter>mode</parameter></title>
    <programlisting role="php">
<![CDATA[
<?php
echo "Método de redondeo con 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 "Método de redondeo con 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[
Método de redondeo con 9.5
float(10)
float(9)
float(10)
float(9)

Método de redondeo con 8.5
float(9)
float(8)
float(8)
float(9)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Ejemplo con <parameter>mode</parameter> y <parameter>precision</parameter></title>
    <programlisting role="php">
<![CDATA[
<?php
echo "Uso de PHP_ROUND_HALF_UP con una precisión de una decimal" . 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 "Uso de PHP_ROUND_HALF_DOWN con una precisión de una decimal" . 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 "Uso de PHP_ROUND_HALF_EVEN con una precisión de una decimal" . 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 "Uso de PHP_ROUND_HALF_ODD con una precisión de una decimal" . 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[
Uso de PHP_ROUND_HALF_UP con una precisión de una decimal
float(1.6)
float(-1.6)

Uso de PHP_ROUND_HALF_DOWN con una precisión de una decimal
float(1.5)
float(-1.5)

Uso de PHP_ROUND_HALF_EVEN con una precisión de una decimal
float(1.6)
float(-1.6)

Uso de PHP_ROUND_HALF_ODD con una precisión de una decimal
float(1.5)
float(-1.5)
]]>
    </screen>
   </example>
     <example>
   <title>Ejemplo de uso de <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
-->