Documentation improvements.

Author: stephentyrone

Sources/IntegerUtilities/RoundingRule.swift

@@ -14,24 +14,84 @@
 ///
 /// [Wikipedia](https://en.wikipedia.org/wiki/Rounding#Rounding_to_integer)
 /// provides a good overview of different rounding rules.
+///
+/// Examples using rounding to integer to illustrate the various options:
+/// ```
+///  value |     down     |      up      |  towardZero  | awayFromZero |
+/// =======+==============+==============+==============+==============+
+///   1.5  |       1      |       2      |       1      |       2      |
+/// -------+--------------+--------------+--------------+--------------+
+///  -0.5  |      -1      |       0      |       0      |      -1      |
+/// -------+--------------+--------------+--------------+--------------+
+///   0.3  |       0      |       1      |       0      |       1      |
+/// -------+--------------+--------------+--------------+--------------+
+///    2   |       2      |       2      |       2      |       2      |
+/// -------+--------------+--------------+--------------+--------------+
+///
+///  value |    toOdd     | toNearestOrAwayFromZero |  toNearestOrEven |
+/// =======+==============+=========================+==================+
+///   1.5  |       1      |            2            |         2        |
+/// -------+--------------+-------------------------+------------------+
+///  -0.5  |      -1      |           -1            |         0        |
+/// -------+--------------+-------------------------+------------------+
+///   0.3  |       1      |            0            |         0        |
+/// -------+--------------+-------------------------+------------------+
+///    2   |       2      |            2            |         2        |
+/// -------+--------------+-------------------------+------------------+
+///
+///  value |    stochastically     |  requireExact  |
+/// =======+=======================+================+
+///   1.5  |     50% 1, 50% 2      |      trap      |
+/// -------+-----------------------+----------------+
+///  -0.5  |    50% -1, 50% 0      |      trap      |
+/// -------+-----------------------+----------------+
+///   0.3  |     70% 0, 30% 1      |      trap      |
+/// -------+-----------------------+----------------+
+///    2   |          2            |        2       |
+/// -------+-----------------------+----------------+
+/// ```
 public enum RoundingRule {
   /// Produces the closest representable value that is less than or equal
   /// to the value being rounded.
   ///
   /// This is the default rounding mode for integer shifts, including the
-  /// shift operators defined in the standard library.
+  /// shift operators defined in the standard library. 
+  ///
+  /// Examples:
+  /// - `(-4).divided(by: 3, rounding: .down)` is `-2`, because –2 is the
+  /// largest integer less than –4/3 = –1.3̅
+  /// - `5.shifted(rightBy: 1, rounding: .down)` is `2`, because 2 is the
+  /// largest integer less than 5/2 = 2.5.
   case down
 
   /// Produces the closest representable value that is greater than or equal
   /// to the value being rounded.
+  ///
+  /// Examples:
+  /// - `(-4).divided(by: 3, rounding: .up)` is `-1`, because –1 is the
+  /// smallest integer greater than –4/3 = –1.3̅
+  /// - `5.shifted(rightBy: 1, rounding: .up)` is `3`, because 3 is the
+  /// smallest integer greater than 5/2 = 2.5.
   case up
 
   /// Produces the closest representable value whose magnitude is less than
   /// or equal to that of the value being rounded.
+  ///
+  /// Examples:
+  /// - `(-4).divided(by: 3, rounding: .towardZero)` is `-1`, because –1
+  /// is the closest integer to –4/3 = –1.3̅ with smaller magnitude.
+  /// - `5.shifted(rightBy: 1, rounding: .towardZero)` is `2`, because 2
+  /// is the closest integer to 5/2 = 2.5 with smaller magnitude.
   case towardZero
 
-  /// Produces the closest representable value whose magnitude is greater than
-  /// or equal to that of the value being rounded.
+  /// Produces the closest representable value whose magnitude is greater
+  /// than or equal to that of the value being rounded.
+  ///
+  /// Examples:
+  /// - `(-4).divided(by: 3, rounding: .awayFromZero)` is `-2`, because –2
+  /// is the closest integer to –4/3 = –1.3̅ with greater magnitude.
+  /// - `5.shifted(rightBy: 1, rounding: .awayFromZero)` is `3`, because 3
+  /// is the closest integer to 5/2 = 2.5 with greater magnitude.
   case awayFromZero
 
   /// If the value being rounded is representable, that value is returned.
@@ -45,16 +105,37 @@ public enum RoundingRule {
   /// we get is the same as if we rounded directly to p₂ in the desired mode
   /// so long as p₂ + 1 < p₁. Other rounding modes do not have this property,
   /// and admit _double roundings_ when interoperating with some modes.
+  ///
+  /// Examples:
+  /// - `(-4).divided(by: 3, rounding: .toOdd)` is `-1`, because –4/3 = –1.3̅
+  /// is not an exact integer, and –1 is the closest odd integer.
+  /// - `4.shifted(rightBy: 1, rounding: .toOdd)` is `2`,
+  /// even though 2 is even, because 4/2 is exactly 2 and no rounding occurs.
   case toOdd
 
   /// Produces the representable value that is closest to the value being
   /// rounded. If two values are equally close, the one that has greater
   /// magnitude is returned.
+  ///
+  /// Examples:
+  /// - `(-4).divided(by: 3, rounding: .toNearestOrAwayFromZero)`
+  /// is `-1`, because –4/3 = –1.3̅ is closer to –1 than it is to –2.
+  ///
+  /// - `5.shifted(rightBy: 1, rounding: .toNearestOrAwayFromZero)` is `3`,
+  /// because 5/2 = 2.5 is equally close to 2 and 3, and 3 is further away
+  /// from zero.
   case toNearestOrAwayFromZero
 
   /// Produces the representable value that is closest to the value being
   /// rounded. If two values are equally close, the one whose least
   /// significant bit is not set is returned.
+  ///
+  /// Examples:
+  /// - `(-4).divided(by: 3, rounding: .toNearestOrEven)`
+  /// is `-1`, because –4/3 = –1.3̅ is closer to –1 than it is to –2.
+  ///
+  /// - `5.shifted(rightBy: 1, rounding: .toNearestOrEven)` is `2`,
+  /// because 5/2 = 2.5 is equally close to 2 and 3, and 2 is even.
   case toNearestOrEven
 
   /// Adds a uniform random value from [0, d) to the value being rounded,
@@ -88,9 +169,19 @@ public enum RoundingRule {
   /// ```
   /// but this isn't always possible in more sophisticated scenarios,
   /// and in those cases this rounding rule may be useful.
+  ///
+  /// Examples:
+  /// - `(-4).divided(by: 3, rounding: .stochastically)`
+  /// will be –1 with probability 2/3 and –2 with probability 1/3.
+  /// - `5.shifted(rightBy: 1, rounding: .stochastically)`
+  /// will be 2 with probability 1/2 and 3 with probability 1/2.
   case stochastically
 
   /// If the value being rounded is representable, that value is returned.
   /// Otherwise, a precondition failure occurs.
+  ///
+  /// Examples:
+  /// - `(-4).divided(by: 3, rounding: .requireExact)` will trap,
+  /// because –4/3 = –1.3̅ is not an integer.
   case requireExact
 }

Sources/IntegerUtilities/ShiftWithRounding.swift

@@ -27,14 +27,14 @@ extension BinaryInteger {
   ///     // is odd.
   ///     3.shifted(rightBy: 1, rounding: .toOdd)
   ///
-  ///     // 7/2^2 = 1.75, so the result is 1 with probability 1/4, and 2
+  ///     // 7/4 = 1.75, so the result is 1 with probability 1/4, and 2
   ///     // with probability 3/4.
   ///     7.shifted(rightBy: 2, rounding: .stochastically)
   ///
-  ///     // 4/2^2 = 4/4 = 1, exactly.
+  ///     // 4/4 is exactly 1, so this does not trap.
   ///     4.shifted(rightBy: 2, rounding: .trap)
   ///
-  ///     // 5/2 is 2.5, which is not exact, so this traps.
+  ///     // 5/2 is 2.5, which is not an integer, so this traps.
   ///     5.shifted(rightBy: 1, rounding: .requireExact)
   ///
   /// When `Self(1) << count` is positive, the following are equivalent:
@@ -124,18 +124,18 @@ extension BinaryInteger {
       return floor + Self((round + lost) >> count)
     case .stochastically:
       // TODO: it's unfortunate that we can't specify a custom random source
-      // for the stochastically rounding rule, but I don't see a nice way to have
-      // that share the API with the other rounding rules, because we'd then
-      // have to take the RNG in-out. The same problem applies to rounding
-      // with dithering. We should consider adding a stateful rounding API
-      // down the road to support those use cases.
+      // for the stochastically rounding rule, but I don't see a nice way to
+      // have that share the API with the other rounding rules, because we'd
+      // then have to take the RNG in-out. The same problem applies to
+      // rounding with dithering. We should consider adding a stateful
+      // rounding API down the road to support those use cases.
       //
       // In theory, u01 should be Self.random(in: 0 ..< onesBit), but the
       // random(in:) method does not exist on BinaryInteger. This is
       // (arguably) good, though, because there's actually no reason to
-      // generate large amounts of randomness just to implement stochastically
-      // rounding for bigints; 32b suffices for most purposes, and 64b is
-      // more than enough.
+      // generate large amounts of randomness just to implement stochastic
+      // rounding; 32b suffices for almost all purposes, and 64b is more
+      // than enough.
       var g = SystemRandomNumberGenerator()
       let u01 = g.next()
       if count < 64 {
@@ -173,14 +173,14 @@ extension BinaryInteger {
   ///     // is odd.
   ///     3.shifted(rightBy: 1, rounding: .toOdd)
   ///
-  ///     // 7/2^2 = 1.75, so the result is 1 with probability 1/4, and 2
+  ///     // 7/4 = 1.75, so the result is 1 with probability 1/4, and 2
   ///     // with probability 3/4.
   ///     7.shifted(rightBy: 2, rounding: .stochastically)
   ///
-  ///     // 4/2^2 = 4/4 = 1, exactly.
+  ///     // 4/4 is exactly 1, so this does not trap.
   ///     4.shifted(rightBy: 2, rounding: .trap)
   ///
-  ///     // 5/2 is 2.5, which is not exact, so this traps.
+  ///     // 5/2 is 2.5, which is not an integer, so this traps.
   ///     5.shifted(rightBy: 1, rounding: .requireExact)
   ///
   /// When `Self(1) << count` is positive, the following are equivalent: