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`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)`repr(C)and is not recommended to be placed in the signatures of FFI functions. Instead safe wrappers of FFI functions may leverage the unsafefrom_ptr` constructor to provide a safe interface to other consumers.

Examples

Inspecting a foreign C string

#![feature(libc)] 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

#![feature(libc)] 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);
}

Converting a foreign C string into a Rust String`String`

#![feature(libc,cstr_to_str)] extern crate libc; use std::ffi::CStr; extern { fn my_string() -> *const libc::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()); }
extern crate libc;
use std::ffi::CStr;

extern { fn my_string() -> *const libc::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`ptrto the` to the CStr`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`ptr`
  • The returned lifetime is not guaranteed to be the actual lifetime of ptr`ptr`
  • There is no guarantee that the memory pointed to by ptr`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

#![feature(libc)] 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

Returns the inner pointer to this C string.

The returned pointer will be valid for as long as self`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`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`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>

Unstable

: recently added

Yields a &str`&strslice if theCStr` contains valid UTF-8.

This function will calculate the length of this string and check for UTF-8 validity, and then return the &str`&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>

Unstable

: recently added

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

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>`Cow, replacing any invalid UTF-8 sequences withU+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

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