Document the definition of the word "unwrap" as used by Rust

[trevyn]

I was teaching a newbie some Rust, and doing the usual hand-waving about error handling using unwrap. They asked what 'unwrap' means. I said look it up in the docs. The docs read (paraphrased) "unwrap unwraps". I was embarrassed.

#68918 Don't use the word "unwrap" to describe "unwrap" methods

The English word "unwrap" is used in the name of numerous methods in core and std, but is not defined by the documentation and does not have a commonly accepted concrete definition in computer science. The everyday concept of "unwrapping" is not detailed enough to resolve questions about the precise meaning of the term as it is used in Rust.

Existing methods:

	methods
Result	unwrap, unwrap_or, unwrap_or_else, unwrap_or_default, unwrap_err
Option	unwrap, unwrap_or, unwrap_or_else, unwrap_or_default, unwrap_none (unstable)
Rc	try_unwrap
Arc	try_unwrap

Based on this existing usage, I propose a definition:

An "unwrap" method in Rust extracts an underlying value from one or more containers, consumes the container(s), and returns an owned value.

Result::unwrap() and Option::unwrap() (and their variants) unwrap two containers in one step: The abstract Result or Option itself, and the concrete Ok or Some tuple variant inside. You might think of unwrap as being shorthand for "unwrap_ok" and "unwrap_some", though these methods do not exist.

Result::unwrap_err() and Option::unwrap_none() (nightly only) express that the Err or None variants are expected instead, and that those containers are the ones that should be unwrapped.

Outstanding questions: Where is the most appropriate place to put a definition of "unwrap"? Is The Book canonical?

Previous discussion in:
#62633 Tracking issue for Option::expect_none(msg) and unwrap_none()
#73077 Stabilize Option::expect_none(msg) and Option::unwrap_none()
#77326 Stabilize Option::unwrap_none and Option::expect_none
#68849 Don't use the word 'unwrap' to describe core 'unwrap' functions
#68918 Don't use the word "unwrap" to describe "unwrap" methods
#23713 Make Option.unwrap documentation more precise
#19149 Rename unwrap functions to into_inner
#430 RFC: Finalizing more naming conventions
etc...

[trevyn]

@steveklabnik Do you have a sense of where in the documentation a canonical definition of the word "unwrap" might belong?

The std documentation appears to strictly break things down by module or other primitive, and this does not intuitively belong to any single one of those, since it cuts across Result, Option, Rc, and Arc. (Not to mention that I believe it only involves re-exports from core, and has importance beyond its use in std.)

[trevyn]

@rustbot modify labels: T-doc

[steveklabnik]

To be honest, I don't really understand why we would "define" a word. It's the name of a method, that's it. There's no special definition, or any strange usage. We don't write definitions of any other method names. The definition is the documentation of the unwrap method.

[dtolnay]

I would not want to dedicate documentation to this either. The meaning in the context of Rust is 100% defined by the set of behaviors that have been given this name. When considering leveraging a preexisting name for a new behavior, the libs team evaluates how much the new behavior is in line with any old behaviors that already use the name. In my experience for those discussions a definition is not necessary, and maybe even counterproductive.

For a word that is more obscure, the place to record the way we choose to use it in standard library APIs would be the standard library dev guide at https://std-dev-guide.rust-lang.org, but I think unwrap is not one where that would be needed.

[trevyn]

Ah, understood. Thank you for the clear explanation.

I still think that understanding “what unwrap actually means” is a meaningful hole in the user experience, but I suppose that’s a job for a community blog post or talk.