Struct sgx_tstd::ffi::CString

pub struct CString { /* fields omitted */ }

A type representing an owned C-compatible string

Methods

impl CString

pub fn new<T>(t: T) -> Result<CString, NulError> where     T: Into<Vec<u8>>,

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.

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.

pub 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.

pub unsafe fn from_raw(ptr: *mut i8) -> CString

Retakes ownership of a CString that was transferred to C.

Additionally, the length of the string will be recalculated from the pointer.

Safety

This should only ever be called with a pointer that was earlier obtained by calling into_raw on a CString. Other usage (e.g. trying to take ownership of a string that was allocated by foreign code) is likely to lead to undefined behavior or allocator corruption.

pub fn into_raw(self) -> *mut i8

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.

pub fn into_string(self) -> Result<String, IntoStringError>

Converts the CString into a String if it contains valid Unicode data.

On failure, ownership of the original CString is returned.

pub fn into_bytes(self) -> Vec<u8>

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.

pub fn into_bytes_with_nul(self) -> Vec<u8>

Equivalent to the into_bytes function except that the returned vector includes the trailing nul byte.

pub 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.

pub fn as_bytes_with_nul(&self) -> &[u8]

Equivalent to the as_bytes function except that the returned slice includes the trailing nul byte.

pub fn as_c_str(&self) -> &CStr

Extracts a CStr slice containing the entire string.

Important traits for Box<I>

impl<I> Iterator for Box<I> where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn into_boxed_c_str(self) -> Box<CStr>

Converts this CString into a boxed CStr.

Methods from Deref<Target = CStr>

pub fn as_ptr(&self) -> *const i8

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.

pub fn to_bytes(&self) -> &[u8]

Converts this C string to a byte slice.

The returned slice will not contain the trailing nul terminator that this C string has.

Note: This method is currently implemented as a constant-time cast, but it is planned to alter its definition in the future to perform the length calculation whenever this method is called.

pub 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 terminator 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.

pub fn to_str(&self) -> Result<&str, Utf8Error>

Yields a &str slice if the CStr contains valid UTF-8.

If the contents of the CStr are valid UTF-8 data, this function will return the corresponding &str slice. Otherwise, it will return an error with details of where UTF-8 validation failed.

Note: This method is currently implemented to check for validity after a constant-time 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.

pub fn to_string_lossy(&self) -> Cow<str>

Converts a CStr into a Cow<str>.

If the contents of the CStr are valid UTF-8 data, this function will return a Cow::Borrowed([&str]) with the the corresponding [&str] slice. Otherwise, it will replace any invalid UTF-8 sequences with U+FFFD REPLACEMENT CHARACTER and return a Cow::[Owned](String) with the result.

Note: This method is currently implemented to check for validity after a constant-time 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.

Trait Implementations

impl Drop for CString

fn drop(&mut self)

Executes the destructor for this type.

impl Debug for CString

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl Clone for CString

fn clone(&self) -> CString

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Hash for CString

fn hash<__H>(&self, state: &mut __H) where     __H: Hasher,

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where     H: Hasher,

Feeds a slice of this type into the given [Hasher].

impl PartialEq<CString> for CString

fn eq(&self, other: &CString) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &CString) -> bool

This method tests for !=.

impl AsRef<CStr> for CString

fn as_ref(&self) -> &CStr

Performs the conversion.

impl Eq for CString

impl Default for CString

fn default() -> CString

Creates an empty CString.

impl Deref for CString

type Target = CStr

The resulting type after dereferencing.

fn deref(&self) -> &CStr

Dereferences the value.

impl From<CString> for Box<CStr>

Important traits for Box<I>

impl<I> Iterator for Box<I> where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

fn from(s: CString) -> Box<CStr>

Performs the conversion.

impl From<Box<CStr>> for CString

fn from(s: Box<CStr>) -> CString

Performs the conversion.

impl From<CString> for Rc<CStr>

fn from(s: CString) -> Rc<CStr>

Performs the conversion.

impl From<CString> for Arc<CStr>

fn from(s: CString) -> Arc<CStr>

Performs the conversion.

impl<'a> From<&'a CStr> for CString

fn from(s: &'a CStr) -> CString

Performs the conversion.

impl From<CString> for Vec<u8>

fn from(s: CString) -> Vec<u8>

Performs the conversion.

impl Borrow<CStr> for CString

fn borrow(&self) -> &CStr

Immutably borrows from an owned value.

impl PartialOrd<CString> for CString

fn partial_cmp(&self, other: &CString) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &CString) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &CString) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &CString) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &CString) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Ord for CString

fn cmp(&self, other: &CString) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

impl Index<RangeFull> for CString

type Output = CStr

The returned type after indexing.

fn index(&self, _index: RangeFull) -> &CStr

Performs the indexing (container[index]) operation.