rename Error::iter_chain() and remove Error::iter_sources()

[haraldh]

Rename

• Error::iter_chain() -> Error::chained()
• Error::iter_sources() -> Error::ancestors()
• ErrorIter -> Chained and Ancestors

according to
#58520 (comment)

Tracker:
#58520

Edit:

Rename

• Error::iter_chain() -> Error::chained()
• ErrorIter -> Chain

So, it seems, that even Path::ancestors() includes itself. So, to avoid confusion and simplify it more, I reduced PR #65557 to only have chained and Chain.

Rationale:

1. Such iterators are helpful. They should better be stabilized sooner than later.
2. self should be included. It is easy to .skip(1) it. Not including self is harmful because it is harder to add self to the iterator than to remove it.
3. The chosen name should be telling and reflect the fact that self is included. .chained() was chosen in honor of error-chain and because the iterator iterates over the chain of errors that is somehow included in self.
4. The resulting iterator is named Chain because the error::Chain is what we want to have.

[rust-highfive]

r? @kennytm

(rust_highfive has picked a reviewer for you, use r? to override)

[kennytm]

r? @withoutboats

[teiesti]

I'd like to suggest to entirely remove Error::chained() and stay only with Error::ancestors() because Error::chained() is essentially an Error::ancestors().skip(1). We don't need a separate API for that but we could give a hint in the documentation of Error::ancestors().

[haraldh]

It's the other way round, but yes, I agree that we might only want to have one.

[teiesti]

Oh, but then the suggested names are somehow counter-intuitive, because std::path::Path::ancestors does include self.

[CryZe]

Am I really confused or is everyone else? Path::ancestors includes the original, while Error::ancestors does not. I'd honestly prefer just .sources() as source is already the terminology we use nowadays for the underlying error. We already deprecated .cause(), so introducing yet another term for it is just confusing as can be seen in this thread.

[haraldh]

So, it seems, that even Path::ancestors() includes itself. So, to avoid confusion and simplify it more, I reduced PR #65557 to only have chained and Chain.

Rationale:

1. Such iterators are helpful. They should better be stabilized sooner than later.
2. self should be included. It is easy to .skip(1) it. Not including self is harmful because it is harder to add self to the iterator than to remove it.
3. The chosen name should be telling and reflect the fact that self is included. .chained() was chosen in honor of error-chain and because the iterator iterates over the chain of errors that is somehow included in self.
4. The resulting iterator is named Chain because the error::Chain is what we want to have.

[CryZe]

I think in the majority of the cases you only want the sources, so I'd say this is definitely catering more towards an edge case scenario where you would want the current Error as well, having a negative impact on the usual use case. But I definitely agree that it simplifies the implementation and reduces the problem to just a single iterator.

[teiesti]

I think in the majority of the cases you only want the sources, so I'd say this is definitely catering more towards an edge case scenario where you would want the current Error as well, having a negative impact on the usual use case.

I disagree. E.g. when displaying errors, I am usually interested in the actual error and all the causes. Thus, an iterator that does not include self may lead to much more code and subtile bugs.

One more data point about the naming: https://docs.rs/anyhow/1.0.17/anyhow/struct.Error.html#method.chain

[withoutboats]

I think we should go with sources as the name. None of the alternatives seem at all clearer, and we have precedent from other std APIs (Path::ancestors) for the specific confusing aspect of the name (that it includes the self type).

Naming APIs "in honor" of old libraries does not seem consistent with std's usual UX, which doesn't make reference to other crates or Rust's history, and doesn't expect the user to know anything about that. The use of "chained" here doesn't seem clear without that context.

I'm +1 on the shape of the API proposed here. If you're comfortable with the name sources @haraldh, I'd r+.

[CryZe]

.sources() including self, instead of just the sources is even more confusing imo. That's not what the current .iter_sources() does and it's the reason why there's a separate .iter_chain().

[haraldh]

.sources() including self, instead of just the sources is even more confusing imo. That's not what the current .iter_sources() does and it's the reason why there's a separate .iter_chain().

exactly this was also my thinking!!

[teiesti]

After thinking once again about this, I believe, the best option is error::Error::chain (without the ed) and error::Chain; including self as the first element.

Rationale:

I think we should go with sources as the name. None of the alternatives seem at all clearer, and we have precedent from other std APIs (Path::ancestors) for the specific confusing aspect of the name (that it includes the self type).

Path::ancestors was initially called Path::parents because the iterator calls Path::parent over and over. We finally renamed it because it seemed to be odd to call self a parent. Calling self some kind of zero-ancestor seemed at least a little better. I think, with sources the rationale is similar: self is not at all its own source.

Naming APIs "in honor" of old libraries does not seem consistent with std's usual UX, which doesn't make reference to other crates or Rust's history, and doesn't expect the user to know anything about that.

Although this is certainly a good approach, I think, we haven't followed it all the time, e.g. when integrating the futures crate into the standard library. But, fair enough, my wording ("in honor of error-chain") was a litte misleading, so let me try clarify what I meant: I do not think we should go with Error::chain in order to honor the error-chain crate but because people are already familiar with the concept of iterating over causal chains of errors because of error-chain and others.

I think, the question to ask is "What does the iterator represent?". My answer is: the causal chain of errors leading to self, thus Error::chain. I think, You don't need more context (e.g. the knowledge of ancient crates) to understand this.

[haraldh]

yeah, I like chain() more than chained() ... changed and force pushed.

[haraldh]

@withoutboats or do you insist on having Error::sources() as an ergonomic shortcut for Error::chain().skip(1) ??

[faern]

A separate method and iterator for sources excluding self could be added later if there is demand. But it can't be removed once stabilized. So to make any progress at all I think we should try to move forward without it.

[JohnCSimon]

Ping from triage
@withoutboats - is this PR ready for merge, or does this PR need more work?
cc: @tspiteri @haraldh
Thanks

[Dylan-DPC-zz]

r? @sfackler

[haraldh]

want me to tackle #58520 (comment) ?

[bors]

⌛ Testing commit 7b9d50d with merge 1eefd5f6621fb7dbbe0e04df6070bc0a608bb6fe...

[tmandry]

@bors retry rolled up

[bors]

⌛ Testing commit 7b9d50d with merge 182ce0c4e2fbe7cf5f95e1871683de94f1d45497...

[tmandry]

@bors retry rolled up

[bors]

⌛ Testing commit 7b9d50d with merge 6f6f08cd026987e2f5961d1df141ef771b370956...

[JohnTitor]

@bors retry rolled up

[bors]

⌛ Testing commit 7b9d50d with merge 3f3b7ba169b20c03f9e014895a87f142f9e4e79c...

[JohnTitor]

@bors retry rolled up

[bors]

⌛ Testing commit 7b9d50d with merge ce36ab2...