std::ffi::OsString - Rust
Description: API documentation for the Rust `OsString` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, OsString

# 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]

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

Constructs a new empty `OsString`.

# Examples

    use std::ffi::OsString;

    let os_string = OsString::new();Run

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

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

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

# 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

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

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

#### `fn with_capacity(capacity: usize) -> OsString`
1.9.0

Creates a new `OsString` with the given capacity.

The string will be able to hold exactly `capacity` lenth 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

#### `fn clear(&mut self)`
1.9.0

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

#### `fn capacity(&self) -> usize`
1.9.0

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

#### `fn reserve(&mut self, additional: usize)`
1.9.0

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

#### `fn reserve_exact(&mut self, additional: usize)`
1.9.0

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

#### `fn shrink_to_fit(&mut self)`
1.19.0

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

#### `fn into_boxed_os_str(self) -> Box<OsStr>`
1.20.0

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>

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

# Examples

    use std::ffi::OsStr;

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

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

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

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

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

#### `fn is_empty(&self) -> bool`
1.9.0

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

#### `fn len(&self) -> usize`
1.9.0

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`

Returns a copy of the value. Read more

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

Performs copy-assignment from `source`. Read more

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

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

Performs the conversion.

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

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

Performs the conversion.

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

#### `type Output = OsStr`

The returned type after indexing

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

The method for the indexing (`container[index]`) operation

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

#### `type Target = OsStr`

The resulting type after dereferencing

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

The method called to dereference a value

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

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

Constructs an empty `OsString`.

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

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

Formats the value using the given formatter.

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

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

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

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

This method tests for `!=`.

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

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

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

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

This method tests for `!=`.

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

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

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

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

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

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

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

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`

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

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

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

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

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

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

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

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`

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

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

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`

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

#### `fn max(self, other: Self) -> Self`

🔬 This is a nightly-only experimental API. (`ord_max_min` #25663)

Compares and returns the maximum of two values. Read more

#### `fn min(self, other: Self) -> Self`

🔬 This is a nightly-only experimental API. (`ord_max_min` #25663)

Compares and returns the minimum of two values. Read more

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

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

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

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

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`

Performs the conversion.

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

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

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

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

This method tests for `!=`.

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

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

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

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

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

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

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`

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

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

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`

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

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

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

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

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

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

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

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`

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

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

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`

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

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

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

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

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

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

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

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`

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

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

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`

Immutably borrows from an owned value. Read more

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

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

Performs the conversion.

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

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

Performs the conversion.

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

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

Performs the conversion.

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

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

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

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

This method tests for `!=`.

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

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

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

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

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

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

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`

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

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

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`

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

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

This method tests for `!=`.

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

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

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

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

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

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

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`

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

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

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`

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

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

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

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

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

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

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

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`

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

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

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`

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

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

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

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

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

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

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

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`

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

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

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`

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

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

Yields the underlying byte vector of this [`OsString`]. 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`)