Struct std::ffi::CStringUnstable
[-] [+]
[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 is created from either a byte slice or a byte vector. After
being created, a CString predominately inherits all of its methods from
the Deref implementation to [libc::c_char]. Note that the underlying
array is represented as an array of libc::c_char as opposed to u8. A
u8 slice can be obtained with the as_bytes method. Slices produced from
a CString do not contain the trailing nul terminator unless otherwise
specified.
Example
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: IntoBytes>(t: T) -> Result<CString, NulError>
Create 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
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.
fn from_slice(v: &[u8]) -> CString
Create a new C-compatible string from a byte slice.
This method will copy the data of the slice provided into a new allocation, ensuring that there is a trailing 0 byte.
Examples
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()); } }
Panics
This function will panic if the provided slice contains any interior nul bytes.
fn from_vec(v: Vec<u8>) -> CString
Create a C-compatible string from a byte vector.
This method will consume ownership of the provided vector, appending a 0 byte to the end after verifying that there are no interior 0 bytes.
Panics
This function will panic if the provided slice contains any interior nul bytes.
unsafe fn from_vec_unchecked(v: Vec<u8>) -> CString
Create a C-compatible string from a byte vector without checking for interior 0 bytes.
This method is equivalent to from_vec except that no runtime assertion
is made that v contains no 0 bytes.
fn as_bytes(&self) -> &[u8]
Returns the contents of this CString as a slice of bytes.
The returned slice does not contain the trailing nul separator and it is guaranteet to not have any interior nul bytes.
fn as_bytes_with_nul(&self) -> &[u8]
Equivalent to the as_bytes function except that the returned slice
includes the trailing nul byte.