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 unsafe
` 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
`from_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); }
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.