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