OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki 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
Show Stats 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
/// 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<u8>);
/// 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<u8> {
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: Into<Vec<u8>>>(t: T) -> Result<CString, NulError> {
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`]`<u8>` 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`]`<u8>` 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<u8>) -> Result<Self, FromVecWithNulError> {
let nul_pos = memchr::memchr(0, &v);
@ -838,9 +782,6 @@ impl From<CString> for Vec<u8> {
/// Converts a [`CString`] into a [`Vec`]`<u8>`.
///
/// 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<u8> {
s.into_bytes()
@ -913,9 +854,6 @@ impl From<Cow<'_, CStr>> for Box<CStr> {
#[stable(feature = "c_string_from_box", since = "1.18.0")]
impl From<Box<CStr>> for CString {
/// Converts a [`Box`]`<CStr>` into a [`CString`] without copying or allocating.
///
/// [`Box`]: ../boxed/struct.Box.html
/// [`CString`]: ../ffi/struct.CString.html
#[inline]
fn from(s: Box<CStr>) -> CString {
s.into_c_string()
@ -926,10 +864,6 @@ impl From<Box<CStr>> for CString {
impl From<Vec<NonZeroU8>> 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<NonZeroU8>) -> CString {
unsafe {
@ -959,9 +893,6 @@ impl Clone for Box<CStr> {
#[stable(feature = "box_from_c_string", since = "1.20.0")]
impl From<CString> for Box<CStr> {
/// Converts a [`CString`] into a [`Box`]`<CStr>` without copying or allocating.
///
/// [`CString`]: ../ffi/struct.CString.html
/// [`Box`]: ../boxed/struct.Box.html
#[inline]
fn from(s: CString) -> Box<CStr> {
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<CString> for Arc<CStr> {
/// Converts a [`CString`] into a [`Arc`]`<CStr>` without copying or allocating.
///
/// [`CString`]: ../ffi/struct.CString.html
/// [`Arc`]: ../sync/struct.Arc.html
#[inline]
fn from(s: CString) -> Arc<CStr> {
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")]
impl From<CString> for Rc<CStr> {
/// Converts a [`CString`] into a [`Rc`]`<CStr>` without copying or allocating.
///
/// [`CString`]: ../ffi/struct.CString.html
/// [`Rc`]: ../rc/struct.Rc.html
#[inline]
fn from(s: CString) -> Rc<CStr> {
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<NulError> 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`]`<CStr>` into a [`CString`] without copying or allocating.
///
/// [`Box`]: ../boxed/struct.Box.html
/// [`CString`]: struct.CString.html
///
/// # Examples
///
/// ```

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

@ -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")]

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.
///
/// **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<String> 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`]`<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")]
pub fn into_os_string(self: Box<OsStr>) -> 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<Cow<'_, OsStr>> for Box<OsStr> {
impl From<Box<OsStr>> 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<OsStr>) -> OsString {
boxed.into_os_string()
}
@ -876,9 +836,6 @@ impl From<Box<OsStr>> for OsString {
#[stable(feature = "box_from_os_string", since = "1.20.0")]
impl From<OsString> for Box<OsStr> {
/// 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> {
s.into_boxed_os_str()
}
@ -895,9 +852,6 @@ impl Clone for Box<OsStr> {
#[stable(feature = "shared_from_slice2", since = "1.24.0")]
impl From<OsString> for Arc<OsStr> {
/// Converts a [`OsString`] into a [`Arc`]`<OsStr>` without copying or allocating.
///
/// [`Arc`]: ../sync/struct.Arc.html
/// [`OsString`]: ../ffi/struct.OsString.html
#[inline]
fn from(s: OsString) -> Arc<OsStr> {
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")]
impl From<OsString> for Rc<OsStr> {
/// Converts a [`OsString`] into a [`Rc`]`<OsStr>` without copying or allocating.
///
/// [`Rc`]: ../rc/struct.Rc.html
/// [`OsString`]: ../ffi/struct.OsString.html
#[inline]
fn from(s: OsString) -> Rc<OsStr> {
let rc = s.inner.into_rc();