# Struct bitflags::__core::ffi::CStr [−] [src]

    pub struct CStr {
        // some fields omitted
    }

1.0.0

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());
        }
    }

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);
    }

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());
    }

## Methods

### `impl CStr`

#### `unsafe fn from_ptr(ptr: *const i8) -> &'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

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

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

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

#### `fn from_bytes_with_nul(bytes: &[u8]) -> Option<&CStr>`

Unstable (`cstr_from_bytes`)

: recently added

Creates a C string wrapper from a byte slice.

This function will cast the provided `bytes` to a `CStr` wrapper after ensuring that it is null terminated and does not contain any interior nul bytes.

# Examples

    use std::ffi::CStr;

    let cstr = CStr::from_bytes_with_nul(b"hello\0");
    assert!(cstr.is_some());

#### `unsafe fn from_bytes_with_nul_unchecked(bytes: &[u8]) -> &CStr`

Unstable (`cstr_from_bytes`)

: recently added

Unsafely creates a C string wrapper from a byte slice.

This function will cast the provided `bytes` to a `CStr` wrapper without performing any sanity checks. The provided slice must be null terminated and not contain any interior nul bytes.

# Examples

    use std::ffi::{CStr, CString};

    unsafe {
        let cstring = CString::new("hello").unwrap();
        let cstr = CStr::from_bytes_with_nul_unchecked(cstring.to_bytes_with_nul());
        assert_eq!(cstr, &*cstring);
    }

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

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>`1.4.0

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>`1.4.0

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` 1.3.0

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

### `impl PartialEq<CStr> for CStr`

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

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

### `impl Eq for CStr`

### `impl PartialOrd<CStr> 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` 1.3.0

#### `type Owned = CString`

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

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

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

### Derived Implementations

### `impl Hash for CStr`

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

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

# 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` or `* -> vec`)