# Struct bitflags::__core::ffi::CString [−] [src]

    pub struct CString {
        // some fields omitted
    }

1.0.0

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` is created from either a byte slice or a byte vector. After being created, a `CString` predominately inherits all of its methods from the `Deref` implementation to `[c_char]`. Note that the underlying array is represented as an array of `c_char` as opposed to `u8`. A `u8` slice can be obtained with the `as_bytes` method. Slices produced from a `CString` do not contain the trailing nul terminator unless otherwise specified.

# Examples

    use std::ffi::CString;
    use std::os::raw::c_char;

    extern {
        fn my_printer(s: *const c_char);
    }

    let c_to_print = CString::new("Hello, world!").unwrap();
    unsafe {
        my_printer(c_to_print.as_ptr());
    }

# Safety

`CString` is intended for working with traditional C-style strings (a sequence of non-null bytes terminated by a single null byte); the primary use case for these kinds of strings is interoperating with C-like code. Often you will need to transfer ownership to/from that external code. It is strongly recommended that you thoroughly read through the documentation of `CString` before use, as improper ownership management of `CString` instances can lead to invalid memory accesses, memory leaks, and other memory errors.

## Methods

### `impl CString`

#### `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.

# Examples

    use std::ffi::CString;
    use std::os::raw::c_char;

    extern { fn puts(s: *const 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` 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.

#### `unsafe fn from_raw(ptr: *mut i8) -> CString` 1.4.0

Retakes ownership of a `CString` that was transferred to C.

This should only ever be called with a pointer that was earlier obtained by calling `into_raw` on a `CString`. Additionally, the length of the string will be recalculated from the pointer.

#### `fn into_raw(self) -> *mut i8` 1.4.0

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.

#### `fn into_string(self) -> Result<String, IntoStringError>`1.7.0

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

On failure, ownership of the original `CString` is returned.

#### `fn into_bytes(self) -> Vec<u8>`1.7.0

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.

#### `fn into_bytes_with_nul(self) -> Vec<u8>`1.7.0

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

#### `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.

#### `fn as_bytes_with_nul(&self) -> &[u8]`

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

## Methods from Deref<Target=CStr>

#### `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.

#### `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` 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` 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.

## Trait Implementations

### `impl Deref for CString`

#### `type Target = CStr`

#### `fn deref(&self) -> &CStr`

### `impl Debug for CString`

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

### `impl Borrow<CStr> for CString` 1.3.0

#### `fn borrow(&self) -> &CStr`

### `impl<'a> From<&'a CStr> for CString` 1.7.0

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

### `impl Index<RangeFull> for CString` 1.7.0

#### `type Output = CStr`

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

### `impl AsRef<CStr> for CString` 1.7.0

#### `fn as_ref(&self) -> &CStr`

### Derived Implementations

### `impl Clone for CString`

#### `fn clone(&self) -> CString`

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

### `impl Hash for CString`

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

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

### `impl Ord for CString`

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

### `impl Eq for CString`

### `impl PartialOrd<CString> 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<CString> for CString`

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

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

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)