GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Downloads
  • Documentation
  • Get Involved
  • Help
  • Getting Started
  • Introduction
  • A simple tutorial
  • Language Reference
  • Basic syntax
  • Types
  • Variables
  • Constants
  • Expressions
  • Operators

This view

  • Original page
  • New address

GeezerVison is showing www.php.net — PHP: round - Manual

PHP 8.6.0 RC5 available for testing
    sin »
    « rad2deg
    • Preface
    • Function Reference
    • Mathematical Extensions
    • Math
    • Math Functions

    round

    (PHP 4, PHP 5, PHP 7, PHP 8)

    round — Rounds a float

    Description

    function round(int|float $num, int $precision = 0, int|RoundingMode $mode = RoundingMode::HalfAwayFromZero): float

    Returns the rounded value of num to specified precision (number of digits after the decimal point). precision can also be negative or zero (default).

    Parameters

    num

    The value to round.

    precision

    The optional number of decimal digits to round to.

    If the precision is positive, num is rounded to precision significant digits after the decimal point.

    If the precision is negative, num is rounded to precision significant digits before the decimal point, i.e. to the nearest multiple of pow(10, -$precision), e.g. for a precision of -1 num is rounded to tens, for a precision of -2 to hundreds, etc.

    mode

    Use RoundingMode or one of the following constants to specify the mode in which rounding occurs.

    Constants Description
    PHP_ROUND_HALF_UP Rounds num away from zero when it is half way there, making 1.5 into 2 and -1.5 into -2.
    PHP_ROUND_HALF_DOWN Rounds num towards zero when it is half way there, making 1.5 into 1 and -1.5 into -1.
    PHP_ROUND_HALF_EVEN Rounds num towards the nearest even value when it is half way there, making both 1.5 and 2.5 into 2.
    PHP_ROUND_HALF_ODD Rounds num towards the nearest odd value when it is half way there, making 1.5 into 1 and 2.5 into 3.
    However, please note that some newly added modes only exist in RoundingMode.

    Return Values

    The value rounded to the given precision as a float.

    Errors/Exceptions

    The function throws a ValueError if mode is invalid. Prior to PHP 8.4.0, an invalid mode would silently default to PHP_ROUND_HALF_UP.

    Changelog

    Version Description
    8.4.0 Four new rounding modes have been added.
    8.4.0 Now throws a ValueError if mode is invalid.
    8.0.0 num no longer accepts internal objects which support numeric conversion.

    Examples

    Example #1 round() examples

    <?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));
    ?>

    The above example will output:

    float(3)
    float(4)
    float(4)
    float(4)
    float(5.05)
    float(5.06)
    float(300)
    float(0)
    float(700)
    float(1000)

    Example #2 How precision affects a float

    <?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));
    ?>

    The above example will output:

    float(135.79)
    float(135.79)
    float(135.8)
    float(136)
    float(140)
    float(100)
    float(0)

    Example #3 mode examples

    <?php
    echo 'Rounding modes with 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 'Rounding modes with 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));
    ?>

    The above example will output:

    Rounding modes with 9.5
    float(10)
    float(9)
    float(10)
    float(9)
    
    Rounding modes with 8.5
    float(9)
    float(8)
    float(8)
    float(9)

    Example #4 mode with precision examples

    <?php
    echo 'Using PHP_ROUND_HALF_UP with 1 decimal digit precision' . 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 'Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision' . 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 'Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision' . 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 'Using PHP_ROUND_HALF_ODD with 1 decimal digit precision' . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
    ?>

    The above example will output:

    Using PHP_ROUND_HALF_UP with 1 decimal digit precision
    float(1.6)
    float(-1.6)
    
    Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision
    float(1.5)
    float(-1.5)
    
    Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision
    float(1.6)
    float(-1.6)
    
    Using PHP_ROUND_HALF_ODD with 1 decimal digit precision
    float(1.5)
    float(-1.5)

    Example #5 Example of using RoundingMode

    <?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";
    }
    ?>

    The above example will output:

    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

    See Also

    • ceil() - Round fractions up
    • floor() - Round fractions down
    • number_format() - Format a number with grouped thousands

    Found A Problem?

    Learn How To Improve This Page • Submit a Pull Request • Report a Bug
    +add a note

    User Contributed Notes 13 notes

    up
    down
    330
    takingsides at gmail dot com ¶
    12 years ago
    In my opinion this function lacks two flags:
    
    - PHP_ROUND_UP - Always round up.
    - PHP_ROUND_DOWN - Always round down.
    
    In accounting, it's often necessary to always round up, or down to a precision of thousandths.
    
    <?php
    function round_up($number, $precision = 2)
    {
        $fig = (int) str_pad('1', $precision, '0');
        return (ceil($number * $fig) / $fig);
    }
    
    function round_down($number, $precision = 2)
    {
        $fig = (int) str_pad('1', $precision, '0');
        return (floor($number * $fig) / $fig);
    }
    ?>
    up
    down
    34
    depaula at unilogica dot com ¶
    9 years ago
    As PHP doesn't have a a native number truncate function, this is my solution - a function that can be usefull if you need truncate instead round a number.
    
    <?php
    /**
     * Truncate a float number, example: <code>truncate(-1.49999, 2); // returns -1.49
     * truncate(.49999, 3); // returns 0.499
     * </code>
     * @param float $val Float number to be truncate
     * @param int f Number of precision
     * @return float
     */
    function truncate($val, $f="0")
    {
        if(($p = strpos($val, '.')) !== false) {
            $val = floatval(substr($val, 0, $p + 1 + $f));
        }
        return $val;
    }
    ?>
    
    Originally posted in http://stackoverflow.com/a/12710283/1596489
    up
    down
    30
    slimusgm at gmail dot com ¶
    12 years ago
    If you have negative zero and you need return positive number simple add +0:
    
    $number = -2.38419e-07;
    var_dump(round($number,1));//float(-0)
    var_dump(round($number,1) + 0);//float(0)
    up
    down
    22
    djcox99 at googlemail dot com ¶
    12 years ago
    I discovered that under some conditions you can get rounding errors with round when converting the number to a string afterwards.
    
    To fix this I swapped round() for number_format().
    
    Unfortunately i cant give an example (because the number cant be represented as a string !)
    
    essentially I had round(0.688888889,2);
    
    which would stay as 0.68888889 when printed as a string.
    
    But using number_format it correctly became 0.69.
    up
    down
    11
    craft at ckdevelop dot org ¶
    12 years ago
    function mround($val, $f=2, $d=6){
        return sprintf("%".$d.".".$f."f", $val);
    }
    
    echo mround(34.89999);  //34.90
    up
    down
    20
    esion99 at gmail dot com ¶
    12 years ago
    Unexpected result or misunderstanding (php v5.5.9)
    
    <?php
    
    echo round(1.55, 1, PHP_ROUND_HALF_DOWN); // 1.5
    echo round(1.551, 1, PHP_ROUND_HALF_DOWN); //1.6
    
    ?>
    up
    down
    19
    twan at ecreation dot nl ¶
    26 years ago
    If you'd only want to round for displaying variables (not for calculating on the rounded result) then you should use printf with the float:
    
    <?php printf ("%6.2f",3.39532); ?>
    
    This returns: 3.40 .
    up
    down
    8
    michaeldnelson dot mdn at gmail dot com ¶
    17 years ago
    This function will let you round to an arbitrary non-zero number.  Zero of course causes a division by zero.
    
    <?php
    function roundTo($number, $to){
        return round($number/$to, 0)* $to;
    }
    
    echo roundTo(87.23, 20); //80
    echo roundTo(-87.23, 20); //-80
    echo roundTo(87.23, .25); //87.25
    echo roundTo(.23, .25); //.25
    ?>
    up
    down
    15
    Anonymous ¶
    16 years ago
    Here is function that rounds to a specified increment, but always up. I had to use it for price adjustment that always went up to $5 increments.
    
    <?php  
    function roundUpTo($number, $increments) {
        $increments = 1 / $increments;
        return (ceil($number * $increments) / $increments);
    }
    ?>
    up
    down
    8
    christian at deligant dot net ¶
    15 years ago
    this function (as all mathematical operators) takes care of the setlocale setting, resulting in some weirdness when using the result where the english math notation is expected, as the printout of the result in a width: style attribute!
    
    <?php
    $a=3/4;
    echo round($a, 2); // 0.75
    
    setlocale(LC_ALL, 'it_IT@euro', 'it_IT', 'it');
    $b=3/4;
    echo round($b,2); // 0,75
    ?>
    up
    down
    4
    greghenle at gmail dot com ¶
    9 years ago
    /**
     * Round to first significant digit
     * +N to +infinity
     * -N to -infinity
     *
     */
    function round1stSignificant ( $N ) {
      if ( $N === 0 ) {
        return 0;
      }
    
      $x = floor ( log10 ( abs( $N ) ) );
    
      return ( $N > 0 )
        ? ceil( $N * pow ( 10, $x * -1 ) ) * pow( 10, $x )
        : floor( $N * pow ( 10, $x * -1 ) ) * pow( 10, $x );
    }
    
    echo round1stSignificant( 39144818 ) . PHP_EOL;
    echo round1stSignificant( 124818 ) . PHP_EOL;
    echo round1stSignificant( 0.07468 ) . PHP_EOL;
    echo round1stSignificant( 0 ) . PHP_EOL;
    echo round1stSignificant( -0.07468 ) . PHP_EOL;
    
    /**
     * Output
     * 
     * 40000000
     * 200000
     * 0.08
     * 0
     * -0.08
     * 
     */
    up
    down
    5
    dastra ¶
    14 years ago
    round() will sometimes return E notation when rounding a float when the amount is small enough - see  https://bugs.php.net/bug.php?id=44223 .  Apparently it's a feature.
    
    To work around this "feature" when converting to a string, surround your round statement with an sprintf:
    
    sprintf("%.10f", round( $amountToBeRounded, 10));
    up
    down
    8
    php at silisoftware dot com ¶
    24 years ago
    Here's a function to round to an arbitary number of significant digits. Don't confuse it with rounding to a negative precision - that counts back from the decimal point, this function counts forward from the Most Significant Digit.
    
    ex:
    
    <?php
    round(1241757, -3); // 1242000
    RoundSigDigs(1241757, 3); // 1240000
    ?>
    
    Works on negative numbers too. $sigdigs should be >= 0
    
    <?php
    function RoundSigDigs($number, $sigdigs) {
        $multiplier = 1;
        while ($number < 0.1) {
            $number *= 10;
            $multiplier /= 10;
        }
        while ($number >= 1) {
            $number /= 10;
            $multiplier *= 10;
        }
        return round($number, $sigdigs) * $multiplier;
    }
    ?>
    +add a note
    • Math Functions
      • abs
      • acos
      • acosh
      • asin
      • asinh
      • atan
      • atan2
      • atanh
      • base_​convert
      • bindec
      • ceil
      • clamp
      • cos
      • cosh
      • decbin
      • dechex
      • decoct
      • deg2rad
      • exp
      • expm1
      • fdiv
      • floor
      • fmod
      • fpow
      • hexdec
      • hypot
      • intdiv
      • is_​finite
      • is_​infinite
      • is_​nan
      • log
      • log10
      • log1p
      • max
      • min
      • octdec
      • pi
      • pow
      • rad2deg
      • round
      • sin
      • sinh
      • sqrt
      • tan
      • tanh
    You are visitor 01402503 — GeezerVison does not store the pages you look up.
    Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.