Struct std::ffi::CStrUnstable

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

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

extern crate libc;
use std::ffi::CStr;

extern { fn my_string() -> *const libc::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

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

extern crate libc;
use std::ffi::{CString, CStr};

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

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

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

Methods

impl CStr

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

Cast 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.

Example

extern crate libc; fn main() { use std::ffi::CStr; use std::str; use libc; extern { fn my_string() -> *const libc::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::str;
use libc;

extern {
    fn my_string() -> *const libc::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

Return the inner pointer to this C string.

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

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

Convert 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]

Convert 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.

Trait Implementations

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

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