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

    pub struct OsString { /* fields omitted */ }

A type that can represent owned, mutable platform-native strings, but is cheaply inter-convertible 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, which 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`
[src]

#### `pub fn new() -> OsString`
[src]

Constructs a new empty `OsString`.

# Examples

    use std::ffi::OsString;

    let os_string = OsString::new();Run

#### `pub fn as_os_str(&self) -> &OsStr`
[src]

Converts to an `OsStr` slice.

# Examples

    use std::ffi::{OsString, OsStr};

    let os_string = OsString::from("foo");
    let os_str = OsStr::new("foo");
    assert_eq!(os_string.as_os_str(), os_str);Run

#### `pub fn into_string(self) -> Result<String, OsString>`
[src]

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

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

# Examples

    use std::ffi::OsString;

    let os_string = OsString::from("foo");
    let string = os_string.into_string();
    assert_eq!(string, Ok(String::from("foo")));Run

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

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

# Examples

    use std::ffi::OsString;

    let mut os_string = OsString::from("foo");
    os_string.push("bar");
    assert_eq!(&os_string, "foobar");Run

#### `pub fn with_capacity(capacity: usize) -> OsString`
1.9.0
[src]

Creates a new `OsString` with the given capacity.

The string will be able to hold exactly `capacity` length units of other OS strings without reallocating. If `capacity` is 0, the string will not allocate.

See main `OsString` documentation information about encoding.

# Examples

    use std::ffi::OsString;

    let mut os_string = OsString::with_capacity(10);
    let capacity = os_string.capacity();

    // This push is done without reallocating
    os_string.push("foo");

    assert_eq!(capacity, os_string.capacity());Run

#### `pub fn clear(&mut self)`
1.9.0
[src]

Truncates the `OsString` to zero length.

# Examples

    use std::ffi::OsString;

    let mut os_string = OsString::from("foo");
    assert_eq!(&os_string, "foo");

    os_string.clear();
    assert_eq!(&os_string, "");Run

#### `pub fn capacity(&self) -> usize`
1.9.0
[src]

Returns the capacity this `OsString` can hold without reallocating.

See `OsString` introduction for information about encoding.

# Examples

    use std::ffi::OsString;

    let mut os_string = OsString::with_capacity(10);
    assert!(os_string.capacity() >= 10);Run

#### `pub fn reserve(&mut self, additional: usize)`
1.9.0
[src]

Reserves capacity for at least `additional` more capacity to be inserted in the given `OsString`.

The collection may reserve more space to avoid frequent reallocations.

# Examples

    use std::ffi::OsString;

    let mut s = OsString::new();
    s.reserve(10);
    assert!(s.capacity() >= 10);Run

#### `pub fn reserve_exact(&mut self, additional: usize)`
1.9.0
[src]

Reserves the minimum capacity for exactly `additional` more capacity to be inserted in the given `OsString`. Does nothing if the capacity is already sufficient.

Note that the allocator may give the collection more space than it requests. Therefore capacity can not be relied upon to be precisely minimal. Prefer reserve if future insertions are expected.

# Examples

    use std::ffi::OsString;

    let mut s = OsString::new();
    s.reserve_exact(10);
    assert!(s.capacity() >= 10);Run

#### `pub fn shrink_to_fit(&mut self)`
1.19.0
[src]

Shrinks the capacity of the `OsString` to match its length.

# Examples

    use std::ffi::OsString;

    let mut s = OsString::from("foo");

    s.reserve(100);
    assert!(s.capacity() >= 100);

    s.shrink_to_fit();
    assert_eq!(3, s.capacity());Run

#### `pub fn into_boxed_os_str(self) -> Box<OsStr>`
1.20.0
[src]

Converts this `OsString` into a boxed `OsStr`.

# Examples

    use std::ffi::{OsString, OsStr};

    let s = OsString::from("hello");

    let b: Box<OsStr> = s.into_boxed_os_str();Run

## Methods from Deref<Target = OsStr>

#### `pub fn to_str(&self) -> Option<&str>`
[src]

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

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

# Examples

    use std::ffi::OsStr;

    let os_str = OsStr::new("foo");
    assert_eq!(os_str.to_str(), Some("foo"));Run

#### `pub fn to_string_lossy(&self) -> Cow<str>`
[src]

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

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

# Examples

Calling `to_string_lossy` on an `OsStr` with valid unicode:

    use std::ffi::OsStr;

    let os_str = OsStr::new("foo");
    assert_eq!(os_str.to_string_lossy(), "foo");Run

Had `os_str` contained invalid unicode, the `to_string_lossy` call might have returned `"fo�"`.

#### `pub fn to_os_string(&self) -> OsString`
[src]

Copies the slice into an owned `OsString`.

# Examples

    use std::ffi::{OsStr, OsString};

    let os_str = OsStr::new("foo");
    let os_string = os_str.to_os_string();
    assert_eq!(os_string, OsString::from("foo"));Run

#### `pub fn is_empty(&self) -> bool`
1.9.0
[src]

Checks whether the `OsStr` is empty.

# Examples

    use std::ffi::OsStr;

    let os_str = OsStr::new("");
    assert!(os_str.is_empty());

    let os_str = OsStr::new("foo");
    assert!(!os_str.is_empty());Run

#### `pub fn len(&self) -> usize`
1.9.0
[src]

Returns the length of this `OsStr`.

Note that this does not return the number of bytes in this string as, for example, OS strings on Windows are encoded as a list of `u16` rather than a list of bytes. This number is simply useful for passing to other methods like `OsString::with_capacity` to avoid reallocations.

See `OsStr` introduction for more information about encoding.

# Examples

    use std::ffi::OsStr;

    let os_str = OsStr::new("");
    assert_eq!(os_str.len(), 0);

    let os_str = OsStr::new("foo");
    assert_eq!(os_str.len(), 3);Run

## Trait Implementations

### `impl Clone for OsString`
[src]

#### `fn clone(&self) -> OsString`
[src]

Returns a copy of the value. Read more

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

Performs copy-assignment from `source`. Read more

### `impl From<String> for OsString`
[src]

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

Performs the conversion.

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

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

Performs the conversion.

### `impl Index<RangeFull> for OsString`
[src]

#### `type Output = OsStr`

The returned type after indexing.

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

Performs the indexing (`container[index]`) operation.

### `impl Deref for OsString`
[src]

#### `type Target = OsStr`

The resulting type after dereferencing.

#### `fn deref(&self) -> &OsStr`
[src]

Dereferences the value.

### `impl Default for OsString`
1.9.0
[src]

#### `fn default() -> OsString`
[src]

Constructs an empty `OsString`.

### `impl Debug for OsString`
[src]

#### `fn fmt(&self, formatter: &mut Formatter) -> Result`
[src]

Formats the value using the given formatter.

### `impl PartialEq for OsString`
[src]

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

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

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

This method tests for `!=`.

### `impl PartialEq<str> for OsString`
[src]

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

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

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

This method tests for `!=`.

### `impl Eq for OsString`
[src]

### `impl PartialOrd for OsString`
[src]

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

This method returns an ordering between `self` and `other` values if one exists. Read more

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

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

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

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

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

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

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

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl PartialOrd<str> for OsString`
[src]

#### `fn partial_cmp(&self, other: &str) -> Option<Ordering>`
[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

#### `fn lt(&self, other: &Rhs) -> bool`
[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

#### `fn le(&self, other: &Rhs) -> bool`
[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

#### `fn gt(&self, other: &Rhs) -> bool`
[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

#### `fn ge(&self, other: &Rhs) -> bool`
[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl Ord for OsString`
[src]

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

This method returns an `Ordering` between `self` and `other`. Read more

#### `fn max(self, other: Self) -> Self`
1.21.0
[src]

Compares and returns the maximum of two values. Read more

#### `fn min(self, other: Self) -> Self`
1.21.0
[src]

Compares and returns the minimum of two values. Read more

### `impl Hash for OsString`
[src]

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

Feeds this value into the given [`Hasher`]. Read more

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

Feeds a slice of this type into the given [`Hasher`]. Read more

### `impl From<Box<OsStr>> for OsString`
1.18.0
[src]

#### `fn from(boxed: Box<OsStr>) -> OsString`
[src]

Performs the conversion.

### `impl<'a, 'b> PartialEq<OsStr> for OsString`
1.8.0
[src]

#### `fn eq(&self, other: &OsStr) -> bool`
[src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

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

This method tests for `!=`.

### `impl<'a, 'b> PartialOrd<OsStr> for OsString`
1.8.0
[src]

#### `fn partial_cmp(&self, other: &OsStr) -> Option<Ordering>`
[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

#### `fn lt(&self, other: &Rhs) -> bool`
[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

#### `fn le(&self, other: &Rhs) -> bool`
[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

#### `fn gt(&self, other: &Rhs) -> bool`
[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

#### `fn ge(&self, other: &Rhs) -> bool`
[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl<'a, 'b> PartialEq<&'a OsStr> for OsString`
1.8.0
[src]

#### `fn eq(&self, other: &&'a OsStr) -> bool`
[src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

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

This method tests for `!=`.

### `impl<'a, 'b> PartialOrd<&'a OsStr> for OsString`
1.8.0
[src]

#### `fn partial_cmp(&self, other: &&'a OsStr) -> Option<Ordering>`
[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

#### `fn lt(&self, other: &Rhs) -> bool`
[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

#### `fn le(&self, other: &Rhs) -> bool`
[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

#### `fn gt(&self, other: &Rhs) -> bool`
[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

#### `fn ge(&self, other: &Rhs) -> bool`
[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl<'a, 'b> PartialEq<Cow<'a, OsStr>> for OsString`
1.8.0
[src]

#### `fn eq(&self, other: &Cow<'a, OsStr>) -> bool`
[src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

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

This method tests for `!=`.

### `impl<'a, 'b> PartialOrd<Cow<'a, OsStr>> for OsString`
1.8.0
[src]

#### `fn partial_cmp(&self, other: &Cow<'a, OsStr>) -> Option<Ordering>`
[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

#### `fn lt(&self, other: &Rhs) -> bool`
[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

#### `fn le(&self, other: &Rhs) -> bool`
[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

#### `fn gt(&self, other: &Rhs) -> bool`
[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

#### `fn ge(&self, other: &Rhs) -> bool`
[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl Borrow<OsStr> for OsString`
[src]

#### `fn borrow(&self) -> &OsStr`
[src]

Immutably borrows from an owned value. Read more

### `impl AsRef<OsStr> for OsString`
[src]

#### `fn as_ref(&self) -> &OsStr`
[src]

Performs the conversion.

### `impl From<PathBuf> for OsString`
1.14.0
[src]

#### `fn from(path_buf: PathBuf) -> OsString`
[src]

Performs the conversion.

### `impl AsRef<Path> for OsString`
[src]

#### `fn as_ref(&self) -> &Path`
[src]

Performs the conversion.

### `impl<'a, 'b> PartialEq<PathBuf> for OsString`
1.8.0
[src]

#### `fn eq(&self, other: &PathBuf) -> bool`
[src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

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

This method tests for `!=`.

### `impl<'a, 'b> PartialOrd<PathBuf> for OsString`
1.8.0
[src]

#### `fn partial_cmp(&self, other: &PathBuf) -> Option<Ordering>`
[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

#### `fn lt(&self, other: &Rhs) -> bool`
[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

#### `fn le(&self, other: &Rhs) -> bool`
[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

#### `fn gt(&self, other: &Rhs) -> bool`
[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

#### `fn ge(&self, other: &Rhs) -> bool`
[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl<'a, 'b> PartialEq<Path> for OsString`
1.8.0
[src]

#### `fn eq(&self, other: &Path) -> bool`
[src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

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

This method tests for `!=`.

### `impl<'a, 'b> PartialOrd<Path> for OsString`
1.8.0
[src]

#### `fn partial_cmp(&self, other: &Path) -> Option<Ordering>`
[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

#### `fn lt(&self, other: &Rhs) -> bool`
[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

#### `fn le(&self, other: &Rhs) -> bool`
[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

#### `fn gt(&self, other: &Rhs) -> bool`
[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

#### `fn ge(&self, other: &Rhs) -> bool`
[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl<'a, 'b> PartialEq<&'a Path> for OsString`
1.8.0
[src]

#### `fn eq(&self, other: &&'a Path) -> bool`
[src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

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

This method tests for `!=`.

### `impl<'a, 'b> PartialOrd<&'a Path> for OsString`
1.8.0
[src]

#### `fn partial_cmp(&self, other: &&'a Path) -> Option<Ordering>`
[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

#### `fn lt(&self, other: &Rhs) -> bool`
[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

#### `fn le(&self, other: &Rhs) -> bool`
[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

#### `fn gt(&self, other: &Rhs) -> bool`
[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

#### `fn ge(&self, other: &Rhs) -> bool`
[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl<'a, 'b> PartialEq<Cow<'a, Path>> for OsString`
1.8.0
[src]

#### `fn eq(&self, other: &Cow<'a, Path>) -> bool`
[src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

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

This method tests for `!=`.

### `impl<'a, 'b> PartialOrd<Cow<'a, Path>> for OsString`
1.8.0
[src]

#### `fn partial_cmp(&self, other: &Cow<'a, Path>) -> Option<Ordering>`
[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

#### `fn lt(&self, other: &Rhs) -> bool`
[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

#### `fn le(&self, other: &Rhs) -> bool`
[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

#### `fn gt(&self, other: &Rhs) -> bool`
[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

#### `fn ge(&self, other: &Rhs) -> bool`
[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

### `impl OsStringExt for OsString`
[src]

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

This is supported on Unix only.

Creates an [`OsString`] from a byte vector. Read more

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

This is supported on Unix only.

Yields the underlying byte vector of this [`OsString`]. Read more

### `impl OsStringExt for OsString`
[src]

#### `fn from_wide(wide: &[u16]) -> OsString`
[src]

This is supported on Windows only.

Creates an `OsString` from a potentially ill-formed UTF-16 slice of 16-bit code units. Read more

# 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
+
  Collapse/expand all sections

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