Struct std::ffi::CString
[−]
[src]
pub struct CString { // some fields omitted }
A type representing an owned C-compatible string
This type serves the primary purpose of being able to safely generate a C-compatible string from a Rust byte slice or vector. An instance of this type is a static guarantee that the underlying bytes contain no interior 0 bytes and the final byte is 0.
A CString
`CStringis created from either a byte slice or a byte vector. After being created, a
` is created from either a byte slice or a byte vector. After
being created, a CString
`CStringpredominately inherits all of its methods from the
` predominately inherits all of its methods from
the Deref
`Derefimplementation to
` implementation to [libc::c_char]
`[libc::c_char]. Note that the underlying array is represented as an array of
`. Note that the underlying
array is represented as an array of libc::c_char
`libc::c_charas opposed to
` as opposed to u8
`u8. A
`. A
u8
`u8slice can be obtained with the
` slice can be obtained with the as_bytes
`as_bytesmethod. Slices produced from a
` method. Slices produced from
a CString
`CString` do not contain the trailing nul terminator unless otherwise
specified.
Examples
#![feature(libc)] extern crate libc; fn main() { use std::ffi::CString; use libc; extern { fn my_printer(s: *const libc::c_char); } let to_print = &b"Hello, world!"[..]; let c_to_print = CString::new(to_print).unwrap(); unsafe { my_printer(c_to_print.as_ptr()); } }use std::ffi::CString; use libc; extern { fn my_printer(s: *const libc::c_char); } let to_print = &b"Hello, world!"[..]; let c_to_print = CString::new(to_print).unwrap(); unsafe { my_printer(c_to_print.as_ptr()); }
Methods
impl CString
fn new<T: Into<Vec<u8>>>(t: T) -> Result<CString, NulError>
Creates a new C-compatible string from a container of bytes.
This method will consume the provided data and use the underlying bytes to construct a new string, ensuring that there is a trailing 0 byte.
Examples
#![feature(libc)] extern crate libc; use std::ffi::CString; extern { fn puts(s: *const libc::c_char); } fn main() { let to_print = CString::new("Hello!").unwrap(); unsafe { puts(to_print.as_ptr()); } }extern crate libc; use std::ffi::CString; extern { fn puts(s: *const libc::c_char); } fn main() { let to_print = CString::new("Hello!").unwrap(); unsafe { puts(to_print.as_ptr()); } }
Errors
This function will return an error if the bytes yielded contain an internal 0 byte. The error returned will contain the bytes as well as the position of the nul byte.
unsafe fn from_vec_unchecked(v: Vec<u8>) -> CString
Creates a C-compatible string from a byte vector without checking for interior 0 bytes.
This method is equivalent to new
`newexcept that no runtime assertion is made that
` except that no runtime assertion
is made that v
`v` contains no 0 bytes, and it requires an actual
byte vector, not anything that can be converted to one with Into.
fn as_bytes(&self) -> &[u8]
Returns the contents of this CString
`CString` as a slice of bytes.
The returned slice does not contain the trailing nul separator and it is guaranteed to not have any interior nul bytes.
fn as_bytes_with_nul(&self) -> &[u8]
Equivalent to the as_bytes
`as_bytes` function except that the returned slice
includes the trailing nul byte.
Methods from Deref<Target=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.