revert to the inconsistent paragraph wrapping. · model-checking/verify-rust-std@9677b70 (original) (raw)

`@@ -2,8 +2,8 @@

2

`//!

3

`` //! [Result<T, E>][Result] is the type used for returning and propagating

4

`` //! errors. It is an enum with the variants, [Ok(T)], representing success and

5

`` -

//! containing a value, and [Err(E)], representing error and containing an

6

//! error value.

5

`` +

//! success and containing a value, and [Err(E)], representing error

6

//! and containing an error value.

7

`//!

8

```` //! ```


`9`

`9`

`//! # #[allow(dead_code)]

`

`@@ -14,10 +14,11 @@

`

`14`

`14`

```` //! ```

15

`//!

16

`` //! Functions return [Result] whenever errors are expected and recoverable. In

17

`` -

//! the std crate, [Result] is most prominently used for

18

//! I/O.

17

`` +

//! recoverable. In the std crate, [Result] is most prominently used

18

//! for I/O.

19

`//!

20

`` -

//! A simple function returning [Result] might be defined and used like so:

20

`` +

//! A simple function returning [Result] might be

21

//! defined and used like so:

21

22

`//!

22

23

```` //! ```


`23`

`24`

`//! #[derive(Debug)]

`

`@@ -40,8 +41,8 @@

`

`40`

`41`

```` //! ```

41

42

`//!

42

43

`` //! Pattern matching on [Result]s is clear and straightforward for simple

43

`` -

//! cases, but [Result] comes with some convenience methods that make working

44

//! with it more succinct.

44

`` +

//! simple cases, but [Result] comes with some convenience methods

45

//! that make working with it more succinct.

45

46

`//!

46

47

```` //! ```


`47`

`48`

`//! let good_result: Result<i32, i32> = Ok(10);

`

`@@ -67,15 +68,16 @@

`

`67`

`68`

`//!

`

`68`

`69`

`//! # Results must be used

`

`69`

`70`

`//!

`

`70`

``

`-

//! A common problem with using return values to indicate errors is that it is

`

`71`

``

`-

//! easy to ignore the return value, thus failing to handle the error.

`

`72`

``

`` -

//! [`Result`] is annotated with the `#[must_use]` attribute, which will cause

``

`73`

``

`-

//! the compiler to issue a warning when a Result value is ignored. This makes

`

`74`

``

`` -

//! [`Result`] especially useful with functions that may encounter errors but

``

`75`

``

`-

//! don't otherwise return a useful value.

`

``

`71`

`+

//! A common problem with using return values to indicate errors is

`

``

`72`

`+

//! that it is easy to ignore the return value, thus failing to handle

`

``

`73`

`` +

//! the error. [`Result`] is annotated with the `#[must_use]` attribute,

``

``

`74`

`+

//! which will cause the compiler to issue a warning when a Result

`

``

`75`

`` +

//! value is ignored. This makes [`Result`] especially useful with

``

``

`76`

`+

//! functions that may encounter errors but don't otherwise return a

`

``

`77`

`+

//! useful value.

`

`76`

`78`

`//!

`

`77`

``

`` -

//! Consider the [`write_all`] method defined for I/O types by the [`Write`]

``

`78`

``

`-

//! trait:

`

``

`79`

`` +

//! Consider the [`write_all`] method defined for I/O types

``

``

`80`

`` +

//! by the [`Write`] trait:

``

`79`

`81`

`//!

`

`80`

`82`

```` //! ```

81

83

`//! use std::io;

`@@ -85,11 +87,12 @@

85

87

`//! }

86

88

```` //! ```


`87`

`89`

`//!

`

`88`

``

`` -

//! *Note: The actual definition of [`Write`] uses [`io::Result`], which is just

``

`89`

``

`-

//! a synonym for <code>[Result]<T, [io::Error]></code>.*

`

``

`90`

`` +

//! *Note: The actual definition of [`Write`] uses [`io::Result`], which

``

``

`91`

`+

//! is just a synonym for <code>[Result]<T, [io::Error]></code>.*

`

`90`

`92`

`//!

`

`91`

``

`-

//! This method doesn't produce a value, but the write may fail. It's crucial to

`

`92`

``

`-

//! handle the error case, and *not* write something like this:

`

``

`93`

`+

//! This method doesn't produce a value, but the write may

`

``

`94`

`+

//! fail. It's crucial to handle the error case, and *not* write

`

``

`95`

`+

//! something like this:

`

`93`

`96`

`//!

`

`94`

`97`

```` //! ```no_run

95

98

`//! # #![allow(unused_must_use)] // \o/

`@@ -102,12 +105,12 @@

102

105

`//! file.write_all(b"important message");

103

106

```` //! ```


`104`

`107`

`//!

`

`105`

``

`-

//! If you *do* write that in Rust, the compiler will give you a warning (by

`

`106`

``

`` -

//! default, controlled by the `unused_must_use` lint).

``

``

`108`

`+

//! If you *do* write that in Rust, the compiler will give you a

`

``

`109`

`` +

//! warning (by default, controlled by the `unused_must_use` lint).

``

`107`

`110`

`//!

`

`108`

``

`-

//! You might instead, if you don't want to handle the error, simply assert

`

`109`

``

`` -

//! success with [`expect`]. This will panic if the write fails, providing a

``

`110`

``

`-

//! marginally useful message indicating why:

`

``

`111`

`+

//! You might instead, if you don't want to handle the error, simply

`

``

`112`

`` +

//! assert success with [`expect`]. This will panic if the

``

``

`113`

`+

//! write fails, providing a marginally useful message indicating why:

`

`111`

`114`

`//!

`

`112`

`115`

```` //! ```no_run

113

116

`//! use std::fs::File;

142

145

`//!

143

146

`` //! # The question mark operator, ?

144

147

`//!

145

`` -

//! When writing code that calls many functions that return the [Result] type,

146

`` -

//! the error handling can be tedious. The question mark operator, [?], hides

147

//! some of the boilerplate of propagating errors up the call stack.

148

//! When writing code that calls many functions that return the

149

`` +

//! [Result] type, the error handling can be tedious. The question mark

150

`` +

//! operator, [?], hides some of the boilerplate of propagating errors

151

//! up the call stack.

148

152

`//!

149

153

`//! It replaces this:

150

154

`//!

205

209

`//!

206

210

`//! It's much nicer!

207

211

`//!

208

`` -

//! Ending the expression with [?] will result in the [Ok]'s unwrapped

209

`` -

//! value, unless the result is [Err], in which case [Err] is returned early

210

//! from the enclosing function.

212

`` +

//! Ending the expression with [?] will result in the [Ok]'s unwrapped value, unless the result

213

`` +

//! is [Err], in which case [Err] is returned early from the enclosing function.

211

214

`//!

212

`` -

//! [?] can be used in functions that return [Result] because of the early

213

`` -

//! return of [Err] that it provides.

215

`` +

//! [?] can be used in functions that return [Result] because of the

216

`` +

//! early return of [Err] that it provides.

214

217

`//!

215

218

`` //! [expect]: Result::expect

216

219

`` //! [Write]: ../../std/io/trait.Write.html "io::Write"

217

`` -

//! [write_all]: ../../std/io/trait.Write.html#method.write_all

218

//! "io::Write::write_all"

220

`` +

//! [write_all]: ../../std/io/trait.Write.html#method.write_all "io::Write::write_all"

219

221

`` //! [io::Result]: ../../std/io/type.Result.html "io::Result"

220

222

`` //! [?]: crate::ops::Try

221

223

`` //! [Ok(T)]: Ok

250

252

`//!

251

253

`//! ## Querying the variant

252

254

`//!

253

`` -

//! The [is_ok] and [is_err] methods return [true] if the [Result] is

254

`` -

//! [Ok] or [Err], respectively.

255

`` +

//! In addition to working with pattern matching, [Result] provides a

256

//! wide variety of different methods.

255

257

`//!

256

258

`` //! [is_err]: Result::is_err

257

259

`` //! [is_ok]: Result::is_ok

`@@ -261,8 +263,8 @@

261

263

`` //! * [as_ref] converts from &Result<T, E> to Result<&T, &E>

262

264

`` //! * [as_mut] converts from &mut Result<T, E> to Result<&mut T, &mut E>

263

265

`` //! * [as_deref] converts from &Result<T, E> to Result<&T::Target, &E>

264

`` -

//! * [as_deref_mut] converts from &mut Result<T, E> to `Result<&mut

265

`` -

//! T::Target, &mut E>`

266

`` +

//! * [as_deref_mut] converts from &mut Result<T, E> to

267

`` +

//! Result<&mut T::Target, &mut E>

266

268

`//!

267

269

`` //! [as_deref]: Result::as_deref

268

270

`` //! [as_deref_mut]: Result::as_deref_mut

`@@ -271,18 +273,19 @@

271

273

`//!

272

274

`//! ## Extracting contained values

273

275

`//!

274

`` -

//! These methods extract the contained value in a [Result<T, E>] when it is

275

`` -

//! the [Ok] variant. If the [Result] is [Err]:

276

`` +

//! These methods extract the contained value in a [Result<T, E>] when it

277

`` +

//! is the [Ok] variant. If the [Result] is [Err]:

276

278

`//!

277

279

`` //! * [expect] panics with a provided custom message

278

280

`` //! * [unwrap] panics with a generic message

279

281

`` //! * [unwrap_or] returns the provided default value

280

`` -

//! * [unwrap_or_default] returns the default value of the type T (which

281

`` -

//! must implement the [Default] trait)

282

`` -

//! * [unwrap_or_else] returns the result of evaluating the provided function

282

`` +

//! * [unwrap_or_default] returns the default value of the type T

283

`` +

//! (which must implement the [Default] trait)

284

`` +

//! * [unwrap_or_else] returns the result of evaluating the provided

285

//! function

283

286

`//!

284

`` -

//! The panicking methods [expect] and [unwrap] require E to implement the

285

`` -

//! [Debug] trait.

287

`` +

//! The panicking methods [expect] and [unwrap] require E to

288

`` +

//! implement the [Debug] trait.

286

289

`//!

287

290

`` //! [Debug]: crate::fmt::Debug

288

291

`` //! [expect]: Result::expect

`@@ -291,9 +294,9 @@

291

294

`` //! [unwrap_or_default]: Result::unwrap_or_default

292

295

`` //! [unwrap_or_else]: Result::unwrap_or_else

293

296

`//!

294

`` -

//! These methods extract the contained value in a [Result<T, E>] when it is

295

`` -

//! the [Err] variant. They require T to implement the [Debug] trait. If

296

`` -

//! the [Result] is [Ok]:

297

`` +

//! These methods extract the contained value in a [Result<T, E>] when it

298

`` +

//! is the [Err] variant. They require T to implement the [Debug]

299

`` +

//! trait. If the [Result] is [Ok]:

297

300

`//!

298

301

`` //! * [expect_err] panics with a provided custom message

299

302

`` //! * [unwrap_err] panics with a generic message

`@@ -308,10 +311,10 @@

308

311

`//!

309

312

`` //! * [err][Result::err] transforms [Result<T, E>] into [Option<E>],

310

313

`` //! mapping [Err(e)] to [Some(e)] and [Ok(v)] to [None]

311

`` -

//! * [ok][Result::ok] transforms [Result<T, E>] into [Option<T>], mapping

312

`` -

//! [Ok(v)] to [Some(v)] and [Err(e)] to [None]

313

`` -

//! * [transpose] transposes a [Result] of an [Option] into an [Option]

314

`` -

//! of a [Result]

314

`` +

//! * [ok][Result::ok] transforms [Result<T, E>] into [Option<T>],

315

`` +

//! mapping [Ok(v)] to [Some(v)] and [Err(e)] to [None]

316

`` +

//! * [transpose] transposes a [Result] of an [Option] into an

317

`` +

//! [Option] of a [Result]

315

318

`//!

316

319

`` // Do NOT add link reference definitions for err or ok, because they

317

320

`` // will generate numerous incorrect URLs for Err and Ok elsewhere, due