# Struct std::ffi::OsString [−] [src]

    pub struct OsString {
        // some fields omitted
    }

A type that can represent owned, mutable platform-native strings, but is cheaply interconvertable with Rust strings.

The need for this type arises from the fact that:

- On Unix systems, strings are often arbitrary sequences of non-zero bytes, in many cases interpreted as UTF-8.

- On Windows, strings are often arbitrary sequences of non-zero 16-bit values, interpreted as UTF-16 when it is valid to do so.

- In Rust, strings are always valid UTF-8, but may contain zeros.

`OsString` and `OsStr` bridge this gap by simultaneously representing Rust and platform-native string values, and in particular allowing a Rust string to be converted into an "OS" string with no cost.

## Methods

### `impl OsString`

#### `fn new() -> OsString`

Constructs a new empty `OsString`.

#### `fn from_bytes<B>(bytes: B) -> Option<OsString> where B: Into<Vec<u8>>`

Deprecated since 1.6.0

: RFC was closed, hides subtle Windows semantics

Constructs an `OsString` from a byte sequence.

# Platform behavior

On Unix systems, any byte sequence can be successfully converted into an `OsString`.

On Windows system, only UTF-8 byte sequences will successfully convert; non UTF-8 data will produce `None`.

#### `fn as_os_str(&self) -> &OsStr`

Converts to an `OsStr` slice.

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

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

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

#### `fn push<T: AsRef<OsStr>>(&mut self, s: T)`

Extends the string with the given `&OsStr` slice.

## Methods from Deref<Target=OsStr>

#### `fn to_str(&self) -> Option<&str>`

Yields a `&str` slice if the `OsStr` is valid unicode.

This conversion may entail doing a check for UTF-8 validity.

#### `fn to_string_lossy(&self) -> Cow<str>`

Converts an `OsStr` to a `Cow<str>`.

Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.

#### `fn to_os_string(&self) -> OsString`

Copies the slice into an owned `OsString`.

#### `fn to_bytes(&self) -> Option<&[u8]>`

Deprecated since 1.6.0

: RFC was closed, hides subtle Windows semantics

Yields this `OsStr` as a byte slice.

# Platform behavior

On Unix systems, this is a no-op.

On Windows systems, this returns `None` unless the `OsStr` is valid unicode, in which case it produces UTF-8-encoded data. This may entail checking validity.

#### `fn to_cstring(&self) -> Option<CString>`

Deprecated since 1.6.0

: RFC was closed, hides subtle Windows semantics

Creates a `CString` containing this `OsStr` data.

Fails if the `OsStr` contains interior nulls.

This is a convenience for creating a `CString` from `self.to_bytes()`, and inherits the platform behavior of the `to_bytes` method.

## Trait Implementations

### `impl From<String> for OsString`

#### `fn from(s: String) -> OsString`

### `impl<'a, T: ?Sized + AsRef<OsStr>> From<&'a T> for OsString`

#### `fn from(s: &'a T) -> OsString`

### `impl Index<RangeFull> for OsString`

#### `type Output = OsStr`

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

### `impl Deref for OsString`

#### `type Target = OsStr`

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

### `impl Debug for OsString`

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

### `impl PartialEq for OsString`

#### `fn eq(&self, other: &OsString) -> bool`

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

### `impl PartialEq<str> for OsString`

#### `fn eq(&self, other: &str) -> bool`

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

### `impl Eq for OsString`

### `impl PartialOrd for OsString`

#### `fn partial_cmp(&self, other: &OsString) -> Option<Ordering>`

#### `fn lt(&self, other: &OsString) -> bool`

#### `fn le(&self, other: &OsString) -> bool`

#### `fn gt(&self, other: &OsString) -> bool`

#### `fn ge(&self, other: &OsString) -> bool`

### `impl PartialOrd<str> for OsString`

#### `fn partial_cmp(&self, other: &str) -> 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 Ord for OsString`

#### `fn cmp(&self, other: &OsString) -> Ordering`

### `impl Hash for OsString`

#### `fn hash<H: Hasher>(&self, state: &mut H)`

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

### `impl Borrow<OsStr> for OsString`

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

### `impl AsRef<OsStr> for OsString`

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

### `impl OsStringExt for OsString`

#### `fn from_vec(vec: Vec<u8>) -> OsString`

#### `fn into_vec(self) -> Vec<u8>`

### `impl AsRef<Path> for OsString`

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

### `impl OsStringExt for OsString`

#### `fn from_vec(vec: Vec<u8>) -> OsString`

#### `fn into_vec(self) -> Vec<u8>`

### Derived Implementations

### `impl Clone for OsString`

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

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

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