rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Rollup merge of #89869 - kpreid:from-doc, r=yaahc

Browse Source 
Add documentation to more `From::from` implementations.

For users looking at documentation through IDE popups, this gives them relevant information rather than the generic trait documentation wording “Performs the conversion”. For users reading the documentation for a specific type for any reason, this informs them when the conversion may allocate or copy significant memory versus when it is always a move or cheap copy.

Notes on specific cases:
* The new documentation for `From<T> for T` explains that it is not a conversion at all.
* Also documented `impl<T, U> Into<U> for T where U: From<T>`, the other central blanket implementation of conversion.
* The new documentation for construction of maps and sets from arrays of keys mentions the handling of duplicates. Future work could be to do this for *all* code paths that convert an iterable to a map or set.
* I did not add documentation to conversions of a specific error type to a more general error type.
* I did not add documentation to unstable code.

This change was prepared by searching for the text "From<... for" and so may have missed some cases that for whatever reason did not match. I also looked for `Into` impls but did not find any worth documenting by the above criteria.
This commit is contained in:
Matthias Krüger
2022-02-17 06:29:57 +01:00
committed by GitHub
parent 930fc4f59d 6fd5cf51c1
commit 1cc0ae4cbb
16 changed files with 63 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
library/std/src/ffi/c_str.rs
View File

@@ -871,6 +871,8 @@ impl Borrow<CStr> for CString {
#[stable(feature = "cstring_from_cow_cstr", since = "1.28.0")]
impl<'a> From<Cow<'a, CStr>> for CString {
/// Converts a `Cow<'a, CStr>` into a `CString`, by copying the contents if they are
/// borrowed.
#[inline]
fn from(s: Cow<'a, CStr>) -> Self {
s.into_owned()
@@ -879,6 +881,8 @@ impl<'a> From<Cow<'a, CStr>> for CString {
#[stable(feature = "box_from_c_str", since = "1.17.0")]
impl From<&CStr> for Box<CStr> {
/// Converts a `&CStr` into a `Box<CStr>`,
/// by copying the contents into a newly allocated [`Box`].
fn from(s: &CStr) -> Box<CStr> {
let boxed: Box<[u8]> = Box::from(s.to_bytes_with_nul());
unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) }
@@ -887,6 +891,8 @@ impl From<&CStr> for Box<CStr> {
#[stable(feature = "box_from_cow", since = "1.45.0")]
impl From<Cow<'_, CStr>> for Box<CStr> {
/// Converts a `Cow<'a, CStr>` into a `Box<CStr>`,
/// by copying the contents if they are borrowed.
#[inline]
fn from(cow: Cow<'_, CStr>) -> Box<CStr> {
match cow {
@@ -984,6 +990,8 @@ impl From<CString> for Arc<CStr> {
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<&CStr> for Arc<CStr> {
/// Converts a `&CStr` into a `Arc<CStr>`,
/// by copying the contents into a newly allocated [`Arc`].
#[inline]
fn from(s: &CStr) -> Arc<CStr> {
let arc: Arc<[u8]> = Arc::from(s.to_bytes_with_nul());
@@ -1004,6 +1012,8 @@ impl From<CString> for Rc<CStr> {
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<&CStr> for Rc<CStr> {
/// Converts a `&CStr` into a `Rc<CStr>`,
/// by copying the contents into a newly allocated [`Rc`].
#[inline]
fn from(s: &CStr) -> Rc<CStr> {
let rc: Rc<[u8]> = Rc::from(s.to_bytes_with_nul());
@@ -1530,6 +1540,7 @@ impl ToOwned for CStr {
#[stable(feature = "cstring_asref", since = "1.7.0")]
impl From<&CStr> for CString {
/// Copies the contents of the `&CStr` into a newly allocated `CString`.
fn from(s: &CStr) -> CString {
s.to_owned()
}

12
library/std/src/ffi/os_str.rs
View File

@@ -452,6 +452,8 @@ impl From<String> for OsString {
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + AsRef<OsStr>> From<&T> for OsString {
/// Copies any value implementing <code>[AsRef]&lt;[OsStr]&gt;</code>
/// into a newly allocated [`OsString`].
fn from(s: &T) -> OsString {
s.as_ref().to_os_string()
}
@@ -942,6 +944,7 @@ impl OsStr {
#[stable(feature = "box_from_os_str", since = "1.17.0")]
impl From<&OsStr> for Box<OsStr> {
/// Copies the string into a newly allocated <code>[Box]&lt;[OsStr]&gt;</code>.
#[inline]
fn from(s: &OsStr) -> Box<OsStr> {
let rw = Box::into_raw(s.inner.into_box()) as *mut OsStr;
@@ -951,6 +954,8 @@ impl From<&OsStr> for Box<OsStr> {
#[stable(feature = "box_from_cow", since = "1.45.0")]
impl From<Cow<'_, OsStr>> for Box<OsStr> {
/// Converts a `Cow<'a, OsStr>` into a <code>[Box]&lt;[OsStr]&gt;</code>,
/// by copying the contents if they are borrowed.
#[inline]
fn from(cow: Cow<'_, OsStr>) -> Box<OsStr> {
match cow {
@@ -1000,6 +1005,7 @@ impl From<OsString> for Arc<OsStr> {
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<&OsStr> for Arc<OsStr> {
/// Copies the string into a newly allocated <code>[Arc]&lt;[OsStr]&gt;</code>.
#[inline]
fn from(s: &OsStr) -> Arc<OsStr> {
let arc = s.inner.into_arc();
@@ -1020,6 +1026,7 @@ impl From<OsString> for Rc<OsStr> {
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<&OsStr> for Rc<OsStr> {
/// Copies the string into a newly allocated <code>[Rc]&lt;[OsStr]&gt;</code>.
#[inline]
fn from(s: &OsStr) -> Rc<OsStr> {
let rc = s.inner.into_rc();
@@ -1029,6 +1036,7 @@ impl From<&OsStr> for Rc<OsStr> {
#[stable(feature = "cow_from_osstr", since = "1.28.0")]
impl<'a> From<OsString> for Cow<'a, OsStr> {
/// Moves the string into a [`Cow::Owned`].
#[inline]
fn from(s: OsString) -> Cow<'a, OsStr> {
Cow::Owned(s)
@@ -1037,6 +1045,7 @@ impl<'a> From<OsString> for Cow<'a, OsStr> {
#[stable(feature = "cow_from_osstr", since = "1.28.0")]
impl<'a> From<&'a OsStr> for Cow<'a, OsStr> {
/// Converts the string reference into a [`Cow::Borrowed`].
#[inline]
fn from(s: &'a OsStr) -> Cow<'a, OsStr> {
Cow::Borrowed(s)
@@ -1045,6 +1054,7 @@ impl<'a> From<&'a OsStr> for Cow<'a, OsStr> {
#[stable(feature = "cow_from_osstr", since = "1.28.0")]
impl<'a> From<&'a OsString> for Cow<'a, OsStr> {
/// Converts the string reference into a [`Cow::Borrowed`].
#[inline]
fn from(s: &'a OsString) -> Cow<'a, OsStr> {
Cow::Borrowed(s.as_os_str())
@@ -1053,6 +1063,8 @@ impl<'a> From<&'a OsString> for Cow<'a, OsStr> {
#[stable(feature = "osstring_from_cow_osstr", since = "1.28.0")]
impl<'a> From<Cow<'a, OsStr>> for OsString {
/// Converts a `Cow<'a, OsStr>` into an [`OsString`],
/// by copying the contents if they are borrowed.
#[inline]
fn from(s: Cow<'a, OsStr>) -> Self {
s.into_owned()

6
library/std/src/path.rs
View File

@@ -1600,7 +1600,7 @@ impl From<Cow<'_, Path>> for Box<Path> {
#[stable(feature = "path_buf_from_box", since = "1.18.0")]
impl From<Box<Path>> for PathBuf {
/// Converts a `Box<Path>` into a `PathBuf`
/// Converts a <code>[Box]&lt;[Path]&gt;</code> into a [`PathBuf`].
///
/// This conversion does not allocate or copy memory.
#[inline]
@@ -1611,7 +1611,7 @@ impl From<Box<Path>> for PathBuf {
#[stable(feature = "box_from_path_buf", since = "1.20.0")]
impl From<PathBuf> for Box<Path> {
/// Converts a `PathBuf` into a `Box<Path>`
/// Converts a [`PathBuf`] into a <code>[Box]&lt;[Path]&gt;</code>.
///
/// This conversion currently should not allocate memory,
/// but this behavior is not guaranteed on all platforms or in all future versions.
@@ -1631,7 +1631,7 @@ impl Clone for Box<Path> {
#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized + AsRef<OsStr>> From<&T> for PathBuf {
/// Converts a borrowed `OsStr` to a `PathBuf`.
/// Converts a borrowed [`OsStr`] to a [`PathBuf`].
///
/// Allocates a [`PathBuf`] and copies the data into it.
#[inline]

8
library/std/src/process.rs
View File

@@ -1277,7 +1277,7 @@ impl fmt::Debug for Stdio {
#[stable(feature = "stdio_from", since = "1.20.0")]
impl From<ChildStdin> for Stdio {
/// Converts a `ChildStdin` into a `Stdio`
/// Converts a [`ChildStdin`] into a [`Stdio`].
///
/// # Examples
///
@@ -1306,7 +1306,7 @@ impl From<ChildStdin> for Stdio {
#[stable(feature = "stdio_from", since = "1.20.0")]
impl From<ChildStdout> for Stdio {
/// Converts a `ChildStdout` into a `Stdio`
/// Converts a [`ChildStdout`] into a [`Stdio`].
///
/// # Examples
///
@@ -1335,7 +1335,7 @@ impl From<ChildStdout> for Stdio {
#[stable(feature = "stdio_from", since = "1.20.0")]
impl From<ChildStderr> for Stdio {
/// Converts a `ChildStderr` into a `Stdio`
/// Converts a [`ChildStderr`] into a [`Stdio`].
///
/// # Examples
///
@@ -1366,7 +1366,7 @@ impl From<ChildStderr> for Stdio {
#[stable(feature = "stdio_from", since = "1.20.0")]
impl From<fs::File> for Stdio {
/// Converts a `File` into a `Stdio`
/// Converts a [`File`](fs::File) into a [`Stdio`].
///
/// # Examples
///