From 2adc8c0e5fd34d88a601d9c572bb2f29d23d0357 Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Thu, 13 Aug 2020 23:19:45 +0200 Subject: [PATCH] Move to intra doc links in std::ffi --- library/std/src/ffi/c_str.rs | 193 +++++++++------------------------- library/std/src/ffi/mod.rs | 42 +++----- library/std/src/ffi/os_str.rs | 79 +++----------- 3 files changed, 81 insertions(+), 233 deletions(-) diff --git a/library/std/src/ffi/c_str.rs b/library/std/src/ffi/c_str.rs index da25a0ede72..194573da767 100644 --- a/library/std/src/ffi/c_str.rs +++ b/library/std/src/ffi/c_str.rs @@ -35,23 +35,23 @@ use crate::sys; /// example, you can build a `CString` straight out of a [`String`] or /// a [`&str`], since both implement that trait). /// -/// The [`new`] method will actually check that the provided `&[u8]` +/// The [`CString::new`] method will actually check that the provided `&[u8]` /// does not have 0 bytes in the middle, and return an error if it /// finds one. /// /// # Extracting a raw pointer to the whole C string /// -/// `CString` implements a [`as_ptr`] method through the [`Deref`] +/// `CString` implements a [`as_ptr`][`CStr::as_ptr`] method through the [`Deref`] /// trait. This method will give you a `*const c_char` which you can /// feed directly to extern functions that expect a nul-terminated -/// string, like C's `strdup()`. Notice that [`as_ptr`] returns a +/// string, like C's `strdup()`. Notice that [`as_ptr`][`CStr::as_ptr`] returns a /// read-only pointer; if the C code writes to it, that causes /// undefined behavior. /// /// # Extracting a slice of the whole C string /// /// Alternatively, you can obtain a `&[`[`u8`]`]` slice from a -/// `CString` with the [`as_bytes`] method. Slices produced in this +/// `CString` with the [`CString::as_bytes`] method. Slices produced in this /// way do *not* contain the trailing nul terminator. This is useful /// when you will be calling an extern function that takes a `*const /// u8` argument which is not necessarily nul-terminated, plus another @@ -60,7 +60,7 @@ use crate::sys; /// [`len`][slice.len] method. /// /// If you need a `&[`[`u8`]`]` slice *with* the nul terminator, you -/// can use [`as_bytes_with_nul`] instead. +/// can use [`CString::as_bytes_with_nul`] instead. /// /// Once you have the kind of slice you need (with or without a nul /// terminator), you can call the slice's own @@ -68,20 +68,11 @@ use crate::sys; /// extern functions. See the documentation for that function for a /// discussion on ensuring the lifetime of the raw pointer. /// -/// [`Into`]: ../convert/trait.Into.html -/// [`Vec`]: ../vec/struct.Vec.html -/// [`String`]: ../string/struct.String.html -/// [`&str`]: ../primitive.str.html -/// [`u8`]: ../primitive.u8.html -/// [`new`]: #method.new -/// [`as_bytes`]: #method.as_bytes -/// [`as_bytes_with_nul`]: #method.as_bytes_with_nul -/// [`as_ptr`]: #method.as_ptr +/// [`&str`]: str /// [slice.as_ptr]: ../primitive.slice.html#method.as_ptr /// [slice.len]: ../primitive.slice.html#method.len -/// [`Deref`]: ../ops/trait.Deref.html -/// [`CStr`]: struct.CStr.html -/// [`&CStr`]: struct.CStr.html +/// [`Deref`]: ops::Deref +/// [`&CStr`]: CStr /// /// # Examples /// @@ -113,7 +104,6 @@ use crate::sys; /// documentation of `CString` before use, as improper ownership management /// of `CString` instances can lead to invalid memory accesses, memory leaks, /// and other memory errors. - #[derive(PartialEq, PartialOrd, Eq, Ord, Hash, Clone)] #[stable(feature = "rust1", since = "1.0.0")] pub struct CString { @@ -137,8 +127,8 @@ pub struct CString { /// /// Note that this structure is **not** `repr(C)` and is not recommended to be /// placed in the signatures of FFI functions. Instead, safe wrappers of FFI -/// functions may leverage the unsafe [`from_ptr`] constructor to provide a safe -/// interface to other consumers. +/// functions may leverage the unsafe [`CStr::from_ptr`] constructor to provide +/// a safe interface to other consumers. /// /// # Examples /// @@ -189,11 +179,7 @@ pub struct CString { /// println!("string: {}", my_string_safe()); /// ``` /// -/// [`u8`]: ../primitive.u8.html -/// [`&str`]: ../primitive.str.html -/// [`String`]: ../string/struct.String.html -/// [`CString`]: struct.CString.html -/// [`from_ptr`]: #method.from_ptr +/// [`&str`]: str #[derive(Hash)] #[stable(feature = "rust1", since = "1.0.0")] // FIXME: @@ -218,9 +204,6 @@ pub struct CStr { /// This error is created by the [`new`][`CString::new`] method on /// [`CString`]. See its documentation for more. /// -/// [`CString`]: struct.CString.html -/// [`CString::new`]: struct.CString.html#method.new -/// /// # Examples /// /// ``` @@ -237,12 +220,9 @@ pub struct NulError(usize, Vec); /// The slice used to create a [`CStr`] must have one and only one nul byte, /// positioned at the end. /// -/// This error is created by the [`from_bytes_with_nul`] method on [`CStr`]. +/// This error is created by the [`CStr::from_bytes_with_nul`] method. /// See its documentation for more. /// -/// [`CStr`]: struct.CStr.html -/// [`from_bytes_with_nul`]: struct.CStr.html#method.from_bytes_with_nul -/// /// # Examples /// /// ``` @@ -261,12 +241,9 @@ pub struct FromBytesWithNulError { /// The vector used to create a [`CString`] must have one and only one nul byte, /// positioned at the end. /// -/// This error is created by the [`from_vec_with_nul`] method on [`CString`]. +/// This error is created by the [`CString::from_vec_with_nul`] method. /// See its documentation for more. /// -/// [`CString`]: struct.CString.html -/// [`from_vec_with_nul`]: struct.CString.html#method.from_vec_with_nul -/// /// # Examples /// /// ``` @@ -316,8 +293,6 @@ impl FromVecWithNulError { /// /// assert_eq!(&bytes[..], value.unwrap_err().as_bytes()); /// ``` - /// - /// [`CString`]: struct.CString.html pub fn as_bytes(&self) -> &[u8] { &self.bytes[..] } @@ -343,8 +318,6 @@ impl FromVecWithNulError { /// /// assert_eq!(bytes, value.unwrap_err().into_bytes()); /// ``` - /// - /// [`CString`]: struct.CString.html pub fn into_bytes(self) -> Vec { self.bytes } @@ -352,17 +325,12 @@ impl FromVecWithNulError { /// An error indicating invalid UTF-8 when converting a [`CString`] into a [`String`]. /// -/// `CString` is just a wrapper over a buffer of bytes with a nul -/// terminator; [`into_string`][`CString::into_string`] performs UTF-8 -/// validation on those bytes and may return this error. +/// `CString` is just a wrapper over a buffer of bytes with a nul terminator; +/// [`CString::into_string`] performs UTF-8 validation on those bytes and may +/// return this error. /// -/// This `struct` is created by the -/// [`into_string`][`CString::into_string`] method on [`CString`]. See +/// This `struct` is created by the [`CString::into_string`] method. See /// its documentation for more. -/// -/// [`String`]: ../string/struct.String.html -/// [`CString`]: struct.CString.html -/// [`CString::into_string`]: struct.CString.html#method.into_string #[derive(Clone, PartialEq, Eq, Debug)] #[stable(feature = "cstring_into", since = "1.7.0")] pub struct IntoStringError { @@ -398,8 +366,6 @@ impl CString { /// This function will return an error if the supplied bytes contain an /// internal 0 byte. The [`NulError`] returned will contain the bytes as well as /// the position of the nul byte. - /// - /// [`NulError`]: struct.NulError.html #[stable(feature = "rust1", since = "1.0.0")] pub fn new>>(t: T) -> Result { trait SpecIntoVec { @@ -439,11 +405,9 @@ impl CString { /// Creates a C-compatible string by consuming a byte vector, /// without checking for interior 0 bytes. /// - /// This method is equivalent to [`new`] except that no runtime assertion - /// is made that `v` contains no 0 bytes, and it requires an actual - /// byte vector, not anything that can be converted to one with Into. - /// - /// [`new`]: #method.new + /// This method is equivalent to [`CString::new`] except that no runtime + /// assertion is made that `v` contains no 0 bytes, and it requires an + /// actual byte vector, not anything that can be converted to one with Into. /// /// # Examples /// @@ -462,21 +426,22 @@ impl CString { CString { inner: v.into_boxed_slice() } } - /// Retakes ownership of a `CString` that was transferred to C via [`into_raw`]. + /// Retakes ownership of a `CString` that was transferred to C via + /// [`CString::into_raw`]. /// /// Additionally, the length of the string will be recalculated from the pointer. /// /// # Safety /// /// This should only ever be called with a pointer that was earlier - /// obtained by calling [`into_raw`] on a `CString`. Other usage (e.g., trying to take + /// obtained by calling [`CString::into_raw`]. Other usage (e.g., trying to take /// ownership of a string that was allocated by foreign code) is likely to lead /// to undefined behavior or allocator corruption. /// /// It should be noted that the length isn't just "recomputed," but that /// the recomputed length must match the original length from the - /// [`into_raw`] call. This means the [`into_raw`]/`from_raw` methods - /// should not be used when passing the string to C functions that can + /// [`CString::into_raw`] call. This means the [`CString::into_raw`]/`from_raw` + /// methods should not be used when passing the string to C functions that can /// modify the string's length. /// /// > **Note:** If you need to borrow a string that was allocated by @@ -485,9 +450,6 @@ impl CString { /// > make your own provisions for freeing it appropriately, likely /// > with the foreign code's API to do that. /// - /// [`into_raw`]: #method.into_raw - /// [`CStr`]: struct.CStr.html - /// /// # Examples /// /// Creates a `CString`, pass ownership to an `extern` function (via raw pointer), then retake @@ -518,18 +480,16 @@ impl CString { /// Consumes the `CString` and transfers ownership of the string to a C caller. /// /// The pointer which this function returns must be returned to Rust and reconstituted using - /// [`from_raw`] to be properly deallocated. Specifically, one + /// [`CString::from_raw`] to be properly deallocated. Specifically, one /// should *not* use the standard C `free()` function to deallocate /// this string. /// - /// Failure to call [`from_raw`] will lead to a memory leak. + /// Failure to call [`CString::from_raw`] will lead to a memory leak. /// /// The C side must **not** modify the length of the string (by writing a /// `NULL` somewhere inside the string or removing the final one) before - /// it makes it back into Rust using [`from_raw`]. See the safety section - /// in [`from_raw`]. - /// - /// [`from_raw`]: #method.from_raw + /// it makes it back into Rust using [`CString::from_raw`]. See the safety section + /// in [`CString::from_raw`]. /// /// # Examples /// @@ -560,8 +520,6 @@ impl CString { /// /// On failure, ownership of the original `CString` is returned. /// - /// [`String`]: ../string/struct.String.html - /// /// # Examples /// /// ``` @@ -608,10 +566,8 @@ impl CString { vec } - /// Equivalent to the [`into_bytes`] function except that the returned vector - /// includes the trailing nul terminator. - /// - /// [`into_bytes`]: #method.into_bytes + /// Equivalent to the [`CString::into_bytes`] function except that the + /// returned vector includes the trailing nul terminator. /// /// # Examples /// @@ -632,9 +588,7 @@ impl CString { /// The returned slice does **not** contain the trailing nul /// terminator, and it is guaranteed to not have any interior nul /// bytes. If you need the nul terminator, use - /// [`as_bytes_with_nul`] instead. - /// - /// [`as_bytes_with_nul`]: #method.as_bytes_with_nul + /// [`CString::as_bytes_with_nul`] instead. /// /// # Examples /// @@ -651,10 +605,8 @@ impl CString { &self.inner[..self.inner.len() - 1] } - /// Equivalent to the [`as_bytes`] function except that the returned slice - /// includes the trailing nul terminator. - /// - /// [`as_bytes`]: #method.as_bytes + /// Equivalent to the [`CString::as_bytes`] function except that the + /// returned slice includes the trailing nul terminator. /// /// # Examples /// @@ -673,8 +625,6 @@ impl CString { /// Extracts a [`CStr`] slice containing the entire string. /// - /// [`CStr`]: struct.CStr.html - /// /// # Examples /// /// ``` @@ -693,8 +643,6 @@ impl CString { /// Converts this `CString` into a boxed [`CStr`]. /// - /// [`CStr`]: struct.CStr.html - /// /// # Examples /// /// ``` @@ -711,8 +659,6 @@ impl CString { } /// Bypass "move out of struct which implements [`Drop`] trait" restriction. - /// - /// [`Drop`]: ../ops/trait.Drop.html fn into_inner(self) -> Box<[u8]> { // Rationale: `mem::forget(self)` invalidates the previous call to `ptr::read(&self.inner)` // so we use `ManuallyDrop` to ensure `self` is not dropped. @@ -722,12 +668,12 @@ impl CString { unsafe { ptr::read(&this.inner) } } - /// Converts a `Vec` of `u8` to a `CString` without checking the invariants - /// on the given `Vec`. + /// Converts a [`Vec`]`` to a [`CString`] without checking the + /// invariants on the given [`Vec`]. /// /// # Safety /// - /// The given `Vec` **must** have one nul byte as its last element. + /// The given [`Vec`] **must** have one nul byte as its last element. /// This means it cannot be empty nor have any other nul byte anywhere else. /// /// # Example @@ -745,10 +691,10 @@ impl CString { Self { inner: v.into_boxed_slice() } } - /// Attempts to converts a `Vec` of `u8` to a `CString`. + /// Attempts to converts a [`Vec`]`` to a [`CString`]. /// /// Runtime checks are present to ensure there is only one nul byte in the - /// `Vec`, its last element. + /// [`Vec`], its last element. /// /// # Errors /// @@ -757,8 +703,8 @@ impl CString { /// /// # Examples /// - /// A successful conversion will produce the same result as [`new`] when - /// called without the ending nul byte. + /// A successful conversion will produce the same result as [`CString::new`] + /// when called without the ending nul byte. /// /// ``` /// #![feature(cstring_from_vec_with_nul)] @@ -770,7 +716,7 @@ impl CString { /// ); /// ``` /// - /// A incorrectly formatted vector will produce an error. + /// A incorrectly formatted [`Vec`] will produce an error. /// /// ``` /// #![feature(cstring_from_vec_with_nul)] @@ -780,8 +726,6 @@ impl CString { /// // No nul byte /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"abc".to_vec()).unwrap_err(); /// ``` - /// - /// [`new`]: #method.new #[unstable(feature = "cstring_from_vec_with_nul", issue = "73179")] pub fn from_vec_with_nul(v: Vec) -> Result { let nul_pos = memchr::memchr(0, &v); @@ -838,9 +782,6 @@ impl From for Vec { /// Converts a [`CString`] into a [`Vec`]``. /// /// The conversion consumes the [`CString`], and removes the terminating NUL byte. - /// - /// [`Vec`]: ../vec/struct.Vec.html - /// [`CString`]: ../ffi/struct.CString.html #[inline] fn from(s: CString) -> Vec { s.into_bytes() @@ -913,9 +854,6 @@ impl From> for Box { #[stable(feature = "c_string_from_box", since = "1.18.0")] impl From> for CString { /// Converts a [`Box`]`` into a [`CString`] without copying or allocating. - /// - /// [`Box`]: ../boxed/struct.Box.html - /// [`CString`]: ../ffi/struct.CString.html #[inline] fn from(s: Box) -> CString { s.into_c_string() @@ -926,10 +864,6 @@ impl From> for CString { impl From> for CString { /// Converts a [`Vec`]`<`[`NonZeroU8`]`>` into a [`CString`] without /// copying nor checking for inner null bytes. - /// - /// [`CString`]: ../ffi/struct.CString.html - /// [`NonZeroU8`]: ../num/struct.NonZeroU8.html - /// [`Vec`]: ../vec/struct.Vec.html #[inline] fn from(v: Vec) -> CString { unsafe { @@ -959,9 +893,6 @@ impl Clone for Box { #[stable(feature = "box_from_c_string", since = "1.20.0")] impl From for Box { /// Converts a [`CString`] into a [`Box`]`` without copying or allocating. - /// - /// [`CString`]: ../ffi/struct.CString.html - /// [`Box`]: ../boxed/struct.Box.html #[inline] fn from(s: CString) -> Box { s.into_boxed_c_str() @@ -995,9 +926,6 @@ impl<'a> From<&'a CString> for Cow<'a, CStr> { #[stable(feature = "shared_from_slice2", since = "1.24.0")] impl From for Arc { /// Converts a [`CString`] into a [`Arc`]`` without copying or allocating. - /// - /// [`CString`]: ../ffi/struct.CString.html - /// [`Arc`]: ../sync/struct.Arc.html #[inline] fn from(s: CString) -> Arc { let arc: Arc<[u8]> = Arc::from(s.into_inner()); @@ -1017,9 +945,6 @@ impl From<&CStr> for Arc { #[stable(feature = "shared_from_slice2", since = "1.24.0")] impl From for Rc { /// Converts a [`CString`] into a [`Rc`]`` without copying or allocating. - /// - /// [`CString`]: ../ffi/struct.CString.html - /// [`Rc`]: ../rc/struct.Rc.html #[inline] fn from(s: CString) -> Rc { let rc: Rc<[u8]> = Rc::from(s.into_inner()); @@ -1048,8 +973,6 @@ impl NulError { /// Returns the position of the nul byte in the slice that caused /// [`CString::new`] to fail. /// - /// [`CString::new`]: struct.CString.html#method.new - /// /// # Examples /// /// ``` @@ -1101,9 +1024,6 @@ impl fmt::Display for NulError { #[stable(feature = "rust1", since = "1.0.0")] impl From for io::Error { /// Converts a [`NulError`] into a [`io::Error`]. - /// - /// [`NulError`]: ../ffi/struct.NulError.html - /// [`io::Error`]: ../io/struct.Error.html fn from(_: NulError) -> io::Error { io::Error::new(io::ErrorKind::InvalidInput, "data provided contains a nul byte") } @@ -1154,8 +1074,6 @@ impl fmt::Display for FromVecWithNulError { impl IntoStringError { /// Consumes this error, returning original [`CString`] which generated the /// error. - /// - /// [`CString`]: struct.CString.html #[stable(feature = "cstring_into", since = "1.7.0")] pub fn into_cstring(self) -> CString { self.inner @@ -1330,7 +1248,8 @@ impl CStr { /// /// This happens because the pointer returned by `as_ptr` does not carry any /// lifetime information and the [`CString`] is deallocated immediately after - /// the `CString::new("Hello").expect("CString::new failed").as_ptr()` expression is evaluated. + /// the `CString::new("Hello").expect("CString::new failed").as_ptr()` + /// expression is evaluated. /// To fix the problem, bind the `CString` to a local variable: /// /// ```no_run @@ -1345,10 +1264,8 @@ impl CStr { /// } /// ``` /// - /// This way, the lifetime of the `CString` in `hello` encompasses + /// This way, the lifetime of the [`CString`] in `hello` encompasses /// the lifetime of `ptr` and the `unsafe` block. - /// - /// [`CString`]: struct.CString.html #[inline] #[stable(feature = "rust1", since = "1.0.0")] #[rustc_const_stable(feature = "const_str_as_ptr", since = "1.32.0")] @@ -1382,15 +1299,13 @@ impl CStr { /// Converts this C string to a byte slice containing the trailing 0 byte. /// - /// This function is the equivalent of [`to_bytes`] except that it will retain - /// the trailing nul terminator instead of chopping it off. + /// This function is the equivalent of [`CStr::to_bytes`] except that it + /// will retain the trailing nul terminator instead of chopping it off. /// /// > **Note**: This method is currently implemented as a 0-cost cast, but /// > it is planned to alter its definition in the future to perform the /// > length calculation whenever this method is called. /// - /// [`to_bytes`]: #method.to_bytes - /// /// # Examples /// /// ``` @@ -1411,7 +1326,7 @@ impl CStr { /// function will return the corresponding [`&str`] slice. Otherwise, /// it will return an error with details of where UTF-8 validation failed. /// - /// [`&str`]: ../primitive.str.html + /// [`&str`]: str /// /// # Examples /// @@ -1439,12 +1354,9 @@ impl CStr { /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD] and return a /// [`Cow`]`::`[`Owned`]`(`[`String`]`)` with the result. /// - /// [`Cow`]: ../borrow/enum.Cow.html - /// [`Borrowed`]: ../borrow/enum.Cow.html#variant.Borrowed - /// [`Owned`]: ../borrow/enum.Cow.html#variant.Owned - /// [`str`]: ../primitive.str.html - /// [`String`]: ../string/struct.String.html - /// [U+FFFD]: ../char/constant.REPLACEMENT_CHARACTER.html + /// [`Borrowed`]: Cow::Borrowed + /// [`Owned`]: Cow::Owned + /// [U+FFFD]: crate::char::REPLACEMENT_CHARACTER /// /// # Examples /// @@ -1479,9 +1391,6 @@ impl CStr { /// Converts a [`Box`]`` into a [`CString`] without copying or allocating. /// - /// [`Box`]: ../boxed/struct.Box.html - /// [`CString`]: struct.CString.html - /// /// # Examples /// /// ``` diff --git a/library/std/src/ffi/mod.rs b/library/std/src/ffi/mod.rs index f442d7fde1a..0184495eecf 100644 --- a/library/std/src/ffi/mod.rs +++ b/library/std/src/ffi/mod.rs @@ -88,7 +88,7 @@ //! [`env::var_os()`] is used to query environment variables; it //! returns an [`Option`]`<`[`OsString`]`>`. If the environment variable //! exists you will get a [`Some`]`(os_string)`, which you can *then* try to -//! convert to a Rust string. This yields a [`Result<>`], so that +//! convert to a Rust string. This yields a [`Result`], so that //! your code can detect errors in case the environment variable did //! not in fact contain valid Unicode data. //! @@ -124,34 +124,22 @@ //! method is an [`OsString`] which can be round-tripped to a Windows //! string losslessly. //! -//! [`String`]: ../string/struct.String.html -//! [`str`]: ../primitive.str.html -//! [`char`]: ../primitive.char.html -//! [`u8`]: ../primitive.u8.html -//! [`u16`]: ../primitive.u16.html //! [Unicode scalar value]: http://www.unicode.org/glossary/#unicode_scalar_value //! [Unicode code point]: http://www.unicode.org/glossary/#code_point -//! [`CString`]: struct.CString.html -//! [`CStr`]: struct.CStr.html -//! [`OsString`]: struct.OsString.html -//! [`OsStr`]: struct.OsStr.html -//! [`env::set_var()`]: ../env/fn.set_var.html -//! [`env::var_os()`]: ../env/fn.var_os.html -//! [`Result<>`]: ../result/enum.Result.html -//! [unix.OsStringExt]: ../os/unix/ffi/trait.OsStringExt.html -//! [`from_vec`]: ../os/unix/ffi/trait.OsStringExt.html#tymethod.from_vec -//! [`into_vec`]: ../os/unix/ffi/trait.OsStringExt.html#tymethod.into_vec -//! [unix.OsStrExt]: ../os/unix/ffi/trait.OsStrExt.html -//! [`from_bytes`]: ../os/unix/ffi/trait.OsStrExt.html#tymethod.from_bytes -//! [`as_bytes`]: ../os/unix/ffi/trait.OsStrExt.html#tymethod.as_bytes -//! [`OsStrExt`]: ../os/unix/ffi/trait.OsStrExt.html -//! [windows.OsStrExt]: ../os/windows/ffi/trait.OsStrExt.html -//! [`encode_wide`]: ../os/windows/ffi/trait.OsStrExt.html#tymethod.encode_wide -//! [`collect`]: ../iter/trait.Iterator.html#method.collect -//! [windows.OsStringExt]: ../os/windows/ffi/trait.OsStringExt.html -//! [`from_wide`]: ../os/windows/ffi/trait.OsStringExt.html#tymethod.from_wide -//! [`Option`]: ../option/enum.Option.html -//! [`Some`]: ../option/enum.Option.html#variant.Some +//! [`env::set_var()`]: crate::env::set_var +//! [`env::var_os()`]: crate::env::var_os +//! [unix.OsStringExt]: crate::os::unix::ffi::OsStringExt +//! [`from_vec`]: crate::os::unix::ffi::OsStringExt::from_vec +//! [`into_vec`]: crate::os::unix::ffi::OsStringExt::into_vec +//! [unix.OsStrExt]: crate::os::unix::ffi::OsStrExt +//! [`from_bytes`]: crate::os::unix::ffi::OsStrExt::from_bytes +//! [`as_bytes`]: crate::os::unix::ffi::OsStrExt::as_bytes +//! [`OsStrExt`]: crate::os::unix::ffi::OsStrExt +//! [windows.OsStrExt]: crate::os::windows::ffi::OsStrExt +//! [`encode_wide`]: crate::os::windows::ffi::OsStrExt::encode_wide +//! [`collect`]: crate::iter::Iterator::collect +//! [windows.OsStringExt]: crate::os::windows::ffi::OsStringExt +//! [`from_wide`]: crate::os::windows::ffi::OsStringExt::from_wide #![stable(feature = "rust1", since = "1.0.0")] diff --git a/library/std/src/ffi/os_str.rs b/library/std/src/ffi/os_str.rs index d1eaf3c583f..262d39d98ee 100644 --- a/library/std/src/ffi/os_str.rs +++ b/library/std/src/ffi/os_str.rs @@ -47,14 +47,14 @@ use crate::sys_common::{AsInner, FromInner, IntoInner}; /// create an `OsString` from a normal Rust string. /// /// **From slices:** Just like you can start with an empty Rust -/// [`String`] and then [`push_str`][String.push_str] `&str` +/// [`String`] and then [`String::push_str`] `&str` /// sub-string slices into it, you can create an empty `OsString` with -/// the [`new`] method and then push string slices into it with the -/// [`push`] method. +/// the [`OsString::new`] method and then push string slices into it with the +/// [`OsString::push`] method. /// /// # Extracting a borrowed reference to the whole OS string /// -/// You can use the [`as_os_str`] method to get an `&`[`OsStr`] from +/// You can use the [`OsString::as_os_str`] method to get an `&`[`OsStr`] from /// an `OsString`; this is effectively a borrowed reference to the /// whole string. /// @@ -63,18 +63,9 @@ use crate::sys_common::{AsInner, FromInner, IntoInner}; /// See the [module's toplevel documentation about conversions][conversions] for a discussion on /// the traits which `OsString` implements for [conversions] from/to native representations. /// -/// [`OsStr`]: struct.OsStr.html -/// [`&OsStr`]: struct.OsStr.html -/// [`CStr`]: struct.CStr.html -/// [`From`]: ../convert/trait.From.html -/// [`String`]: ../string/struct.String.html -/// [`&str`]: ../primitive.str.html -/// [`u8`]: ../primitive.u8.html -/// [`u16`]: ../primitive.u16.html -/// [String.push_str]: ../string/struct.String.html#method.push_str -/// [`new`]: #method.new -/// [`push`]: #method.push -/// [`as_os_str`]: #method.as_os_str +/// [`&OsStr`]: OsStr +/// [`&str`]: str +/// [`CStr`]: crate::ffi::CStr /// [conversions]: index.html#conversions #[derive(Clone)] #[stable(feature = "rust1", since = "1.0.0")] @@ -93,9 +84,7 @@ pub struct OsString { /// See the [module's toplevel documentation about conversions][conversions] for a discussion on /// the traits which `OsStr` implements for [conversions] from/to native representations. /// -/// [`OsString`]: struct.OsString.html -/// [`&str`]: ../primitive.str.html -/// [`String`]: ../string/struct.String.html +/// [`&str`]: str /// [conversions]: index.html#conversions #[stable(feature = "rust1", since = "1.0.0")] // FIXME: @@ -125,8 +114,6 @@ impl OsString { /// Converts to an [`OsStr`] slice. /// - /// [`OsStr`]: struct.OsStr.html - /// /// # Examples /// /// ``` @@ -145,8 +132,6 @@ impl OsString { /// /// On failure, ownership of the original `OsString` is returned. /// - /// [`String`]: ../../std/string/struct.String.html - /// /// # Examples /// /// ``` @@ -163,7 +148,7 @@ impl OsString { /// Extends the string with the given [`&OsStr`] slice. /// - /// [`&OsStr`]: struct.OsStr.html + /// [`&OsStr`]: OsStr /// /// # Examples /// @@ -333,8 +318,6 @@ impl OsString { /// Converts this `OsString` into a boxed [`OsStr`]. /// - /// [`OsStr`]: struct.OsStr.html - /// /// # Examples /// /// ``` @@ -356,8 +339,6 @@ impl From for OsString { /// Converts a [`String`] into a [`OsString`]. /// /// The conversion copies the data, and includes an allocation on the heap. - /// - /// [`OsString`]: ../../std/ffi/struct.OsString.html fn from(s: String) -> OsString { OsString { inner: Buf::from_string(s) } } @@ -544,7 +525,7 @@ impl OsStr { /// /// This conversion may entail doing a check for UTF-8 validity. /// - /// [`&str`]: ../../std/primitive.str.html + /// [`&str`]: str /// /// # Examples /// @@ -564,9 +545,7 @@ impl OsStr { /// Any non-Unicode sequences are replaced with /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD]. /// - /// [`Cow`]: ../../std/borrow/enum.Cow.html - /// [`str`]: ../../std/primitive.str.html - /// [U+FFFD]: ../../std/char/constant.REPLACEMENT_CHARACTER.html + /// [U+FFFD]: crate::char::REPLACEMENT_CHARACTER /// /// # Examples /// @@ -613,8 +592,6 @@ impl OsStr { /// Copies the slice into an owned [`OsString`]. /// - /// [`OsString`]: struct.OsString.html - /// /// # Examples /// /// ``` @@ -662,9 +639,6 @@ impl OsStr { /// This number is simply useful for passing to other methods, like /// [`OsString::with_capacity`] to avoid reallocations. /// - /// [`OsString`]: struct.OsString.html - /// [`OsString::with_capacity`]: struct.OsString.html#method.with_capacity - /// /// # Examples /// /// ``` @@ -682,9 +656,6 @@ impl OsStr { } /// Converts a [`Box`]`` into an [`OsString`] without copying or allocating. - /// - /// [`Box`]: ../boxed/struct.Box.html - /// [`OsString`]: struct.OsString.html #[stable(feature = "into_boxed_os_str", since = "1.20.0")] pub fn into_os_string(self: Box) -> OsString { let boxed = unsafe { Box::from_raw(Box::into_raw(self) as *mut Slice) }; @@ -706,9 +677,7 @@ impl OsStr { /// but non-ASCII letters are unchanged. /// /// To return a new lowercased value without modifying the existing one, use - /// [`to_ascii_lowercase`]. - /// - /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase + /// [`OsStr::to_ascii_lowercase`]. /// /// # Examples /// @@ -733,9 +702,7 @@ impl OsStr { /// but non-ASCII letters are unchanged. /// /// To return a new uppercased value without modifying the existing one, use - /// [`to_ascii_uppercase`]. - /// - /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase + /// [`OsStr::to_ascii_uppercase`]. /// /// # Examples /// @@ -760,9 +727,7 @@ impl OsStr { /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', /// but non-ASCII letters are unchanged. /// - /// To lowercase the value in-place, use [`make_ascii_lowercase`]. - /// - /// [`make_ascii_lowercase`]: #method.make_ascii_lowercase + /// To lowercase the value in-place, use [`OsStr::make_ascii_lowercase`]. /// /// # Examples /// @@ -784,9 +749,7 @@ impl OsStr { /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', /// but non-ASCII letters are unchanged. /// - /// To uppercase the value in-place, use [`make_ascii_uppercase`]. - /// - /// [`make_ascii_uppercase`]: #method.make_ascii_uppercase + /// To uppercase the value in-place, use [`OsStr::make_ascii_uppercase`]. /// /// # Examples /// @@ -865,9 +828,6 @@ impl From> for Box { impl From> for OsString { /// Converts a [`Box`]`<`[`OsStr`]`>` into a `OsString` without copying or /// allocating. - /// - /// [`Box`]: ../boxed/struct.Box.html - /// [`OsStr`]: ../ffi/struct.OsStr.html fn from(boxed: Box) -> OsString { boxed.into_os_string() } @@ -876,9 +836,6 @@ impl From> for OsString { #[stable(feature = "box_from_os_string", since = "1.20.0")] impl From for Box { /// Converts a [`OsString`] into a [`Box`]`` without copying or allocating. - /// - /// [`Box`]: ../boxed/struct.Box.html - /// [`OsString`]: ../ffi/struct.OsString.html fn from(s: OsString) -> Box { s.into_boxed_os_str() } @@ -895,9 +852,6 @@ impl Clone for Box { #[stable(feature = "shared_from_slice2", since = "1.24.0")] impl From for Arc { /// Converts a [`OsString`] into a [`Arc`]`` without copying or allocating. - /// - /// [`Arc`]: ../sync/struct.Arc.html - /// [`OsString`]: ../ffi/struct.OsString.html #[inline] fn from(s: OsString) -> Arc { let arc = s.inner.into_arc(); @@ -917,9 +871,6 @@ impl From<&OsStr> for Arc { #[stable(feature = "shared_from_slice2", since = "1.24.0")] impl From for Rc { /// Converts a [`OsString`] into a [`Rc`]`` without copying or allocating. - /// - /// [`Rc`]: ../rc/struct.Rc.html - /// [`OsString`]: ../ffi/struct.OsString.html #[inline] fn from(s: OsString) -> Rc { let rc = s.inner.into_rc();