mirror of
https://github.com/rust-lang/rust
synced 2024-09-05 08:37:14 +00:00
Rollup merge of #42749 - frewsxcv:frewsxcxv/doc-examples, r=QuietMisdreavus
Additions/improvements for doc examples. None
This commit is contained in:
commit
d3e116a945
|
@ -438,6 +438,35 @@ pub struct JoinPathsError {
|
|||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// Joining paths on a Unix-like platform:
|
||||
///
|
||||
/// ```
|
||||
/// # if cfg!(unix) {
|
||||
/// use std::env;
|
||||
/// use std::ffi::OsString;
|
||||
/// use std::path::Path;
|
||||
///
|
||||
/// let paths = [Path::new("/bin"), Path::new("/usr/bin")];
|
||||
/// let path_os_string = env::join_paths(paths.iter()).unwrap();
|
||||
/// assert_eq!(path_os_string, OsString::from("/bin:/usr/bin"));
|
||||
/// # }
|
||||
/// ```
|
||||
///
|
||||
/// Joining a path containing a colon on a Unix-like platform results in an error:
|
||||
///
|
||||
/// ```
|
||||
/// # if cfg!(unix) {
|
||||
/// use std::env;
|
||||
/// use std::path::Path;
|
||||
///
|
||||
/// let paths = [Path::new("/bin"), Path::new("/usr/bi:n")];
|
||||
/// assert!(env::join_paths(paths.iter()).is_err());
|
||||
/// # }
|
||||
/// ```
|
||||
///
|
||||
/// Using `env::join_paths` with `env::spit_paths` to append an item to the `PATH` environment
|
||||
/// variable:
|
||||
///
|
||||
/// ```
|
||||
/// use std::env;
|
||||
/// use std::path::PathBuf;
|
||||
|
|
|
@ -152,6 +152,14 @@ pub struct CStr {
|
|||
/// in the vector provided.
|
||||
///
|
||||
/// [`CString::new`]: struct.CString.html#method.new
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::ffi::{CString, NulError};
|
||||
///
|
||||
/// let _: NulError = CString::new(b"f\0oo".to_vec()).unwrap_err();
|
||||
/// ```
|
||||
#[derive(Clone, PartialEq, Eq, Debug)]
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub struct NulError(usize, Vec<u8>);
|
||||
|
@ -160,6 +168,14 @@ pub struct CStr {
|
|||
/// byte was found too early in the slice provided or one wasn't found at all.
|
||||
///
|
||||
/// [`CStr::from_bytes_with_nul`]: struct.CStr.html#method.from_bytes_with_nul
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::ffi::{CStr, FromBytesWithNulError};
|
||||
///
|
||||
/// let _: FromBytesWithNulError = CStr::from_bytes_with_nul(b"f\0oo").unwrap_err();
|
||||
/// ```
|
||||
#[derive(Clone, PartialEq, Eq, Debug)]
|
||||
#[stable(feature = "cstr_from_bytes", since = "1.10.0")]
|
||||
pub struct FromBytesWithNulError {
|
||||
|
@ -271,6 +287,27 @@ pub unsafe fn from_vec_unchecked(mut v: Vec<u8>) -> CString {
|
|||
/// to undefined behavior or allocator corruption.
|
||||
///
|
||||
/// [`into_raw`]: #method.into_raw
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// Create a `CString`, pass ownership to an `extern` function (via raw pointer), then retake
|
||||
/// ownership with `from_raw`:
|
||||
///
|
||||
/// ```no_run
|
||||
/// use std::ffi::CString;
|
||||
/// use std::os::raw::c_char;
|
||||
///
|
||||
/// extern {
|
||||
/// fn some_extern_function(s: *mut c_char);
|
||||
/// }
|
||||
///
|
||||
/// let c_string = CString::new("Hello!").unwrap();
|
||||
/// let raw = c_string.into_raw();
|
||||
/// unsafe {
|
||||
/// some_extern_function(raw);
|
||||
/// let c_string = CString::from_raw(raw);
|
||||
/// }
|
||||
/// ```
|
||||
#[stable(feature = "cstr_memory", since = "1.4.0")]
|
||||
pub unsafe fn from_raw(ptr: *mut c_char) -> CString {
|
||||
let len = libc::strlen(ptr) + 1; // Including the NUL byte
|
||||
|
@ -412,6 +449,18 @@ pub fn as_bytes_with_nul(&self) -> &[u8] {
|
|||
/// Extracts a [`CStr`] slice containing the entire string.
|
||||
///
|
||||
/// [`CStr`]: struct.CStr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// #![feature(as_c_str)]
|
||||
///
|
||||
/// use std::ffi::{CString, CStr};
|
||||
///
|
||||
/// let c_string = CString::new(b"foo".to_vec()).unwrap();
|
||||
/// let c_str = c_string.as_c_str();
|
||||
/// assert_eq!(c_str, CStr::from_bytes_with_nul(b"foo\0").unwrap());
|
||||
/// ```
|
||||
#[inline]
|
||||
#[unstable(feature = "as_c_str", issue = "40380")]
|
||||
pub fn as_c_str(&self) -> &CStr {
|
||||
|
@ -421,6 +470,18 @@ pub fn as_c_str(&self) -> &CStr {
|
|||
/// Converts this `CString` into a boxed [`CStr`].
|
||||
///
|
||||
/// [`CStr`]: struct.CStr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// #![feature(into_boxed_c_str)]
|
||||
///
|
||||
/// use std::ffi::{CString, CStr};
|
||||
///
|
||||
/// let c_string = CString::new(b"foo".to_vec()).unwrap();
|
||||
/// let boxed = c_string.into_boxed_c_str();
|
||||
/// assert_eq!(&*boxed, CStr::from_bytes_with_nul(b"foo\0").unwrap());
|
||||
/// ```
|
||||
#[unstable(feature = "into_boxed_c_str", issue = "40380")]
|
||||
pub fn into_boxed_c_str(self) -> Box<CStr> {
|
||||
unsafe { mem::transmute(self.into_inner()) }
|
||||
|
@ -708,6 +769,24 @@ pub unsafe fn from_ptr<'a>(ptr: *const c_char) -> &'a CStr {
|
|||
/// let cstr = CStr::from_bytes_with_nul(b"hello\0");
|
||||
/// assert!(cstr.is_ok());
|
||||
/// ```
|
||||
///
|
||||
/// Creating a `CStr` without a trailing nul byte is an error:
|
||||
///
|
||||
/// ```
|
||||
/// use std::ffi::CStr;
|
||||
///
|
||||
/// let c_str = CStr::from_bytes_with_nul(b"hello");
|
||||
/// assert!(c_str.is_err());
|
||||
/// ```
|
||||
///
|
||||
/// Creating a `CStr` with an interior nul byte is an error:
|
||||
///
|
||||
/// ```
|
||||
/// use std::ffi::CStr;
|
||||
///
|
||||
/// let c_str = CStr::from_bytes_with_nul(b"he\0llo\0");
|
||||
/// assert!(c_str.is_err());
|
||||
/// ```
|
||||
#[stable(feature = "cstr_from_bytes", since = "1.10.0")]
|
||||
pub fn from_bytes_with_nul(bytes: &[u8])
|
||||
-> Result<&CStr, FromBytesWithNulError> {
|
||||
|
@ -800,6 +879,15 @@ pub fn as_ptr(&self) -> *const c_char {
|
|||
/// > **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.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::ffi::CStr;
|
||||
///
|
||||
/// let c_str = CStr::from_bytes_with_nul(b"foo\0").unwrap();
|
||||
/// assert_eq!(c_str.to_bytes(), b"foo");
|
||||
/// ```
|
||||
#[inline]
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub fn to_bytes(&self) -> &[u8] {
|
||||
|
@ -817,6 +905,15 @@ pub fn to_bytes(&self) -> &[u8] {
|
|||
/// > length calculation whenever this method is called.
|
||||
///
|
||||
/// [`to_bytes`]: #method.to_bytes
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::ffi::CStr;
|
||||
///
|
||||
/// let c_str = CStr::from_bytes_with_nul(b"foo\0").unwrap();
|
||||
/// assert_eq!(c_str.to_bytes_with_nul(), b"foo\0");
|
||||
/// ```
|
||||
#[inline]
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub fn to_bytes_with_nul(&self) -> &[u8] {
|
||||
|
@ -834,6 +931,15 @@ pub fn to_bytes_with_nul(&self) -> &[u8] {
|
|||
/// > check whenever this method is called.
|
||||
///
|
||||
/// [`&str`]: ../primitive.str.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::ffi::CStr;
|
||||
///
|
||||
/// let c_str = CStr::from_bytes_with_nul(b"foo\0").unwrap();
|
||||
/// assert_eq!(c_str.to_str(), Ok("foo"));
|
||||
/// ```
|
||||
#[stable(feature = "cstr_to_str", since = "1.4.0")]
|
||||
pub fn to_str(&self) -> Result<&str, str::Utf8Error> {
|
||||
// NB: When CStr is changed to perform the length check in .to_bytes()
|
||||
|
@ -857,6 +963,31 @@ pub fn to_str(&self) -> Result<&str, str::Utf8Error> {
|
|||
///
|
||||
/// [`Cow`]: ../borrow/enum.Cow.html
|
||||
/// [`str`]: ../primitive.str.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// Calling `to_string_lossy` on a `CStr` containing valid UTF-8:
|
||||
///
|
||||
/// ```
|
||||
/// use std::borrow::Cow;
|
||||
/// use std::ffi::CStr;
|
||||
///
|
||||
/// let c_str = CStr::from_bytes_with_nul(b"Hello World\0").unwrap();
|
||||
/// assert_eq!(c_str.to_string_lossy(), Cow::Borrowed("Hello World"));
|
||||
/// ```
|
||||
///
|
||||
/// Calling `to_string_lossy` on a `CStr` containing invalid UTF-8:
|
||||
///
|
||||
/// ```
|
||||
/// use std::borrow::Cow;
|
||||
/// use std::ffi::CStr;
|
||||
///
|
||||
/// let c_str = CStr::from_bytes_with_nul(b"Hello \xF0\x90\x80World\0").unwrap();
|
||||
/// assert_eq!(
|
||||
/// c_str.to_string_lossy(),
|
||||
/// Cow::Owned(String::from("Hello <20>World")) as Cow<str>
|
||||
/// );
|
||||
/// ```
|
||||
#[stable(feature = "cstr_to_str", since = "1.4.0")]
|
||||
pub fn to_string_lossy(&self) -> Cow<str> {
|
||||
String::from_utf8_lossy(self.to_bytes())
|
||||
|
@ -866,6 +997,18 @@ pub fn to_string_lossy(&self) -> Cow<str> {
|
|||
///
|
||||
/// [`Box`]: ../boxed/struct.Box.html
|
||||
/// [`CString`]: struct.CString.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// #![feature(into_boxed_c_str)]
|
||||
///
|
||||
/// use std::ffi::CString;
|
||||
///
|
||||
/// let c_string = CString::new(b"foo".to_vec()).unwrap();
|
||||
/// let boxed = c_string.into_boxed_c_str();
|
||||
/// assert_eq!(boxed.into_c_string(), CString::new("foo").unwrap());
|
||||
/// ```
|
||||
#[unstable(feature = "into_boxed_c_str", issue = "40380")]
|
||||
pub fn into_c_string(self: Box<CStr>) -> CString {
|
||||
unsafe { mem::transmute(self) }
|
||||
|
|
Loading…
Reference in a new issue