/// }
/// # }
/// ```
+///
+/// # 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 {
/// An error returned from `CString::into_string` to indicate that a UTF-8 error
/// was encountered during the conversion.
#[derive(Clone, PartialEq, Debug)]
-#[unstable(feature = "cstring_into", reason = "recently added", issue = "29157")]
+#[stable(feature = "cstring_into", since = "1.7.0")]
pub struct IntoStringError {
inner: CString,
error: Utf8Error,
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
/// Converts the `CString` into a `String` if it contains valid Unicode data.
///
/// On failure, ownership of the original `CString` is returned.
- #[unstable(feature = "cstring_into", reason = "recently added", issue = "29157")]
+ #[stable(feature = "cstring_into", since = "1.7.0")]
pub fn into_string(self) -> Result<String, IntoStringError> {
String::from_utf8(self.into_bytes())
.map_err(|e| IntoStringError {
///
/// The returned buffer does **not** contain the trailing nul separator and
/// it is guaranteed to not have any interior nul bytes.
- #[unstable(feature = "cstring_into", reason = "recently added", issue = "29157")]
+ #[stable(feature = "cstring_into", since = "1.7.0")]
pub fn into_bytes(self) -> Vec<u8> {
- // FIXME: Once this method becomes stable, add an `impl Into<Vec<u8>> for CString`
let mut vec = self.inner.into_vec();
let _nul = vec.pop();
debug_assert_eq!(_nul, Some(0u8));
/// Equivalent to the `into_bytes` function except that the returned vector
/// includes the trailing nul byte.
- #[unstable(feature = "cstring_into", reason = "recently added", issue = "29157")]
+ #[stable(feature = "cstring_into", since = "1.7.0")]
pub fn into_bytes_with_nul(self) -> Vec<u8> {
self.inner.into_vec()
}
}
}
+#[stable(feature = "cstring_into", since = "1.7.0")]
+impl From<CString> for Vec<u8> {
+ fn from(s: CString) -> Vec<u8> {
+ s.into_bytes()
+ }
+}
+
#[stable(feature = "cstr_debug", since = "1.3.0")]
impl fmt::Debug for CStr {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
impl IntoStringError {
/// Consumes this error, returning original `CString` which generated the
/// error.
- #[unstable(feature = "cstring_into", reason = "recently added", issue = "29157")]
+ #[stable(feature = "cstring_into", since = "1.7.0")]
pub fn into_cstring(self) -> CString {
self.inner
}
/// Access the underlying UTF-8 error that was the cause of this error.
- #[unstable(feature = "cstring_into", reason = "recently added", issue = "29157")]
+ #[stable(feature = "cstring_into", since = "1.7.0")]
pub fn utf8_error(&self) -> Utf8Error {
self.error
}
}
-#[unstable(feature = "cstring_into", reason = "recently added", issue = "29157")]
+#[stable(feature = "cstring_into", since = "1.7.0")]
impl Error for IntoStringError {
fn description(&self) -> &str {
- Error::description(&self.error)
+ "C string contained non-utf8 bytes"
+ }
+
+ fn cause(&self) -> Option<&Error> {
+ Some(&self.error)
}
}
-#[unstable(feature = "cstring_into", reason = "recently added", issue = "29157")]
+#[stable(feature = "cstring_into", since = "1.7.0")]
impl fmt::Display for IntoStringError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
- fmt::Display::fmt(&self.error, f)
+ self.description().fmt(f)
}
}
/// # fn main() {
/// use std::ffi::CStr;
/// use std::os::raw::c_char;
- /// use std::str;
///
/// extern {
/// fn my_string() -> *const c_char;
///
/// unsafe {
/// let slice = CStr::from_ptr(my_string());
- /// println!("string returned: {}",
- /// str::from_utf8(slice.to_bytes()).unwrap());
+ /// println!("string returned: {}", slice.to_str().unwrap());
/// }
/// # }
/// ```
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 and does not contain any interior
+ /// nul bytes.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// # #![feature(cstr_from_bytes)]
+ /// use std::ffi::CStr;
+ ///
+ /// # fn main() {
+ /// let cstr = CStr::from_bytes_with_nul(b"hello\0");
+ /// assert!(cstr.is_some());
+ /// # }
+ /// ```
+ #[unstable(feature = "cstr_from_bytes", reason = "recently added", issue = "31190")]
+ pub fn from_bytes_with_nul(bytes: &[u8]) -> Option<&CStr> {
+ if bytes.is_empty() || memchr::memchr(0, &bytes) != Some(bytes.len() - 1) {
+ None
+ } else {
+ Some(unsafe { Self::from_bytes_with_nul_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_with_nul_unchecked(cstring.to_bytes_with_nul());
+ /// assert_eq!(cstr, &*cstring);
+ /// }
+ /// # }
+ /// ```
+ #[unstable(feature = "cstr_from_bytes", reason = "recently added", issue = "31190")]
+ pub unsafe fn from_bytes_with_nul_unchecked(bytes: &[u8]) -> &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
assert_eq!(cstr_hash, cstring_hash);
}
+
+ #[test]
+ fn from_bytes_with_nul() {
+ let data = b"123\0";
+ let cstr = CStr::from_bytes_with_nul(data);
+ assert_eq!(cstr.map(CStr::to_bytes), Some(&b"123"[..]));
+ assert_eq!(cstr.map(CStr::to_bytes_with_nul), Some(&b"123\0"[..]));
+
+ unsafe {
+ let cstr_unchecked = CStr::from_bytes_with_nul_unchecked(data);
+ assert_eq!(cstr, Some(cstr_unchecked));
+ }
+ }
+
+ #[test]
+ fn from_bytes_with_nul_unterminated() {
+ let data = b"123";
+ let cstr = CStr::from_bytes_with_nul(data);
+ assert!(cstr.is_none());
+ }
+
+ #[test]
+ fn from_bytes_with_nul_interior() {
+ let data = b"1\023\0";
+ let cstr = CStr::from_bytes_with_nul(data);
+ assert!(cstr.is_none());
+ }
}
projects / rust.git / blobdiff