tracking issue for debug_non_exhaustive feature

[richard-uk1]

Feature gate: #![feature(debug_non_exhaustive)]

This is a tracking issue for adding the ability to add an ellipsis to the end of the Debug representation of a struct, to indicate that the struct has more fields, but that these fields are not displayable. This involves adding the finish_non_exhaustive method to DebugStruct, that produces output like

Name { field1: value1, .. }

where the .. indicate that there are more hidden fields.

Public API

// core::fmt

impl<'a, 'b: 'a> DebugStruct<'a, 'b> {
    pub fn finish_non_exhaustive(&mut self) -> fmt::Result;
}

Steps / History

• Implementation: Implement DebugStruct::non_exhaustive. #66716
• Final commenting period (FCP): tracking issue for debug_non_exhaustive feature #67364 (comment)
• Stabilization PR: stabilize debug_non_exhaustive #83041
• Replace .finish() by .finish_non_exhaustive() within the standard library where it makes sense: Use DebugStruct::finish_non_exhaustive() in std. #83558 Improve Debug implementations of Mutex and RwLock. #83561

Unresolved Questions

• Should this method be implemented for DebugTuple and DebugMap as well?
  • I would probably say "no" since I can't think of any use cases for them. They could always be added later.

[rossmacarthur]

Any ETA as to when this might be stabilized? What is blocking this being stabilized?

[richard-uk1]

AFAIK there aren't any blockers to stabilizing. Things normally live in nightly so they can be tested, but in this case it's unlikely someone will drop stable support just so they can use this feature. I think it will only be used once it's stable.

[richard-uk1]

It's a small low-risk change (since the methods can be reimplemented or deprecated if they are really broken).

[rossmacarthur]

Although not its primary intention I also find this feature quite useful when implementing Debug for structs that can't be derived. Where you still want to indicate that not all fields are shown. For example:

struct Example {
    field: String,
    func: Box<dyn Fn(&str) -> bool + 'static>
}

impl fmt::Debug for Example {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.debug_struct("Example")
            .field("field", &self.field)
            .finish_non_exhaustive()
    }
}

[richard-uk1]

It could be possible to extend #[derive(Debug)] to work on structs/enums with non-Derive fields, by skipping them and marking it non-exhaustive.

[kornelski]

I also have a use-case for partially printing structs. In my case printing all of struct's fields in a meaningful way would be rather complex and require potentially-expensive FFI calls, so I'd rather omit them from debug output, but I still want to leave a hint that they exist.

[bbqsrc]

I have a use case for printing expensive structs as well.

[dimpolo]

It would be nice to have a finish_non_exhaustive method on DebugTuple for my crate.

[richard-uk1]

It would be nice to have a finish_non_exhaustive method on DebugTuple for my crate.

Maybe its time to revisit the open question. I could implement this if there were consensus it's a good idea.

[m-ou-se]

Any ETA as to when this might be stabilized? What is blocking this being stabilized?

Looks like there are no blockers. There's still the question of whether this is also wanted on DebugList, DebugMap, DebugSet, and/or DebugTuple. But that doesn't have to block stabilization of DebugStruct::finish_non_exhaustive.

[guswynn]

I think that at least for DebugTuple finish_non_exhaustive makes sense as its at least partially is intended to be used with tuple structs. As for DebugList, DebugMap, and DebugSet, I would guess that people wanting this would be less common, but it is likely a small enough api surface to be uncontroversial. @derekdreery For me, DebugStruct::finish_non_exhaustive is nice enough that I will likely submit a stabilization PR, and if you are no longer interested in creating a new feature for impls on the other ones, I may be able to find time to do that as well!

[richard-uk1]

Hey @guswynn can you put a note on here if you start working on adding support for the other struct types, to make sure that we don't duplicate work. :)

[m-ou-se]

@rfcbot merge

DebugStruct::finish_non_exhaustive() is an alternative to DebugStruct::finish() that prints , .. } instead of }.

Similar functionality on DebugList, DebugMap, DebugSet, and/or DebugTuple was briefly discussed but seems less important, so is not included here.

[rfcbot]

Team member @m-ou-se has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @KodrAus
• @dtolnay
• @joshtriplett
• @m-ou-se
• @sfackler

No concerns currently listed.

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 this document for info about what commands tagged team members can give me.

[m-ou-se]

I've added a to do item to the steps above:

• Replace .finish() by .finish_non_exhaustive() within the standard library where it makes sense.

Not critical, but it'd be nice if we (std/core) set the right example.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, 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.

The RFC will be merged soon.

[guswynn]

@pickfire I believe that would be a significant departure from how debug_struct works, as it currently knows nothing about what fields are in the struct. As far as I can tell, what you describe would have to be supported by the derive(Debug) macro or something like that

[guswynn]

@pickfire https://docs.rs/debug_stub_derive/0.3.0/debug_stub_derive/ may cover what you want?

[ranile]

What is preventing this from being stabilized? As far as I can tell, all the requirements are met.

[jhpratt]

@hamza1311 It's stable on nightly. It will land in Rust 1.53.

[m-ou-se]

This was stablized a month ago: #83041

Closing this issue, since the other action items are now also completed.

[dcormier]

I, too, would like to see this on DebugTuple, and was just surprised to find that it wasn't. I was already familiar with it on DebugStruct, so I didn't realize it was only there.

In my case, I wanted to shorten the debug representation of a tuple when any of the fields are None, and indicate that fields were left out.

[richard-uk1]

If anyone wanted to have a go at writing a PR, this (implementing for DebugTuple) would be a good first issue. It can go in as unstable for experimentation, assuming that the powers that be agree on its usefulness.

[ian-h-chamberlain]

I found this issue while wondering why there wasn't an equivalent finish_non_exhaustive for DebugTuple, but in the meantime I though I'd share a workaround I found in case people are looking for something to use on stable.

You can (ab?)use the fact that std::ops::RangeFull has a Debug impl to your advantage, and use the existing field() to display .. when you want to omit some fields:

f.debug_tuple("Foo").field(&{..}).finish()

Playground example: https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=d1b7f91c84969e0de54f70b90d9570bc

This may not be as nice as a first-class finish_non_exhaustive method would be, but it offers some nice flexibility and works today!

Also worth noting, perhaps, is how rust docs display private fields on tuple structs, e.g.
https://doc.rust-lang.org/std/thread/struct.JoinHandle.html

I think you could emulate this with a struct that has _ as its debug representation, but it ends up being a good chunk of boilerplate with little benefit IMO.

[richard-uk1]

That's a great hack! Honestly though AFAIK the only thing stopping there being an impl for this on tuples is someone writing the patch. It should be relatively straightforward even for someone who doesn't know the rustc codebase if you use this PR as a template.