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