]>
Commit | Line | Data |
---|---|---|
3dfed10e | 1 | #![deny(unsafe_op_in_unsafe_fn)] |
1b1a35ee XL |
2 | |
3 | #[cfg(test)] | |
4 | mod tests; | |
5 | ||
532ac7d7 | 6 | use crate::ascii; |
dfeec247 | 7 | use crate::borrow::{Borrow, Cow}; |
532ac7d7 XL |
8 | use crate::cmp::Ordering; |
9 | use crate::error::Error; | |
10 | use crate::fmt::{self, Write}; | |
11 | use crate::io; | |
12 | use crate::mem; | |
13 | use crate::memchr; | |
74b04a01 | 14 | use crate::num::NonZeroU8; |
532ac7d7 XL |
15 | use crate::ops; |
16 | use crate::os::raw::c_char; | |
17 | use crate::ptr; | |
18 | use crate::rc::Rc; | |
19 | use crate::slice; | |
20 | use crate::str::{self, Utf8Error}; | |
21 | use crate::sync::Arc; | |
22 | use crate::sys; | |
1a4d82fc | 23 | |
abe05a73 XL |
24 | /// A type representing an owned, C-compatible, nul-terminated string with no nul bytes in the |
25 | /// middle. | |
1a4d82fc | 26 | /// |
abe05a73 | 27 | /// This type serves the purpose of being able to safely generate a |
1a4d82fc JJ |
28 | /// C-compatible string from a Rust byte slice or vector. An instance of this |
29 | /// type is a static guarantee that the underlying bytes contain no interior 0 | |
abe05a73 | 30 | /// bytes ("nul characters") and that the final byte is 0 ("nul terminator"). |
1a4d82fc | 31 | /// |
b7449926 | 32 | /// `CString` is to [`&CStr`] as [`String`] is to [`&str`]: the former |
abe05a73 XL |
33 | /// in each pair are owned strings; the latter are borrowed |
34 | /// references. | |
7cac9316 | 35 | /// |
abe05a73 XL |
36 | /// # Creating a `CString` |
37 | /// | |
38 | /// A `CString` is created from either a byte slice or a byte vector, | |
39 | /// or anything that implements [`Into`]`<`[`Vec`]`<`[`u8`]`>>` (for | |
40 | /// example, you can build a `CString` straight out of a [`String`] or | |
41 | /// a [`&str`], since both implement that trait). | |
42 | /// | |
3dfed10e | 43 | /// The [`CString::new`] method will actually check that the provided `&[u8]` |
abe05a73 XL |
44 | /// does not have 0 bytes in the middle, and return an error if it |
45 | /// finds one. | |
46 | /// | |
47 | /// # Extracting a raw pointer to the whole C string | |
48 | /// | |
3dfed10e | 49 | /// `CString` implements a [`as_ptr`][`CStr::as_ptr`] method through the [`Deref`] |
abe05a73 XL |
50 | /// trait. This method will give you a `*const c_char` which you can |
51 | /// feed directly to extern functions that expect a nul-terminated | |
3dfed10e | 52 | /// string, like C's `strdup()`. Notice that [`as_ptr`][`CStr::as_ptr`] returns a |
48663c56 XL |
53 | /// read-only pointer; if the C code writes to it, that causes |
54 | /// undefined behavior. | |
abe05a73 XL |
55 | /// |
56 | /// # Extracting a slice of the whole C string | |
57 | /// | |
58 | /// Alternatively, you can obtain a `&[`[`u8`]`]` slice from a | |
3dfed10e | 59 | /// `CString` with the [`CString::as_bytes`] method. Slices produced in this |
abe05a73 XL |
60 | /// way do *not* contain the trailing nul terminator. This is useful |
61 | /// when you will be calling an extern function that takes a `*const | |
62 | /// u8` argument which is not necessarily nul-terminated, plus another | |
63 | /// argument with the length of the string — like C's `strndup()`. | |
64 | /// You can of course get the slice's length with its | |
65 | /// [`len`][slice.len] method. | |
66 | /// | |
67 | /// If you need a `&[`[`u8`]`]` slice *with* the nul terminator, you | |
3dfed10e | 68 | /// can use [`CString::as_bytes_with_nul`] instead. |
abe05a73 XL |
69 | /// |
70 | /// Once you have the kind of slice you need (with or without a nul | |
71 | /// terminator), you can call the slice's own | |
48663c56 | 72 | /// [`as_ptr`][slice.as_ptr] method to get a read-only raw pointer to pass to |
abe05a73 XL |
73 | /// extern functions. See the documentation for that function for a |
74 | /// discussion on ensuring the lifetime of the raw pointer. | |
75 | /// | |
3dfed10e | 76 | /// [`&str`]: prim@str |
abe05a73 XL |
77 | /// [slice.as_ptr]: ../primitive.slice.html#method.as_ptr |
78 | /// [slice.len]: ../primitive.slice.html#method.len | |
3dfed10e XL |
79 | /// [`Deref`]: ops::Deref |
80 | /// [`&CStr`]: CStr | |
1a4d82fc | 81 | /// |
c34b1796 | 82 | /// # Examples |
1a4d82fc | 83 | /// |
0531ce1d | 84 | /// ```ignore (extern-declaration) |
1a4d82fc JJ |
85 | /// # fn main() { |
86 | /// use std::ffi::CString; | |
92a42be0 | 87 | /// use std::os::raw::c_char; |
1a4d82fc JJ |
88 | /// |
89 | /// extern { | |
92a42be0 | 90 | /// fn my_printer(s: *const c_char); |
1a4d82fc JJ |
91 | /// } |
92 | /// | |
abe05a73 | 93 | /// // We are certain that our string doesn't have 0 bytes in the middle, |
b7449926 XL |
94 | /// // so we can .expect() |
95 | /// let c_to_print = CString::new("Hello, world!").expect("CString::new failed"); | |
1a4d82fc JJ |
96 | /// unsafe { |
97 | /// my_printer(c_to_print.as_ptr()); | |
98 | /// } | |
99 | /// # } | |
100 | /// ``` | |
7453a54e SL |
101 | /// |
102 | /// # Safety | |
103 | /// | |
104 | /// `CString` is intended for working with traditional C-style strings | |
abe05a73 | 105 | /// (a sequence of non-nul bytes terminated by a single nul byte); the |
7453a54e SL |
106 | /// primary use case for these kinds of strings is interoperating with C-like |
107 | /// code. Often you will need to transfer ownership to/from that external | |
108 | /// code. It is strongly recommended that you thoroughly read through the | |
109 | /// documentation of `CString` before use, as improper ownership management | |
110 | /// of `CString` instances can lead to invalid memory accesses, memory leaks, | |
111 | /// and other memory errors. | |
c1a9b12d | 112 | #[derive(PartialEq, PartialOrd, Eq, Ord, Hash, Clone)] |
c34b1796 | 113 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 114 | pub struct CString { |
9e0c209e SL |
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. | |
62682a34 | 118 | inner: Box<[u8]>, |
85aaf69f SL |
119 | } |
120 | ||
121 | /// Representation of a borrowed C string. | |
122 | /// | |
abe05a73 XL |
123 | /// This type represents a borrowed reference to a nul-terminated |
124 | /// array of bytes. It can be constructed safely from a `&[`[`u8`]`]` | |
125 | /// slice, or unsafely from a raw `*const c_char`. It can then be | |
126 | /// converted to a Rust [`&str`] by performing UTF-8 validation, or | |
127 | /// into an owned [`CString`]. | |
128 | /// | |
b7449926 | 129 | /// `&CStr` is to [`CString`] as [`&str`] is to [`String`]: the former |
abe05a73 XL |
130 | /// in each pair are borrowed references; the latter are owned |
131 | /// strings. | |
85aaf69f SL |
132 | /// |
133 | /// Note that this structure is **not** `repr(C)` and is not recommended to be | |
abe05a73 | 134 | /// placed in the signatures of FFI functions. Instead, safe wrappers of FFI |
3dfed10e XL |
135 | /// functions may leverage the unsafe [`CStr::from_ptr`] constructor to provide |
136 | /// a safe interface to other consumers. | |
85aaf69f SL |
137 | /// |
138 | /// # Examples | |
139 | /// | |
7cac9316 | 140 | /// Inspecting a foreign C string: |
85aaf69f | 141 | /// |
0531ce1d | 142 | /// ```ignore (extern-declaration) |
85aaf69f | 143 | /// use std::ffi::CStr; |
92a42be0 | 144 | /// use std::os::raw::c_char; |
85aaf69f | 145 | /// |
92a42be0 | 146 | /// extern { fn my_string() -> *const c_char; } |
85aaf69f | 147 | /// |
5bcae85e SL |
148 | /// unsafe { |
149 | /// let slice = CStr::from_ptr(my_string()); | |
abe05a73 | 150 | /// println!("string buffer size without nul terminator: {}", slice.to_bytes().len()); |
85aaf69f SL |
151 | /// } |
152 | /// ``` | |
153 | /// | |
7cac9316 | 154 | /// Passing a Rust-originating C string: |
85aaf69f | 155 | /// |
0531ce1d | 156 | /// ```ignore (extern-declaration) |
85aaf69f | 157 | /// use std::ffi::{CString, CStr}; |
92a42be0 | 158 | /// use std::os::raw::c_char; |
85aaf69f SL |
159 | /// |
160 | /// fn work(data: &CStr) { | |
92a42be0 | 161 | /// extern { fn work_with(data: *const c_char); } |
85aaf69f SL |
162 | /// |
163 | /// unsafe { work_with(data.as_ptr()) } | |
164 | /// } | |
165 | /// | |
b7449926 | 166 | /// let s = CString::new("data data data data").expect("CString::new failed"); |
5bcae85e | 167 | /// work(&s); |
85aaf69f | 168 | /// ``` |
62682a34 | 169 | /// |
7cac9316 XL |
170 | /// Converting a foreign C string into a Rust [`String`]: |
171 | /// | |
0531ce1d | 172 | /// ```ignore (extern-declaration) |
62682a34 | 173 | /// use std::ffi::CStr; |
92a42be0 | 174 | /// use std::os::raw::c_char; |
62682a34 | 175 | /// |
92a42be0 | 176 | /// extern { fn my_string() -> *const c_char; } |
62682a34 SL |
177 | /// |
178 | /// fn my_string_safe() -> String { | |
179 | /// unsafe { | |
180 | /// CStr::from_ptr(my_string()).to_string_lossy().into_owned() | |
181 | /// } | |
182 | /// } | |
183 | /// | |
5bcae85e | 184 | /// println!("string: {}", my_string_safe()); |
62682a34 | 185 | /// ``` |
abe05a73 | 186 | /// |
3dfed10e | 187 | /// [`&str`]: prim@str |
85aaf69f | 188 | #[derive(Hash)] |
c34b1796 | 189 | #[stable(feature = "rust1", since = "1.0.0")] |
416331ca XL |
190 | // FIXME: |
191 | // `fn from` in `impl From<&CStr> for Box<CStr>` current implementation relies | |
192 | // on `CStr` being layout-compatible with `[u8]`. | |
193 | // When attribute privacy is implemented, `CStr` should be annotated as `#[repr(transparent)]`. | |
194 | // Anyway, `CStr` representation and layout are considered implementation detail, are | |
195 | // not documented and must not be relied upon. | |
85aaf69f | 196 | pub struct CStr { |
c34b1796 | 197 | // FIXME: this should not be represented with a DST slice but rather with |
92a42be0 | 198 | // just a raw `c_char` along with some form of marker to make |
c34b1796 AL |
199 | // this an unsized type. Essentially `sizeof(&CStr)` should be the |
200 | // same as `sizeof(&c_char)` but `CStr` should be an unsized type. | |
dfeec247 | 201 | inner: [c_char], |
85aaf69f SL |
202 | } |
203 | ||
abe05a73 XL |
204 | /// An error indicating that an interior nul byte was found. |
205 | /// | |
206 | /// While Rust strings may contain nul bytes in the middle, C strings | |
207 | /// can't, as that byte would effectively truncate the string. | |
7cac9316 | 208 | /// |
abe05a73 XL |
209 | /// This error is created by the [`new`][`CString::new`] method on |
210 | /// [`CString`]. See its documentation for more. | |
211 | /// | |
041b39d2 XL |
212 | /// # Examples |
213 | /// | |
214 | /// ``` | |
215 | /// use std::ffi::{CString, NulError}; | |
216 | /// | |
217 | /// let _: NulError = CString::new(b"f\0oo".to_vec()).unwrap_err(); | |
218 | /// ``` | |
9e0c209e | 219 | #[derive(Clone, PartialEq, Eq, Debug)] |
c34b1796 | 220 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f SL |
221 | pub struct NulError(usize, Vec<u8>); |
222 | ||
abe05a73 XL |
223 | /// An error indicating that a nul byte was not in the expected position. |
224 | /// | |
f035d41b XL |
225 | /// The slice used to create a [`CStr`] must have one and only one nul byte, |
226 | /// positioned at the end. | |
7cac9316 | 227 | /// |
3dfed10e | 228 | /// This error is created by the [`CStr::from_bytes_with_nul`] method. |
f035d41b | 229 | /// See its documentation for more. |
abe05a73 | 230 | /// |
041b39d2 XL |
231 | /// # Examples |
232 | /// | |
233 | /// ``` | |
234 | /// use std::ffi::{CStr, FromBytesWithNulError}; | |
235 | /// | |
236 | /// let _: FromBytesWithNulError = CStr::from_bytes_with_nul(b"f\0oo").unwrap_err(); | |
237 | /// ``` | |
9e0c209e | 238 | #[derive(Clone, PartialEq, Eq, Debug)] |
a7813a04 | 239 | #[stable(feature = "cstr_from_bytes", since = "1.10.0")] |
8bb4bdeb XL |
240 | pub struct FromBytesWithNulError { |
241 | kind: FromBytesWithNulErrorKind, | |
242 | } | |
243 | ||
f035d41b XL |
244 | /// An error indicating that a nul byte was not in the expected position. |
245 | /// | |
246 | /// The vector used to create a [`CString`] must have one and only one nul byte, | |
247 | /// positioned at the end. | |
248 | /// | |
3dfed10e | 249 | /// This error is created by the [`CString::from_vec_with_nul`] method. |
f035d41b XL |
250 | /// See its documentation for more. |
251 | /// | |
f035d41b XL |
252 | /// # Examples |
253 | /// | |
254 | /// ``` | |
255 | /// #![feature(cstring_from_vec_with_nul)] | |
256 | /// use std::ffi::{CString, FromVecWithNulError}; | |
257 | /// | |
258 | /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"f\0oo".to_vec()).unwrap_err(); | |
259 | /// ``` | |
260 | #[derive(Clone, PartialEq, Eq, Debug)] | |
261 | #[unstable(feature = "cstring_from_vec_with_nul", issue = "73179")] | |
262 | pub struct FromVecWithNulError { | |
263 | error_kind: FromBytesWithNulErrorKind, | |
264 | bytes: Vec<u8>, | |
265 | } | |
266 | ||
8bb4bdeb XL |
267 | #[derive(Clone, PartialEq, Eq, Debug)] |
268 | enum FromBytesWithNulErrorKind { | |
269 | InteriorNul(usize), | |
270 | NotNulTerminated, | |
271 | } | |
272 | ||
273 | impl FromBytesWithNulError { | |
274 | fn interior_nul(pos: usize) -> FromBytesWithNulError { | |
dfeec247 | 275 | FromBytesWithNulError { kind: FromBytesWithNulErrorKind::InteriorNul(pos) } |
8bb4bdeb XL |
276 | } |
277 | fn not_nul_terminated() -> FromBytesWithNulError { | |
dfeec247 | 278 | FromBytesWithNulError { kind: FromBytesWithNulErrorKind::NotNulTerminated } |
8bb4bdeb XL |
279 | } |
280 | } | |
a7813a04 | 281 | |
f035d41b XL |
282 | #[unstable(feature = "cstring_from_vec_with_nul", issue = "73179")] |
283 | impl FromVecWithNulError { | |
284 | /// Returns a slice of [`u8`]s bytes that were attempted to convert to a [`CString`]. | |
285 | /// | |
286 | /// # Examples | |
287 | /// | |
288 | /// Basic usage: | |
289 | /// | |
290 | /// ``` | |
291 | /// #![feature(cstring_from_vec_with_nul)] | |
292 | /// use std::ffi::CString; | |
293 | /// | |
294 | /// // Some invalid bytes in a vector | |
295 | /// let bytes = b"f\0oo".to_vec(); | |
296 | /// | |
297 | /// let value = CString::from_vec_with_nul(bytes.clone()); | |
298 | /// | |
299 | /// assert_eq!(&bytes[..], value.unwrap_err().as_bytes()); | |
300 | /// ``` | |
f035d41b XL |
301 | pub fn as_bytes(&self) -> &[u8] { |
302 | &self.bytes[..] | |
303 | } | |
304 | ||
305 | /// Returns the bytes that were attempted to convert to a [`CString`]. | |
306 | /// | |
307 | /// This method is carefully constructed to avoid allocation. It will | |
308 | /// consume the error, moving out the bytes, so that a copy of the bytes | |
309 | /// does not need to be made. | |
310 | /// | |
311 | /// # Examples | |
312 | /// | |
313 | /// Basic usage: | |
314 | /// | |
315 | /// ``` | |
316 | /// #![feature(cstring_from_vec_with_nul)] | |
317 | /// use std::ffi::CString; | |
318 | /// | |
319 | /// // Some invalid bytes in a vector | |
320 | /// let bytes = b"f\0oo".to_vec(); | |
321 | /// | |
322 | /// let value = CString::from_vec_with_nul(bytes.clone()); | |
323 | /// | |
324 | /// assert_eq!(bytes, value.unwrap_err().into_bytes()); | |
325 | /// ``` | |
f035d41b XL |
326 | pub fn into_bytes(self) -> Vec<u8> { |
327 | self.bytes | |
328 | } | |
329 | } | |
330 | ||
abe05a73 XL |
331 | /// An error indicating invalid UTF-8 when converting a [`CString`] into a [`String`]. |
332 | /// | |
3dfed10e XL |
333 | /// `CString` is just a wrapper over a buffer of bytes with a nul terminator; |
334 | /// [`CString::into_string`] performs UTF-8 validation on those bytes and may | |
335 | /// return this error. | |
abe05a73 | 336 | /// |
3dfed10e | 337 | /// This `struct` is created by [`CString::into_string()`]. See |
abe05a73 | 338 | /// its documentation for more. |
9e0c209e | 339 | #[derive(Clone, PartialEq, Eq, Debug)] |
9cc50fc6 | 340 | #[stable(feature = "cstring_into", since = "1.7.0")] |
b039eaaf SL |
341 | pub struct IntoStringError { |
342 | inner: CString, | |
343 | error: Utf8Error, | |
344 | } | |
345 | ||
1a4d82fc | 346 | impl CString { |
9346a6ac | 347 | /// Creates a new C-compatible string from a container of bytes. |
85aaf69f | 348 | /// |
abe05a73 XL |
349 | /// This function will consume the provided data and use the |
350 | /// underlying bytes to construct a new string, ensuring that | |
351 | /// there is a trailing 0 byte. This trailing 0 byte will be | |
352 | /// appended by this function; the provided data should *not* | |
353 | /// contain any 0 bytes in it. | |
85aaf69f SL |
354 | /// |
355 | /// # Examples | |
356 | /// | |
0531ce1d | 357 | /// ```ignore (extern-declaration) |
85aaf69f | 358 | /// use std::ffi::CString; |
92a42be0 | 359 | /// use std::os::raw::c_char; |
85aaf69f | 360 | /// |
92a42be0 | 361 | /// extern { fn puts(s: *const c_char); } |
85aaf69f | 362 | /// |
b7449926 | 363 | /// let to_print = CString::new("Hello!").expect("CString::new failed"); |
5bcae85e SL |
364 | /// unsafe { |
365 | /// puts(to_print.as_ptr()); | |
85aaf69f SL |
366 | /// } |
367 | /// ``` | |
368 | /// | |
369 | /// # Errors | |
370 | /// | |
abe05a73 XL |
371 | /// This function will return an error if the supplied bytes contain an |
372 | /// internal 0 byte. The [`NulError`] returned will contain the bytes as well as | |
85aaf69f | 373 | /// the position of the nul byte. |
c34b1796 AL |
374 | #[stable(feature = "rust1", since = "1.0.0")] |
375 | pub fn new<T: Into<Vec<u8>>>(t: T) -> Result<CString, NulError> { | |
e74abb32 XL |
376 | trait SpecIntoVec { |
377 | fn into_vec(self) -> Vec<u8>; | |
378 | } | |
379 | impl<T: Into<Vec<u8>>> SpecIntoVec for T { | |
380 | default fn into_vec(self) -> Vec<u8> { | |
381 | self.into() | |
382 | } | |
383 | } | |
384 | // Specialization for avoiding reallocation. | |
385 | impl SpecIntoVec for &'_ [u8] { | |
386 | fn into_vec(self) -> Vec<u8> { | |
387 | let mut v = Vec::with_capacity(self.len() + 1); | |
388 | v.extend(self); | |
389 | v | |
390 | } | |
391 | } | |
392 | impl SpecIntoVec for &'_ str { | |
393 | fn into_vec(self) -> Vec<u8> { | |
394 | let mut v = Vec::with_capacity(self.len() + 1); | |
395 | v.extend(self.as_bytes()); | |
396 | v | |
397 | } | |
398 | } | |
399 | ||
400 | Self::_new(SpecIntoVec::into_vec(t)) | |
e9174d1e SL |
401 | } |
402 | ||
403 | fn _new(bytes: Vec<u8>) -> Result<CString, NulError> { | |
9cc50fc6 | 404 | match memchr::memchr(0, &bytes) { |
85aaf69f SL |
405 | Some(i) => Err(NulError(i, bytes)), |
406 | None => Ok(unsafe { CString::from_vec_unchecked(bytes) }), | |
407 | } | |
408 | } | |
409 | ||
abe05a73 XL |
410 | /// Creates a C-compatible string by consuming a byte vector, |
411 | /// without checking for interior 0 bytes. | |
1a4d82fc | 412 | /// |
3dfed10e XL |
413 | /// This method is equivalent to [`CString::new`] except that no runtime |
414 | /// assertion is made that `v` contains no 0 bytes, and it requires an | |
415 | /// actual byte vector, not anything that can be converted to one with Into. | |
7cac9316 | 416 | /// |
9e0c209e SL |
417 | /// # Examples |
418 | /// | |
419 | /// ``` | |
420 | /// use std::ffi::CString; | |
421 | /// | |
422 | /// let raw = b"foo".to_vec(); | |
423 | /// unsafe { | |
424 | /// let c_string = CString::from_vec_unchecked(raw); | |
425 | /// } | |
426 | /// ``` | |
c34b1796 | 427 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 428 | pub unsafe fn from_vec_unchecked(mut v: Vec<u8>) -> CString { |
9e0c209e | 429 | v.reserve_exact(1); |
1a4d82fc | 430 | v.push(0); |
62682a34 SL |
431 | CString { inner: v.into_boxed_slice() } |
432 | } | |
433 | ||
3dfed10e XL |
434 | /// Retakes ownership of a `CString` that was transferred to C via |
435 | /// [`CString::into_raw`]. | |
e9174d1e | 436 | /// |
9e0c209e SL |
437 | /// Additionally, the length of the string will be recalculated from the pointer. |
438 | /// | |
439 | /// # Safety | |
440 | /// | |
7453a54e | 441 | /// This should only ever be called with a pointer that was earlier |
3dfed10e | 442 | /// obtained by calling [`CString::into_raw`]. Other usage (e.g., trying to take |
9e0c209e SL |
443 | /// ownership of a string that was allocated by foreign code) is likely to lead |
444 | /// to undefined behavior or allocator corruption. | |
7cac9316 | 445 | /// |
f035d41b XL |
446 | /// It should be noted that the length isn't just "recomputed," but that |
447 | /// the recomputed length must match the original length from the | |
3dfed10e XL |
448 | /// [`CString::into_raw`] call. This means the [`CString::into_raw`]/`from_raw` |
449 | /// methods should not be used when passing the string to C functions that can | |
f035d41b XL |
450 | /// modify the string's length. |
451 | /// | |
abe05a73 XL |
452 | /// > **Note:** If you need to borrow a string that was allocated by |
453 | /// > foreign code, use [`CStr`]. If you need to take ownership of | |
454 | /// > a string that was allocated by foreign code, you will need to | |
455 | /// > make your own provisions for freeing it appropriately, likely | |
456 | /// > with the foreign code's API to do that. | |
457 | /// | |
041b39d2 XL |
458 | /// # Examples |
459 | /// | |
9fa01778 | 460 | /// Creates a `CString`, pass ownership to an `extern` function (via raw pointer), then retake |
041b39d2 XL |
461 | /// ownership with `from_raw`: |
462 | /// | |
0531ce1d | 463 | /// ```ignore (extern-declaration) |
041b39d2 XL |
464 | /// use std::ffi::CString; |
465 | /// use std::os::raw::c_char; | |
466 | /// | |
467 | /// extern { | |
468 | /// fn some_extern_function(s: *mut c_char); | |
469 | /// } | |
470 | /// | |
b7449926 | 471 | /// let c_string = CString::new("Hello!").expect("CString::new failed"); |
041b39d2 XL |
472 | /// let raw = c_string.into_raw(); |
473 | /// unsafe { | |
474 | /// some_extern_function(raw); | |
475 | /// let c_string = CString::from_raw(raw); | |
476 | /// } | |
477 | /// ``` | |
e9174d1e | 478 | #[stable(feature = "cstr_memory", since = "1.4.0")] |
92a42be0 | 479 | pub unsafe fn from_raw(ptr: *mut c_char) -> CString { |
3dfed10e XL |
480 | // SAFETY: This is called with a pointer that was obtained from a call |
481 | // to `CString::into_raw` and the length has not been modified. As such, | |
482 | // we know there is a NUL byte (and only one) at the end and that the | |
483 | // information about the size of the allocation is correct on Rust's | |
484 | // side. | |
485 | unsafe { | |
486 | let len = sys::strlen(ptr) + 1; // Including the NUL byte | |
487 | let slice = slice::from_raw_parts_mut(ptr, len as usize); | |
488 | CString { inner: Box::from_raw(slice as *mut [c_char] as *mut [u8]) } | |
489 | } | |
62682a34 SL |
490 | } |
491 | ||
abe05a73 | 492 | /// Consumes the `CString` and transfers ownership of the string to a C caller. |
62682a34 | 493 | /// |
abe05a73 | 494 | /// The pointer which this function returns must be returned to Rust and reconstituted using |
3dfed10e | 495 | /// [`CString::from_raw`] to be properly deallocated. Specifically, one |
abe05a73 | 496 | /// should *not* use the standard C `free()` function to deallocate |
62682a34 SL |
497 | /// this string. |
498 | /// | |
3dfed10e | 499 | /// Failure to call [`CString::from_raw`] will lead to a memory leak. |
7cac9316 | 500 | /// |
f035d41b XL |
501 | /// The C side must **not** modify the length of the string (by writing a |
502 | /// `NULL` somewhere inside the string or removing the final one) before | |
3dfed10e XL |
503 | /// it makes it back into Rust using [`CString::from_raw`]. See the safety section |
504 | /// in [`CString::from_raw`]. | |
041b39d2 XL |
505 | /// |
506 | /// # Examples | |
507 | /// | |
508 | /// ``` | |
509 | /// use std::ffi::CString; | |
510 | /// | |
b7449926 | 511 | /// let c_string = CString::new("foo").expect("CString::new failed"); |
041b39d2 XL |
512 | /// |
513 | /// let ptr = c_string.into_raw(); | |
514 | /// | |
515 | /// unsafe { | |
516 | /// assert_eq!(b'f', *ptr as u8); | |
517 | /// assert_eq!(b'o', *ptr.offset(1) as u8); | |
518 | /// assert_eq!(b'o', *ptr.offset(2) as u8); | |
519 | /// assert_eq!(b'\0', *ptr.offset(3) as u8); | |
520 | /// | |
521 | /// // retake pointer to free memory | |
522 | /// let _ = CString::from_raw(ptr); | |
523 | /// } | |
524 | /// ``` | |
525 | #[inline] | |
e9174d1e | 526 | #[stable(feature = "cstr_memory", since = "1.4.0")] |
92a42be0 | 527 | pub fn into_raw(self) -> *mut c_char { |
9e0c209e | 528 | Box::into_raw(self.into_inner()) as *mut c_char |
1a4d82fc JJ |
529 | } |
530 | ||
abe05a73 | 531 | /// Converts the `CString` into a [`String`] if it contains valid UTF-8 data. |
b039eaaf SL |
532 | /// |
533 | /// On failure, ownership of the original `CString` is returned. | |
7cac9316 | 534 | /// |
abe05a73 XL |
535 | /// # Examples |
536 | /// | |
537 | /// ``` | |
538 | /// use std::ffi::CString; | |
539 | /// | |
540 | /// let valid_utf8 = vec![b'f', b'o', b'o']; | |
b7449926 XL |
541 | /// let cstring = CString::new(valid_utf8).expect("CString::new failed"); |
542 | /// assert_eq!(cstring.into_string().expect("into_string() call failed"), "foo"); | |
abe05a73 XL |
543 | /// |
544 | /// let invalid_utf8 = vec![b'f', 0xff, b'o', b'o']; | |
b7449926 XL |
545 | /// let cstring = CString::new(invalid_utf8).expect("CString::new failed"); |
546 | /// let err = cstring.into_string().err().expect("into_string().err() failed"); | |
abe05a73 XL |
547 | /// assert_eq!(err.utf8_error().valid_up_to(), 1); |
548 | /// ``` | |
549 | ||
9cc50fc6 | 550 | #[stable(feature = "cstring_into", since = "1.7.0")] |
b039eaaf | 551 | pub fn into_string(self) -> Result<String, IntoStringError> { |
dfeec247 XL |
552 | String::from_utf8(self.into_bytes()).map_err(|e| IntoStringError { |
553 | error: e.utf8_error(), | |
554 | inner: unsafe { CString::from_vec_unchecked(e.into_bytes()) }, | |
555 | }) | |
b039eaaf SL |
556 | } |
557 | ||
abe05a73 | 558 | /// Consumes the `CString` and returns the underlying byte buffer. |
b039eaaf | 559 | /// |
abe05a73 XL |
560 | /// The returned buffer does **not** contain the trailing nul |
561 | /// terminator, and it is guaranteed to not have any interior nul | |
562 | /// bytes. | |
041b39d2 XL |
563 | /// |
564 | /// # Examples | |
565 | /// | |
566 | /// ``` | |
567 | /// use std::ffi::CString; | |
568 | /// | |
b7449926 | 569 | /// let c_string = CString::new("foo").expect("CString::new failed"); |
041b39d2 XL |
570 | /// let bytes = c_string.into_bytes(); |
571 | /// assert_eq!(bytes, vec![b'f', b'o', b'o']); | |
572 | /// ``` | |
9cc50fc6 | 573 | #[stable(feature = "cstring_into", since = "1.7.0")] |
b039eaaf | 574 | pub fn into_bytes(self) -> Vec<u8> { |
9e0c209e | 575 | let mut vec = self.into_inner().into_vec(); |
b039eaaf SL |
576 | let _nul = vec.pop(); |
577 | debug_assert_eq!(_nul, Some(0u8)); | |
578 | vec | |
579 | } | |
580 | ||
3dfed10e XL |
581 | /// Equivalent to [`CString::into_bytes()`] except that the |
582 | /// returned vector includes the trailing nul terminator. | |
041b39d2 XL |
583 | /// |
584 | /// # Examples | |
585 | /// | |
586 | /// ``` | |
587 | /// use std::ffi::CString; | |
588 | /// | |
b7449926 | 589 | /// let c_string = CString::new("foo").expect("CString::new failed"); |
041b39d2 XL |
590 | /// let bytes = c_string.into_bytes_with_nul(); |
591 | /// assert_eq!(bytes, vec![b'f', b'o', b'o', b'\0']); | |
592 | /// ``` | |
9cc50fc6 | 593 | #[stable(feature = "cstring_into", since = "1.7.0")] |
b039eaaf | 594 | pub fn into_bytes_with_nul(self) -> Vec<u8> { |
9e0c209e | 595 | self.into_inner().into_vec() |
b039eaaf SL |
596 | } |
597 | ||
85aaf69f SL |
598 | /// Returns the contents of this `CString` as a slice of bytes. |
599 | /// | |
abe05a73 XL |
600 | /// The returned slice does **not** contain the trailing nul |
601 | /// terminator, and it is guaranteed to not have any interior nul | |
602 | /// bytes. If you need the nul terminator, use | |
3dfed10e | 603 | /// [`CString::as_bytes_with_nul`] instead. |
041b39d2 XL |
604 | /// |
605 | /// # Examples | |
606 | /// | |
607 | /// ``` | |
608 | /// use std::ffi::CString; | |
609 | /// | |
b7449926 | 610 | /// let c_string = CString::new("foo").expect("CString::new failed"); |
041b39d2 XL |
611 | /// let bytes = c_string.as_bytes(); |
612 | /// assert_eq!(bytes, &[b'f', b'o', b'o']); | |
613 | /// ``` | |
614 | #[inline] | |
c34b1796 | 615 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 616 | pub fn as_bytes(&self) -> &[u8] { |
85aaf69f | 617 | &self.inner[..self.inner.len() - 1] |
1a4d82fc JJ |
618 | } |
619 | ||
3dfed10e XL |
620 | /// Equivalent to [`CString::as_bytes()`] except that the |
621 | /// returned slice includes the trailing nul terminator. | |
041b39d2 XL |
622 | /// |
623 | /// # Examples | |
624 | /// | |
625 | /// ``` | |
626 | /// use std::ffi::CString; | |
627 | /// | |
b7449926 | 628 | /// let c_string = CString::new("foo").expect("CString::new failed"); |
041b39d2 XL |
629 | /// let bytes = c_string.as_bytes_with_nul(); |
630 | /// assert_eq!(bytes, &[b'f', b'o', b'o', b'\0']); | |
631 | /// ``` | |
632 | #[inline] | |
c34b1796 | 633 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 634 | pub fn as_bytes_with_nul(&self) -> &[u8] { |
85aaf69f | 635 | &self.inner |
1a4d82fc | 636 | } |
9e0c209e | 637 | |
7cac9316 XL |
638 | /// Extracts a [`CStr`] slice containing the entire string. |
639 | /// | |
041b39d2 XL |
640 | /// # Examples |
641 | /// | |
642 | /// ``` | |
643 | /// use std::ffi::{CString, CStr}; | |
644 | /// | |
b7449926 | 645 | /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed"); |
e1599b0c XL |
646 | /// let cstr = c_string.as_c_str(); |
647 | /// assert_eq!(cstr, | |
b7449926 | 648 | /// CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed")); |
041b39d2 XL |
649 | /// ``` |
650 | #[inline] | |
651 | #[stable(feature = "as_c_str", since = "1.20.0")] | |
cc61c64b XL |
652 | pub fn as_c_str(&self) -> &CStr { |
653 | &*self | |
654 | } | |
655 | ||
7cac9316 XL |
656 | /// Converts this `CString` into a boxed [`CStr`]. |
657 | /// | |
041b39d2 XL |
658 | /// # Examples |
659 | /// | |
660 | /// ``` | |
661 | /// use std::ffi::{CString, CStr}; | |
662 | /// | |
b7449926 | 663 | /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed"); |
041b39d2 | 664 | /// let boxed = c_string.into_boxed_c_str(); |
b7449926 XL |
665 | /// assert_eq!(&*boxed, |
666 | /// CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed")); | |
041b39d2 XL |
667 | /// ``` |
668 | #[stable(feature = "into_boxed_c_str", since = "1.20.0")] | |
8bb4bdeb | 669 | pub fn into_boxed_c_str(self) -> Box<CStr> { |
ea8adc8c | 670 | unsafe { Box::from_raw(Box::into_raw(self.into_inner()) as *mut CStr) } |
8bb4bdeb XL |
671 | } |
672 | ||
b7449926 | 673 | /// Bypass "move out of struct which implements [`Drop`] trait" restriction. |
9e0c209e | 674 | fn into_inner(self) -> Box<[u8]> { |
416331ca XL |
675 | // Rationale: `mem::forget(self)` invalidates the previous call to `ptr::read(&self.inner)` |
676 | // so we use `ManuallyDrop` to ensure `self` is not dropped. | |
677 | // Then we can return the box directly without invalidating it. | |
678 | // See https://github.com/rust-lang/rust/issues/62553. | |
679 | let this = mem::ManuallyDrop::new(self); | |
680 | unsafe { ptr::read(&this.inner) } | |
9e0c209e | 681 | } |
f035d41b | 682 | |
3dfed10e XL |
683 | /// Converts a [`Vec`]`<u8>` to a [`CString`] without checking the |
684 | /// invariants on the given [`Vec`]. | |
f035d41b XL |
685 | /// |
686 | /// # Safety | |
687 | /// | |
3dfed10e | 688 | /// The given [`Vec`] **must** have one nul byte as its last element. |
f035d41b XL |
689 | /// This means it cannot be empty nor have any other nul byte anywhere else. |
690 | /// | |
691 | /// # Example | |
692 | /// | |
693 | /// ``` | |
694 | /// #![feature(cstring_from_vec_with_nul)] | |
695 | /// use std::ffi::CString; | |
696 | /// assert_eq!( | |
697 | /// unsafe { CString::from_vec_with_nul_unchecked(b"abc\0".to_vec()) }, | |
698 | /// unsafe { CString::from_vec_unchecked(b"abc".to_vec()) } | |
699 | /// ); | |
700 | /// ``` | |
701 | #[unstable(feature = "cstring_from_vec_with_nul", issue = "73179")] | |
702 | pub unsafe fn from_vec_with_nul_unchecked(v: Vec<u8>) -> Self { | |
703 | Self { inner: v.into_boxed_slice() } | |
704 | } | |
705 | ||
3dfed10e | 706 | /// Attempts to converts a [`Vec`]`<u8>` to a [`CString`]. |
f035d41b XL |
707 | /// |
708 | /// Runtime checks are present to ensure there is only one nul byte in the | |
3dfed10e | 709 | /// [`Vec`], its last element. |
f035d41b XL |
710 | /// |
711 | /// # Errors | |
712 | /// | |
713 | /// If a nul byte is present and not the last element or no nul bytes | |
714 | /// is present, an error will be returned. | |
715 | /// | |
716 | /// # Examples | |
717 | /// | |
3dfed10e XL |
718 | /// A successful conversion will produce the same result as [`CString::new`] |
719 | /// when called without the ending nul byte. | |
f035d41b XL |
720 | /// |
721 | /// ``` | |
722 | /// #![feature(cstring_from_vec_with_nul)] | |
723 | /// use std::ffi::CString; | |
724 | /// assert_eq!( | |
725 | /// CString::from_vec_with_nul(b"abc\0".to_vec()) | |
726 | /// .expect("CString::from_vec_with_nul failed"), | |
727 | /// CString::new(b"abc".to_vec()).expect("CString::new failed") | |
728 | /// ); | |
729 | /// ``` | |
730 | /// | |
3dfed10e | 731 | /// A incorrectly formatted [`Vec`] will produce an error. |
f035d41b XL |
732 | /// |
733 | /// ``` | |
734 | /// #![feature(cstring_from_vec_with_nul)] | |
735 | /// use std::ffi::{CString, FromVecWithNulError}; | |
736 | /// // Interior nul byte | |
737 | /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"a\0bc".to_vec()).unwrap_err(); | |
738 | /// // No nul byte | |
739 | /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"abc".to_vec()).unwrap_err(); | |
740 | /// ``` | |
f035d41b XL |
741 | #[unstable(feature = "cstring_from_vec_with_nul", issue = "73179")] |
742 | pub fn from_vec_with_nul(v: Vec<u8>) -> Result<Self, FromVecWithNulError> { | |
743 | let nul_pos = memchr::memchr(0, &v); | |
744 | match nul_pos { | |
745 | Some(nul_pos) if nul_pos + 1 == v.len() => { | |
746 | // SAFETY: We know there is only one nul byte, at the end | |
747 | // of the vec. | |
748 | Ok(unsafe { Self::from_vec_with_nul_unchecked(v) }) | |
749 | } | |
750 | Some(nul_pos) => Err(FromVecWithNulError { | |
751 | error_kind: FromBytesWithNulErrorKind::InteriorNul(nul_pos), | |
752 | bytes: v, | |
753 | }), | |
754 | None => Err(FromVecWithNulError { | |
755 | error_kind: FromBytesWithNulErrorKind::NotNulTerminated, | |
756 | bytes: v, | |
757 | }), | |
758 | } | |
759 | } | |
9e0c209e SL |
760 | } |
761 | ||
762 | // Turns this `CString` into an empty string to prevent | |
e1599b0c | 763 | // memory-unsafe code from working by accident. Inline |
c30ab7b3 | 764 | // to prevent LLVM from optimizing it away in debug builds. |
9e0c209e SL |
765 | #[stable(feature = "cstring_drop", since = "1.13.0")] |
766 | impl Drop for CString { | |
c30ab7b3 | 767 | #[inline] |
9e0c209e | 768 | fn drop(&mut self) { |
dfeec247 XL |
769 | unsafe { |
770 | *self.inner.get_unchecked_mut(0) = 0; | |
771 | } | |
9e0c209e | 772 | } |
1a4d82fc JJ |
773 | } |
774 | ||
c34b1796 | 775 | #[stable(feature = "rust1", since = "1.0.0")] |
9cc50fc6 | 776 | impl ops::Deref for CString { |
85aaf69f | 777 | type Target = CStr; |
1a4d82fc | 778 | |
041b39d2 | 779 | #[inline] |
85aaf69f | 780 | fn deref(&self) -> &CStr { |
cc61c64b | 781 | unsafe { CStr::from_bytes_with_nul_unchecked(self.as_bytes_with_nul()) } |
1a4d82fc JJ |
782 | } |
783 | } | |
784 | ||
85aaf69f SL |
785 | #[stable(feature = "rust1", since = "1.0.0")] |
786 | impl fmt::Debug for CString { | |
532ac7d7 | 787 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
c1a9b12d SL |
788 | fmt::Debug::fmt(&**self, f) |
789 | } | |
790 | } | |
791 | ||
9cc50fc6 SL |
792 | #[stable(feature = "cstring_into", since = "1.7.0")] |
793 | impl From<CString> for Vec<u8> { | |
b7449926 XL |
794 | /// Converts a [`CString`] into a [`Vec`]`<u8>`. |
795 | /// | |
796 | /// The conversion consumes the [`CString`], and removes the terminating NUL byte. | |
041b39d2 | 797 | #[inline] |
9cc50fc6 SL |
798 | fn from(s: CString) -> Vec<u8> { |
799 | s.into_bytes() | |
800 | } | |
801 | } | |
802 | ||
c1a9b12d SL |
803 | #[stable(feature = "cstr_debug", since = "1.3.0")] |
804 | impl fmt::Debug for CStr { | |
532ac7d7 | 805 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
54a0048b | 806 | write!(f, "\"")?; |
c1a9b12d | 807 | for byte in self.to_bytes().iter().flat_map(|&b| ascii::escape_default(b)) { |
54a0048b | 808 | f.write_char(byte as char)?; |
c1a9b12d SL |
809 | } |
810 | write!(f, "\"") | |
1a4d82fc JJ |
811 | } |
812 | } | |
813 | ||
a7813a04 | 814 | #[stable(feature = "cstr_default", since = "1.10.0")] |
9fa01778 XL |
815 | impl Default for &CStr { |
816 | fn default() -> Self { | |
0731742a | 817 | const SLICE: &[c_char] = &[0]; |
a7813a04 XL |
818 | unsafe { CStr::from_ptr(SLICE.as_ptr()) } |
819 | } | |
820 | } | |
821 | ||
822 | #[stable(feature = "cstr_default", since = "1.10.0")] | |
823 | impl Default for CString { | |
9e0c209e | 824 | /// Creates an empty `CString`. |
a7813a04 XL |
825 | fn default() -> CString { |
826 | let a: &CStr = Default::default(); | |
827 | a.to_owned() | |
828 | } | |
829 | } | |
830 | ||
c1a9b12d SL |
831 | #[stable(feature = "cstr_borrow", since = "1.3.0")] |
832 | impl Borrow<CStr> for CString { | |
041b39d2 | 833 | #[inline] |
dfeec247 XL |
834 | fn borrow(&self) -> &CStr { |
835 | self | |
836 | } | |
c1a9b12d SL |
837 | } |
838 | ||
94b46f34 XL |
839 | #[stable(feature = "cstring_from_cow_cstr", since = "1.28.0")] |
840 | impl<'a> From<Cow<'a, CStr>> for CString { | |
841 | #[inline] | |
842 | fn from(s: Cow<'a, CStr>) -> Self { | |
843 | s.into_owned() | |
844 | } | |
845 | } | |
846 | ||
8bb4bdeb | 847 | #[stable(feature = "box_from_c_str", since = "1.17.0")] |
532ac7d7 XL |
848 | impl From<&CStr> for Box<CStr> { |
849 | fn from(s: &CStr) -> Box<CStr> { | |
8bb4bdeb | 850 | let boxed: Box<[u8]> = Box::from(s.to_bytes_with_nul()); |
ea8adc8c | 851 | unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) } |
8bb4bdeb XL |
852 | } |
853 | } | |
854 | ||
f9f354fc XL |
855 | #[stable(feature = "box_from_cow", since = "1.45.0")] |
856 | impl From<Cow<'_, CStr>> for Box<CStr> { | |
857 | #[inline] | |
858 | fn from(cow: Cow<'_, CStr>) -> Box<CStr> { | |
859 | match cow { | |
860 | Cow::Borrowed(s) => Box::from(s), | |
861 | Cow::Owned(s) => Box::from(s), | |
862 | } | |
863 | } | |
864 | } | |
865 | ||
7cac9316 | 866 | #[stable(feature = "c_string_from_box", since = "1.18.0")] |
cc61c64b | 867 | impl From<Box<CStr>> for CString { |
b7449926 | 868 | /// Converts a [`Box`]`<CStr>` into a [`CString`] without copying or allocating. |
041b39d2 | 869 | #[inline] |
cc61c64b XL |
870 | fn from(s: Box<CStr>) -> CString { |
871 | s.into_c_string() | |
872 | } | |
873 | } | |
874 | ||
74b04a01 XL |
875 | #[stable(feature = "cstring_from_vec_of_nonzerou8", since = "1.43.0")] |
876 | impl From<Vec<NonZeroU8>> for CString { | |
877 | /// Converts a [`Vec`]`<`[`NonZeroU8`]`>` into a [`CString`] without | |
878 | /// copying nor checking for inner null bytes. | |
74b04a01 XL |
879 | #[inline] |
880 | fn from(v: Vec<NonZeroU8>) -> CString { | |
881 | unsafe { | |
882 | // Transmute `Vec<NonZeroU8>` to `Vec<u8>`. | |
883 | let v: Vec<u8> = { | |
1b1a35ee | 884 | // SAFETY: |
74b04a01 XL |
885 | // - transmuting between `NonZeroU8` and `u8` is sound; |
886 | // - `alloc::Layout<NonZeroU8> == alloc::Layout<u8>`. | |
887 | let (ptr, len, cap): (*mut NonZeroU8, _, _) = Vec::into_raw_parts(v); | |
888 | Vec::from_raw_parts(ptr.cast::<u8>(), len, cap) | |
889 | }; | |
1b1a35ee | 890 | // SAFETY: `v` cannot contain null bytes, given the type-level |
74b04a01 XL |
891 | // invariant of `NonZeroU8`. |
892 | CString::from_vec_unchecked(v) | |
893 | } | |
894 | } | |
895 | } | |
896 | ||
8faf50e0 XL |
897 | #[stable(feature = "more_box_slice_clone", since = "1.29.0")] |
898 | impl Clone for Box<CStr> { | |
899 | #[inline] | |
900 | fn clone(&self) -> Self { | |
901 | (**self).into() | |
902 | } | |
903 | } | |
904 | ||
041b39d2 XL |
905 | #[stable(feature = "box_from_c_string", since = "1.20.0")] |
906 | impl From<CString> for Box<CStr> { | |
b7449926 | 907 | /// Converts a [`CString`] into a [`Box`]`<CStr>` without copying or allocating. |
041b39d2 XL |
908 | #[inline] |
909 | fn from(s: CString) -> Box<CStr> { | |
910 | s.into_boxed_c_str() | |
cc61c64b XL |
911 | } |
912 | } | |
913 | ||
94b46f34 XL |
914 | #[stable(feature = "cow_from_cstr", since = "1.28.0")] |
915 | impl<'a> From<CString> for Cow<'a, CStr> { | |
916 | #[inline] | |
917 | fn from(s: CString) -> Cow<'a, CStr> { | |
918 | Cow::Owned(s) | |
919 | } | |
920 | } | |
921 | ||
922 | #[stable(feature = "cow_from_cstr", since = "1.28.0")] | |
923 | impl<'a> From<&'a CStr> for Cow<'a, CStr> { | |
924 | #[inline] | |
925 | fn from(s: &'a CStr) -> Cow<'a, CStr> { | |
926 | Cow::Borrowed(s) | |
927 | } | |
928 | } | |
929 | ||
930 | #[stable(feature = "cow_from_cstr", since = "1.28.0")] | |
931 | impl<'a> From<&'a CString> for Cow<'a, CStr> { | |
932 | #[inline] | |
933 | fn from(s: &'a CString) -> Cow<'a, CStr> { | |
934 | Cow::Borrowed(s.as_c_str()) | |
935 | } | |
936 | } | |
937 | ||
2c00a5a8 | 938 | #[stable(feature = "shared_from_slice2", since = "1.24.0")] |
ff7c6d11 | 939 | impl From<CString> for Arc<CStr> { |
b7449926 | 940 | /// Converts a [`CString`] into a [`Arc`]`<CStr>` without copying or allocating. |
ff7c6d11 XL |
941 | #[inline] |
942 | fn from(s: CString) -> Arc<CStr> { | |
943 | let arc: Arc<[u8]> = Arc::from(s.into_inner()); | |
944 | unsafe { Arc::from_raw(Arc::into_raw(arc) as *const CStr) } | |
945 | } | |
946 | } | |
947 | ||
2c00a5a8 | 948 | #[stable(feature = "shared_from_slice2", since = "1.24.0")] |
532ac7d7 | 949 | impl From<&CStr> for Arc<CStr> { |
ff7c6d11 XL |
950 | #[inline] |
951 | fn from(s: &CStr) -> Arc<CStr> { | |
952 | let arc: Arc<[u8]> = Arc::from(s.to_bytes_with_nul()); | |
953 | unsafe { Arc::from_raw(Arc::into_raw(arc) as *const CStr) } | |
954 | } | |
955 | } | |
956 | ||
2c00a5a8 | 957 | #[stable(feature = "shared_from_slice2", since = "1.24.0")] |
ff7c6d11 | 958 | impl From<CString> for Rc<CStr> { |
b7449926 | 959 | /// Converts a [`CString`] into a [`Rc`]`<CStr>` without copying or allocating. |
ff7c6d11 XL |
960 | #[inline] |
961 | fn from(s: CString) -> Rc<CStr> { | |
962 | let rc: Rc<[u8]> = Rc::from(s.into_inner()); | |
963 | unsafe { Rc::from_raw(Rc::into_raw(rc) as *const CStr) } | |
964 | } | |
965 | } | |
966 | ||
2c00a5a8 | 967 | #[stable(feature = "shared_from_slice2", since = "1.24.0")] |
532ac7d7 | 968 | impl From<&CStr> for Rc<CStr> { |
ff7c6d11 XL |
969 | #[inline] |
970 | fn from(s: &CStr) -> Rc<CStr> { | |
971 | let rc: Rc<[u8]> = Rc::from(s.to_bytes_with_nul()); | |
972 | unsafe { Rc::from_raw(Rc::into_raw(rc) as *const CStr) } | |
973 | } | |
974 | } | |
975 | ||
8bb4bdeb XL |
976 | #[stable(feature = "default_box_extra", since = "1.17.0")] |
977 | impl Default for Box<CStr> { | |
978 | fn default() -> Box<CStr> { | |
979 | let boxed: Box<[u8]> = Box::from([0]); | |
ea8adc8c | 980 | unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) } |
8bb4bdeb XL |
981 | } |
982 | } | |
983 | ||
85aaf69f | 984 | impl NulError { |
abe05a73 XL |
985 | /// Returns the position of the nul byte in the slice that caused |
986 | /// [`CString::new`] to fail. | |
7cac9316 | 987 | /// |
5bcae85e SL |
988 | /// # Examples |
989 | /// | |
990 | /// ``` | |
991 | /// use std::ffi::CString; | |
992 | /// | |
993 | /// let nul_error = CString::new("foo\0bar").unwrap_err(); | |
994 | /// assert_eq!(nul_error.nul_position(), 3); | |
995 | /// | |
996 | /// let nul_error = CString::new("foo bar\0").unwrap_err(); | |
997 | /// assert_eq!(nul_error.nul_position(), 7); | |
998 | /// ``` | |
c34b1796 | 999 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 XL |
1000 | pub fn nul_position(&self) -> usize { |
1001 | self.0 | |
1002 | } | |
85aaf69f SL |
1003 | |
1004 | /// Consumes this error, returning the underlying vector of bytes which | |
1005 | /// generated the error in the first place. | |
5bcae85e SL |
1006 | /// |
1007 | /// # Examples | |
1008 | /// | |
1009 | /// ``` | |
1010 | /// use std::ffi::CString; | |
1011 | /// | |
1012 | /// let nul_error = CString::new("foo\0bar").unwrap_err(); | |
1013 | /// assert_eq!(nul_error.into_vec(), b"foo\0bar"); | |
1014 | /// ``` | |
c34b1796 | 1015 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 XL |
1016 | pub fn into_vec(self) -> Vec<u8> { |
1017 | self.1 | |
1018 | } | |
85aaf69f SL |
1019 | } |
1020 | ||
c34b1796 | 1021 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 1022 | impl Error for NulError { |
dfeec247 XL |
1023 | #[allow(deprecated)] |
1024 | fn description(&self) -> &str { | |
1025 | "nul byte found in data" | |
1026 | } | |
85aaf69f SL |
1027 | } |
1028 | ||
c34b1796 | 1029 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 1030 | impl fmt::Display for NulError { |
532ac7d7 | 1031 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
85aaf69f SL |
1032 | write!(f, "nul byte found in provided data at position: {}", self.0) |
1033 | } | |
1034 | } | |
1035 | ||
c34b1796 AL |
1036 | #[stable(feature = "rust1", since = "1.0.0")] |
1037 | impl From<NulError> for io::Error { | |
b7449926 | 1038 | /// Converts a [`NulError`] into a [`io::Error`]. |
c34b1796 | 1039 | fn from(_: NulError) -> io::Error { |
dfeec247 | 1040 | io::Error::new(io::ErrorKind::InvalidInput, "data provided contains a nul byte") |
85aaf69f SL |
1041 | } |
1042 | } | |
1043 | ||
8bb4bdeb XL |
1044 | #[stable(feature = "frombyteswithnulerror_impls", since = "1.17.0")] |
1045 | impl Error for FromBytesWithNulError { | |
dfeec247 | 1046 | #[allow(deprecated)] |
8bb4bdeb XL |
1047 | fn description(&self) -> &str { |
1048 | match self.kind { | |
dfeec247 XL |
1049 | FromBytesWithNulErrorKind::InteriorNul(..) => { |
1050 | "data provided contains an interior nul byte" | |
1051 | } | |
1052 | FromBytesWithNulErrorKind::NotNulTerminated => "data provided is not nul terminated", | |
8bb4bdeb XL |
1053 | } |
1054 | } | |
1055 | } | |
1056 | ||
1057 | #[stable(feature = "frombyteswithnulerror_impls", since = "1.17.0")] | |
1058 | impl fmt::Display for FromBytesWithNulError { | |
dfeec247 | 1059 | #[allow(deprecated, deprecated_in_future)] |
532ac7d7 | 1060 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
8bb4bdeb XL |
1061 | f.write_str(self.description())?; |
1062 | if let FromBytesWithNulErrorKind::InteriorNul(pos) = self.kind { | |
1063 | write!(f, " at byte pos {}", pos)?; | |
1064 | } | |
1065 | Ok(()) | |
1066 | } | |
1067 | } | |
1068 | ||
f035d41b XL |
1069 | #[unstable(feature = "cstring_from_vec_with_nul", issue = "73179")] |
1070 | impl Error for FromVecWithNulError {} | |
1071 | ||
1072 | #[unstable(feature = "cstring_from_vec_with_nul", issue = "73179")] | |
1073 | impl fmt::Display for FromVecWithNulError { | |
1074 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { | |
1075 | match self.error_kind { | |
1076 | FromBytesWithNulErrorKind::InteriorNul(pos) => { | |
1077 | write!(f, "data provided contains an interior nul byte at pos {}", pos) | |
1078 | } | |
1079 | FromBytesWithNulErrorKind::NotNulTerminated => { | |
1080 | write!(f, "data provided is not nul terminated") | |
1081 | } | |
1082 | } | |
1083 | } | |
1084 | } | |
1085 | ||
b039eaaf | 1086 | impl IntoStringError { |
7cac9316 | 1087 | /// Consumes this error, returning original [`CString`] which generated the |
b039eaaf | 1088 | /// error. |
9cc50fc6 | 1089 | #[stable(feature = "cstring_into", since = "1.7.0")] |
b039eaaf SL |
1090 | pub fn into_cstring(self) -> CString { |
1091 | self.inner | |
1092 | } | |
1093 | ||
1094 | /// Access the underlying UTF-8 error that was the cause of this error. | |
9cc50fc6 | 1095 | #[stable(feature = "cstring_into", since = "1.7.0")] |
b039eaaf SL |
1096 | pub fn utf8_error(&self) -> Utf8Error { |
1097 | self.error | |
1098 | } | |
1099 | } | |
1100 | ||
9cc50fc6 | 1101 | #[stable(feature = "cstring_into", since = "1.7.0")] |
b039eaaf | 1102 | impl Error for IntoStringError { |
dfeec247 | 1103 | #[allow(deprecated)] |
b039eaaf | 1104 | fn description(&self) -> &str { |
9cc50fc6 SL |
1105 | "C string contained non-utf8 bytes" |
1106 | } | |
1107 | ||
e74abb32 | 1108 | fn source(&self) -> Option<&(dyn Error + 'static)> { |
9cc50fc6 | 1109 | Some(&self.error) |
b039eaaf SL |
1110 | } |
1111 | } | |
1112 | ||
9cc50fc6 | 1113 | #[stable(feature = "cstring_into", since = "1.7.0")] |
b039eaaf | 1114 | impl fmt::Display for IntoStringError { |
dfeec247 | 1115 | #[allow(deprecated, deprecated_in_future)] |
532ac7d7 | 1116 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
9cc50fc6 | 1117 | self.description().fmt(f) |
b039eaaf SL |
1118 | } |
1119 | } | |
1120 | ||
85aaf69f | 1121 | impl CStr { |
abe05a73 | 1122 | /// Wraps a raw C string with a safe C string wrapper. |
85aaf69f | 1123 | /// |
abe05a73 | 1124 | /// This function will wrap the provided `ptr` with a `CStr` wrapper, which |
e1599b0c XL |
1125 | /// allows inspection and interoperation of non-owned C strings. The total |
1126 | /// size of the raw C string must be smaller than `isize::MAX` **bytes** | |
1127 | /// in memory due to calling the `slice::from_raw_parts` function. | |
1128 | /// This method is unsafe for a number of reasons: | |
85aaf69f | 1129 | /// |
7cac9316 | 1130 | /// * There is no guarantee to the validity of `ptr`. |
85aaf69f | 1131 | /// * The returned lifetime is not guaranteed to be the actual lifetime of |
7cac9316 | 1132 | /// `ptr`. |
85aaf69f SL |
1133 | /// * There is no guarantee that the memory pointed to by `ptr` contains a |
1134 | /// valid nul terminator byte at the end of the string. | |
0531ce1d XL |
1135 | /// * It is not guaranteed that the memory pointed by `ptr` won't change |
1136 | /// before the `CStr` has been destroyed. | |
85aaf69f SL |
1137 | /// |
1138 | /// > **Note**: This operation is intended to be a 0-cost cast but it is | |
1139 | /// > currently implemented with an up-front calculation of the length of | |
1140 | /// > the string. This is not guaranteed to always be the case. | |
1141 | /// | |
c34b1796 | 1142 | /// # Examples |
85aaf69f | 1143 | /// |
0531ce1d | 1144 | /// ```ignore (extern-declaration) |
85aaf69f SL |
1145 | /// # fn main() { |
1146 | /// use std::ffi::CStr; | |
92a42be0 | 1147 | /// use std::os::raw::c_char; |
85aaf69f SL |
1148 | /// |
1149 | /// extern { | |
92a42be0 | 1150 | /// fn my_string() -> *const c_char; |
85aaf69f SL |
1151 | /// } |
1152 | /// | |
1153 | /// unsafe { | |
1154 | /// let slice = CStr::from_ptr(my_string()); | |
7453a54e | 1155 | /// println!("string returned: {}", slice.to_str().unwrap()); |
85aaf69f SL |
1156 | /// } |
1157 | /// # } | |
1158 | /// ``` | |
c34b1796 | 1159 | #[stable(feature = "rust1", since = "1.0.0")] |
92a42be0 | 1160 | pub unsafe fn from_ptr<'a>(ptr: *const c_char) -> &'a CStr { |
3dfed10e XL |
1161 | // SAFETY: The caller has provided a pointer that points to a valid C |
1162 | // string with a NUL terminator of size less than `isize::MAX`, whose | |
1163 | // content remain valid and doesn't change for the lifetime of the | |
1164 | // returned `CStr`. | |
1165 | // | |
1166 | // Thus computing the length is fine (a NUL byte exists), the call to | |
1167 | // from_raw_parts is safe because we know the length is at most `isize::MAX`, meaning | |
1168 | // the call to `from_bytes_with_nul_unchecked` is correct. | |
1169 | // | |
1170 | // The cast from c_char to u8 is ok because a c_char is always one byte. | |
1171 | unsafe { | |
1172 | let len = sys::strlen(ptr); | |
1173 | let ptr = ptr as *const u8; | |
1174 | CStr::from_bytes_with_nul_unchecked(slice::from_raw_parts(ptr, len as usize + 1)) | |
1175 | } | |
85aaf69f SL |
1176 | } |
1177 | ||
7453a54e SL |
1178 | /// Creates a C string wrapper from a byte slice. |
1179 | /// | |
abe05a73 XL |
1180 | /// This function will cast the provided `bytes` to a `CStr` |
1181 | /// wrapper after ensuring that the byte slice is nul-terminated | |
1182 | /// and does not contain any interior nul bytes. | |
7453a54e SL |
1183 | /// |
1184 | /// # Examples | |
1185 | /// | |
1186 | /// ``` | |
7453a54e SL |
1187 | /// use std::ffi::CStr; |
1188 | /// | |
7453a54e | 1189 | /// let cstr = CStr::from_bytes_with_nul(b"hello\0"); |
a7813a04 | 1190 | /// assert!(cstr.is_ok()); |
7453a54e | 1191 | /// ``` |
041b39d2 | 1192 | /// |
abe05a73 | 1193 | /// Creating a `CStr` without a trailing nul terminator is an error: |
041b39d2 XL |
1194 | /// |
1195 | /// ``` | |
1196 | /// use std::ffi::CStr; | |
1197 | /// | |
e1599b0c XL |
1198 | /// let cstr = CStr::from_bytes_with_nul(b"hello"); |
1199 | /// assert!(cstr.is_err()); | |
041b39d2 XL |
1200 | /// ``` |
1201 | /// | |
1202 | /// Creating a `CStr` with an interior nul byte is an error: | |
1203 | /// | |
1204 | /// ``` | |
1205 | /// use std::ffi::CStr; | |
1206 | /// | |
e1599b0c XL |
1207 | /// let cstr = CStr::from_bytes_with_nul(b"he\0llo\0"); |
1208 | /// assert!(cstr.is_err()); | |
041b39d2 | 1209 | /// ``` |
a7813a04 | 1210 | #[stable(feature = "cstr_from_bytes", since = "1.10.0")] |
dfeec247 | 1211 | pub fn from_bytes_with_nul(bytes: &[u8]) -> Result<&CStr, FromBytesWithNulError> { |
8bb4bdeb XL |
1212 | let nul_pos = memchr::memchr(0, bytes); |
1213 | if let Some(nul_pos) = nul_pos { | |
1214 | if nul_pos + 1 != bytes.len() { | |
1215 | return Err(FromBytesWithNulError::interior_nul(nul_pos)); | |
1216 | } | |
1217 | Ok(unsafe { CStr::from_bytes_with_nul_unchecked(bytes) }) | |
7453a54e | 1218 | } else { |
8bb4bdeb | 1219 | Err(FromBytesWithNulError::not_nul_terminated()) |
7453a54e SL |
1220 | } |
1221 | } | |
1222 | ||
1223 | /// Unsafely creates a C string wrapper from a byte slice. | |
1224 | /// | |
1225 | /// This function will cast the provided `bytes` to a `CStr` wrapper without | |
abe05a73 | 1226 | /// performing any sanity checks. The provided slice **must** be nul-terminated |
7453a54e SL |
1227 | /// and not contain any interior nul bytes. |
1228 | /// | |
1229 | /// # Examples | |
1230 | /// | |
1231 | /// ``` | |
7453a54e SL |
1232 | /// use std::ffi::{CStr, CString}; |
1233 | /// | |
7453a54e | 1234 | /// unsafe { |
b7449926 | 1235 | /// let cstring = CString::new("hello").expect("CString::new failed"); |
7453a54e SL |
1236 | /// let cstr = CStr::from_bytes_with_nul_unchecked(cstring.to_bytes_with_nul()); |
1237 | /// assert_eq!(cstr, &*cstring); | |
1238 | /// } | |
7453a54e | 1239 | /// ``` |
041b39d2 | 1240 | #[inline] |
a7813a04 | 1241 | #[stable(feature = "cstr_from_bytes", since = "1.10.0")] |
dfeec247 | 1242 | #[rustc_const_unstable(feature = "const_cstr_unchecked", issue = "none")] |
0bf4aa26 | 1243 | pub const unsafe fn from_bytes_with_nul_unchecked(bytes: &[u8]) -> &CStr { |
3dfed10e XL |
1244 | // SAFETY: Casting to CStr is safe because its internal representation |
1245 | // is a [u8] too (safe only inside std). | |
1246 | // Dereferencing the obtained pointer is safe because it comes from a | |
1247 | // reference. Making a reference is then safe because its lifetime | |
1248 | // is bound by the lifetime of the given `bytes`. | |
1249 | unsafe { &*(bytes as *const [u8] as *const CStr) } | |
7453a54e SL |
1250 | } |
1251 | ||
9346a6ac | 1252 | /// Returns the inner pointer to this C string. |
85aaf69f | 1253 | /// |
abe05a73 | 1254 | /// The returned pointer will be valid for as long as `self` is, and points |
c34b1796 | 1255 | /// to a contiguous region of memory terminated with a 0 byte to represent |
85aaf69f | 1256 | /// the end of the string. |
3157f602 XL |
1257 | /// |
1258 | /// **WARNING** | |
1259 | /// | |
48663c56 XL |
1260 | /// The returned pointer is read-only; writing to it (including passing it |
1261 | /// to C code that writes to it) causes undefined behavior. | |
1262 | /// | |
3157f602 XL |
1263 | /// It is your responsibility to make sure that the underlying memory is not |
1264 | /// freed too early. For example, the following code will cause undefined | |
3b2f2976 | 1265 | /// behavior when `ptr` is used inside the `unsafe` block: |
3157f602 XL |
1266 | /// |
1267 | /// ```no_run | |
83c7162d | 1268 | /// # #![allow(unused_must_use)] |
416331ca | 1269 | /// use std::ffi::CString; |
3157f602 | 1270 | /// |
b7449926 | 1271 | /// let ptr = CString::new("Hello").expect("CString::new failed").as_ptr(); |
3157f602 XL |
1272 | /// unsafe { |
1273 | /// // `ptr` is dangling | |
1274 | /// *ptr; | |
1275 | /// } | |
1276 | /// ``` | |
1277 | /// | |
1278 | /// This happens because the pointer returned by `as_ptr` does not carry any | |
abe05a73 | 1279 | /// lifetime information and the [`CString`] is deallocated immediately after |
3dfed10e XL |
1280 | /// the `CString::new("Hello").expect("CString::new failed").as_ptr()` |
1281 | /// expression is evaluated. | |
abe05a73 | 1282 | /// To fix the problem, bind the `CString` to a local variable: |
3157f602 XL |
1283 | /// |
1284 | /// ```no_run | |
83c7162d | 1285 | /// # #![allow(unused_must_use)] |
416331ca | 1286 | /// use std::ffi::CString; |
3157f602 | 1287 | /// |
b7449926 | 1288 | /// let hello = CString::new("Hello").expect("CString::new failed"); |
3157f602 XL |
1289 | /// let ptr = hello.as_ptr(); |
1290 | /// unsafe { | |
1291 | /// // `ptr` is valid because `hello` is in scope | |
1292 | /// *ptr; | |
1293 | /// } | |
1294 | /// ``` | |
abe05a73 | 1295 | /// |
3dfed10e | 1296 | /// This way, the lifetime of the [`CString`] in `hello` encompasses |
abe05a73 | 1297 | /// the lifetime of `ptr` and the `unsafe` block. |
041b39d2 | 1298 | #[inline] |
c34b1796 | 1299 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 | 1300 | #[rustc_const_stable(feature = "const_str_as_ptr", since = "1.32.0")] |
a1dfa0c6 | 1301 | pub const fn as_ptr(&self) -> *const c_char { |
85aaf69f SL |
1302 | self.inner.as_ptr() |
1303 | } | |
1304 | ||
9346a6ac | 1305 | /// Converts this C string to a byte slice. |
85aaf69f | 1306 | /// |
abe05a73 | 1307 | /// The returned slice will **not** contain the trailing nul terminator that this C |
85aaf69f SL |
1308 | /// string has. |
1309 | /// | |
2c00a5a8 XL |
1310 | /// > **Note**: This method is currently implemented as a constant-time |
1311 | /// > cast, but it is planned to alter its definition in the future to | |
1312 | /// > perform the length calculation whenever this method is called. | |
041b39d2 XL |
1313 | /// |
1314 | /// # Examples | |
1315 | /// | |
1316 | /// ``` | |
1317 | /// use std::ffi::CStr; | |
1318 | /// | |
e1599b0c XL |
1319 | /// let cstr = CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"); |
1320 | /// assert_eq!(cstr.to_bytes(), b"foo"); | |
041b39d2 XL |
1321 | /// ``` |
1322 | #[inline] | |
c34b1796 | 1323 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f SL |
1324 | pub fn to_bytes(&self) -> &[u8] { |
1325 | let bytes = self.to_bytes_with_nul(); | |
1326 | &bytes[..bytes.len() - 1] | |
1327 | } | |
1328 | ||
9346a6ac | 1329 | /// Converts this C string to a byte slice containing the trailing 0 byte. |
85aaf69f | 1330 | /// |
3dfed10e XL |
1331 | /// This function is the equivalent of [`CStr::to_bytes`] except that it |
1332 | /// will retain the trailing nul terminator instead of chopping it off. | |
85aaf69f SL |
1333 | /// |
1334 | /// > **Note**: This method is currently implemented as a 0-cost cast, but | |
1335 | /// > it is planned to alter its definition in the future to perform the | |
1336 | /// > length calculation whenever this method is called. | |
7cac9316 | 1337 | /// |
041b39d2 XL |
1338 | /// # Examples |
1339 | /// | |
1340 | /// ``` | |
1341 | /// use std::ffi::CStr; | |
1342 | /// | |
e1599b0c XL |
1343 | /// let cstr = CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"); |
1344 | /// assert_eq!(cstr.to_bytes_with_nul(), b"foo\0"); | |
041b39d2 XL |
1345 | /// ``` |
1346 | #[inline] | |
c34b1796 | 1347 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 1348 | pub fn to_bytes_with_nul(&self) -> &[u8] { |
ea8adc8c | 1349 | unsafe { &*(&self.inner as *const [c_char] as *const [u8]) } |
85aaf69f | 1350 | } |
62682a34 | 1351 | |
7cac9316 | 1352 | /// Yields a [`&str`] slice if the `CStr` contains valid UTF-8. |
62682a34 | 1353 | /// |
abe05a73 XL |
1354 | /// If the contents of the `CStr` are valid UTF-8 data, this |
1355 | /// function will return the corresponding [`&str`] slice. Otherwise, | |
1356 | /// it will return an error with details of where UTF-8 validation failed. | |
62682a34 | 1357 | /// |
3dfed10e | 1358 | /// [`&str`]: prim@str |
041b39d2 XL |
1359 | /// |
1360 | /// # Examples | |
1361 | /// | |
1362 | /// ``` | |
1363 | /// use std::ffi::CStr; | |
1364 | /// | |
e1599b0c XL |
1365 | /// let cstr = CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"); |
1366 | /// assert_eq!(cstr.to_str(), Ok("foo")); | |
041b39d2 | 1367 | /// ``` |
e9174d1e | 1368 | #[stable(feature = "cstr_to_str", since = "1.4.0")] |
62682a34 | 1369 | pub fn to_str(&self) -> Result<&str, str::Utf8Error> { |
0731742a XL |
1370 | // N.B., when `CStr` is changed to perform the length check in `.to_bytes()` |
1371 | // instead of in `from_ptr()`, it may be worth considering if this should | |
e9174d1e SL |
1372 | // be rewritten to do the UTF-8 check inline with the length calculation |
1373 | // instead of doing it afterwards. | |
62682a34 SL |
1374 | str::from_utf8(self.to_bytes()) |
1375 | } | |
1376 | ||
7cac9316 | 1377 | /// Converts a `CStr` into a [`Cow`]`<`[`str`]`>`. |
62682a34 | 1378 | /// |
abe05a73 XL |
1379 | /// If the contents of the `CStr` are valid UTF-8 data, this |
1380 | /// function will return a [`Cow`]`::`[`Borrowed`]`(`[`&str`]`)` | |
a1dfa0c6 | 1381 | /// with the corresponding [`&str`] slice. Otherwise, it will |
b7449926 XL |
1382 | /// replace any invalid UTF-8 sequences with |
1383 | /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD] and return a | |
1384 | /// [`Cow`]`::`[`Owned`]`(`[`String`]`)` with the result. | |
62682a34 | 1385 | /// |
3dfed10e XL |
1386 | /// [`str`]: prim@str |
1387 | /// [`Borrowed`]: Cow::Borrowed | |
1388 | /// [`Owned`]: Cow::Owned | |
1389 | /// [U+FFFD]: crate::char::REPLACEMENT_CHARACTER | |
041b39d2 XL |
1390 | /// |
1391 | /// # Examples | |
1392 | /// | |
1393 | /// Calling `to_string_lossy` on a `CStr` containing valid UTF-8: | |
1394 | /// | |
1395 | /// ``` | |
1396 | /// use std::borrow::Cow; | |
1397 | /// use std::ffi::CStr; | |
1398 | /// | |
e1599b0c | 1399 | /// let cstr = CStr::from_bytes_with_nul(b"Hello World\0") |
b7449926 | 1400 | /// .expect("CStr::from_bytes_with_nul failed"); |
e1599b0c | 1401 | /// assert_eq!(cstr.to_string_lossy(), Cow::Borrowed("Hello World")); |
041b39d2 XL |
1402 | /// ``` |
1403 | /// | |
1404 | /// Calling `to_string_lossy` on a `CStr` containing invalid UTF-8: | |
1405 | /// | |
1406 | /// ``` | |
1407 | /// use std::borrow::Cow; | |
1408 | /// use std::ffi::CStr; | |
1409 | /// | |
e1599b0c | 1410 | /// let cstr = CStr::from_bytes_with_nul(b"Hello \xF0\x90\x80World\0") |
b7449926 | 1411 | /// .expect("CStr::from_bytes_with_nul failed"); |
041b39d2 | 1412 | /// assert_eq!( |
e1599b0c | 1413 | /// cstr.to_string_lossy(), |
532ac7d7 | 1414 | /// Cow::Owned(String::from("Hello �World")) as Cow<'_, str> |
041b39d2 XL |
1415 | /// ); |
1416 | /// ``` | |
e9174d1e | 1417 | #[stable(feature = "cstr_to_str", since = "1.4.0")] |
532ac7d7 | 1418 | pub fn to_string_lossy(&self) -> Cow<'_, str> { |
62682a34 SL |
1419 | String::from_utf8_lossy(self.to_bytes()) |
1420 | } | |
cc61c64b | 1421 | |
7cac9316 XL |
1422 | /// Converts a [`Box`]`<CStr>` into a [`CString`] without copying or allocating. |
1423 | /// | |
041b39d2 XL |
1424 | /// # Examples |
1425 | /// | |
1426 | /// ``` | |
1427 | /// use std::ffi::CString; | |
1428 | /// | |
b7449926 | 1429 | /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed"); |
041b39d2 | 1430 | /// let boxed = c_string.into_boxed_c_str(); |
b7449926 | 1431 | /// assert_eq!(boxed.into_c_string(), CString::new("foo").expect("CString::new failed")); |
041b39d2 XL |
1432 | /// ``` |
1433 | #[stable(feature = "into_boxed_c_str", since = "1.20.0")] | |
cc61c64b | 1434 | pub fn into_c_string(self: Box<CStr>) -> CString { |
ea8adc8c XL |
1435 | let raw = Box::into_raw(self) as *mut [u8]; |
1436 | CString { inner: unsafe { Box::from_raw(raw) } } | |
cc61c64b | 1437 | } |
85aaf69f SL |
1438 | } |
1439 | ||
c34b1796 | 1440 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f SL |
1441 | impl PartialEq for CStr { |
1442 | fn eq(&self, other: &CStr) -> bool { | |
c34b1796 | 1443 | self.to_bytes().eq(other.to_bytes()) |
85aaf69f SL |
1444 | } |
1445 | } | |
c34b1796 | 1446 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 1447 | impl Eq for CStr {} |
c34b1796 | 1448 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f SL |
1449 | impl PartialOrd for CStr { |
1450 | fn partial_cmp(&self, other: &CStr) -> Option<Ordering> { | |
1451 | self.to_bytes().partial_cmp(&other.to_bytes()) | |
1452 | } | |
1453 | } | |
c34b1796 | 1454 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f SL |
1455 | impl Ord for CStr { |
1456 | fn cmp(&self, other: &CStr) -> Ordering { | |
1457 | self.to_bytes().cmp(&other.to_bytes()) | |
1458 | } | |
1459 | } | |
1460 | ||
c1a9b12d SL |
1461 | #[stable(feature = "cstr_borrow", since = "1.3.0")] |
1462 | impl ToOwned for CStr { | |
1463 | type Owned = CString; | |
1464 | ||
1465 | fn to_owned(&self) -> CString { | |
8bb4bdeb | 1466 | CString { inner: self.to_bytes_with_nul().into() } |
c1a9b12d | 1467 | } |
ba9703b0 XL |
1468 | |
1469 | fn clone_into(&self, target: &mut CString) { | |
1470 | let mut b = Vec::from(mem::take(&mut target.inner)); | |
1471 | self.to_bytes_with_nul().clone_into(&mut b); | |
1472 | target.inner = b.into_boxed_slice(); | |
1473 | } | |
c1a9b12d SL |
1474 | } |
1475 | ||
9cc50fc6 | 1476 | #[stable(feature = "cstring_asref", since = "1.7.0")] |
532ac7d7 XL |
1477 | impl From<&CStr> for CString { |
1478 | fn from(s: &CStr) -> CString { | |
9cc50fc6 SL |
1479 | s.to_owned() |
1480 | } | |
1481 | } | |
1482 | ||
1483 | #[stable(feature = "cstring_asref", since = "1.7.0")] | |
1484 | impl ops::Index<ops::RangeFull> for CString { | |
1485 | type Output = CStr; | |
1486 | ||
1487 | #[inline] | |
1488 | fn index(&self, _index: ops::RangeFull) -> &CStr { | |
1489 | self | |
1490 | } | |
1491 | } | |
1492 | ||
3dfed10e XL |
1493 | #[stable(feature = "cstr_range_from", since = "1.47.0")] |
1494 | impl ops::Index<ops::RangeFrom<usize>> for CStr { | |
1495 | type Output = CStr; | |
1496 | ||
1497 | fn index(&self, index: ops::RangeFrom<usize>) -> &CStr { | |
1498 | let bytes = self.to_bytes_with_nul(); | |
1499 | // we need to manually check the starting index to account for the null | |
1500 | // byte, since otherwise we could get an empty string that doesn't end | |
1501 | // in a null. | |
1502 | if index.start < bytes.len() { | |
1503 | unsafe { CStr::from_bytes_with_nul_unchecked(&bytes[index.start..]) } | |
1504 | } else { | |
1505 | panic!( | |
1506 | "index out of bounds: the len is {} but the index is {}", | |
1507 | bytes.len(), | |
1508 | index.start | |
1509 | ); | |
1510 | } | |
1511 | } | |
1512 | } | |
1513 | ||
9cc50fc6 SL |
1514 | #[stable(feature = "cstring_asref", since = "1.7.0")] |
1515 | impl AsRef<CStr> for CStr { | |
041b39d2 | 1516 | #[inline] |
9cc50fc6 SL |
1517 | fn as_ref(&self) -> &CStr { |
1518 | self | |
1519 | } | |
1520 | } | |
1521 | ||
1522 | #[stable(feature = "cstring_asref", since = "1.7.0")] | |
1523 | impl AsRef<CStr> for CString { | |
041b39d2 | 1524 | #[inline] |
9cc50fc6 SL |
1525 | fn as_ref(&self) -> &CStr { |
1526 | self | |
1527 | } | |
1528 | } |