Skip to content

proposal: errors: document what errors.Is(x, nil) means #73122

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
cederlys opened this issue Apr 1, 2025 · 3 comments
Closed

proposal: errors: document what errors.Is(x, nil) means #73122

cederlys opened this issue Apr 1, 2025 · 3 comments
Labels
Documentation Issues describing a change to documentation. LibraryProposal Issues describing a requested change to the Go standard library or x/ libraries, but not to a tool Proposal
Milestone
Proposal

Comments

@cederlys
Copy link

cederlys commented Apr 1, 2025

Proposal Details

Given the current implementation of errors.Is, doing err != nil is equivalent to !errors.Is(err, nil). The err != nil is arguably often better: it is shorter, perhaps faster, and a common Go idiom. But there are occasions where using nil arguments to errors.Is makes sense.

One such example is test code. You might have a list of input and expected outputs of a function under test. If the function returns an error err, it makes sense to use if !errors.Is(err, expected_error) { return ErrWrongError }, even if expected_error is nil.

This currently works, but the behavior is not documented. In both #40442 and #40673 it was suggested that this should be documented, but apparently that never happened.

I propose that the current behavior is documented. Proposal: add one sentence in the first paragraph, so that it becomes:

Is reports whether any error in err's tree matches target. If target is nil, err matches target if err is also nil.
@gopherbot gopherbot added this to the Proposal milestone Apr 1, 2025
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Apr 1, 2025
@gabyhelp
Copy link

gabyhelp commented Apr 1, 2025

Related Issues

Related Documentation

(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)

@gabyhelp gabyhelp added the LibraryProposal Issues describing a requested change to the Go standard library or x/ libraries, but not to a tool label Apr 1, 2025
@seankhliao
Copy link
Member

The current docs say:

An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.

I believe this is sufficient to cover nil.
Reading the past proposals, I don't think checks against nil a property to promote. The canonical nil check is err != nil, and that is what we expect users to write.

@seankhliao seankhliao closed this as not planned Won't fix, can't repro, duplicate, stale Apr 1, 2025
@cederlys
Copy link
Author

cederlys commented Apr 2, 2025

Thanks for the clarification. In my view, nil isn't an error (that is why err != nil works), so I assumed that sentence only said anything about non-nil values. Given all the earlier discussions, I still think the documentation could be improved, to avoid the same confusion in the future. But now at least I have this ticket to point to.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. LibraryProposal Issues describing a requested change to the Go standard library or x/ libraries, but not to a tool Proposal
Projects
None yet
Milestone
Proposal
Development

No branches or pull requests
4 participants
@cederlys @gopherbot @seankhliao @gabyhelp