CStr::from_bytes

[rust.git] / src / libstd / ffi / c_str.rs

diff --git a/src/libstd/ffi/c_str.rs b/src/libstd/ffi/c_str.rs
index 9d505607a60c48abac8909ecae77a2690a8b29b8..f50e906f14c484b266d0b65b0d7fae697311beb6 100644 (file)
--- a/src/libstd/ffi/c_str.rs
+++ b/src/libstd/ffi/c_str.rs
@@ -60,6 +60,18 @@
 /// }
 /// # }
 /// ```
+///
+/// # Safety
+///
+/// `CString` is intended for working with traditional C-style strings
+/// (a sequence of non-null bytes terminated by a single null byte); the
+/// primary use case for these kinds of strings is interoperating with C-like
+/// code. Often you will need to transfer ownership to/from that external
+/// code. It is strongly recommended that you thoroughly read through the
+/// 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 {
@@ -207,11 +219,11 @@ pub unsafe fn from_vec_unchecked(mut v: Vec<u8>) -> CString {
         CString { inner: v.into_boxed_slice() }
     }
 
-    /// Retakes ownership of a CString that was transferred to C.
+    /// Retakes ownership of a `CString` that was transferred to C.
     ///
-    /// The only appropriate argument is a pointer obtained by calling
-    /// `into_raw`. The length of the string will be recalculated
-    /// using the pointer.
+    /// This should only ever be called with a pointer that was earlier
+    /// obtained by calling `into_raw` on a `CString`. Additionally, the length
+    /// of the string will be recalculated from the pointer.
     #[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
@@ -424,6 +436,57 @@ pub unsafe fn from_ptr<'a>(ptr: *const c_char) -> &'a CStr {
         mem::transmute(slice::from_raw_parts(ptr, len as usize + 1))
     }
 
+    /// Creates a C string wrapper from a byte slice.
+    ///
+    /// This function will cast the provided `bytes` to a `CStr` wrapper after
+    /// ensuring that it is null terminated but does not contain any interior
+    /// nul bytes.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #![feature(cstr_from_bytes)]
+    /// use std::ffi::CStr;
+    ///
+    /// # fn main() {
+    /// let cstr = CStr::from_bytes(b"hello\0");
+    /// assert!(cstr.is_some());
+    /// # }
+    /// ```
+    #[unstable(feature = "cstr_from_bytes", reason = "recently added", issue = "0")]
+    pub fn from_bytes<'a>(bytes: &'a [u8]) -> Option<&'a CStr> {
+        if bytes.is_empty() || memchr::memchr(0, &bytes) != Some(bytes.len() - 1) {
+            None
+        } else {
+            Some(unsafe { Self::from_bytes_unchecked(bytes) })
+        }
+    }
+
+    /// Unsafely creates a C string wrapper from a byte slice.
+    ///
+    /// This function will cast the provided `bytes` to a `CStr` wrapper without
+    /// performing any sanity checks. The provided slice must be null terminated
+    /// and not contain any interior nul bytes.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #![feature(cstr_from_bytes)]
+    /// use std::ffi::{CStr, CString};
+    ///
+    /// # fn main() {
+    /// unsafe {
+    ///     let cstring = CString::new("hello").unwrap();
+    ///     let cstr = CStr::from_bytes_unchecked(cstring.to_bytes_with_nul());
+    ///     assert_eq!(cstr, &*cstring);
+    /// }
+    /// # }
+    /// ```
+    #[unstable(feature = "cstr_from_bytes", reason = "recently added", issue = "0")]
+    pub unsafe fn from_bytes_unchecked<'a>(bytes: &'a [u8]) -> &'a CStr {
+        mem::transmute(bytes)
+    }
+
     /// Returns the inner pointer to this C string.
     ///
     /// The returned pointer will be valid for as long as `self` is and points