Struct std::ffi::CString
[−]
[src]
pub struct CString {
// some fields omitted
}1.0.0A 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 [c_char]. Note that the underlying array
is represented as an array of 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.
Examples
fn main() { use std::ffi::CString; use std::os::raw::c_char; extern { fn my_printer(s: *const c_char); } let c_to_print = CString::new("Hello, world!").unwrap(); unsafe { my_printer(c_to_print.as_ptr()); } }use std::ffi::CString; use std::os::raw::c_char; extern { fn my_printer(s: *const c_char); } let c_to_print = CString::new("Hello, world!").unwrap(); unsafe { my_printer(c_to_print.as_ptr()); }
Safety
CString is intended for working with traditional C-style strings
(a sequence of non-null bytes terminated by a single null byte); the
primary use case for these kinds of strings is interoperating with C-like
code. Often you will need to transfer ownership to/from that external
code. It is strongly recommended that you thoroughly read through the
documentation of CString before use, as improper ownership management
of CString instances can lead to invalid memory accesses, memory leaks,
and other memory errors.
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
use std::ffi::CString; use std::os::raw::c_char; extern { fn puts(s: *const c_char); } fn main() { let to_print = CString::new("Hello!").unwrap(); unsafe { puts(to_print.as_ptr()); } }use std::ffi::CString; use std::os::raw::c_char; extern { fn puts(s: *const 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 except that no runtime assertion
is made that v contains no 0 bytes, and it requires an actual
byte vector, not anything that can be converted to one with Into.
unsafe fn from_raw(ptr: *mut c_char) -> CString1.4.0
Retakes ownership of a CString that was transferred to C.
This should only ever be called with a pointer that was earlier
obtained by calling into_raw on a CString. Additionally, the length
of the string will be recalculated from the pointer.
fn into_raw(self) -> *mut c_char1.4.0
Transfers ownership of the string to a C caller.
The pointer must be returned to Rust and reconstituted using
from_raw to be properly deallocated. Specifically, one
should not use the standard C free function to deallocate
this string.
Failure to call from_raw will lead to a memory leak.
fn into_string(self) -> Result<String, IntoStringError>1.7.0
Converts the CString into a String if it contains valid Unicode data.
On failure, ownership of the original CString is returned.
fn into_bytes(self) -> Vec<u8>1.7.0
Returns the underlying byte buffer.
The returned buffer does not contain the trailing nul separator and it is guaranteed to not have any interior nul bytes.
fn into_bytes_with_nul(self) -> Vec<u8>1.7.0
Equivalent to the into_bytes function except that the returned vector
includes the trailing nul byte.
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 guaranteed 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.
Methods from Deref<Target=CStr>
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 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 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 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>1.4.0
Yields a &str slice 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 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>1.4.0
Converts a CStr into a Cow<str>.
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>, 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.