# Struct std::ffi::CStr [−] [src]

    pub struct CStr {
        // some fields omitted
    }

Representation of a borrowed C string.

This dynamically sized type is only safely constructed via a borrowed version of an instance of `CString`. This type can be constructed from a raw C string as well and represents a C string borrowed from another location.

Note that this structure is not `repr(C)` and is not recommended to be placed in the signatures of FFI functions. Instead safe wrappers of FFI functions may leverage the unsafe `from_ptr` constructor to provide a safe interface to other consumers.

# Examples

Inspecting a foreign C string

use std::ffi::CStr; use std::os::raw::c_char; extern { fn my_string() -> *const c_char; } fn main() { unsafe { let slice = CStr::from_ptr(my_string()); println!("string length: {}", slice.to_bytes().len()); } }

    use std::ffi::CStr;
    use std::os::raw::c_char;

    extern { fn my_string() -> *const c_char; }

    fn main() {
        unsafe {
            let slice = CStr::from_ptr(my_string());
            println!("string length: {}", slice.to_bytes().len());
        }
    }

Passing a Rust-originating C string

use std::ffi::{CString, CStr}; use std::os::raw::c_char; fn work(data: &CStr) { extern { fn work_with(data: *const c_char); } unsafe { work_with(data.as_ptr()) } } fn main() { let s = CString::new("data data data data").unwrap(); work(&s); }

    use std::ffi::{CString, CStr};
    use std::os::raw::c_char;

    fn work(data: &CStr) {
        extern { fn work_with(data: *const c_char); }

        unsafe { work_with(data.as_ptr()) }
    }

    fn main() {
        let s = CString::new("data data data data").unwrap();
        work(&s);
    }

Converting a foreign C string into a Rust `String`

use std::ffi::CStr; use std::os::raw::c_char; extern { fn my_string() -> *const c_char; } fn my_string_safe() -> String { unsafe { CStr::from_ptr(my_string()).to_string_lossy().into_owned() } } fn main() { println!("string: {}", my_string_safe()); }

    use std::ffi::CStr;
    use std::os::raw::c_char;

    extern { fn my_string() -> *const c_char; }

    fn my_string_safe() -> String {
        unsafe {
            CStr::from_ptr(my_string()).to_string_lossy().into_owned()
        }
    }

    fn main() {
        println!("string: {}", my_string_safe());
    }

## Methods

### `impl CStr`

#### `unsafe fn from_ptr<'a>(ptr: *const c_char) -> &'a CStr`

Casts a raw C string to a safe C string wrapper.

This function will cast the provided `ptr` to the `CStr` wrapper which allows inspection and interoperation of non-owned C strings. This method is unsafe for a number of reasons:

- There is no guarantee to the validity of `ptr`
- The returned lifetime is not guaranteed to be the actual lifetime of `ptr`
- There is no guarantee that the memory pointed to by `ptr` contains a valid nul terminator byte at the end of the string.

> Note: This operation is intended to be a 0-cost cast but it is currently implemented with an up-front calculation of the length of the string. This is not guaranteed to always be the case.

# Examples

fn main() { use std::ffi::CStr; use std::os::raw::c_char; use std::str; extern { fn my_string() -> *const c_char; } unsafe { let slice = CStr::from_ptr(my_string()); println!("string returned: {}", str::from_utf8(slice.to_bytes()).unwrap()); } }

    use std::ffi::CStr;
    use std::os::raw::c_char;
    use std::str;

    extern {
        fn my_string() -> *const c_char;
    }

    unsafe {
        let slice = CStr::from_ptr(my_string());
        println!("string returned: {}",
                 str::from_utf8(slice.to_bytes()).unwrap());
    }

#### `fn as_ptr(&self) -> *const c_char`

Returns the inner pointer to this C string.

The returned pointer will be valid for as long as `self` is and points to a contiguous region of memory terminated with a 0 byte to represent the end of the string.

#### `fn to_bytes(&self) -> &[u8]`

Converts this C string to a byte slice.

This function will calculate the length of this string (which normally requires a linear amount of work to be done) and then return the resulting slice of `u8` elements.

The returned slice will not contain the trailing nul that this C string has.

> Note: This method is currently implemented as a 0-cost cast, but it is planned to alter its definition in the future to perform the length calculation whenever this method is called.

#### `fn to_bytes_with_nul(&self) -> &[u8]`

Converts this C string to a byte slice containing the trailing 0 byte.

This function is the equivalent of `to_bytes` except that it will retain the trailing nul instead of chopping it off.

> Note: This method is currently implemented as a 0-cost cast, but it is planned to alter its definition in the future to perform the length calculation whenever this method is called.

#### `fn to_str(&self) -> Result<&str, Utf8Error>`

Yields a `&str` slice if the `CStr` contains valid UTF-8.

This function will calculate the length of this string and check for UTF-8 validity, and then return the `&str` if it's valid.

> Note: This method is currently implemented to check for validity after a 0-cost cast, but it is planned to alter its definition in the future to perform the length calculation in addition to the UTF-8 check whenever this method is called.

#### `fn to_string_lossy(&self) -> Cow<str>`

Converts a `CStr` into a `Cow<str>`.

This function will calculate the length of this string (which normally requires a linear amount of work to be done) and then return the resulting slice as a `Cow<str>`, replacing any invalid UTF-8 sequences with `U+FFFD REPLACEMENT CHARACTER`.

> Note: This method is currently implemented to check for validity after a 0-cost cast, but it is planned to alter its definition in the future to perform the length calculation in addition to the UTF-8 check whenever this method is called.

## Trait Implementations

### `impl Debug for CStr`

#### `fn fmt(&self, f: &mut Formatter) -> Result`

### `impl PartialEq for CStr`

#### `fn eq(&self, other: &CStr) -> bool`

#### `fn ne(&self, other: &Rhs) -> bool`

### `impl Eq for CStr`

### `impl PartialOrd for CStr`

#### `fn partial_cmp(&self, other: &CStr) -> Option<Ordering>`

#### `fn lt(&self, other: &Rhs) -> bool`

#### `fn le(&self, other: &Rhs) -> bool`

#### `fn gt(&self, other: &Rhs) -> bool`

#### `fn ge(&self, other: &Rhs) -> bool`

### `impl Ord for CStr`

#### `fn cmp(&self, other: &CStr) -> Ordering`

### `impl ToOwned for CStr`

#### `type Owned = CString`

#### `fn to_owned(&self) -> CString`

### `impl AsRef<CStr> for CStr`

#### `fn as_ref(&self) -> &CStr`

### Derived Implementations

### `impl Hash for CStr`

#### `fn hash<__H: Hasher>(&self, __arg_0: &mut __H)`

#### `fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize`)