Change:
/// # Examples /// /// ``` <del> /// #![feature(io_error_downcast)] /// </del> /// use std::fmt; /// use std::io; /// use std::error::Error;

Discussion:
Feature gate: This is a tracking issue for new API . Existing APIs requires two separate calls to obtain the raw os error or the inner error and they both return . Thus, users would have to first call to check that we indeed has an inner error and checked that it  the type we expected. Users cannot use becuase takes the error by value and returns instead of . They also cannot workaround this issue by calling , since the can also be constructed using  or using other internal methods only accessible by the std library. This new feature solved this issue by providing new API to downcast the inner error easily without or . [x] API Change Proposal: [x] Implementation: [x] Update return type and doc: [x] Final comment period (FCP)[^1] [ ] Stabilization PR <!-- Once the feature has gone through a few release cycles and there are no unresolved questions left, the feature might be ready for stabilization. If this feature didn't go through the RFC process, a final comment period (FCP) is always needed before stabilization. This works as follows: A library API team member can kick off the stabilization process, at which point the rfcbot will ask all the team members to verify they agree with stabilization. Once enough members agree and there are no concerns, the final comment period begins: this issue will be marked as such and will be listed in the next This Week in Rust newsletter. If no blocking concerns are raised in that period of 10 days, a stabilzation PR can be opened by anyone. --- None yet. [^1]: https://std-dev-
I'd like to push for stabilisation of this feature. The only thing I'm not sure about is the return value Returning a here might expose too much of an internal detail, in case the internals of change in future to use something like a thin box.
Emmm it seems I can't at libs-api team...
r?
"r?" doesn't seem to work for me... Is that because I don't have the permission to do so?
I'd want to stablise the feature and I'd like your feedback. IMHO there's nothing blocking the stablisation.
Pinging
implemented in A summary of the API is included . n/a
seems to be on away from github Can we have a fcp poll for this?
r?

libs-api
Hmmm, sorry for the @ mentions, I didn't know how to proper request for stablisation.
label +S-waiting-on-team
fcp merge Signature resembles these existing stable ones:
Team member has proposed to merge this. The next step is review by the rest of the tagged team members: [x] [x] [x] [ ] [x] Concerns: resolved by resolved by Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up! See for info about what commands tagged team members can give me.
concern docs The docs here I think should be up a bit. I see a few things worth improving: prose in the docs use the word "downgrade" but the method is called "downcast." I expect we want these to be consistent? think it'd be worth mentioning that this is a convenience routine for some other sequence of methods. example looks pretty circuitous and incomplete. It shows but doesn't actually show something that can be executed and whose result can be asserted. Can we come up with something better please? API guarantee stated here seems a little iffy. Is it really true that will always return an error if the was constructed via any means other than ? I'd really prefer if we could state the contract without referring to "you had to have called this particular method for this to work." Instead, can we talk about the data inside of it?
concern box mentioned a question above about returning a here potentially limiting our choices down the line. Is this true? It looks like there are other APIs on that return a , so I wonder if that ship has already sailed. Also, AIUI, an can be , but the API being proposed here asks for a sized . Am I understanding that correctly? If so, and if the implicit constraint is intentional, then presumably we don't need to return a at all and could just return an . But I imagine we probably want to support ?
I was worried about that could change their implementation later. It currently uses something like to store the error, but it could be changed to something else later.

For example, it could change  to store and the error in one allocation, though that will require it to manually deal with vtable and unsized allocation, but it is indeed possible. In that case, returning could incur additional overhead, though it could be alleviated by simply resizing the allocation. Yes, [], the API where is modeled after, return a . But TBF, [] returns so it has to use . returns a concrete type so it does not have to return a boxed value. []: Yes, that's right. Well, I don't think we need support for . [] can take any type that , but AFAIK we can only create from value right now. In the future where it might be supported, but in practice I rarely seen types that are . I think it makes more sense to remove the than adding support. []: Yes. Won't that leak the internal into the API? There are actually 4 ways of constructing : : Only store in : Only store a in : Store plus a . : Stores : The first 3 are public and can be done by everybody, the last one is and can be only done by std itself. It's possible for to add more variants that are internal to std, so not sure this is a great idea. Also, it's hard to explain that there is a only , that will only make the reader more confusing. Yes, I can submit a PR to improve its doc once we settle on whether to remove the or makes . I don't think this is necessary though. Putting convenience aside, using also removes one , one heap deallocation and heap allocation if the isn't the error stores internally: I actually have an example of this from : As you can see, it has to call (which could be optimized out, but still a hazard if the user is pedantic) and it has to call , which deallocates the stored internally in and it calls again if unmatch, which requires to be allocated again. I haven't checked the generated assembly, the optimizer might be smart enough to optimize these heap allocation out. But that isn't a guarantee and crates like is built using , so that might not actually happen.
We discussed this in the libs-api meeting. We think that we can move forward with the FCP once the changes proposed by are addressed: should return plain instead of boxing the error.

While it's true that the error is boxed internally, this may not always be true in the future, and if you're downcasting to a specific type then you usually don't need the box. Regarding the docs, I think your response addresses the concerns, so this should be resolved.
implemented in Update return type and doc according to concern from in signature resembles existing stable ones: n/a
I believe your concerns have now been addressed
resolve box
I think my docs concerns have not been fully addressed here. The docs for this routine seem both too sparse and too odd to me. I'll try to respond to the bits of comment above that I think are relevant here. I'd really prefer if we could state the contract without referring to "you had to have called this particular method for this to work." Instead, can we talk about the data inside of it? No. I'm certainly not asking that the documentation of a type discuss its internal representation. What I'm asking for is a contract that doesn't involve wording like, "you have to have called this method to get this guarantee." Like, I grant there are some situations in which it can make sense to use wording like that, but it's IMO bad juju to start phrasing API contracts in terms of sequences of function calls. It's rather inflexible. And while you enumerated the list of possible constructors today, that isn't necessarily an exhaustive list for all time. Indeed, it's already wrong! (Where "it" is the docs as written today. I see that you mention in your comment.) Because it looks to me like will also attempt downcasting when was used to build the error. Instead, I'd rather see the phrasing be something like this: "when this contains a custom boxed error, downcasting will be attempted on the boxed error." I think it'd be worth mentioning that this is a convenience routine for some other sequence of methods. I'm not really sure how to interpret this response, but the point of saying this is to orient the user's understanding of a routine in terms of another one. That is, it's useful to be able to say, "this doesn't introduce any new expressive power, but is instead a convenience routine for some other thing." Please add this to the docs.

I also still see a couple of other problems with the docs: says "downgrade" instead of "downcast." docs should minimally state what "success" means. That is, that is the same underlying type as the boxed error that contains.
I have opened , would like you to have a look NOTE that this is actually copied from , so you would probably also want to update doc for that method.
Now that is merged, resolve docs
:bell: This is now entering its final comment period, as per the . :bell:
The final comment period, with a disposition to merge, as per the , is now complete. As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed. This will be merged soon.