https://github.com/python/cpython/commit/b1ebbb5d65713c65c4bb9764f93c8f6c9cfd3a45
commit: b1ebbb5d65713c65c4bb9764f93c8f6c9cfd3a45
branch: 3.13
author: Miss Islington (bot) <31488909+miss-isling...@users.noreply.github.com>
committer: encukou <encu...@gmail.com>
date: 2024-06-13T09:07:37+02:00
summary:
[3.13] gh-101575: document Decimal.__round__() (GH-101737) (GH-120394)
gh-101575: document Decimal.__round__() (GH-101737)
(cherry picked from commit 7dd8c37a067f9fcb6a2a658d6a93b294cc2e6fb4)
Co-authored-by: Owain Davies <116417456+othe...@users.noreply.github.com>
files:
M Doc/library/decimal.rst
diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index 3e33581f96f16a..db323802a6f68c 100644
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -897,6 +897,48 @@ Decimal objects
:const:`Rounded`. If given, applies *rounding*; otherwise, uses the
rounding method in either the supplied *context* or the current context.
+ Decimal numbers can be rounded using the :func:`.round` function:
+
+ .. describe:: round(number)
+ .. describe:: round(number, ndigits)
+
+ If *ndigits* is not given or ``None``,
+ returns the nearest :class:`int` to *number*,
+ rounding ties to even, and ignoring the rounding mode of the
+ :class:`Decimal` context. Raises :exc:`OverflowError` if *number* is an
+ infinity or :exc:`ValueError` if it is a (quiet or signaling) NaN.
+
+ If *ndigits* is an :class:`int`, the context's rounding mode is respected
+ and a :class:`Decimal` representing *number* rounded to the nearest
+ multiple of ``Decimal('1E-ndigits')`` is returned; in this case,
+ ``round(number, ndigits)`` is equivalent to
+ ``self.quantize(Decimal('1E-ndigits'))``. Returns ``Decimal('NaN')`` if
+ *number* is a quiet NaN. Raises :class:`InvalidOperation` if *number*
+ is an infinity, a signaling NaN, or if the length of the coefficient
after
+ the quantize operation would be greater than the current context's
+ precision. In other words, for the non-corner cases:
+
+ * if *ndigits* is positive, return *number* rounded to *ndigits* decimal
+ places;
+ * if *ndigits* is zero, return *number* rounded to the nearest integer;
+ * if *ndigits* is negative, return *number* rounded to the nearest
+ multiple of ``10**abs(ndigits)``.
+
+ For example::
+
+ >>> from decimal import Decimal, getcontext, ROUND_DOWN
+ >>> getcontext().rounding = ROUND_DOWN
+ >>> round(Decimal('3.75')) # context rounding ignored
+ 4
+ >>> round(Decimal('3.5')) # round-ties-to-even
+ 4
+ >>> round(Decimal('3.75'), 0) # uses the context rounding
+ Decimal('3')
+ >>> round(Decimal('3.75'), 1)
+ Decimal('3.7')
+ >>> round(Decimal('3.75'), -1)
+ Decimal('0E+1')
+
.. _logical_operands_label:
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
