Add math.remainder operation

[mdickinson]

BPO	29962
Nosy	@rhettinger, @mdickinson, @serhiy-storchaka
PRs	#950

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2017-04-05.17:36:36.662>
created_at = <Date 2017-04-01.14:32:38.422>
labels = ['extension-modules', 'type-feature', '3.7']
title = 'Add math.remainder operation'
updated_at = <Date 2017-04-05.17:36:36.662>
user = 'https://github.com/mdickinson'

bugs.python.org fields:

activity = <Date 2017-04-05.17:36:36.662>
actor = 'mark.dickinson'
assignee = 'none'
closed = True
closed_date = <Date 2017-04-05.17:36:36.662>
closer = 'mark.dickinson'
components = ['Extension Modules']
creation = <Date 2017-04-01.14:32:38.422>
creator = 'mark.dickinson'
dependencies = []
files = []
hgrepos = []
issue_num = 29962
keywords = []
message_count = 7.0
messages = ['290985', '290987', '290988', '290989', '290990', '290991', '291188']
nosy_count = 3.0
nosy_names = ['rhettinger', 'mark.dickinson', 'serhiy.storchaka']
pr_nums = ['950']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue29962'
versions = ['Python 3.7']

[mdickinson]

IEEE 754, the C99 standard, the Decimal IBM standard and Java all support/specify a 'remainder-near' operation. Apart from being standard, this has a number of useful applications:

1. Argument reduction in numerical algorithms: it's common to want to reduce to a range [-modulus/2, modulus/2] rather than [0, modulus).
2. Particular case of the above: reduction of angles to lie in the range [-pi, pi]
3. Rounding a float x to the nearest multiple of y. This is a much-asked StackOverflow question, and the standard answer of y * round(x / y) risks introducing floating-point error and so can give incorrect results in corner cases. With a remainder operation, it's trivial to do this correctly: x - remainder(x, y) gives the closest representable float to the closest integer multiple of y to x.

remainder(x, y) has some nice properties: it's *always* exactly representable (unlike x % y), it satisfies the symmetry remainder(-x, y) == -remainder(x, y), and it's periodic with period 2*y.

I have a patch, and will make a PR shortly.

[serhiy-storchaka]

See also Decimal.remainder_near and _PyLong_DivmodNear. Shouldn't the new function be named math.remainder_near?

In many cases the function that returns the nearest integer quotient is useful. See Fraction.__round__, datetime._divide_and_round, _pydecimal._div_nearest, etc.

[mdickinson]

Shouldn't the new function be named math.remainder_near?

Not clear. :-) I'd prefer to keep the name that's consistent with both C and IEEE 754. (We already have plenty of naming differences between Decimal and math; attempting to reconcile them is likely futile.)

FTR:

IEEE 754: remainder
C99: remainder
IBM Decimal spec: remainder-near
Java: IEEEremainder
.NET: IEEERemainder

[mdickinson]

In many cases the function that returns the nearest integer quotient is useful.

Agreed, but I'd like to keep the scope of this issue small for now: we're simply wrapping / implementing another C99 math.h function.

[mdickinson]

FTR, I don't have strong opinions on the name: I could be persuaded by any of remainder, remainder_near or ieee_remainder. I find ieee_remainder somewhat more informative than remainder_near.

[rhettinger]

I'd prefer to keep the name that's consistent with both C and IEEE 754.

+1

Also, the decimal module names are a poor guide. Its usability has been impaired by opaque naming (i.e. needing to use quantize() when you want to round to a fixed number of places).

[mdickinson]

New changeset a0ce375 by Mark Dickinson in branch 'master':
bpo-29962: add math.remainder (#950)
a0ce375