round.json

{
    "id": "round",
    "summary": "Round to a specified precision",
    "description": "Rounds a real number `x` to specified precision `p`.\n\nIf `x` is halfway between closest numbers of precision `p`, it is rounded to the closest even number of precision `p`.\nThis behavior follows [IEEE Standard 754](https://ieeexplore.ieee.org/document/8766229) and is often called \"round to nearest (even)\" or \"banker's rounding\". It minimizes rounding errors that result from consistently rounding a midpoint value in a single direction.\n\nThe no-data value `null` is passed through and therefore gets propagated.",
    "categories": [
        "math > rounding"
    ],
    "parameters": [
        {
            "name": "x",
            "description": "A number to round.",
            "schema": {
                "type": [
                    "number",
                    "null"
                ]
            }
        },
        {
            "name": "p",
            "description": "A positive number specifies the number of digits after the decimal point to round to. A negative number means rounding to a power of ten, so for example *-2* rounds to the nearest hundred. Defaults to *0*.",
            "schema": {
                "type": "integer"
            },
            "default": 0,
            "optional": true
        }
    ],
    "returns": {
        "description": "The rounded number.",
        "schema": {
            "type": [
                "number",
                "null"
            ]
        }
    },
    "examples": [
        {
            "arguments": {
                "x": 0
            },
            "returns": 0
        },
        {
            "arguments": {
                "x": 3.56,
                "p": 1
            },
            "returns": 3.6
        },
        {
            "arguments": {
                "x": -0.4444444,
                "p": 2
            },
            "returns": -0.44
        },
        {
            "arguments": {
                "x": -2.5
            },
            "returns": -2
        },
        {
            "arguments": {
                "x": -3.5
            },
            "returns": -4
        },
        {
            "arguments": {
                "x": 0.25,
                "p": 1
            },
            "returns": 0.2
        },
        {
            "arguments": {
                "x": 0.35,
                "p": 1
            },
            "returns": 0.4
        },
        {
            "arguments": {
                "x": 1234.5,
                "p": -2
            },
            "returns": 1200
        }
    ],
    "links": [
        {
            "rel": "about",
            "href": "http://mathworld.wolfram.com/AbsoluteValue.html",
            "title": "Absolute value explained by Wolfram MathWorld"
        },
        {
            "rel": "about",
            "href": "https://ieeexplore.ieee.org/document/8766229",
            "title": "IEEE Standard 754-2019 for Floating-Point Arithmetic"
        }
    ]
}