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
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); }
Converting a foreign C string into a Rust String
`String`
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>
: recently added
Yields a &str
`&strslice 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
`&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>
: 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 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.