Project

General

Profile

Misc #15109

Improve safe navigation operator's docs

Added by zverok (Victor Shepelev) 2 months ago. Updated about 1 month ago.

Status:
Closed
Priority:
Normal
Assignee:
-
[ruby-core:88960]

Description

Reason: current docs look this way (in "Receiver" section, one paragraph before last):

You may use &. to designate a receiver, then my_method is not invoked and the result is nil when the receiver is nil. In that case, the arguments of my_method are not evaluated.

There are several problems:

  • "safe navigation operator" is never spelled explicitly (so nobody can google these docs);
  • it is rendered as "unimportant secondary" feature (just before note about legacy :: call syntax).

While mentoring newcomers, I noticed it is hard for them just to be aware of the feature. So, the proposed rendering is subsection of "Receiver" spelled this way:

=== Safe navigation operator

<code>&.</code>, called "safe navigation operator", allows to skip method call
when receiver is +nil+. It returns +nil+ and doesn't evaluate method's arguments
if the call is skipped.

  REGEX = /(ruby) is (\w+)/i
  "Ruby is awesome!".match(REGEX).values_at(1, 2)
  # => ["Ruby", "awesome"]
  "Python is fascinating!".match(REGEX).values_at(1, 2)
  # NoMethodError: undefined method `values_at' for nil:NilClass
  "Python is fascinating!".match(REGEX)&.values_at(1, 2)
  # => nil

This allows to easily chain methods which could return empty value. Note that
<code>&.</code> skips only one next call, so for a longer chain it is necessary
to add operator on each level:

  "Python is fascinating!".match(REGEX)&.values_at(1, 2).join(' - ')
  # NoMethodError: undefined method `join' for nil:NilClass
  "Python is fascinating!".match(REGEX)&.values_at(1, 2)&.join(' - ')
  # => nil

safe_navigation.patch (1.73 KB) safe_navigation.patch zverok (Victor Shepelev), 09/12/2018 06:42 PM

Associated revisions

Revision ecc627b2
Added by aycabta (aycabta .) about 1 month ago

Improve safe navigation operator's docs [Misc #15109]

  • doc/syntax/calling_methods.rdoc: Add Safe navigation operator section.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@65228 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

Revision 65228
Added by aycabta (aycabta .) about 1 month ago

Improve safe navigation operator's docs [Misc #15109]

  • doc/syntax/calling_methods.rdoc: Add Safe navigation operator section.

History

#1 [ruby-core:88997] Updated by shevegen (Robert A. Heiler) 2 months ago

I think it is good to have more documentation. I would however
had perhaps replace the word Python with Ruby (or Duck or
something else), if possible.

#2 Updated by aycabta (aycabta .) about 1 month ago

  • Status changed from Open to Closed

Applied in changeset trunk|r65228.


Improve safe navigation operator's docs [Misc #15109]

  • doc/syntax/calling_methods.rdoc: Add Safe navigation operator section.

Also available in: Atom PDF