Updates to proposal

Author: robmaceachern

proposals/nnnn-binaryinteger-iseven-isodd-isdivisible.md

@@ -0,0 +1,133 @@
+# Adding `isEven`, `isOdd`, `isDivisible` to `BinaryInteger`
+
+* Proposal: [SE-NNNN](NNNN-binaryinteger-iseven-isodd.md)
+* Authors: [Robert MacEachern](https://robmaceachern.com), [SiliconUnicorn](https://forums.swift.org/u/siliconunicorn/summary)
+* Review Manager: TBD
+* Status: **Awaiting implementation**
+
+## Introduction
+
+We propose adding `var isEven: Bool`, `var isOdd: Bool`, and `func isDivisible(by denominator: Self) -> Bool` to the `BinaryInteger` protocol. `isEven` and `isOdd` are convenience properties for querying the [parity](https://en.wikipedia.org/wiki/Parity_(mathematics)) of the integer and `isDivisible` is a more general function to determine the divisibility of an integer by an arbitrary denominator.
+
+Swift-evolution thread: [Even and Odd Integers](https://forums.swift.org/t/even-and-odd-integers/11774)
+
+## Motivation
+
+It is sometimes necessary to know whether or not an integer is divisible by a particular value. The most common case is testing for divisibility by 2, even and oddness.
+
+**Commonality:** Testing divisibility shows up in a surprising number of contexts including UI code, algorithm implementations (often in the form of assertions), tests, benchmarks, documentation and tutorial code.
+
+The most common way to test a value for divisibility is by using the remainder operator (`%`) checking for a remainder of zero: `12 % 2 == 0 // returns true. 12 is divisible by 2`. Similarly, testing for indivisibility is done by checking for a remainder other than zero: `13 % 2 != 0 // returns true. 13 is not divisible by 2`.
+
+Alternatively, it is also possible to use the bitwise AND operator (`&`) to check the even/oddness of a value: `12 & 1 == 0 // returns true`.
+
+```swift
+// Gray background for even rows, white for odd.
+view.backgroundColor = indexPath.row % 2 == 0 ? .gray : .white
+
+// Codable.swift.gyb in apple/swift
+guard count % 2 == 0 else { throw DecodingError.dataCorrupted(...) }
+
+// Bool.swift in apple/swift
+public static func random<T: RandomNumberGenerator>(using generator: inout T) -> Bool {
+    return (generator.next() >> 17) & 1 == 0
+}
+
+// KeyPath.swift in apple/swift
+_sanityCheck(bytes > 0 && bytes % 4 == 0, "capacity must be multiple of 4 bytes")
+
+// ReversedCollection Index.base documentation https://developer.apple.com/documentation/swift/reversedcollection/index/2965437-base
+guard let i = reversedNumbers.firstIndex(where: { $0 % 2 == 0 })
+```
+
+**Readability:** This proposal significantly improves readability.  There is no need to understand operator precedence rules (`%` has higher precedence than `==`) which are non-obvious.
+
+The properties are also fewer characters wide than the modulus approach (maximum 7 characters for `.isEven` vs 9 for ` % 2 == 0`) which saves horizontal space while being clearer in intent.
+
+```swift
+// Gray background for even rows, white for odd.
+view.backgroundColor = indexPath.row.isEven ? .gray : .white
+
+// Codable.swift.gyb in apple/swift
+guard count.isEven else { throw DecodingError.dataCorrupted(...) }
+
+// Bool.swift in apple/swift
+public static func random<T: RandomNumberGenerator>(using generator: inout T) -> Bool {
+    return (generator.next() >> 17).isEven
+}
+
+// KeyPath.swift in apple/swift
+_sanityCheck(bytes > 0 && bytes.isDivisible(by: 4), "capacity must be multiple of 4 bytes")
+```
+
+**Discoverability:** Determining whether a value is even or odd is a common question across programming languages, at least based on these Stack Overflow questions:
+[c - How do I check if an integer is even or odd?](https://stackoverflow.com/questions/160930/how-do-i-check-if-an-integer-is-even-or-odd) 300,000+ views
+[java - Check whether number is even or odd](https://stackoverflow.com/questions/7342237/check-whether-number-is-even-or-odd) 350,000+ views
+[Check if a number is odd or even in python](https://stackoverflow.com/questions/21837208/check-if-a-number-is-odd-or-even-in-python) 140,000+ views
+
+IDEs will be able to suggest `.isEven` and `.isOdd` as part of autocomplete which will aid discoverability.
+
+**Consistency:** It would be relatively easy to reproduce the properties in user code but there would be benefits to having a standard implementation. It may not be obvious to some users exactly which protocol these properties belong on (`Int`?, `SignedInteger`?, `FixedWidthInteger`?, `BinaryInteger`?). This inconsistency can be seen in a [popular Swift utility library](https://github.com/SwifterSwift/SwifterSwift/blob/master/Sources/Extensions/SwiftStdlib/SignedIntegerExtensions.swift#L28) which defines `isEven` and `isOdd` on `SignedInteger` which results in the properties being inaccessible for unsigned integers.
+
+These properties will also eliminate the need to use remainder 2 and bitwise AND 1 to determine parity.
+
+Adding `isEven` and `isOdd` is also consistent with the `.isEmpty` utility property, which is a convenience for `.count == 0`.
+```swift
+if array.count == 0 { ... }
+if array.isEmpty { ... }
+
+if value % 2 == 0 { ... }
+if value.isEven { ... }
+```
+
+**Correctness:** There is a minor correctness risk in misinterpreting something like `value % 2 == 0`, particularly when used in a more complex statement, when compared to `value.isEven`.
+
+**Performance:** This proposal likely won’t have a major positive impact on performance but it should not introduce any additional overhead thanks to  `@inlineable`.
+
+## Proposed solution
+
+Add two computed properties, `isEven` and `isOdd`, and a function `isDivisible` to the `BinaryInteger` protocol.
+
+```swift
+    @inlinable
+    /// A Boolean value indicating whether this value is even.
+    ///
+    /// An integer is even if it is divisible by two.
+    public var isEven: Bool {
+        return isDivisible(by: 2)
+    }
+
+    @inlinable
+    /// A Boolean value indicating whether this value is odd.
+    ///
+    /// An integer is odd if it is not divisible by two.
+    public var isOdd: Bool {
+        return !isDivisible(by: 2)
+    }
+
+    @inlinable
+    ///
+    func isDivisible(by denominator: Self) -> Bool {
+        return self % denominator == 0
+    }
+```
+
+## Detailed design
+
+N/A
+
+## Source compatibility
+
+This is strictly additive.
+
+## Effect on ABI stability
+
+N/A
+
+## Effect on API resilience
+
+N/A
+
+## Alternatives considered
+
+N/A