Struct std::c_str::CStringUnstable [-]  [+] [src]

pub struct CString {
    // some fields omitted
}

The representation of a C String.

This structure wraps a *libc::c_char, and will automatically free the memory it is pointing to when it goes out of scope.

Methods

impl CString

unsafe fn new(buf: *const c_char, owns_buffer: bool) -> CString

Create a C String from a pointer, with memory managed by C's allocator API, so avoid calling it with a pointer to memory managed by Rust's allocator API, as the behaviour would not be well defined.

Panics

Panics if buf is null

fn as_ptr(&self) -> *const c_char

Return a pointer to the NUL-terminated string data.

.as_ptr returns an internal pointer into the CString, and may be invalidated when the CString falls out of scope (the destructor will run, freeing the allocation if there is one).

fn main() { let foo = "some string"; // right let x = foo.to_c_str(); let p = x.as_ptr(); // wrong (the CString will be freed, invalidating `p`) let p = foo.to_c_str().as_ptr(); }
let foo = "some string";

// right
let x = foo.to_c_str();
let p = x.as_ptr();

// wrong (the CString will be freed, invalidating `p`)
let p = foo.to_c_str().as_ptr();

Example

extern crate libc; fn main() { let c_str = "foo bar".to_c_str(); unsafe { libc::puts(c_str.as_ptr()); } }
extern crate libc;

fn main() {
    let c_str = "foo bar".to_c_str();
    unsafe {
        libc::puts(c_str.as_ptr());
    }
}

fn as_mut_ptr(&mut self) -> *mut c_char

Return a mutable pointer to the NUL-terminated string data.

.as_mut_ptr returns an internal pointer into the CString, and may be invalidated when the CString falls out of scope (the destructor will run, freeing the allocation if there is one).

fn main() { let foo = "some string"; // right let mut x = foo.to_c_str(); let p = x.as_mut_ptr(); // wrong (the CString will be freed, invalidating `p`) let p = foo.to_c_str().as_mut_ptr(); }
let foo = "some string";

// right
let mut x = foo.to_c_str();
let p = x.as_mut_ptr();

// wrong (the CString will be freed, invalidating `p`)
let p = foo.to_c_str().as_mut_ptr();

fn owns_buffer(&self) -> bool

Returns whether or not the CString owns the buffer.

fn as_bytes<'a>(&'a self) -> &'a [u8]

Converts the CString into a &[u8] without copying. Includes the terminating NUL byte.

fn as_bytes_no_nul<'a>(&'a self) -> &'a [u8]

Converts the CString into a &[u8] without copying. Does not include the terminating NUL byte.

fn as_str<'a>(&'a self) -> Option<&'a str>

Converts the CString into a &str without copying. Returns None if the CString is not UTF-8.

fn iter<'a>(&'a self) -> CChars<'a>

Return a CString iterator.

unsafe fn into_inner(self) -> *const c_char

Unwraps the wrapped *libc::c_char from the CString wrapper.

Any ownership of the buffer by the CString wrapper is forgotten, meaning that the backing allocation of this CString is not automatically freed if it owns the allocation. In this case, a user of .unwrap() should ensure the allocation is freed, to avoid leaking memory. You should use libc's memory allocator in this case.

Prefer .as_ptr() when just retrieving a pointer to the string data, as that does not relinquish ownership.

unsafe fn unwrap(self) -> *const c_char

Deprecated, use into_inner() instead

fn len(&self) -> uint

Return the number of bytes in the CString (not including the NUL terminator).

fn is_empty(&self) -> bool

Returns if there are no bytes in this string

Trait Implementations

impl Send for CString

impl Sync for CString

impl Clone for CString

fn clone(&self) -> CString

Clone this CString into a new, uniquely owned CString. For safety reasons, this is always a deep clone with the memory allocated with C's allocator API, rather than the usual shallow clone.

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

impl PartialEq for CString

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

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

impl PartialOrd for CString

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

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

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

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

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

impl Eq for CString

impl<S: Writer> Hash<S> for CString

fn hash(&self, state: &mut S)

impl Drop for CString

fn drop(&mut self)

impl Show for CString

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

impl BytesContainer for CString

fn container_as_bytes<'a>(&'a self) -> &'a [u8]

fn container_as_str<'a>(&'a self) -> Option<&'a str>

fn is_str(_: Option<&Self>) -> bool