Bug #18163: Unclear String documentation of <=> and casecmp methods

• Status: Closed
• Assignee: -
• Target version: -
• ruby -v: ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-linux]
• Backport: 2.6: DONTNEED, 2.7: DONTNEED, 3.0: DONE

[pvalena (Pavel Valena)]

I have a new student learning Ruby, and there are apparent inconsistencies in Ruby documentation.
The problem appears to be in the order of parameters / variables self and other_string.

<=>
https://docs.ruby-lang.org/en/3.0.0/String.html#method-i-3C-3D-3E

Firstly it says:

 string <=> other_string → -1, 0, 1, or nil

  -1 if other_string is smaller.

I'd expect 'B' <=> 'A' to result in -1 since 'B' is smaller. However that's not the case.

irb(main):001:0> 'B' <=> 'A'
=> 1

casecmp
https://docs.ruby-lang.org/en/3.0.0/String.html#method-i-casecmp

Identical issue, but I think more apparent is with casecmp

casecmp(other_str) → -1, 0, 1, or nil

  -1 if other_string is smaller.

From the description, I expect other_str = 'food' in the following example:

'foo'.casecmp('food') # => -1

food (other_string) is however not smaller than foo, so I'd expect the result to be 1.

[pvalena (Pavel Valena)]

I'd expect 'B' <=> 'A' to result in -1 since 'B' is smaller.

This should've been: since 'A' is smaller.

[jeremyevans0 (Jeremy Evans)]

• Status changed from Open to Closed
• Backport changed from 2.6: UNKNOWN, 2.7: UNKNOWN, 3.0: UNKNOWN to 2.6: DONTNEED, 2.7: DONTNEED, 3.0: REQUIRED

The documentation was fixed in 7f4e86804d426d79807cc038fe4444f7c65f5c4a, but it hasn't been backported to 3.0. I'm marking it for backporting.

[nagachika (Tomoyuki Chikanaga)]

• Backport changed from 2.6: DONTNEED, 2.7: DONTNEED, 3.0: REQUIRED to 2.6: DONTNEED, 2.7: DONTNEED, 3.0: DONE

ruby_3_0 badffc7bee32251e2bea5897dc502b887e7ffa9b merged revision(s) 7f4e86804d426d79807cc038fe4444f7c65f5c4a.