Struct c_string::CStrBuf
[−]
[src]
pub struct CStrBuf { /* fields omitted */ }
An adaptor type to pass C string data to foreign functions.
Values of this type can be obtained by conversion from Rust strings and byte slices.
This type serves the same purpose as std::ffi::CString
, but provides
in-place optimization for small strings and different ergonomics in the
ways CStrBuf
values can be constructed.
Methods
impl CStrBuf
[src]
fn from_iter<I>(iterable: I) -> Result<CStrBuf, NulError> where
I: IntoIterator<Item = u8>,
I: IntoIterator<Item = u8>,
Create a CStrBuf
by consuming an iterable source of bytes.
Failure
Returns Err
if the source contains an interior NUL byte.
fn from_str(s: &str) -> Result<CStrBuf, NulError>
Create a CStrBuf
by copying a string slice.
Failure
Returns Err
if the string contains an interior NUL character.
fn from_vec(vec: Vec<u8>) -> Result<CStrBuf, NulError>
Consumes a byte vector to create CStrBuf
, taking care to avoid
copying.
Failure
If the given vector contains a NUL byte, then an error containing
the original vector and NulError
information is returned.
unsafe fn from_vec_unchecked(vec: Vec<u8>) -> CStrBuf
Like from_vec
, but without checking for interior NUL bytes.
fn into_vec(self) -> Vec<u8>
Converts self
into a byte vector, potentially saving an allocation.
Methods from Deref<Target = CStr>
fn as_ptr(&self) -> *const i8
1.0.0
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.
WARNING
It is your responsibility to make sure that the underlying memory is not
freed too early. For example, the following code will cause undefined
behaviour when ptr
is used inside the unsafe
block:
use std::ffi::{CString}; let ptr = CString::new("Hello").unwrap().as_ptr(); unsafe { // `ptr` is dangling *ptr; }
This happens because the pointer returned by as_ptr
does not carry any
lifetime information and the string is deallocated immediately after
the CString::new("Hello").unwrap().as_ptr()
expression is evaluated.
To fix the problem, bind the string to a local variable:
use std::ffi::{CString}; let hello = CString::new("Hello").unwrap(); let ptr = hello.as_ptr(); unsafe { // `ptr` is valid because `hello` is in scope *ptr; }
fn to_bytes(&self) -> &[u8]
1.0.0
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]
1.0.0
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.
fn into_c_string(self: Box<CStr>) -> CString
into_boxed_c_str
)Trait Implementations
impl Clone for CStrBuf
[src]
fn clone(&self) -> CStrBuf
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more