[ruby-core:105222] [Ruby master Bug#18163] Unclear String documentation of <=> and casecmp methods

Issue #18163 has been updated by jeremyevans0 (Jeremy Evans).

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

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

----------------------------------------
Bug #18163: Unclear String documentation of <=> and casecmp methods
https://bugs.ruby-lang.org/issues/18163#change-93628

* Author: pvalena (Pavel Valena)
* Status: Closed
* Priority: Normal
* ruby -v: ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-linux]
* Backport: 2.6: DONTNEED, 2.7: DONTNEED, 3.0: REQUIRED
----------------------------------------
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`.





-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:[e-mail]?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>