Skip to content

Commit d146804

Browse files
pietroalbinipietroalbini
authored
Rollup merge of rust-lang#53523 - phungleson:fix-impl-from-for-std-error, r=GuillaumeGomez
Add doc for impl From for Std Error As part of issue rust-lang#51430 (cc @skade). I am not sure if it is going to a correct direction so put up here so that people can comment.
2 parents 6ddab3e + 30f2e96 commit d146804

File tree

1 file changed

+141
-0
lines changed

1 file changed

+141
-0
lines changed

‎src/libstd/error.rs

+141
Original file line numberDiff line numberDiff line change
@@ -217,20 +217,97 @@ pub trait Error: Debug + Display {
217217

218218
#[stable(feature = "rust1", since = "1.0.0")]
219219
impl<'a, E: Error + 'a> From<E> for Box<dyn Error + 'a> {
220+
/// Converts a type of [`Error`] into a box of dyn [`Error`].
221+
///
222+
/// # Examples
223+
///
224+
/// ```
225+
/// use std::error::Error;
226+
/// use std::fmt;
227+
/// use std::mem;
228+
///
229+
/// #[derive(Debug)]
230+
/// struct AnError;
231+
///
232+
/// impl fmt::Display for AnError {
233+
/// fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
234+
/// write!(f , "An error")
235+
/// }
236+
/// }
237+
///
238+
/// impl Error for AnError {
239+
/// fn description(&self) -> &str {
240+
/// "Description of an error"
241+
/// }
242+
/// }
243+
///
244+
/// let an_error = AnError;
245+
/// assert!(0 == mem::size_of_val(&an_error));
246+
/// let a_boxed_error = Box::<Error>::from(an_error);
247+
/// assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
248+
/// ```
220249
fn from(err: E) -> Box<dyn Error + 'a> {
221250
Box::new(err)
222251
}
223252
}
224253

225254
#[stable(feature = "rust1", since = "1.0.0")]
226255
impl<'a, E: Error + Send + Sync + 'a> From<E> for Box<dyn Error + Send + Sync + 'a> {
256+
/// Converts a type of [`Error`] + [`Send`] + [`Sync`] into a box of dyn [`Error`] +
257+
/// [`Send`] + [`Sync`].
258+
///
259+
/// # Examples
260+
///
261+
/// ```
262+
/// use std::error::Error;
263+
/// use std::fmt;
264+
/// use std::mem;
265+
///
266+
/// #[derive(Debug)]
267+
/// struct AnError;
268+
///
269+
/// impl fmt::Display for AnError {
270+
/// fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
271+
/// write!(f , "An error")
272+
/// }
273+
/// }
274+
///
275+
/// impl Error for AnError {
276+
/// fn description(&self) -> &str {
277+
/// "Description of an error"
278+
/// }
279+
/// }
280+
///
281+
/// unsafe impl Send for AnError {}
282+
///
283+
/// unsafe impl Sync for AnError {}
284+
///
285+
/// let an_error = AnError;
286+
/// assert!(0 == mem::size_of_val(&an_error));
287+
/// let a_boxed_error = Box::<Error + Send + Sync>::from(an_error);
288+
/// assert!(
289+
/// mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
290+
/// ```
227291
fn from(err: E) -> Box<dyn Error + Send + Sync + 'a> {
228292
Box::new(err)
229293
}
230294
}
231295

232296
#[stable(feature = "rust1", since = "1.0.0")]
233297
impl From<String> for Box<dyn Error + Send + Sync> {
298+
/// Converts a [`String`] into a box of dyn [`Error`] + [`Send`] + [`Sync`].
299+
///
300+
/// # Examples
301+
///
302+
/// ```
303+
/// use std::error::Error;
304+
/// use std::mem;
305+
///
306+
/// let a_string_error = "a string error".to_string();
307+
/// let a_boxed_error = Box::<Error + Send + Sync>::from(a_string_error);
308+
/// assert!(
309+
/// mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
310+
/// ```
234311
fn from(err: String) -> Box<dyn Error + Send + Sync> {
235312
#[derive(Debug)]
236313
struct StringError(String);
@@ -251,6 +328,18 @@ impl From<String> for Box<dyn Error + Send + Sync> {
251328

252329
#[stable(feature = "string_box_error", since = "1.6.0")]
253330
impl From<String> for Box<dyn Error> {
331+
/// Converts a [`String`] into a box of dyn [`Error`].
332+
///
333+
/// # Examples
334+
///
335+
/// ```
336+
/// use std::error::Error;
337+
/// use std::mem;
338+
///
339+
/// let a_string_error = "a string error".to_string();
340+
/// let a_boxed_error = Box::<Error>::from(a_string_error);
341+
/// assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
342+
/// ```
254343
fn from(str_err: String) -> Box<dyn Error> {
255344
let err1: Box<dyn Error + Send + Sync> = From::from(str_err);
256345
let err2: Box<dyn Error> = err1;
@@ -260,27 +349,79 @@ impl From<String> for Box<dyn Error> {
260349

261350
#[stable(feature = "rust1", since = "1.0.0")]
262351
impl<'a, 'b> From<&'b str> for Box<dyn Error + Send + Sync + 'a> {
352+
/// Converts a [`str`] into a box of dyn [`Error`] + [`Send`] + [`Sync`].
353+
///
354+
/// # Examples
355+
///
356+
/// ```
357+
/// use std::error::Error;
358+
/// use std::mem;
359+
///
360+
/// let a_str_error = "a str error";
361+
/// let a_boxed_error = Box::<Error + Send + Sync>::from(a_str_error);
362+
/// assert!(
363+
/// mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
364+
/// ```
263365
fn from(err: &'b str) -> Box<dyn Error + Send + Sync + 'a> {
264366
From::from(String::from(err))
265367
}
266368
}
267369

268370
#[stable(feature = "string_box_error", since = "1.6.0")]
269371
impl<'a> From<&'a str> for Box<dyn Error> {
372+
/// Converts a [`str`] into a box of dyn [`Error`].
373+
///
374+
/// # Examples
375+
///
376+
/// ```
377+
/// use std::error::Error;
378+
/// use std::mem;
379+
///
380+
/// let a_str_error = "a str error";
381+
/// let a_boxed_error = Box::<Error>::from(a_str_error);
382+
/// assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
383+
/// ```
270384
fn from(err: &'a str) -> Box<dyn Error> {
271385
From::from(String::from(err))
272386
}
273387
}
274388

275389
#[stable(feature = "cow_box_error", since = "1.22.0")]
276390
impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + Send + Sync + 'a> {
391+
/// Converts a [`Cow`] into a box of dyn [`Error`] + [`Send`] + [`Sync`].
392+
///
393+
/// # Examples
394+
///
395+
/// ```
396+
/// use std::error::Error;
397+
/// use std::mem;
398+
/// use std::borrow::Cow;
399+
///
400+
/// let a_cow_str_error = Cow::from("a str error");
401+
/// let a_boxed_error = Box::<Error + Send + Sync>::from(a_cow_str_error);
402+
/// assert!(
403+
/// mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
404+
/// ```
277405
fn from(err: Cow<'b, str>) -> Box<dyn Error + Send + Sync + 'a> {
278406
From::from(String::from(err))
279407
}
280408
}
281409

282410
#[stable(feature = "cow_box_error", since = "1.22.0")]
283411
impl<'a> From<Cow<'a, str>> for Box<dyn Error> {
412+
/// Converts a [`Cow`] into a box of dyn [`Error`].
413+
///
414+
/// # Examples
415+
///
416+
/// ```
417+
/// use std::error::Error;
418+
/// use std::mem;
419+
/// use std::borrow::Cow;
420+
///
421+
/// let a_cow_str_error = Cow::from("a str error");
422+
/// let a_boxed_error = Box::<Error>::from(a_cow_str_error);
423+
/// assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
424+
/// ```
284425
fn from(err: Cow<'a, str>) -> Box<dyn Error> {
285426
From::from(String::from(err))
286427
}

0 commit comments

Comments
 (0)