diff --git a/src/libstd/env.rs b/src/libstd/env.rs index 889ba81e778..770bca7524c 100644 --- a/src/libstd/env.rs +++ b/src/libstd/env.rs @@ -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; diff --git a/src/libstd/ffi/c_str.rs b/src/libstd/ffi/c_str.rs index 74ac9d528bb..1a91417ca0e 100644 --- a/src/libstd/ffi/c_str.rs +++ b/src/libstd/ffi/c_str.rs @@ -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); @@ -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) -> 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 { 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 �World")) as Cow + /// ); + /// ``` #[stable(feature = "cstr_to_str", since = "1.4.0")] pub fn to_string_lossy(&self) -> Cow { String::from_utf8_lossy(self.to_bytes()) @@ -866,6 +997,18 @@ pub fn to_string_lossy(&self) -> Cow { /// /// [`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) -> CString { unsafe { mem::transmute(self) }