bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Move to intra doc links in std::ffi

Browse source
This commit is contained in:
Alexis Bourget 2020-08-13 23:19:45 +02:00
parent b6396b75e7
commit 2adc8c0e5f
3 changed files with 81 additions and 233 deletions
Download patch file Download diff file Expand all files Collapse all files

193
library/std/src/ffi/c_str.rs
View file

@ -35,23 +35,23 @@ use crate::sys;
/// example, you can build a `CString` straight out of a [`String`] or /// example, you can build a `CString` straight out of a [`String`] or
/// a [`&str`], since both implement that trait). /// 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 /// does not have 0 bytes in the middle, and return an error if it
/// finds one. /// finds one.
/// ///
/// # Extracting a raw pointer to the whole C string /// # 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 /// trait. This method will give you a `*const c_char` which you can
/// feed directly to extern functions that expect a nul-terminated /// 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 /// read-only pointer; if the C code writes to it, that causes
/// undefined behavior. /// undefined behavior.
/// ///
/// # Extracting a slice of the whole C string /// # Extracting a slice of the whole C string
/// ///
/// Alternatively, you can obtain a `&[`[`u8`]`]` slice from a /// 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 /// way do *not* contain the trailing nul terminator. This is useful
/// when you will be calling an extern function that takes a `*const /// when you will be calling an extern function that takes a `*const
/// u8` argument which is not necessarily nul-terminated, plus another /// u8` argument which is not necessarily nul-terminated, plus another
@ -60,7 +60,7 @@ use crate::sys;
/// [`len`][slice.len] method. /// [`len`][slice.len] method.
/// ///
/// If you need a `&[`[`u8`]`]` slice *with* the nul terminator, you /// 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 /// Once you have the kind of slice you need (with or without a nul
/// terminator), you can call the slice's own /// 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 /// extern functions. See the documentation for that function for a
/// discussion on ensuring the lifetime of the raw pointer. /// discussion on ensuring the lifetime of the raw pointer.
/// ///
/// [`Into`]: ../convert/trait.Into.html /// [`&str`]: str
/// [`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
/// [slice.as_ptr]: ../primitive.slice.html#method.as_ptr /// [slice.as_ptr]: ../primitive.slice.html#method.as_ptr
/// [slice.len]: ../primitive.slice.html#method.len /// [slice.len]: ../primitive.slice.html#method.len
/// [`Deref`]: ../ops/trait.Deref.html /// [`Deref`]: ops::Deref
/// [`CStr`]: struct.CStr.html /// [`&CStr`]: CStr
/// [`&CStr`]: struct.CStr.html
/// ///
/// # Examples /// # Examples
/// ///
@ -113,7 +104,6 @@ use crate::sys;
/// documentation of `CString` before use, as improper ownership management /// documentation of `CString` before use, as improper ownership management
/// of `CString` instances can lead to invalid memory accesses, memory leaks, /// of `CString` instances can lead to invalid memory accesses, memory leaks,
/// and other memory errors. /// and other memory errors.
#[derive(PartialEq, PartialOrd, Eq, Ord, Hash, Clone)] #[derive(PartialEq, PartialOrd, Eq, Ord, Hash, Clone)]
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct CString { pub struct CString {
@ -137,8 +127,8 @@ pub struct CString {
/// ///
/// Note that this structure is **not** `repr(C)` and is not recommended to be /// 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 /// placed in the signatures of FFI functions. Instead, safe wrappers of FFI
/// functions may leverage the unsafe [`from_ptr`] constructor to provide a safe /// functions may leverage the unsafe [`CStr::from_ptr`] constructor to provide
/// interface to other consumers. /// a safe interface to other consumers.
/// ///
/// # Examples /// # Examples
/// ///
@ -189,11 +179,7 @@ pub struct CString {
/// println!("string: {}", my_string_safe()); /// println!("string: {}", my_string_safe());
/// ``` /// ```
/// ///
/// [`u8`]: ../primitive.u8.html /// [`&str`]: str
/// [`&str`]: ../primitive.str.html
/// [`String`]: ../string/struct.String.html
/// [`CString`]: struct.CString.html
/// [`from_ptr`]: #method.from_ptr
#[derive(Hash)] #[derive(Hash)]
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
// FIXME: // FIXME:
@ -218,9 +204,6 @@ pub struct CStr {
/// This error is created by the [`new`][`CString::new`] method on /// This error is created by the [`new`][`CString::new`] method on
/// [`CString`]. See its documentation for more. /// [`CString`]. See its documentation for more.
/// ///
/// [`CString`]: struct.CString.html
/// [`CString::new`]: struct.CString.html#method.new
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -237,12 +220,9 @@ pub struct NulError(usize, Vec<u8>);
/// The slice used to create a [`CStr`] must have one and only one nul byte, /// The slice used to create a [`CStr`] must have one and only one nul byte,
/// positioned at the end. /// 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. /// See its documentation for more.
/// ///
/// [`CStr`]: struct.CStr.html
/// [`from_bytes_with_nul`]: struct.CStr.html#method.from_bytes_with_nul
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -261,12 +241,9 @@ pub struct FromBytesWithNulError {
/// The vector used to create a [`CString`] must have one and only one nul byte, /// The vector used to create a [`CString`] must have one and only one nul byte,
/// positioned at the end. /// 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. /// See its documentation for more.
/// ///
/// [`CString`]: struct.CString.html
/// [`from_vec_with_nul`]: struct.CString.html#method.from_vec_with_nul
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -316,8 +293,6 @@ impl FromVecWithNulError {
/// ///
/// assert_eq!(&bytes[..], value.unwrap_err().as_bytes()); /// assert_eq!(&bytes[..], value.unwrap_err().as_bytes());
/// ``` /// ```
///
/// [`CString`]: struct.CString.html
pub fn as_bytes(&self) -> &[u8] { pub fn as_bytes(&self) -> &[u8] {
&self.bytes[..] &self.bytes[..]
} }
@ -343,8 +318,6 @@ impl FromVecWithNulError {
/// ///
/// assert_eq!(bytes, value.unwrap_err().into_bytes()); /// assert_eq!(bytes, value.unwrap_err().into_bytes());
/// ``` /// ```
///
/// [`CString`]: struct.CString.html
pub fn into_bytes(self) -> Vec<u8> { pub fn into_bytes(self) -> Vec<u8> {
self.bytes self.bytes
} }
@ -352,17 +325,12 @@ impl FromVecWithNulError {
/// An error indicating invalid UTF-8 when converting a [`CString`] into a [`String`]. /// 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 /// `CString` is just a wrapper over a buffer of bytes with a nul terminator;
/// terminator; [`into_string`][`CString::into_string`] performs UTF-8 /// [`CString::into_string`] performs UTF-8 validation on those bytes and may
/// validation on those bytes and may return this error. /// return this error.
/// ///
/// This `struct` is created by the /// This `struct` is created by the [`CString::into_string`] method. See
/// [`into_string`][`CString::into_string`] method on [`CString`]. See
/// its documentation for more. /// 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)] #[derive(Clone, PartialEq, Eq, Debug)]
#[stable(feature = "cstring_into", since = "1.7.0")] #[stable(feature = "cstring_into", since = "1.7.0")]
pub struct IntoStringError { pub struct IntoStringError {
@ -398,8 +366,6 @@ impl CString {
/// This function will return an error if the supplied bytes contain an /// 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 /// internal 0 byte. The [`NulError`] returned will contain the bytes as well as
/// the position of the nul byte. /// the position of the nul byte.
///
/// [`NulError`]: struct.NulError.html
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub fn new<T: Into<Vec<u8>>>(t: T) -> Result<CString, NulError> { pub fn new<T: Into<Vec<u8>>>(t: T) -> Result<CString, NulError> {
trait SpecIntoVec { trait SpecIntoVec {
@ -439,11 +405,9 @@ impl CString {
/// Creates a C-compatible string by consuming a byte vector, /// Creates a C-compatible string by consuming a byte vector,
/// without checking for interior 0 bytes. /// without checking for interior 0 bytes.
/// ///
/// This method is equivalent to [`new`] except that no runtime assertion /// This method is equivalent to [`CString::new`] except that no runtime
/// is made that `v` contains no 0 bytes, and it requires an actual /// assertion is made that `v` contains no 0 bytes, and it requires an
/// byte vector, not anything that can be converted to one with Into. /// actual byte vector, not anything that can be converted to one with Into.
///
/// [`new`]: #method.new
/// ///
/// # Examples /// # Examples
/// ///
@ -462,21 +426,22 @@ impl CString {
CString { inner: v.into_boxed_slice() } 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. /// Additionally, the length of the string will be recalculated from the pointer.
/// ///
/// # Safety /// # Safety
/// ///
/// This should only ever be called with a pointer that was earlier /// 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 /// ownership of a string that was allocated by foreign code) is likely to lead
/// to undefined behavior or allocator corruption. /// to undefined behavior or allocator corruption.
/// ///
/// It should be noted that the length isn't just "recomputed," but that /// It should be noted that the length isn't just "recomputed," but that
/// the recomputed length must match the original length from the /// the recomputed length must match the original length from the
/// [`into_raw`] call. This means the [`into_raw`]/`from_raw` methods /// [`CString::into_raw`] call. This means the [`CString::into_raw`]/`from_raw`
/// should not be used when passing the string to C functions that can /// methods should not be used when passing the string to C functions that can
/// modify the string's length. /// modify the string's length.
/// ///
/// > **Note:** If you need to borrow a string that was allocated by /// > **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 /// > make your own provisions for freeing it appropriately, likely
/// > with the foreign code's API to do that. /// > with the foreign code's API to do that.
/// ///
/// [`into_raw`]: #method.into_raw
/// [`CStr`]: struct.CStr.html
///
/// # Examples /// # Examples
/// ///
/// Creates a `CString`, pass ownership to an `extern` function (via raw pointer), then retake /// 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. /// 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 /// 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 /// should *not* use the standard C `free()` function to deallocate
/// this string. /// 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 /// 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 /// `NULL` somewhere inside the string or removing the final one) before
/// it makes it back into Rust using [`from_raw`]. See the safety section /// it makes it back into Rust using [`CString::from_raw`]. See the safety section
/// in [`from_raw`]. /// in [`CString::from_raw`].
///
/// [`from_raw`]: #method.from_raw
/// ///
/// # Examples /// # Examples
/// ///
@ -560,8 +520,6 @@ impl CString {
/// ///
/// On failure, ownership of the original `CString` is returned. /// On failure, ownership of the original `CString` is returned.
/// ///
/// [`String`]: ../string/struct.String.html
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -608,10 +566,8 @@ impl CString {
vec vec
} }
/// Equivalent to the [`into_bytes`] function except that the returned vector /// Equivalent to the [`CString::into_bytes`] function except that the
/// includes the trailing nul terminator. /// returned vector includes the trailing nul terminator.
///
/// [`into_bytes`]: #method.into_bytes
/// ///
/// # Examples /// # Examples
/// ///
@ -632,9 +588,7 @@ impl CString {
/// The returned slice does **not** contain the trailing nul /// The returned slice does **not** contain the trailing nul
/// terminator, and it is guaranteed to not have any interior nul /// terminator, and it is guaranteed to not have any interior nul
/// bytes. If you need the nul terminator, use /// bytes. If you need the nul terminator, use
/// [`as_bytes_with_nul`] instead. /// [`CString::as_bytes_with_nul`] instead.
///
/// [`as_bytes_with_nul`]: #method.as_bytes_with_nul
/// ///
/// # Examples /// # Examples
/// ///
@ -651,10 +605,8 @@ impl CString {
&self.inner[..self.inner.len() - 1] &self.inner[..self.inner.len() - 1]
} }
/// Equivalent to the [`as_bytes`] function except that the returned slice /// Equivalent to the [`CString::as_bytes`] function except that the
/// includes the trailing nul terminator. /// returned slice includes the trailing nul terminator.
///
/// [`as_bytes`]: #method.as_bytes
/// ///
/// # Examples /// # Examples
/// ///
@ -673,8 +625,6 @@ impl CString {
/// Extracts a [`CStr`] slice containing the entire string. /// Extracts a [`CStr`] slice containing the entire string.
/// ///
/// [`CStr`]: struct.CStr.html
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -693,8 +643,6 @@ impl CString {
/// Converts this `CString` into a boxed [`CStr`]. /// Converts this `CString` into a boxed [`CStr`].
/// ///
/// [`CStr`]: struct.CStr.html
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -711,8 +659,6 @@ impl CString {
} }
/// Bypass "move out of struct which implements [`Drop`] trait" restriction. /// Bypass "move out of struct which implements [`Drop`] trait" restriction.
///
/// [`Drop`]: ../ops/trait.Drop.html
fn into_inner(self) -> Box<[u8]> { fn into_inner(self) -> Box<[u8]> {
// Rationale: `mem::forget(self)` invalidates the previous call to `ptr::read(&self.inner)` // Rationale: `mem::forget(self)` invalidates the previous call to `ptr::read(&self.inner)`
// so we use `ManuallyDrop` to ensure `self` is not dropped. // so we use `ManuallyDrop` to ensure `self` is not dropped.
@ -722,12 +668,12 @@ impl CString {
unsafe { ptr::read(&this.inner) } unsafe { ptr::read(&this.inner) }
} }
/// Converts a `Vec` of `u8` to a `CString` without checking the invariants /// Converts a [`Vec`]`<u8>` to a [`CString`] without checking the
/// on the given `Vec`. /// invariants on the given [`Vec`].
/// ///
/// # Safety /// # 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. /// This means it cannot be empty nor have any other nul byte anywhere else.
/// ///
/// # Example /// # Example
@ -745,10 +691,10 @@ impl CString {
Self { inner: v.into_boxed_slice() } Self { inner: v.into_boxed_slice() }
} }
/// Attempts to converts a `Vec` of `u8` to a `CString`. /// Attempts to converts a [`Vec`]`<u8>` to a [`CString`].
/// ///
/// Runtime checks are present to ensure there is only one nul byte in the /// Runtime checks are present to ensure there is only one nul byte in the
/// `Vec`, its last element. /// [`Vec`], its last element.
/// ///
/// # Errors /// # Errors
/// ///
@ -757,8 +703,8 @@ impl CString {
/// ///
/// # Examples /// # Examples
/// ///
/// A successful conversion will produce the same result as [`new`] when /// A successful conversion will produce the same result as [`CString::new`]
/// called without the ending nul byte. /// when called without the ending nul byte.
/// ///
/// ``` /// ```
/// #![feature(cstring_from_vec_with_nul)] /// #![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)] /// #![feature(cstring_from_vec_with_nul)]
@ -780,8 +726,6 @@ impl CString {
/// // No nul byte /// // No nul byte
/// let _: FromVecWithNulError = CString::from_vec_with_nul(b"abc".to_vec()).unwrap_err(); /// 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")] #[unstable(feature = "cstring_from_vec_with_nul", issue = "73179")]
pub fn from_vec_with_nul(v: Vec<u8>) -> Result<Self, FromVecWithNulError> { pub fn from_vec_with_nul(v: Vec<u8>) -> Result<Self, FromVecWithNulError> {
let nul_pos = memchr::memchr(0, &v); let nul_pos = memchr::memchr(0, &v);
@ -838,9 +782,6 @@ impl From<CString> for Vec<u8> {
/// Converts a [`CString`] into a [`Vec`]`<u8>`. /// Converts a [`CString`] into a [`Vec`]`<u8>`.
/// ///
/// The conversion consumes the [`CString`], and removes the terminating NUL byte. /// The conversion consumes the [`CString`], and removes the terminating NUL byte.
///
/// [`Vec`]: ../vec/struct.Vec.html
/// [`CString`]: ../ffi/struct.CString.html
#[inline] #[inline]
fn from(s: CString) -> Vec<u8> { fn from(s: CString) -> Vec<u8> {
s.into_bytes() s.into_bytes()
@ -913,9 +854,6 @@ impl From<Cow<'_, CStr>> for Box<CStr> {
#[stable(feature = "c_string_from_box", since = "1.18.0")] #[stable(feature = "c_string_from_box", since = "1.18.0")]
impl From<Box<CStr>> for CString { impl From<Box<CStr>> for CString {
/// Converts a [`Box`]`<CStr>` into a [`CString`] without copying or allocating. /// Converts a [`Box`]`<CStr>` into a [`CString`] without copying or allocating.
///
/// [`Box`]: ../boxed/struct.Box.html
/// [`CString`]: ../ffi/struct.CString.html
#[inline] #[inline]
fn from(s: Box<CStr>) -> CString { fn from(s: Box<CStr>) -> CString {
s.into_c_string() s.into_c_string()
@ -926,10 +864,6 @@ impl From<Box<CStr>> for CString {
impl From<Vec<NonZeroU8>> for CString { impl From<Vec<NonZeroU8>> for CString {
/// Converts a [`Vec`]`<`[`NonZeroU8`]`>` into a [`CString`] without /// Converts a [`Vec`]`<`[`NonZeroU8`]`>` into a [`CString`] without
/// copying nor checking for inner null bytes. /// copying nor checking for inner null bytes.
///
/// [`CString`]: ../ffi/struct.CString.html
/// [`NonZeroU8`]: ../num/struct.NonZeroU8.html
/// [`Vec`]: ../vec/struct.Vec.html
#[inline] #[inline]
fn from(v: Vec<NonZeroU8>) -> CString { fn from(v: Vec<NonZeroU8>) -> CString {
unsafe { unsafe {
@ -959,9 +893,6 @@ impl Clone for Box<CStr> {
#[stable(feature = "box_from_c_string", since = "1.20.0")] #[stable(feature = "box_from_c_string", since = "1.20.0")]
impl From<CString> for Box<CStr> { impl From<CString> for Box<CStr> {
/// Converts a [`CString`] into a [`Box`]`<CStr>` without copying or allocating. /// Converts a [`CString`] into a [`Box`]`<CStr>` without copying or allocating.
///
/// [`CString`]: ../ffi/struct.CString.html
/// [`Box`]: ../boxed/struct.Box.html
#[inline] #[inline]
fn from(s: CString) -> Box<CStr> { fn from(s: CString) -> Box<CStr> {
s.into_boxed_c_str() 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")] #[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<CString> for Arc<CStr> { impl From<CString> for Arc<CStr> {
/// Converts a [`CString`] into a [`Arc`]`<CStr>` without copying or allocating. /// Converts a [`CString`] into a [`Arc`]`<CStr>` without copying or allocating.
///
/// [`CString`]: ../ffi/struct.CString.html
/// [`Arc`]: ../sync/struct.Arc.html
#[inline] #[inline]
fn from(s: CString) -> Arc<CStr> { fn from(s: CString) -> Arc<CStr> {
let arc: Arc<[u8]> = Arc::from(s.into_inner()); let arc: Arc<[u8]> = Arc::from(s.into_inner());
@ -1017,9 +945,6 @@ impl From<&CStr> for Arc<CStr> {
#[stable(feature = "shared_from_slice2", since = "1.24.0")] #[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<CString> for Rc<CStr> { impl From<CString> for Rc<CStr> {
/// Converts a [`CString`] into a [`Rc`]`<CStr>` without copying or allocating. /// Converts a [`CString`] into a [`Rc`]`<CStr>` without copying or allocating.
///
/// [`CString`]: ../ffi/struct.CString.html
/// [`Rc`]: ../rc/struct.Rc.html
#[inline] #[inline]
fn from(s: CString) -> Rc<CStr> { fn from(s: CString) -> Rc<CStr> {
let rc: Rc<[u8]> = Rc::from(s.into_inner()); 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 /// Returns the position of the nul byte in the slice that caused
/// [`CString::new`] to fail. /// [`CString::new`] to fail.
/// ///
/// [`CString::new`]: struct.CString.html#method.new
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -1101,9 +1024,6 @@ impl fmt::Display for NulError {
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
impl From<NulError> for io::Error { impl From<NulError> for io::Error {
/// Converts a [`NulError`] into a [`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 { fn from(_: NulError) -> io::Error {
io::Error::new(io::ErrorKind::InvalidInput, "data provided contains a nul byte") io::Error::new(io::ErrorKind::InvalidInput, "data provided contains a nul byte")
} }
@ -1154,8 +1074,6 @@ impl fmt::Display for FromVecWithNulError {
impl IntoStringError { impl IntoStringError {
/// Consumes this error, returning original [`CString`] which generated the /// Consumes this error, returning original [`CString`] which generated the
/// error. /// error.
///
/// [`CString`]: struct.CString.html
#[stable(feature = "cstring_into", since = "1.7.0")] #[stable(feature = "cstring_into", since = "1.7.0")]
pub fn into_cstring(self) -> CString { pub fn into_cstring(self) -> CString {
self.inner self.inner
@ -1330,7 +1248,8 @@ impl CStr {
/// ///
/// This happens because the pointer returned by `as_ptr` does not carry any /// This happens because the pointer returned by `as_ptr` does not carry any
/// lifetime information and the [`CString`] is deallocated immediately after /// 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: /// To fix the problem, bind the `CString` to a local variable:
/// ///
/// ```no_run /// ```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. /// the lifetime of `ptr` and the `unsafe` block.
///
/// [`CString`]: struct.CString.html
#[inline] #[inline]
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
#[rustc_const_stable(feature = "const_str_as_ptr", since = "1.32.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. /// 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 /// This function is the equivalent of [`CStr::to_bytes`] except that it
/// the trailing nul terminator instead of chopping it off. /// will retain the trailing nul terminator instead of chopping it off.
/// ///
/// > **Note**: This method is currently implemented as a 0-cost cast, but /// > **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 /// > it is planned to alter its definition in the future to perform the
/// > length calculation whenever this method is called. /// > length calculation whenever this method is called.
/// ///
/// [`to_bytes`]: #method.to_bytes
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -1411,7 +1326,7 @@ impl CStr {
/// function will return the corresponding [`&str`] slice. Otherwise, /// function will return the corresponding [`&str`] slice. Otherwise,
/// it will return an error with details of where UTF-8 validation failed. /// it will return an error with details of where UTF-8 validation failed.
/// ///
/// [`&str`]: ../primitive.str.html /// [`&str`]: str
/// ///
/// # Examples /// # Examples
/// ///
@ -1439,12 +1354,9 @@ impl CStr {
/// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD] and return a /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD] and return a
/// [`Cow`]`::`[`Owned`]`(`[`String`]`)` with the result. /// [`Cow`]`::`[`Owned`]`(`[`String`]`)` with the result.
/// ///
/// [`Cow`]: ../borrow/enum.Cow.html /// [`Borrowed`]: Cow::Borrowed
/// [`Borrowed`]: ../borrow/enum.Cow.html#variant.Borrowed /// [`Owned`]: Cow::Owned
/// [`Owned`]: ../borrow/enum.Cow.html#variant.Owned /// [U+FFFD]: crate::char::REPLACEMENT_CHARACTER
/// [`str`]: ../primitive.str.html
/// [`String`]: ../string/struct.String.html
/// [U+FFFD]: ../char/constant.REPLACEMENT_CHARACTER.html
/// ///
/// # Examples /// # Examples
/// ///
@ -1479,9 +1391,6 @@ impl CStr {
/// Converts a [`Box`]`<CStr>` into a [`CString`] without copying or allocating. /// Converts a [`Box`]`<CStr>` into a [`CString`] without copying or allocating.
/// ///
/// [`Box`]: ../boxed/struct.Box.html
/// [`CString`]: struct.CString.html
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```

42
library/std/src/ffi/mod.rs
View file

@ -88,7 +88,7 @@
//! [`env::var_os()`] is used to query environment variables; it //! [`env::var_os()`] is used to query environment variables; it
//! returns an [`Option`]`<`[`OsString`]`>`. If the environment variable //! returns an [`Option`]`<`[`OsString`]`>`. If the environment variable
//! exists you will get a [`Some`]`(os_string)`, which you can *then* try to //! 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 //! your code can detect errors in case the environment variable did
//! not in fact contain valid Unicode data. //! not in fact contain valid Unicode data.
//! //!
@ -124,34 +124,22 @@
//! method is an [`OsString`] which can be round-tripped to a Windows //! method is an [`OsString`] which can be round-tripped to a Windows
//! string losslessly. //! 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 scalar value]: http://www.unicode.org/glossary/#unicode_scalar_value
//! [Unicode code point]: http://www.unicode.org/glossary/#code_point //! [Unicode code point]: http://www.unicode.org/glossary/#code_point
//! [`CString`]: struct.CString.html //! [`env::set_var()`]: crate::env::set_var
//! [`CStr`]: struct.CStr.html //! [`env::var_os()`]: crate::env::var_os
//! [`OsString`]: struct.OsString.html //! [unix.OsStringExt]: crate::os::unix::ffi::OsStringExt
//! [`OsStr`]: struct.OsStr.html //! [`from_vec`]: crate::os::unix::ffi::OsStringExt::from_vec
//! [`env::set_var()`]: ../env/fn.set_var.html //! [`into_vec`]: crate::os::unix::ffi::OsStringExt::into_vec
//! [`env::var_os()`]: ../env/fn.var_os.html //! [unix.OsStrExt]: crate::os::unix::ffi::OsStrExt
//! [`Result<>`]: ../result/enum.Result.html //! [`from_bytes`]: crate::os::unix::ffi::OsStrExt::from_bytes
//! [unix.OsStringExt]: ../os/unix/ffi/trait.OsStringExt.html //! [`as_bytes`]: crate::os::unix::ffi::OsStrExt::as_bytes
//! [`from_vec`]: ../os/unix/ffi/trait.OsStringExt.html#tymethod.from_vec //! [`OsStrExt`]: crate::os::unix::ffi::OsStrExt
//! [`into_vec`]: ../os/unix/ffi/trait.OsStringExt.html#tymethod.into_vec //! [windows.OsStrExt]: crate::os::windows::ffi::OsStrExt
//! [unix.OsStrExt]: ../os/unix/ffi/trait.OsStrExt.html //! [`encode_wide`]: crate::os::windows::ffi::OsStrExt::encode_wide
//! [`from_bytes`]: ../os/unix/ffi/trait.OsStrExt.html#tymethod.from_bytes //! [`collect`]: crate::iter::Iterator::collect
//! [`as_bytes`]: ../os/unix/ffi/trait.OsStrExt.html#tymethod.as_bytes //! [windows.OsStringExt]: crate::os::windows::ffi::OsStringExt
//! [`OsStrExt`]: ../os/unix/ffi/trait.OsStrExt.html //! [`from_wide`]: crate::os::windows::ffi::OsStringExt::from_wide
//! [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
#![stable(feature = "rust1", since = "1.0.0")] #![stable(feature = "rust1", since = "1.0.0")]

79
library/std/src/ffi/os_str.rs
View file

@ -47,14 +47,14 @@ use crate::sys_common::{AsInner, FromInner, IntoInner};
/// create an `OsString` from a normal Rust string. /// create an `OsString` from a normal Rust string.
/// ///
/// **From slices:** Just like you can start with an empty Rust /// **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 /// sub-string slices into it, you can create an empty `OsString` with
/// the [`new`] method and then push string slices into it with the /// the [`OsString::new`] method and then push string slices into it with the
/// [`push`] method. /// [`OsString::push`] method.
/// ///
/// # Extracting a borrowed reference to the whole OS string /// # 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 /// an `OsString`; this is effectively a borrowed reference to the
/// whole string. /// 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 /// See the [module's toplevel documentation about conversions][conversions] for a discussion on
/// the traits which `OsString` implements for [conversions] from/to native representations. /// the traits which `OsString` implements for [conversions] from/to native representations.
/// ///
/// [`OsStr`]: struct.OsStr.html /// [`&OsStr`]: OsStr
/// [`&OsStr`]: struct.OsStr.html /// [`&str`]: str
/// [`CStr`]: struct.CStr.html /// [`CStr`]: crate::ffi::CStr
/// [`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
/// [conversions]: index.html#conversions /// [conversions]: index.html#conversions
#[derive(Clone)] #[derive(Clone)]
#[stable(feature = "rust1", since = "1.0.0")] #[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 /// See the [module's toplevel documentation about conversions][conversions] for a discussion on
/// the traits which `OsStr` implements for [conversions] from/to native representations. /// the traits which `OsStr` implements for [conversions] from/to native representations.
/// ///
/// [`OsString`]: struct.OsString.html /// [`&str`]: str
/// [`&str`]: ../primitive.str.html
/// [`String`]: ../string/struct.String.html
/// [conversions]: index.html#conversions /// [conversions]: index.html#conversions
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
// FIXME: // FIXME:
@ -125,8 +114,6 @@ impl OsString {
/// Converts to an [`OsStr`] slice. /// Converts to an [`OsStr`] slice.
/// ///
/// [`OsStr`]: struct.OsStr.html
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -145,8 +132,6 @@ impl OsString {
/// ///
/// On failure, ownership of the original `OsString` is returned. /// On failure, ownership of the original `OsString` is returned.
/// ///
/// [`String`]: ../../std/string/struct.String.html
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -163,7 +148,7 @@ impl OsString {
/// Extends the string with the given [`&OsStr`] slice. /// Extends the string with the given [`&OsStr`] slice.
/// ///
/// [`&OsStr`]: struct.OsStr.html /// [`&OsStr`]: OsStr
/// ///
/// # Examples /// # Examples
/// ///
@ -333,8 +318,6 @@ impl OsString {
/// Converts this `OsString` into a boxed [`OsStr`]. /// Converts this `OsString` into a boxed [`OsStr`].
/// ///
/// [`OsStr`]: struct.OsStr.html
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -356,8 +339,6 @@ impl From<String> for OsString {
/// Converts a [`String`] into a [`OsString`]. /// Converts a [`String`] into a [`OsString`].
/// ///
/// The conversion copies the data, and includes an allocation on the heap. /// The conversion copies the data, and includes an allocation on the heap.
///
/// [`OsString`]: ../../std/ffi/struct.OsString.html
fn from(s: String) -> OsString { fn from(s: String) -> OsString {
OsString { inner: Buf::from_string(s) } OsString { inner: Buf::from_string(s) }
} }
@ -544,7 +525,7 @@ impl OsStr {
/// ///
/// This conversion may entail doing a check for UTF-8 validity. /// This conversion may entail doing a check for UTF-8 validity.
/// ///
/// [`&str`]: ../../std/primitive.str.html /// [`&str`]: str
/// ///
/// # Examples /// # Examples
/// ///
@ -564,9 +545,7 @@ impl OsStr {
/// Any non-Unicode sequences are replaced with /// Any non-Unicode sequences are replaced with
/// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD]. /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD].
/// ///
/// [`Cow`]: ../../std/borrow/enum.Cow.html /// [U+FFFD]: crate::char::REPLACEMENT_CHARACTER
/// [`str`]: ../../std/primitive.str.html
/// [U+FFFD]: ../../std/char/constant.REPLACEMENT_CHARACTER.html
/// ///
/// # Examples /// # Examples
/// ///
@ -613,8 +592,6 @@ impl OsStr {
/// Copies the slice into an owned [`OsString`]. /// Copies the slice into an owned [`OsString`].
/// ///
/// [`OsString`]: struct.OsString.html
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -662,9 +639,6 @@ impl OsStr {
/// This number is simply useful for passing to other methods, like /// This number is simply useful for passing to other methods, like
/// [`OsString::with_capacity`] to avoid reallocations. /// [`OsString::with_capacity`] to avoid reallocations.
/// ///
/// [`OsString`]: struct.OsString.html
/// [`OsString::with_capacity`]: struct.OsString.html#method.with_capacity
///
/// # Examples /// # Examples
/// ///
/// ``` /// ```
@ -682,9 +656,6 @@ impl OsStr {
} }
/// Converts a [`Box`]`<OsStr>` into an [`OsString`] without copying or allocating. /// Converts a [`Box`]`<OsStr>` 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")] #[stable(feature = "into_boxed_os_str", since = "1.20.0")]
pub fn into_os_string(self: Box<OsStr>) -> OsString { pub fn into_os_string(self: Box<OsStr>) -> OsString {
let boxed = unsafe { Box::from_raw(Box::into_raw(self) as *mut Slice) }; 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. /// but non-ASCII letters are unchanged.
/// ///
/// To return a new lowercased value without modifying the existing one, use /// To return a new lowercased value without modifying the existing one, use
/// [`to_ascii_lowercase`]. /// [`OsStr::to_ascii_lowercase`].
///
/// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
/// ///
/// # Examples /// # Examples
/// ///
@ -733,9 +702,7 @@ impl OsStr {
/// but non-ASCII letters are unchanged. /// but non-ASCII letters are unchanged.
/// ///
/// To return a new uppercased value without modifying the existing one, use /// To return a new uppercased value without modifying the existing one, use
/// [`to_ascii_uppercase`]. /// [`OsStr::to_ascii_uppercase`].
///
/// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
/// ///
/// # Examples /// # Examples
/// ///
@ -760,9 +727,7 @@ impl OsStr {
/// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
/// but non-ASCII letters are unchanged. /// but non-ASCII letters are unchanged.
/// ///
/// To lowercase the value in-place, use [`make_ascii_lowercase`]. /// To lowercase the value in-place, use [`OsStr::make_ascii_lowercase`].
///
/// [`make_ascii_lowercase`]: #method.make_ascii_lowercase
/// ///
/// # Examples /// # Examples
/// ///
@ -784,9 +749,7 @@ impl OsStr {
/// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
/// but non-ASCII letters are unchanged. /// but non-ASCII letters are unchanged.
/// ///
/// To uppercase the value in-place, use [`make_ascii_uppercase`]. /// To uppercase the value in-place, use [`OsStr::make_ascii_uppercase`].
///
/// [`make_ascii_uppercase`]: #method.make_ascii_uppercase
/// ///
/// # Examples /// # Examples
/// ///
@ -865,9 +828,6 @@ impl From<Cow<'_, OsStr>> for Box<OsStr> {
impl From<Box<OsStr>> for OsString { impl From<Box<OsStr>> for OsString {
/// Converts a [`Box`]`<`[`OsStr`]`>` into a `OsString` without copying or /// Converts a [`Box`]`<`[`OsStr`]`>` into a `OsString` without copying or
/// allocating. /// allocating.
///
/// [`Box`]: ../boxed/struct.Box.html
/// [`OsStr`]: ../ffi/struct.OsStr.html
fn from(boxed: Box<OsStr>) -> OsString { fn from(boxed: Box<OsStr>) -> OsString {
boxed.into_os_string() boxed.into_os_string()
} }
@ -876,9 +836,6 @@ impl From<Box<OsStr>> for OsString {
#[stable(feature = "box_from_os_string", since = "1.20.0")] #[stable(feature = "box_from_os_string", since = "1.20.0")]
impl From<OsString> for Box<OsStr> { impl From<OsString> for Box<OsStr> {
/// Converts a [`OsString`] into a [`Box`]`<OsStr>` without copying or allocating. /// Converts a [`OsString`] into a [`Box`]`<OsStr>` without copying or allocating.
///
/// [`Box`]: ../boxed/struct.Box.html
/// [`OsString`]: ../ffi/struct.OsString.html
fn from(s: OsString) -> Box<OsStr> { fn from(s: OsString) -> Box<OsStr> {
s.into_boxed_os_str() s.into_boxed_os_str()
} }
@ -895,9 +852,6 @@ impl Clone for Box<OsStr> {
#[stable(feature = "shared_from_slice2", since = "1.24.0")] #[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<OsString> for Arc<OsStr> { impl From<OsString> for Arc<OsStr> {
/// Converts a [`OsString`] into a [`Arc`]`<OsStr>` without copying or allocating. /// Converts a [`OsString`] into a [`Arc`]`<OsStr>` without copying or allocating.
///
/// [`Arc`]: ../sync/struct.Arc.html
/// [`OsString`]: ../ffi/struct.OsString.html
#[inline] #[inline]
fn from(s: OsString) -> Arc<OsStr> { fn from(s: OsString) -> Arc<OsStr> {
let arc = s.inner.into_arc(); let arc = s.inner.into_arc();
@ -917,9 +871,6 @@ impl From<&OsStr> for Arc<OsStr> {
#[stable(feature = "shared_from_slice2", since = "1.24.0")] #[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<OsString> for Rc<OsStr> { impl From<OsString> for Rc<OsStr> {
/// Converts a [`OsString`] into a [`Rc`]`<OsStr>` without copying or allocating. /// Converts a [`OsString`] into a [`Rc`]`<OsStr>` without copying or allocating.
///
/// [`Rc`]: ../rc/struct.Rc.html
/// [`OsString`]: ../ffi/struct.OsString.html
#[inline] #[inline]
fn from(s: OsString) -> Rc<OsStr> { fn from(s: OsString) -> Rc<OsStr> {
let rc = s.inner.into_rc(); let rc = s.inner.into_rc();