No quick help for operators and % operator incorrectly documented?

There seem to be no quick help available for operators in Xcode. So in order to see the documentation for the % operator in eg

let r = 123 % 4

we have to do "Jump to Definition" on the % operator, which will take us to the following generated interface:

/// Returns the remainder of dividing the first value by the second.
///
/// The result of the modulo operator (`%`) has the same sign as `lhs` and is
/// less than `rhs.magnitude`.
///
///     let x = 22 % 5
///     // x == 2
///     let y = 22 % -5
///     // y == 2
///     let z = -22 % -5
///     // z == -2
///
/// For any two integers `a` and `b`, their quotient `q`, and their remainder
/// `r`, `a == b * q + r`.
///
/// - Parameters:
///   - lhs: The value to divide.
///   - rhs: The value to divide `lhs` by. `rhs` must not be zero.
public static func % (lhs: Int, rhs: Int) -> Int

(I'm using an Xcode 10 beta.)

Note that it says "The result of the modulo operator (%) has …"
while The Language Reference calls it "the remainder operator" and includes the following note:

NOTE
The remainder operator (%) is also known as a modulo operator in other languages. However, its behavior in Swift for negative numbers means that, strictly speaking, it’s a remainder rather than a modulo operation.


So, two questions:

  • Is the no-quick-help-for-operators-issue known? If not, should it be reported to Jira or as a radar?

  • Should I file a Jira for improving the % operator documentation by replacing "modulo" with "remainder"?

2 Likes

It's a known bug in Xcode.

Please do, thanks!

1 Like

Perhaps one could also improve the description of the operator. The Language Reference explains

To calculate 9 % 4, you first work out how many 4s will fit inside 9:
...
You can fit two 4s inside 9, and the remainder is 1.

which is fine, but later:

The same method is applied when calculating the remainder for a negative value of a:
-9 % 4 // equals -1

The “same method?” How many 4s fit into -9 ???

1 Like

What would you suggest changing there? I've read the text over a few times and it flows fairly naturally to me. My parsing of it is that the "same method" is talking about the equation solving technique that happens in between the two parts you quoted.

Two, if you're starting a -9, then walking toward 0. Then you're left with -1 as the remainder. I haven't thought about remainders deeply recently, but it seems like a plausible interpretation of numbers fitting into negative numbers.

But according to the recipe

a = (b x some multiplier) + remainder
where some multiplier is the largest number of multiples of b that will fit inside a.

4 fits (-2) times into -9, so that

-9 = (4 x -2) + -1

gives a remainder of -1.

I would probably use the descriptive explanation only for the case of positive dividend and divisor, and

a % b = a - b * (a / b)

(with the truncating division) for the general case. But I don't want to distract the conversation too far, perhaps this is just my personal problem with the formulation :)

Yes, please report on Jira, and CC me and @nnnnnnnn (or simply create a patch if you prefer).

SR-8255

2 Likes