1//! [`CString`] and its related types.
2
3use core::borrow::Borrow;
4use core::ffi::{CStr, c_char};
5use core::num::NonZero;
6use core::slice::memchr;
7use core::str::{self, FromStr, Utf8Error};
8use core::{fmt, mem, ops, ptr, slice};
9
10use crate::borrow::{Cow, ToOwned};
11use crate::boxed::Box;
12use crate::rc::Rc;
13use crate::string::String;
14#[cfg(target_has_atomic = "ptr")]
15use crate::sync::Arc;
16use crate::vec::Vec;
17
18/// A type representing an owned, C-compatible, nul-terminated string with no nul bytes in the
19/// middle.
20///
21/// This type serves the purpose of being able to safely generate a
22/// C-compatible string from a Rust byte slice or vector. An instance of this
23/// type is a static guarantee that the underlying bytes contain no interior 0
24/// bytes ("nul characters") and that the final byte is 0 ("nul terminator").
25///
26/// `CString` is to <code>&[CStr]</code> as [`String`] is to <code>&[str]</code>: the former
27/// in each pair are owned strings; the latter are borrowed
28/// references.
29///
30/// # Creating a `CString`
31///
32/// A `CString` is created from either a byte slice or a byte vector,
33/// or anything that implements <code>[Into]<[Vec]<[u8]>></code> (for
34/// example, you can build a `CString` straight out of a [`String`] or
35/// a <code>&[str]</code>, since both implement that trait).
36/// You can create a `CString` from a literal with `CString::from(c"Text")`.
37///
38/// The [`CString::new`] method will actually check that the provided <code>&[[u8]]</code>
39/// does not have 0 bytes in the middle, and return an error if it
40/// finds one.
41///
42/// # Extracting a raw pointer to the whole C string
43///
44/// `CString` implements an [`as_ptr`][`CStr::as_ptr`] method through the [`Deref`]
45/// trait. This method will give you a `*const c_char` which you can
46/// feed directly to extern functions that expect a nul-terminated
47/// string, like C's `strdup()`. Notice that [`as_ptr`][`CStr::as_ptr`] returns a
48/// read-only pointer; if the C code writes to it, that causes
49/// undefined behavior.
50///
51/// # Extracting a slice of the whole C string
52///
53/// Alternatively, you can obtain a <code>&[[u8]]</code> slice from a
54/// `CString` with the [`CString::as_bytes`] method. Slices produced in this
55/// way do *not* contain the trailing nul terminator. This is useful
56/// when you will be calling an extern function that takes a `*const
57/// u8` argument which is not necessarily nul-terminated, plus another
58/// argument with the length of the string — like C's `strndup()`.
59/// You can of course get the slice's length with its
60/// [`len`][slice::len] method.
61///
62/// If you need a <code>&[[u8]]</code> slice *with* the nul terminator, you
63/// can use [`CString::as_bytes_with_nul`] instead.
64///
65/// Once you have the kind of slice you need (with or without a nul
66/// terminator), you can call the slice's own
67/// [`as_ptr`][slice::as_ptr] method to get a read-only raw pointer to pass to
68/// extern functions. See the documentation for that function for a
69/// discussion on ensuring the lifetime of the raw pointer.
70///
71/// [str]: prim@str "str"
72/// [`Deref`]: ops::Deref
73///
74/// # Examples
75///
76/// ```ignore (extern-declaration)
77/// # fn main() {
78/// use std::ffi::CString;
79/// use std::os::raw::c_char;
80///
81/// extern "C" {
82/// fn my_printer(s: *const c_char);
83/// }
84///
85/// // We are certain that our string doesn't have 0 bytes in the middle,
86/// // so we can .expect()
87/// let c_to_print = CString::new("Hello, world!").expect("CString::new failed");
88/// unsafe {
89/// my_printer(c_to_print.as_ptr());
90/// }
91/// # }
92/// ```
93///
94/// # Safety
95///
96/// `CString` is intended for working with traditional C-style strings
97/// (a sequence of non-nul bytes terminated by a single nul byte); the
98/// primary use case for these kinds of strings is interoperating with C-like
99/// code. Often you will need to transfer ownership to/from that external
100/// code. It is strongly recommended that you thoroughly read through the
101/// documentation of `CString` before use, as improper ownership management
102/// of `CString` instances can lead to invalid memory accesses, memory leaks,
103/// and other memory errors.
104#[derive(PartialEq, PartialOrd, Eq, Ord, Hash, Clone)]
105#[rustc_diagnostic_item = "cstring_type"]
106#[stable(feature = "alloc_c_string", since = "1.64.0")]
107pub struct CString {
108 // Invariant 1: the slice ends with a zero byte and has a length of at least one.
109 // Invariant 2: the slice contains only one zero byte.
110 // Improper usage of unsafe function can break Invariant 2, but not Invariant 1.
111 inner: Box<[u8]>,
112}
113
114/// An error indicating that an interior nul byte was found.
115///
116/// While Rust strings may contain nul bytes in the middle, C strings
117/// can't, as that byte would effectively truncate the string.
118///
119/// This error is created by the [`new`][`CString::new`] method on
120/// [`CString`]. See its documentation for more.
121///
122/// # Examples
123///
124/// ```
125/// use std::ffi::{CString, NulError};
126///
127/// let _: NulError = CString::new(b"f\0oo".to_vec()).unwrap_err();
128/// ```
129#[derive(Clone, PartialEq, Eq, Debug)]
130#[stable(feature = "alloc_c_string", since = "1.64.0")]
131pub struct NulError(usize, Vec<u8>);
132
133#[derive(Clone, PartialEq, Eq, Debug)]
134enum FromBytesWithNulErrorKind {
135 InteriorNul(usize),
136 NotNulTerminated,
137}
138
139/// An error indicating that a nul byte was not in the expected position.
140///
141/// The vector used to create a [`CString`] must have one and only one nul byte,
142/// positioned at the end.
143///
144/// This error is created by the [`CString::from_vec_with_nul`] method.
145/// See its documentation for more.
146///
147/// # Examples
148///
149/// ```
150/// use std::ffi::{CString, FromVecWithNulError};
151///
152/// let _: FromVecWithNulError = CString::from_vec_with_nul(b"f\0oo".to_vec()).unwrap_err();
153/// ```
154#[derive(Clone, PartialEq, Eq, Debug)]
155#[stable(feature = "alloc_c_string", since = "1.64.0")]
156pub struct FromVecWithNulError {
157 error_kind: FromBytesWithNulErrorKind,
158 bytes: Vec<u8>,
159}
160
161#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
162impl FromVecWithNulError {
163 /// Returns a slice of [`u8`]s bytes that were attempted to convert to a [`CString`].
164 ///
165 /// # Examples
166 ///
167 /// Basic usage:
168 ///
169 /// ```
170 /// use std::ffi::CString;
171 ///
172 /// // Some invalid bytes in a vector
173 /// let bytes = b"f\0oo".to_vec();
174 ///
175 /// let value = CString::from_vec_with_nul(bytes.clone());
176 ///
177 /// assert_eq!(&bytes[..], value.unwrap_err().as_bytes());
178 /// ```
179 #[must_use]
180 #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
181 pub fn as_bytes(&self) -> &[u8] {
182 &self.bytes[..]
183 }
184
185 /// Returns the bytes that were attempted to convert to a [`CString`].
186 ///
187 /// This method is carefully constructed to avoid allocation. It will
188 /// consume the error, moving out the bytes, so that a copy of the bytes
189 /// does not need to be made.
190 ///
191 /// # Examples
192 ///
193 /// Basic usage:
194 ///
195 /// ```
196 /// use std::ffi::CString;
197 ///
198 /// // Some invalid bytes in a vector
199 /// let bytes = b"f\0oo".to_vec();
200 ///
201 /// let value = CString::from_vec_with_nul(bytes.clone());
202 ///
203 /// assert_eq!(bytes, value.unwrap_err().into_bytes());
204 /// ```
205 #[must_use = "`self` will be dropped if the result is not used"]
206 #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
207 pub fn into_bytes(self) -> Vec<u8> {
208 self.bytes
209 }
210}
211
212/// An error indicating invalid UTF-8 when converting a [`CString`] into a [`String`].
213///
214/// `CString` is just a wrapper over a buffer of bytes with a nul terminator;
215/// [`CString::into_string`] performs UTF-8 validation on those bytes and may
216/// return this error.
217///
218/// This `struct` is created by [`CString::into_string()`]. See
219/// its documentation for more.
220#[derive(Clone, PartialEq, Eq, Debug)]
221#[stable(feature = "alloc_c_string", since = "1.64.0")]
222pub struct IntoStringError {
223 inner: CString,
224 error: Utf8Error,
225}
226
227impl CString {
228 /// Creates a new C-compatible string from a container of bytes.
229 ///
230 /// This function will consume the provided data and use the
231 /// underlying bytes to construct a new string, ensuring that
232 /// there is a trailing 0 byte. This trailing 0 byte will be
233 /// appended by this function; the provided data should *not*
234 /// contain any 0 bytes in it.
235 ///
236 /// # Examples
237 ///
238 /// ```ignore (extern-declaration)
239 /// use std::ffi::CString;
240 /// use std::os::raw::c_char;
241 ///
242 /// extern "C" { fn puts(s: *const c_char); }
243 ///
244 /// let to_print = CString::new("Hello!").expect("CString::new failed");
245 /// unsafe {
246 /// puts(to_print.as_ptr());
247 /// }
248 /// ```
249 ///
250 /// # Errors
251 ///
252 /// This function will return an error if the supplied bytes contain an
253 /// internal 0 byte. The [`NulError`] returned will contain the bytes as well as
254 /// the position of the nul byte.
255 #[stable(feature = "rust1", since = "1.0.0")]
256 pub fn new<T: Into<Vec<u8>>>(t: T) -> Result<CString, NulError> {
257 trait SpecNewImpl {
258 fn spec_new_impl(self) -> Result<CString, NulError>;
259 }
260
261 impl<T: Into<Vec<u8>>> SpecNewImpl for T {
262 default fn spec_new_impl(self) -> Result<CString, NulError> {
263 let bytes: Vec<u8> = self.into();
264 match memchr::memchr(0, &bytes) {
265 Some(i) => Err(NulError(i, bytes)),
266 None => Ok(unsafe { CString::_from_vec_unchecked(bytes) }),
267 }
268 }
269 }
270
271 // Specialization for avoiding reallocation
272 #[inline(always)] // Without that it is not inlined into specializations
273 fn spec_new_impl_bytes(bytes: &[u8]) -> Result<CString, NulError> {
274 // We cannot have such large slice that we would overflow here
275 // but using `checked_add` allows LLVM to assume that capacity never overflows
276 // and generate twice shorter code.
277 // `saturating_add` doesn't help for some reason.
278 let capacity = bytes.len().checked_add(1).unwrap();
279
280 // Allocate before validation to avoid duplication of allocation code.
281 // We still need to allocate and copy memory even if we get an error.
282 let mut buffer = Vec::with_capacity(capacity);
283 buffer.extend(bytes);
284
285 // Check memory of self instead of new buffer.
286 // This allows better optimizations if lto enabled.
287 match memchr::memchr(0, bytes) {
288 Some(i) => Err(NulError(i, buffer)),
289 None => Ok(unsafe { CString::_from_vec_unchecked(buffer) }),
290 }
291 }
292
293 impl SpecNewImpl for &'_ [u8] {
294 fn spec_new_impl(self) -> Result<CString, NulError> {
295 spec_new_impl_bytes(self)
296 }
297 }
298
299 impl SpecNewImpl for &'_ str {
300 fn spec_new_impl(self) -> Result<CString, NulError> {
301 spec_new_impl_bytes(self.as_bytes())
302 }
303 }
304
305 impl SpecNewImpl for &'_ mut [u8] {
306 fn spec_new_impl(self) -> Result<CString, NulError> {
307 spec_new_impl_bytes(self)
308 }
309 }
310
311 t.spec_new_impl()
312 }
313
314 /// Creates a C-compatible string by consuming a byte vector,
315 /// without checking for interior 0 bytes.
316 ///
317 /// Trailing 0 byte will be appended by this function.
318 ///
319 /// This method is equivalent to [`CString::new`] except that no runtime
320 /// assertion is made that `v` contains no 0 bytes, and it requires an
321 /// actual byte vector, not anything that can be converted to one with Into.
322 ///
323 /// # Examples
324 ///
325 /// ```
326 /// use std::ffi::CString;
327 ///
328 /// let raw = b"foo".to_vec();
329 /// unsafe {
330 /// let c_string = CString::from_vec_unchecked(raw);
331 /// }
332 /// ```
333 #[must_use]
334 #[stable(feature = "rust1", since = "1.0.0")]
335 pub unsafe fn from_vec_unchecked(v: Vec<u8>) -> Self {
336 debug_assert!(memchr::memchr(0, &v).is_none());
337 unsafe { Self::_from_vec_unchecked(v) }
338 }
339
340 unsafe fn _from_vec_unchecked(mut v: Vec<u8>) -> Self {
341 v.reserve_exact(1);
342 v.push(0);
343 Self { inner: v.into_boxed_slice() }
344 }
345
346 /// Retakes ownership of a `CString` that was transferred to C via
347 /// [`CString::into_raw`].
348 ///
349 /// Additionally, the length of the string will be recalculated from the pointer.
350 ///
351 /// # Safety
352 ///
353 /// This should only ever be called with a pointer that was earlier
354 /// obtained by calling [`CString::into_raw`]. Other usage (e.g., trying to take
355 /// ownership of a string that was allocated by foreign code) is likely to lead
356 /// to undefined behavior or allocator corruption.
357 ///
358 /// It should be noted that the length isn't just "recomputed," but that
359 /// the recomputed length must match the original length from the
360 /// [`CString::into_raw`] call. This means the [`CString::into_raw`]/`from_raw`
361 /// methods should not be used when passing the string to C functions that can
362 /// modify the string's length.
363 ///
364 /// > **Note:** If you need to borrow a string that was allocated by
365 /// > foreign code, use [`CStr`]. If you need to take ownership of
366 /// > a string that was allocated by foreign code, you will need to
367 /// > make your own provisions for freeing it appropriately, likely
368 /// > with the foreign code's API to do that.
369 ///
370 /// # Examples
371 ///
372 /// Creates a `CString`, pass ownership to an `extern` function (via raw pointer), then retake
373 /// ownership with `from_raw`:
374 ///
375 /// ```ignore (extern-declaration)
376 /// use std::ffi::CString;
377 /// use std::os::raw::c_char;
378 ///
379 /// extern "C" {
380 /// fn some_extern_function(s: *mut c_char);
381 /// }
382 ///
383 /// let c_string = CString::from(c"Hello!");
384 /// let raw = c_string.into_raw();
385 /// unsafe {
386 /// some_extern_function(raw);
387 /// let c_string = CString::from_raw(raw);
388 /// }
389 /// ```
390 #[must_use = "call `drop(from_raw(ptr))` if you intend to drop the `CString`"]
391 #[stable(feature = "cstr_memory", since = "1.4.0")]
392 pub unsafe fn from_raw(ptr: *mut c_char) -> CString {
393 // SAFETY: This is called with a pointer that was obtained from a call
394 // to `CString::into_raw` and the length has not been modified. As such,
395 // we know there is a NUL byte (and only one) at the end and that the
396 // information about the size of the allocation is correct on Rust's
397 // side.
398 unsafe {
399 unsafe extern "C" {
400 /// Provided by libc or compiler_builtins.
401 fn strlen(s: *const c_char) -> usize;
402 }
403 let len = strlen(ptr) + 1; // Including the NUL byte
404 let slice = slice::from_raw_parts_mut(ptr, len);
405 CString { inner: Box::from_raw(slice as *mut [c_char] as *mut [u8]) }
406 }
407 }
408
409 /// Consumes the `CString` and transfers ownership of the string to a C caller.
410 ///
411 /// The pointer which this function returns must be returned to Rust and reconstituted using
412 /// [`CString::from_raw`] to be properly deallocated. Specifically, one
413 /// should *not* use the standard C `free()` function to deallocate
414 /// this string.
415 ///
416 /// Failure to call [`CString::from_raw`] will lead to a memory leak.
417 ///
418 /// The C side must **not** modify the length of the string (by writing a
419 /// nul byte somewhere inside the string or removing the final one) before
420 /// it makes it back into Rust using [`CString::from_raw`]. See the safety section
421 /// in [`CString::from_raw`].
422 ///
423 /// # Examples
424 ///
425 /// ```
426 /// use std::ffi::CString;
427 ///
428 /// let c_string = CString::from(c"foo");
429 ///
430 /// let ptr = c_string.into_raw();
431 ///
432 /// unsafe {
433 /// assert_eq!(b'f', *ptr as u8);
434 /// assert_eq!(b'o', *ptr.add(1) as u8);
435 /// assert_eq!(b'o', *ptr.add(2) as u8);
436 /// assert_eq!(b'\0', *ptr.add(3) as u8);
437 ///
438 /// // retake pointer to free memory
439 /// let _ = CString::from_raw(ptr);
440 /// }
441 /// ```
442 #[inline]
443 #[must_use = "`self` will be dropped if the result is not used"]
444 #[stable(feature = "cstr_memory", since = "1.4.0")]
445 pub fn into_raw(self) -> *mut c_char {
446 Box::into_raw(self.into_inner()) as *mut c_char
447 }
448
449 /// Converts the `CString` into a [`String`] if it contains valid UTF-8 data.
450 ///
451 /// On failure, ownership of the original `CString` is returned.
452 ///
453 /// # Examples
454 ///
455 /// ```
456 /// use std::ffi::CString;
457 ///
458 /// let valid_utf8 = vec![b'f', b'o', b'o'];
459 /// let cstring = CString::new(valid_utf8).expect("CString::new failed");
460 /// assert_eq!(cstring.into_string().expect("into_string() call failed"), "foo");
461 ///
462 /// let invalid_utf8 = vec![b'f', 0xff, b'o', b'o'];
463 /// let cstring = CString::new(invalid_utf8).expect("CString::new failed");
464 /// let err = cstring.into_string().err().expect("into_string().err() failed");
465 /// assert_eq!(err.utf8_error().valid_up_to(), 1);
466 /// ```
467 #[stable(feature = "cstring_into", since = "1.7.0")]
468 pub fn into_string(self) -> Result<String, IntoStringError> {
469 String::from_utf8(self.into_bytes()).map_err(|e| IntoStringError {
470 error: e.utf8_error(),
471 inner: unsafe { Self::_from_vec_unchecked(e.into_bytes()) },
472 })
473 }
474
475 /// Consumes the `CString` and returns the underlying byte buffer.
476 ///
477 /// The returned buffer does **not** contain the trailing nul
478 /// terminator, and it is guaranteed to not have any interior nul
479 /// bytes.
480 ///
481 /// # Examples
482 ///
483 /// ```
484 /// use std::ffi::CString;
485 ///
486 /// let c_string = CString::from(c"foo");
487 /// let bytes = c_string.into_bytes();
488 /// assert_eq!(bytes, vec![b'f', b'o', b'o']);
489 /// ```
490 #[must_use = "`self` will be dropped if the result is not used"]
491 #[stable(feature = "cstring_into", since = "1.7.0")]
492 pub fn into_bytes(self) -> Vec<u8> {
493 let mut vec = self.into_inner().into_vec();
494 let _nul = vec.pop();
495 debug_assert_eq!(_nul, Some(0u8));
496 vec
497 }
498
499 /// Equivalent to [`CString::into_bytes()`] except that the
500 /// returned vector includes the trailing nul terminator.
501 ///
502 /// # Examples
503 ///
504 /// ```
505 /// use std::ffi::CString;
506 ///
507 /// let c_string = CString::from(c"foo");
508 /// let bytes = c_string.into_bytes_with_nul();
509 /// assert_eq!(bytes, vec![b'f', b'o', b'o', b'\0']);
510 /// ```
511 #[must_use = "`self` will be dropped if the result is not used"]
512 #[stable(feature = "cstring_into", since = "1.7.0")]
513 pub fn into_bytes_with_nul(self) -> Vec<u8> {
514 self.into_inner().into_vec()
515 }
516
517 /// Returns the contents of this `CString` as a slice of bytes.
518 ///
519 /// The returned slice does **not** contain the trailing nul
520 /// terminator, and it is guaranteed to not have any interior nul
521 /// bytes. If you need the nul terminator, use
522 /// [`CString::as_bytes_with_nul`] instead.
523 ///
524 /// # Examples
525 ///
526 /// ```
527 /// use std::ffi::CString;
528 ///
529 /// let c_string = CString::from(c"foo");
530 /// let bytes = c_string.as_bytes();
531 /// assert_eq!(bytes, &[b'f', b'o', b'o']);
532 /// ```
533 #[inline]
534 #[must_use]
535 #[stable(feature = "rust1", since = "1.0.0")]
536 pub fn as_bytes(&self) -> &[u8] {
537 // SAFETY: CString has a length at least 1
538 unsafe { self.inner.get_unchecked(..self.inner.len() - 1) }
539 }
540
541 /// Equivalent to [`CString::as_bytes()`] except that the
542 /// returned slice includes the trailing nul terminator.
543 ///
544 /// # Examples
545 ///
546 /// ```
547 /// use std::ffi::CString;
548 ///
549 /// let c_string = CString::from(c"foo");
550 /// let bytes = c_string.as_bytes_with_nul();
551 /// assert_eq!(bytes, &[b'f', b'o', b'o', b'\0']);
552 /// ```
553 #[inline]
554 #[must_use]
555 #[stable(feature = "rust1", since = "1.0.0")]
556 pub fn as_bytes_with_nul(&self) -> &[u8] {
557 &self.inner
558 }
559
560 /// Extracts a [`CStr`] slice containing the entire string.
561 ///
562 /// # Examples
563 ///
564 /// ```
565 /// use std::ffi::{CString, CStr};
566 ///
567 /// let c_string = CString::from(c"foo");
568 /// let cstr = c_string.as_c_str();
569 /// assert_eq!(cstr,
570 /// CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"));
571 /// ```
572 #[inline]
573 #[must_use]
574 #[stable(feature = "as_c_str", since = "1.20.0")]
575 #[rustc_diagnostic_item = "cstring_as_c_str"]
576 pub fn as_c_str(&self) -> &CStr {
577 &*self
578 }
579
580 /// Converts this `CString` into a boxed [`CStr`].
581 ///
582 /// # Examples
583 ///
584 /// ```
585 /// let c_string = c"foo".to_owned();
586 /// let boxed = c_string.into_boxed_c_str();
587 /// assert_eq!(boxed.to_bytes_with_nul(), b"foo\0");
588 /// ```
589 #[must_use = "`self` will be dropped if the result is not used"]
590 #[stable(feature = "into_boxed_c_str", since = "1.20.0")]
591 pub fn into_boxed_c_str(self) -> Box<CStr> {
592 unsafe { Box::from_raw(Box::into_raw(self.into_inner()) as *mut CStr) }
593 }
594
595 /// Bypass "move out of struct which implements [`Drop`] trait" restriction.
596 #[inline]
597 fn into_inner(self) -> Box<[u8]> {
598 // Rationale: `mem::forget(self)` invalidates the previous call to `ptr::read(&self.inner)`
599 // so we use `ManuallyDrop` to ensure `self` is not dropped.
600 // Then we can return the box directly without invalidating it.
601 // See https://github.com/rust-lang/rust/issues/62553.
602 let this = mem::ManuallyDrop::new(self);
603 unsafe { ptr::read(&this.inner) }
604 }
605
606 /// Converts a <code>[Vec]<[u8]></code> to a [`CString`] without checking the
607 /// invariants on the given [`Vec`].
608 ///
609 /// # Safety
610 ///
611 /// The given [`Vec`] **must** have one nul byte as its last element.
612 /// This means it cannot be empty nor have any other nul byte anywhere else.
613 ///
614 /// # Example
615 ///
616 /// ```
617 /// use std::ffi::CString;
618 /// assert_eq!(
619 /// unsafe { CString::from_vec_with_nul_unchecked(b"abc\0".to_vec()) },
620 /// unsafe { CString::from_vec_unchecked(b"abc".to_vec()) }
621 /// );
622 /// ```
623 #[must_use]
624 #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
625 pub unsafe fn from_vec_with_nul_unchecked(v: Vec<u8>) -> Self {
626 debug_assert!(memchr::memchr(0, &v).unwrap() + 1 == v.len());
627 unsafe { Self::_from_vec_with_nul_unchecked(v) }
628 }
629
630 unsafe fn _from_vec_with_nul_unchecked(v: Vec<u8>) -> Self {
631 Self { inner: v.into_boxed_slice() }
632 }
633
634 /// Attempts to converts a <code>[Vec]<[u8]></code> to a [`CString`].
635 ///
636 /// Runtime checks are present to ensure there is only one nul byte in the
637 /// [`Vec`], its last element.
638 ///
639 /// # Errors
640 ///
641 /// If a nul byte is present and not the last element or no nul bytes
642 /// is present, an error will be returned.
643 ///
644 /// # Examples
645 ///
646 /// A successful conversion will produce the same result as [`CString::new`]
647 /// when called without the ending nul byte.
648 ///
649 /// ```
650 /// use std::ffi::CString;
651 /// assert_eq!(
652 /// CString::from_vec_with_nul(b"abc\0".to_vec())
653 /// .expect("CString::from_vec_with_nul failed"),
654 /// c"abc".to_owned()
655 /// );
656 /// ```
657 ///
658 /// An incorrectly formatted [`Vec`] will produce an error.
659 ///
660 /// ```
661 /// use std::ffi::{CString, FromVecWithNulError};
662 /// // Interior nul byte
663 /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"a\0bc".to_vec()).unwrap_err();
664 /// // No nul byte
665 /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"abc".to_vec()).unwrap_err();
666 /// ```
667 #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
668 pub fn from_vec_with_nul(v: Vec<u8>) -> Result<Self, FromVecWithNulError> {
669 let nul_pos = memchr::memchr(0, &v);
670 match nul_pos {
671 Some(nul_pos) if nul_pos + 1 == v.len() => {
672 // SAFETY: We know there is only one nul byte, at the end
673 // of the vec.
674 Ok(unsafe { Self::_from_vec_with_nul_unchecked(v) })
675 }
676 Some(nul_pos) => Err(FromVecWithNulError {
677 error_kind: FromBytesWithNulErrorKind::InteriorNul(nul_pos),
678 bytes: v,
679 }),
680 None => Err(FromVecWithNulError {
681 error_kind: FromBytesWithNulErrorKind::NotNulTerminated,
682 bytes: v,
683 }),
684 }
685 }
686}
687
688// Turns this `CString` into an empty string to prevent
689// memory-unsafe code from working by accident. Inline
690// to prevent LLVM from optimizing it away in debug builds.
691#[stable(feature = "cstring_drop", since = "1.13.0")]
692#[rustc_insignificant_dtor]
693impl Drop for CString {
694 #[inline]
695 fn drop(&mut self) {
696 unsafe {
697 *self.inner.get_unchecked_mut(index:0) = 0;
698 }
699 }
700}
701
702#[stable(feature = "rust1", since = "1.0.0")]
703impl ops::Deref for CString {
704 type Target = CStr;
705
706 #[inline]
707 fn deref(&self) -> &CStr {
708 unsafe { CStr::from_bytes_with_nul_unchecked(self.as_bytes_with_nul()) }
709 }
710}
711
712#[stable(feature = "rust1", since = "1.0.0")]
713impl fmt::Debug for CString {
714 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
715 fmt::Debug::fmt(&**self, f)
716 }
717}
718
719#[stable(feature = "cstring_into", since = "1.7.0")]
720impl From<CString> for Vec<u8> {
721 /// Converts a [`CString`] into a <code>[Vec]<[u8]></code>.
722 ///
723 /// The conversion consumes the [`CString`], and removes the terminating NUL byte.
724 #[inline]
725 fn from(s: CString) -> Vec<u8> {
726 s.into_bytes()
727 }
728}
729
730#[stable(feature = "cstr_default", since = "1.10.0")]
731impl Default for CString {
732 /// Creates an empty `CString`.
733 fn default() -> CString {
734 let a: &CStr = Default::default();
735 a.to_owned()
736 }
737}
738
739#[stable(feature = "cstr_borrow", since = "1.3.0")]
740impl Borrow<CStr> for CString {
741 #[inline]
742 fn borrow(&self) -> &CStr {
743 self
744 }
745}
746
747#[stable(feature = "cstring_from_cow_cstr", since = "1.28.0")]
748impl<'a> From<Cow<'a, CStr>> for CString {
749 /// Converts a `Cow<'a, CStr>` into a `CString`, by copying the contents if they are
750 /// borrowed.
751 #[inline]
752 fn from(s: Cow<'a, CStr>) -> Self {
753 s.into_owned()
754 }
755}
756
757#[stable(feature = "box_from_c_str", since = "1.17.0")]
758impl From<&CStr> for Box<CStr> {
759 /// Converts a `&CStr` into a `Box<CStr>`,
760 /// by copying the contents into a newly allocated [`Box`].
761 fn from(s: &CStr) -> Box<CStr> {
762 let boxed: Box<[u8]> = Box::from(s.to_bytes_with_nul());
763 unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) }
764 }
765}
766
767#[stable(feature = "box_from_mut_slice", since = "1.84.0")]
768impl From<&mut CStr> for Box<CStr> {
769 /// Converts a `&mut CStr` into a `Box<CStr>`,
770 /// by copying the contents into a newly allocated [`Box`].
771 fn from(s: &mut CStr) -> Box<CStr> {
772 Self::from(&*s)
773 }
774}
775
776#[stable(feature = "box_from_cow", since = "1.45.0")]
777impl From<Cow<'_, CStr>> for Box<CStr> {
778 /// Converts a `Cow<'a, CStr>` into a `Box<CStr>`,
779 /// by copying the contents if they are borrowed.
780 #[inline]
781 fn from(cow: Cow<'_, CStr>) -> Box<CStr> {
782 match cow {
783 Cow::Borrowed(s: &CStr) => Box::from(s),
784 Cow::Owned(s: CString) => Box::from(s),
785 }
786 }
787}
788
789#[stable(feature = "c_string_from_box", since = "1.18.0")]
790impl From<Box<CStr>> for CString {
791 /// Converts a <code>[Box]<[CStr]></code> into a [`CString`] without copying or allocating.
792 #[inline]
793 fn from(s: Box<CStr>) -> CString {
794 let raw: *mut [u8] = Box::into_raw(s) as *mut [u8];
795 CString { inner: unsafe { Box::from_raw(raw) } }
796 }
797}
798
799#[stable(feature = "cstring_from_vec_of_nonzerou8", since = "1.43.0")]
800impl From<Vec<NonZero<u8>>> for CString {
801 /// Converts a <code>[Vec]<[NonZero]<[u8]>></code> into a [`CString`] without
802 /// copying nor checking for inner nul bytes.
803 #[inline]
804 fn from(v: Vec<NonZero<u8>>) -> CString {
805 unsafe {
806 // Transmute `Vec<NonZero<u8>>` to `Vec<u8>`.
807 let v: Vec<u8> = {
808 // SAFETY:
809 // - transmuting between `NonZero<u8>` and `u8` is sound;
810 // - `alloc::Layout<NonZero<u8>> == alloc::Layout<u8>`.
811 let (ptr: *mut NonZero, len: usize, cap: usize): (*mut NonZero<u8>, _, _) = Vec::into_raw_parts(self:v);
812 Vec::from_raw_parts(ptr.cast::<u8>(), length:len, capacity:cap)
813 };
814 // SAFETY: `v` cannot contain nul bytes, given the type-level
815 // invariant of `NonZero<u8>`.
816 Self::_from_vec_unchecked(v)
817 }
818 }
819}
820
821impl FromStr for CString {
822 type Err = NulError;
823
824 /// Converts a string `s` into a [`CString`].
825 ///
826 /// This method is equivalent to [`CString::new`].
827 #[inline]
828 fn from_str(s: &str) -> Result<Self, Self::Err> {
829 Self::new(s)
830 }
831}
832
833impl TryFrom<CString> for String {
834 type Error = IntoStringError;
835
836 /// Converts a [`CString`] into a [`String`] if it contains valid UTF-8 data.
837 ///
838 /// This method is equivalent to [`CString::into_string`].
839 #[inline]
840 fn try_from(value: CString) -> Result<Self, Self::Error> {
841 value.into_string()
842 }
843}
844
845#[stable(feature = "more_box_slice_clone", since = "1.29.0")]
846impl Clone for Box<CStr> {
847 #[inline]
848 fn clone(&self) -> Self {
849 (**self).into()
850 }
851}
852
853#[stable(feature = "box_from_c_string", since = "1.20.0")]
854impl From<CString> for Box<CStr> {
855 /// Converts a [`CString`] into a <code>[Box]<[CStr]></code> without copying or allocating.
856 #[inline]
857 fn from(s: CString) -> Box<CStr> {
858 s.into_boxed_c_str()
859 }
860}
861
862#[stable(feature = "cow_from_cstr", since = "1.28.0")]
863impl<'a> From<CString> for Cow<'a, CStr> {
864 /// Converts a [`CString`] into an owned [`Cow`] without copying or allocating.
865 #[inline]
866 fn from(s: CString) -> Cow<'a, CStr> {
867 Cow::Owned(s)
868 }
869}
870
871#[stable(feature = "cow_from_cstr", since = "1.28.0")]
872impl<'a> From<&'a CStr> for Cow<'a, CStr> {
873 /// Converts a [`CStr`] into a borrowed [`Cow`] without copying or allocating.
874 #[inline]
875 fn from(s: &'a CStr) -> Cow<'a, CStr> {
876 Cow::Borrowed(s)
877 }
878}
879
880#[stable(feature = "cow_from_cstr", since = "1.28.0")]
881impl<'a> From<&'a CString> for Cow<'a, CStr> {
882 /// Converts a `&`[`CString`] into a borrowed [`Cow`] without copying or allocating.
883 #[inline]
884 fn from(s: &'a CString) -> Cow<'a, CStr> {
885 Cow::Borrowed(s.as_c_str())
886 }
887}
888
889#[cfg(target_has_atomic = "ptr")]
890#[stable(feature = "shared_from_slice2", since = "1.24.0")]
891impl From<CString> for Arc<CStr> {
892 /// Converts a [`CString`] into an <code>[Arc]<[CStr]></code> by moving the [`CString`]
893 /// data into a new [`Arc`] buffer.
894 #[inline]
895 fn from(s: CString) -> Arc<CStr> {
896 let arc: Arc<[u8]> = Arc::from(s.into_inner());
897 unsafe { Arc::from_raw(ptr:Arc::into_raw(this:arc) as *const CStr) }
898 }
899}
900
901#[cfg(target_has_atomic = "ptr")]
902#[stable(feature = "shared_from_slice2", since = "1.24.0")]
903impl From<&CStr> for Arc<CStr> {
904 /// Converts a `&CStr` into a `Arc<CStr>`,
905 /// by copying the contents into a newly allocated [`Arc`].
906 #[inline]
907 fn from(s: &CStr) -> Arc<CStr> {
908 let arc: Arc<[u8]> = Arc::from(s.to_bytes_with_nul());
909 unsafe { Arc::from_raw(ptr:Arc::into_raw(this:arc) as *const CStr) }
910 }
911}
912
913#[cfg(target_has_atomic = "ptr")]
914#[stable(feature = "shared_from_mut_slice", since = "1.84.0")]
915impl From<&mut CStr> for Arc<CStr> {
916 /// Converts a `&mut CStr` into a `Arc<CStr>`,
917 /// by copying the contents into a newly allocated [`Arc`].
918 #[inline]
919 fn from(s: &mut CStr) -> Arc<CStr> {
920 Arc::from(&*s)
921 }
922}
923
924#[stable(feature = "shared_from_slice2", since = "1.24.0")]
925impl From<CString> for Rc<CStr> {
926 /// Converts a [`CString`] into an <code>[Rc]<[CStr]></code> by moving the [`CString`]
927 /// data into a new [`Rc`] buffer.
928 #[inline]
929 fn from(s: CString) -> Rc<CStr> {
930 let rc: Rc<[u8]> = Rc::from(s.into_inner());
931 unsafe { Rc::from_raw(ptr:Rc::into_raw(this:rc) as *const CStr) }
932 }
933}
934
935#[stable(feature = "shared_from_slice2", since = "1.24.0")]
936impl From<&CStr> for Rc<CStr> {
937 /// Converts a `&CStr` into a `Rc<CStr>`,
938 /// by copying the contents into a newly allocated [`Rc`].
939 #[inline]
940 fn from(s: &CStr) -> Rc<CStr> {
941 let rc: Rc<[u8]> = Rc::from(s.to_bytes_with_nul());
942 unsafe { Rc::from_raw(ptr:Rc::into_raw(this:rc) as *const CStr) }
943 }
944}
945
946#[stable(feature = "shared_from_mut_slice", since = "1.84.0")]
947impl From<&mut CStr> for Rc<CStr> {
948 /// Converts a `&mut CStr` into a `Rc<CStr>`,
949 /// by copying the contents into a newly allocated [`Rc`].
950 #[inline]
951 fn from(s: &mut CStr) -> Rc<CStr> {
952 Rc::from(&*s)
953 }
954}
955
956#[cfg(not(no_global_oom_handling))]
957#[stable(feature = "more_rc_default_impls", since = "1.80.0")]
958impl Default for Rc<CStr> {
959 /// Creates an empty CStr inside an Rc
960 ///
961 /// This may or may not share an allocation with other Rcs on the same thread.
962 #[inline]
963 fn default() -> Self {
964 let rc: Rc<[u8]> = Rc::<[u8]>::from(*b"\0");
965 // `[u8]` has the same layout as `CStr`, and it is `NUL` terminated.
966 unsafe { Rc::from_raw(ptr:Rc::into_raw(this:rc) as *const CStr) }
967 }
968}
969
970#[stable(feature = "default_box_extra", since = "1.17.0")]
971impl Default for Box<CStr> {
972 fn default() -> Box<CStr> {
973 let boxed: Box<[u8]> = Box::from([0]);
974 unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) }
975 }
976}
977
978impl NulError {
979 /// Returns the position of the nul byte in the slice that caused
980 /// [`CString::new`] to fail.
981 ///
982 /// # Examples
983 ///
984 /// ```
985 /// use std::ffi::CString;
986 ///
987 /// let nul_error = CString::new("foo\0bar").unwrap_err();
988 /// assert_eq!(nul_error.nul_position(), 3);
989 ///
990 /// let nul_error = CString::new("foo bar\0").unwrap_err();
991 /// assert_eq!(nul_error.nul_position(), 7);
992 /// ```
993 #[must_use]
994 #[stable(feature = "rust1", since = "1.0.0")]
995 pub fn nul_position(&self) -> usize {
996 self.0
997 }
998
999 /// Consumes this error, returning the underlying vector of bytes which
1000 /// generated the error in the first place.
1001 ///
1002 /// # Examples
1003 ///
1004 /// ```
1005 /// use std::ffi::CString;
1006 ///
1007 /// let nul_error = CString::new("foo\0bar").unwrap_err();
1008 /// assert_eq!(nul_error.into_vec(), b"foo\0bar");
1009 /// ```
1010 #[must_use = "`self` will be dropped if the result is not used"]
1011 #[stable(feature = "rust1", since = "1.0.0")]
1012 pub fn into_vec(self) -> Vec<u8> {
1013 self.1
1014 }
1015}
1016
1017#[stable(feature = "rust1", since = "1.0.0")]
1018impl fmt::Display for NulError {
1019 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1020 write!(f, "nul byte found in provided data at position: {}", self.0)
1021 }
1022}
1023
1024#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
1025impl fmt::Display for FromVecWithNulError {
1026 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1027 match self.error_kind {
1028 FromBytesWithNulErrorKind::InteriorNul(pos: usize) => {
1029 write!(f, "data provided contains an interior nul byte at pos {pos}")
1030 }
1031 FromBytesWithNulErrorKind::NotNulTerminated => {
1032 write!(f, "data provided is not nul terminated")
1033 }
1034 }
1035 }
1036}
1037
1038impl IntoStringError {
1039 /// Consumes this error, returning original [`CString`] which generated the
1040 /// error.
1041 #[must_use = "`self` will be dropped if the result is not used"]
1042 #[stable(feature = "cstring_into", since = "1.7.0")]
1043 pub fn into_cstring(self) -> CString {
1044 self.inner
1045 }
1046
1047 /// Access the underlying UTF-8 error that was the cause of this error.
1048 #[must_use]
1049 #[stable(feature = "cstring_into", since = "1.7.0")]
1050 pub fn utf8_error(&self) -> Utf8Error {
1051 self.error
1052 }
1053}
1054
1055impl IntoStringError {
1056 fn description(&self) -> &str {
1057 "C string contained non-utf8 bytes"
1058 }
1059}
1060
1061#[stable(feature = "cstring_into", since = "1.7.0")]
1062impl fmt::Display for IntoStringError {
1063 #[allow(deprecated, deprecated_in_future)]
1064 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1065 self.description().fmt(f)
1066 }
1067}
1068
1069#[stable(feature = "cstr_borrow", since = "1.3.0")]
1070impl ToOwned for CStr {
1071 type Owned = CString;
1072
1073 fn to_owned(&self) -> CString {
1074 CString { inner: self.to_bytes_with_nul().into() }
1075 }
1076
1077 fn clone_into(&self, target: &mut CString) {
1078 let mut b: Vec = mem::take(&mut target.inner).into_vec();
1079 self.to_bytes_with_nul().clone_into(&mut b);
1080 target.inner = b.into_boxed_slice();
1081 }
1082}
1083
1084#[stable(feature = "cstring_asref", since = "1.7.0")]
1085impl From<&CStr> for CString {
1086 /// Converts a <code>&[CStr]</code> into a [`CString`]
1087 /// by copying the contents into a new allocation.
1088 fn from(s: &CStr) -> CString {
1089 s.to_owned()
1090 }
1091}
1092
1093#[stable(feature = "cstring_asref", since = "1.7.0")]
1094impl ops::Index<ops::RangeFull> for CString {
1095 type Output = CStr;
1096
1097 #[inline]
1098 fn index(&self, _index: ops::RangeFull) -> &CStr {
1099 self
1100 }
1101}
1102
1103#[stable(feature = "cstring_asref", since = "1.7.0")]
1104impl AsRef<CStr> for CString {
1105 #[inline]
1106 fn as_ref(&self) -> &CStr {
1107 self
1108 }
1109}
1110
1111impl CStr {
1112 /// Converts a `CStr` into a <code>[Cow]<[str]></code>.
1113 ///
1114 /// If the contents of the `CStr` are valid UTF-8 data, this
1115 /// function will return a <code>[Cow]::[Borrowed]\(&[str])</code>
1116 /// with the corresponding <code>&[str]</code> slice. Otherwise, it will
1117 /// replace any invalid UTF-8 sequences with
1118 /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD] and return a
1119 /// <code>[Cow]::[Owned]\(&[str])</code> with the result.
1120 ///
1121 /// [str]: prim@str "str"
1122 /// [Borrowed]: Cow::Borrowed
1123 /// [Owned]: Cow::Owned
1124 /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER "std::char::REPLACEMENT_CHARACTER"
1125 ///
1126 /// # Examples
1127 ///
1128 /// Calling `to_string_lossy` on a `CStr` containing valid UTF-8. The leading
1129 /// `c` on the string literal denotes a `CStr`.
1130 ///
1131 /// ```
1132 /// use std::borrow::Cow;
1133 ///
1134 /// assert_eq!(c"Hello World".to_string_lossy(), Cow::Borrowed("Hello World"));
1135 /// ```
1136 ///
1137 /// Calling `to_string_lossy` on a `CStr` containing invalid UTF-8:
1138 ///
1139 /// ```
1140 /// use std::borrow::Cow;
1141 ///
1142 /// assert_eq!(
1143 /// c"Hello \xF0\x90\x80World".to_string_lossy(),
1144 /// Cow::Owned(String::from("Hello �World")) as Cow<'_, str>
1145 /// );
1146 /// ```
1147 #[rustc_allow_incoherent_impl]
1148 #[must_use = "this returns the result of the operation, \
1149 without modifying the original"]
1150 #[stable(feature = "cstr_to_str", since = "1.4.0")]
1151 pub fn to_string_lossy(&self) -> Cow<'_, str> {
1152 String::from_utf8_lossy(self.to_bytes())
1153 }
1154
1155 /// Converts a <code>[Box]<[CStr]></code> into a [`CString`] without copying or allocating.
1156 ///
1157 /// # Examples
1158 ///
1159 /// ```
1160 /// use std::ffi::{CStr, CString};
1161 ///
1162 /// let boxed: Box<CStr> = Box::from(c"foo");
1163 /// let c_string: CString = c"foo".to_owned();
1164 ///
1165 /// assert_eq!(boxed.into_c_string(), c_string);
1166 /// ```
1167 #[rustc_allow_incoherent_impl]
1168 #[must_use = "`self` will be dropped if the result is not used"]
1169 #[stable(feature = "into_boxed_c_str", since = "1.20.0")]
1170 pub fn into_c_string(self: Box<Self>) -> CString {
1171 CString::from(self)
1172 }
1173}
1174
1175#[stable(feature = "rust1", since = "1.0.0")]
1176impl core::error::Error for NulError {
1177 #[allow(deprecated)]
1178 fn description(&self) -> &str {
1179 "nul byte found in data"
1180 }
1181}
1182
1183#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")]
1184impl core::error::Error for FromVecWithNulError {}
1185
1186#[stable(feature = "cstring_into", since = "1.7.0")]
1187impl core::error::Error for IntoStringError {
1188 #[allow(deprecated)]
1189 fn description(&self) -> &str {
1190 "C string contained non-utf8 bytes"
1191 }
1192
1193 fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
1194 Some(&self.error)
1195 }
1196}
1197

Provided by KDAB

Privacy Policy