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.

Trait Implementations

impl Deref for CString

type Target = CStr

fn deref(&self) -> &CStr

impl Debug for CString

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

Derived Implementations

impl Hash for CString

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

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

impl Ord for CString

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

impl Eq for CString

impl PartialOrd for CString

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

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

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

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

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

impl PartialEq for CString

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

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

impl Clone for CString

fn clone(&self) -> CString

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