+#![deny(unsafe_op_in_unsafe_fn)]
use crate::ascii;
use crate::borrow::{Borrow, Cow};
use crate::cmp::Ordering;
/// 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
/// [`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
/// 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
///
/// 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 {
///
/// 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
///
/// 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:
/// 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
///
/// ```
/// 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
///
/// ```
/// 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
///
/// ```
///
/// assert_eq!(&bytes[..], value.unwrap_err().as_bytes());
/// ```
- ///
- /// [`CString`]: struct.CString.html
pub fn as_bytes(&self) -> &[u8] {
&self.bytes[..]
}
///
/// assert_eq!(bytes, value.unwrap_err().into_bytes());
/// ```
- ///
- /// [`CString`]: struct.CString.html
pub fn into_bytes(self) -> Vec<u8> {
self.bytes
}
/// 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 [`CString::into_string()`]. 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 {
/// 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 {
/// 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
///
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
/// > 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
/// ```
#[stable(feature = "cstr_memory", since = "1.4.0")]
pub unsafe fn from_raw(ptr: *mut c_char) -> CString {
- let len = sys::strlen(ptr) + 1; // Including the NUL byte
- let slice = slice::from_raw_parts_mut(ptr, len as usize);
- CString { inner: Box::from_raw(slice as *mut [c_char] as *mut [u8]) }
+ // SAFETY: This is called with a pointer that was obtained from a call
+ // to `CString::into_raw` and the length has not been modified. As such,
+ // we know there is a NUL byte (and only one) at the end and that the
+ // information about the size of the allocation is correct on Rust's
+ // side.
+ unsafe {
+ let len = sys::strlen(ptr) + 1; // Including the NUL byte
+ let slice = slice::from_raw_parts_mut(ptr, len as usize);
+ CString { inner: Box::from_raw(slice as *mut [c_char] as *mut [u8]) }
+ }
}
/// 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
///
///
/// On failure, ownership of the original `CString` is returned.
///
- /// [`String`]: ../string/struct.String.html
- ///
/// # Examples
///
/// ```
vec
}
- /// Equivalent to the [`into_bytes`] function except that the returned vector
- /// includes the trailing nul terminator.
- ///
- /// [`into_bytes`]: #method.into_bytes
+ /// Equivalent to [`CString::into_bytes()`] except that the
+ /// returned vector includes the trailing nul terminator.
///
/// # Examples
///
/// 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
///
&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 [`CString::as_bytes()`] except that the
+ /// returned slice includes the trailing nul terminator.
///
/// # Examples
///
/// Extracts a [`CStr`] slice containing the entire string.
///
- /// [`CStr`]: struct.CStr.html
- ///
/// # Examples
///
/// ```
/// Converts this `CString` into a boxed [`CStr`].
///
- /// [`CStr`]: struct.CStr.html
- ///
/// # Examples
///
/// ```
}
/// 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.
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
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
///
///
/// # 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)]
/// );
/// ```
///
- /// A incorrectly formatted vector will produce an error.
+ /// A incorrectly formatted [`Vec`] will produce an error.
///
/// ```
/// #![feature(cstring_from_vec_with_nul)]
/// // 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);
/// 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()
#[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()
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 {
#[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()
#[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());
#[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());
/// Returns the position of the nul byte in the slice that caused
/// [`CString::new`] to fail.
///
- /// [`CString::new`]: struct.CString.html#method.new
- ///
/// # Examples
///
/// ```
#[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")
}
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
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub unsafe fn from_ptr<'a>(ptr: *const c_char) -> &'a CStr {
- let len = sys::strlen(ptr);
- let ptr = ptr as *const u8;
- CStr::from_bytes_with_nul_unchecked(slice::from_raw_parts(ptr, len as usize + 1))
+ // SAFETY: The caller has provided a pointer that points to a valid C
+ // string with a NUL terminator of size less than `isize::MAX`, whose
+ // content remain valid and doesn't change for the lifetime of the
+ // returned `CStr`.
+ //
+ // Thus computing the length is fine (a NUL byte exists), the call to
+ // from_raw_parts is safe because we know the length is at most `isize::MAX`, meaning
+ // the call to `from_bytes_with_nul_unchecked` is correct.
+ //
+ // The cast from c_char to u8 is ok because a c_char is always one byte.
+ unsafe {
+ let len = sys::strlen(ptr);
+ let ptr = ptr as *const u8;
+ CStr::from_bytes_with_nul_unchecked(slice::from_raw_parts(ptr, len as usize + 1))
+ }
}
/// Creates a C string wrapper from a byte slice.
#[stable(feature = "cstr_from_bytes", since = "1.10.0")]
#[rustc_const_unstable(feature = "const_cstr_unchecked", issue = "none")]
pub const unsafe fn from_bytes_with_nul_unchecked(bytes: &[u8]) -> &CStr {
- &*(bytes as *const [u8] as *const CStr)
+ // SAFETY: Casting to CStr is safe because its internal representation
+ // is a [u8] too (safe only inside std).
+ // Dereferencing the obtained pointer is safe because it comes from a
+ // reference. Making a reference is then safe because its lifetime
+ // is bound by the lifetime of the given `bytes`.
+ unsafe { &*(bytes as *const [u8] as *const CStr) }
}
/// Returns the inner pointer to this C string.
///
/// 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
/// }
/// ```
///
- /// 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")]
/// 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
///
/// ```
/// 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
///
/// [`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
///
/// Converts a [`Box`]`<CStr>` into a [`CString`] without copying or allocating.
///
- /// [`Box`]: ../boxed/struct.Box.html
- /// [`CString`]: struct.CString.html
- ///
/// # Examples
///
/// ```
projects / rust.git / blobdiff