Skip to main content

## OsStr

# Struct OsStr

Source

    pub struct OsStr { /* private fields */ }

Expand description

A UTF-8-encoded fixed string

NOTE: To support dynamic values (i.e. `OsString`), enable the `string` feature

## Implementations§

Source§

### impl OsStr

Source

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

Get the raw string as an `std::ffi::OsStr`

Source

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

Get the raw string as an `OsString`

## Methods from Deref<Target = OsStr>§

1.0.0 · Source

#### pub 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"));

1.0.0 · Source

#### pub fn to_string_lossy(&self) -> Cow<'_, str>

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

Any non-UTF-8 sequences are replaced with `U+FFFD REPLACEMENT CHARACTER`.

##### §Examples

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

    // Note, due to differences in how Unix and Windows represent strings,
    // we are forced to complicate this example, setting up example `OsStr`s
    // with different source data and via different platform extensions.
    // Understand that in reality you could end up with such example invalid
    // sequences simply through collecting user command line arguments, for
    // example.

    #[cfg(unix)] {
        use std::ffi::OsStr;
        use std::os::unix::ffi::OsStrExt;

        // Here, the values 0x66 and 0x6f correspond to 'f' and 'o'
        // respectively. The value 0x80 is a lone continuation byte, invalid
        // in a UTF-8 sequence.
        let source = [0x66, 0x6f, 0x80, 0x6f];
        let os_str = OsStr::from_bytes(&source[..]);

        assert_eq!(os_str.to_string_lossy(), "fo�o");
    }
    #[cfg(windows)] {
        use std::ffi::OsString;
        use std::os::windows::prelude::*;

        // Here the values 0x0066 and 0x006f correspond to 'f' and 'o'
        // respectively. The value 0xD800 is a lone surrogate half, invalid
        // in a UTF-16 sequence.
        let source = [0x0066, 0x006f, 0xD800, 0x006f];
        let os_string = OsString::from_wide(&source[..]);
        let os_str = os_string.as_os_str();

        assert_eq!(os_str.to_string_lossy(), "fo�o");
    }

1.0.0 · Source

#### pub 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"));

1.9.0 · Source

#### pub fn is_empty(&self) -> bool

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());

1.9.0 · Source

#### pub fn len(&self) -> usize

Returns the length of this `OsStr`.

Note that this does not return the number of bytes in the string in OS string form.

The length returned is that of the underlying storage used by `OsStr`. As discussed in the `OsString` introduction, `OsString` and `OsStr` store strings in a form best suited for cheap inter-conversion between native-platform and Rust string forms, which may differ significantly from both of them, including in storage size and encoding.

This number is simply useful for passing to other methods, like `OsString::with_capacity` to avoid reallocations.

See the main `OsString` documentation information about encoding and capacity units.

##### §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);

Source

#### pub fn split_at(&self, mid: usize) -> (&OsStr, &OsStr)

🔬This is a nightly-only experimental API. (`os_str_split_at`)

Divides one string slice into two at an index.

The two slices returned go from the start of the string slice to `mid`, and from `mid` to the end of the string slice.

The argument, `mid`, should be a byte offset from the start of the string. It must also be on a valid `OsStr` boundary. See `split_at_checked` for the definition of a valid boundary.

Panics

Panics if `mid` is not on a valid boundary, or if it is past the end of the last code point of the string slice. For a non-panicking alternative see `split_at_checked`.

Source

#### pub fn split_at_checked(&self, mid: usize) -> Option<(&OsStr, &OsStr)>

🔬This is a nightly-only experimental API. (`os_str_split_at`)

Divides one string slice into two at an index.

The two slices returned go from the start of the string slice to `mid`, and from `mid` to the end of the string slice.

The argument, `mid`, should be a valid byte offset from the start of the string. It must also be on a valid `OsStr` boundary. The method returns `None` if that’s not the case. A valid `OsStr` boundary is one of:

- The start of the string
- The end of the string
- The start of a valid non-empty UTF-8 substring
- Immediately follows a valid non-empty UTF-8 substring

1.74.0 · Source

#### pub fn as_encoded_bytes(&self) -> &[u8] ⓘ

Converts an OS string slice to a byte slice. To convert the byte slice back into an OS string slice, use the `OsStr::from_encoded_bytes_unchecked` function.

The byte encoding is an unspecified, platform-specific, self-synchronizing superset of UTF-8. By being a self-synchronizing superset of UTF-8, this encoding is also a superset of 7-bit ASCII.

Note: As the encoding is unspecified, any sub-slice of bytes that is not valid UTF-8 should be treated as opaque and only comparable within the same Rust version built for the same target platform. For example, sending the slice over the network or storing it in a file will likely result in incompatible byte slices. See `OsString` for more encoding details and `std::ffi` for platform-specific, specified conversions.

Source

#### pub fn slice_encoded_bytes<R>(&self, range: R) -> &OsStr
where R: RangeBounds<usize>,

🔬This is a nightly-only experimental API. (`os_str_slice`)

Takes a substring based on a range that corresponds to the return value of `OsStr::as_encoded_bytes`.

The range’s start and end must lie on valid `OsStr` boundaries. A valid `OsStr` boundary is one of:

- The start of the string
- The end of the string
- Immediately before a valid non-empty UTF-8 substring
- Immediately after a valid non-empty UTF-8 substring

##### §Panics

Panics if `range` does not lie on valid `OsStr` boundaries or if it exceeds the end of the string.

##### §Example

    #![feature(os_str_slice)]

    use std::ffi::OsStr;

    let os_str = OsStr::new("foo=bar");
    let bytes = os_str.as_encoded_bytes();
    if let Some(index) = bytes.iter().position(|b| *b == b'=') {
        let key = os_str.slice_encoded_bytes(..index);
        let value = os_str.slice_encoded_bytes(index + 1..);
        assert_eq!(key, "foo");
        assert_eq!(value, "bar");
    }

1.53.0 · Source

#### pub fn to_ascii_lowercase(&self) -> OsString

Returns a copy of this string where each character is mapped to its ASCII lower case equivalent.

ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, but non-ASCII letters are unchanged.

To lowercase the value in-place, use `OsStr::make_ascii_lowercase`.

##### §Examples

    use std::ffi::OsString;
    let s = OsString::from("Grüße, Jürgen ❤");

    assert_eq!("grüße, jürgen ❤", s.to_ascii_lowercase());

1.53.0 · Source

#### pub fn to_ascii_uppercase(&self) -> OsString

Returns a copy of this string where each character is mapped to its ASCII upper case equivalent.

ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, but non-ASCII letters are unchanged.

To uppercase the value in-place, use `OsStr::make_ascii_uppercase`.

##### §Examples

    use std::ffi::OsString;
    let s = OsString::from("Grüße, Jürgen ❤");

    assert_eq!("GRüßE, JüRGEN ❤", s.to_ascii_uppercase());

1.53.0 · Source

#### pub fn is_ascii(&self) -> bool

Checks if all characters in this string are within the ASCII range.

An empty string returns `true`.

##### §Examples

    use std::ffi::OsString;

    let ascii = OsString::from("hello!\n");
    let non_ascii = OsString::from("Grüße, Jürgen ❤");

    assert!(ascii.is_ascii());
    assert!(!non_ascii.is_ascii());

1.53.0 · Source

#### pub fn eq_ignore_ascii_case<S>(&self, other: S) -> bool
where S: AsRef<OsStr>,

Checks that two strings are an ASCII case-insensitive match.

Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`, but without allocating and copying temporaries.

##### §Examples

    use std::ffi::OsString;

    assert!(OsString::from("Ferris").eq_ignore_ascii_case("FERRIS"));
    assert!(OsString::from("Ferrös").eq_ignore_ascii_case("FERRöS"));
    assert!(!OsString::from("Ferrös").eq_ignore_ascii_case("FERRÖS"));

1.87.0 · Source

#### pub fn display(&self) -> Display<'_>

Returns an object that implements `Display` for safely printing an `OsStr` that may contain non-Unicode data. This may perform lossy conversion, depending on the platform. If you would like an implementation which escapes the `OsStr` please use `Debug` instead.

##### §Examples

    use std::ffi::OsStr;

    let s = OsStr::new("Hello, world!");
    println!("{}", s.display());

Source

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

🔬This is a nightly-only experimental API. (`str_as_str`)

Returns the same string as a string slice `&OsStr`.

This method is redundant when used directly on `&OsStr`, but it helps dereferencing other string-like types to string slices, for example references to `Box<OsStr>` or `Arc<OsStr>`.

## Trait Implementations§

Source§

### impl AsRef<OsStr> for OsStr

Source§

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

Converts this type into a shared reference of the (usually inferred) input type.
Source§

### impl AsRef<Path> for OsStr

Source§

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

Converts this type into a shared reference of the (usually inferred) input type.
Source§

### impl Borrow<OsStr> for OsStr

Source§

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

Immutably borrows from an owned value. Read more
Source§

### impl Clone for OsStr

Source§

#### fn clone(&self) -> OsStr

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from `source`. Read more
Source§

### impl Debug for OsStr

Source§

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

Formats the value using the given formatter. Read more
Source§

### impl Default for OsStr

Source§

#### fn default() -> OsStr

Returns the “default value” for a type. Read more
Source§

### impl Deref for OsStr

Source§

#### type Target = OsStr

The resulting type after dereferencing.
Source§

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

Dereferences the value.
Source§

### impl Eq for OsStr

Source§

### impl From<&&'static OsStr> for OsStr

Source§

#### fn from(name: &&'static OsStr) -> OsStr

Converts to this type from the input type.
Source§

### impl From<&&'static str> for OsStr

Source§

#### fn from(name: &&'static str) -> OsStr

Converts to this type from the input type.
Source§

### impl From<&'static OsStr> for OsStr

Source§

#### fn from(name: &'static OsStr) -> OsStr

Converts to this type from the input type.
Source§

### impl From<&'static str> for OsStr

Source§

#### fn from(name: &'static str) -> OsStr

Converts to this type from the input type.
Source§

### impl From<&OsStr> for OsStr

Source§

#### fn from(id: &OsStr) -> OsStr

Converts to this type from the input type.
Source§

### impl From<&OsString> for OsStr

Available on crate feature `string` only.
Source§

#### fn from(name: &OsString) -> OsStr

Converts to this type from the input type.
Source§

### impl From<&Str> for OsStr

Source§

#### fn from(id: &Str) -> OsStr

Converts to this type from the input type.
Source§

### impl From<&String> for OsStr

Available on crate feature `string` only.
Source§

#### fn from(name: &String) -> OsStr

Converts to this type from the input type.
Source§

### impl From<Cow<'static, str>> for OsStr

Available on crate feature `string` only.
Source§

#### fn from(cow: Cow<'static, str>) -> OsStr

Converts to this type from the input type.
Source§

### impl From<OsString> for OsStr

Available on crate feature `string` only.
Source§

#### fn from(name: OsString) -> OsStr

Converts to this type from the input type.
Source§

### impl From<Str> for OsStr

Available on crate feature `string` only.
Source§

#### fn from(id: Str) -> OsStr

Converts to this type from the input type.
Source§

### impl From<String> for OsStr

Available on crate feature `string` only.
Source§

#### fn from(name: String) -> OsStr

Converts to this type from the input type.
Source§

### impl Hash for OsStr

Source§

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

Feeds this value into the given `Hasher`. Read more
1.3.0 · Source§

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

Feeds a slice of this type into the given `Hasher`. Read more
Source§

### impl IntoResettable<OsStr> for Option<&'static str>

Source§

#### fn into_resettable(self) -> Resettable<OsStr>

Convert to the intended resettable type
Source§

### impl Ord for OsStr

Source§

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

This method returns an `Ordering` between `self` and `other`. Read more
1.21.0 (const: unstable) · Source§

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

Compares and returns the maximum of two values. Read more
1.21.0 (const: unstable) · Source§

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

Compares and returns the minimum of two values. Read more
1.50.0 (const: unstable) · Source§

#### fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized,

Restrict a value to a certain interval. Read more
Source§

### impl PartialEq for OsStr

Source§

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

Equality operator `==`. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator `!=`. Read more
Source§

### impl PartialEq<&OsStr> for OsStr

Source§

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

Equality operator `==`. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator `!=`. Read more
Source§

### impl PartialEq<&str> for OsStr

Source§

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

Equality operator `==`. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator `!=`. Read more
Source§

### impl PartialEq<OsStr> for str

Source§

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

Equality operator `==`. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator `!=`. Read more
Source§

### impl PartialEq<OsStr> for &str

Source§

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

Equality operator `==`. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator `!=`. Read more
Source§

### impl PartialEq<OsStr> for &OsStr

Source§

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

Equality operator `==`. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator `!=`. Read more
Source§

### impl PartialEq<OsString> for OsStr

Source§

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

Equality operator `==`. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator `!=`. Read more
Source§

### impl PartialEq<String> for OsStr

Source§

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

Equality operator `==`. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator `!=`. Read more
Source§

### impl PartialEq<str> for OsStr

Source§

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

Equality operator `==`. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator `!=`. Read more
Source§

### impl PartialOrd for OsStr

Source§

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

This method returns an ordering between `self` and `other` values if one exists. Read more
1.0.0 (const: unstable) · Source§

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

Tests less than (for `self` and `other`) and is used by the `<` operator. Read more
1.0.0 (const: unstable) · Source§

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

Tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more
1.0.0 (const: unstable) · Source§

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

Tests greater than (for `self` and `other`) and is used by the `>` operator. Read more
1.0.0 (const: unstable) · Source§

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

Tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more
Source§

### impl StructuralPartialEq for OsStr

## Auto Trait Implementations§

§

### impl Freeze for OsStr

§

### impl RefUnwindSafe for OsStr

§

### impl Send for OsStr

§

### impl Sync for OsStr

§

### impl Unpin for OsStr

§

### impl UnsafeUnpin for OsStr

§

### impl UnwindSafe for OsStr

## Blanket Implementations§

Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T> CloneToUninit for T
where T: Clone,

Source§

#### unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (`clone_to_uninit`)
Performs copy-assignment from `self` to `dest`. Read more
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

Source§

### impl<I> IntoResettable<OsStr> for I
where I: Into<OsStr>,

Source§

#### fn into_resettable(self) -> Resettable<OsStr>

Convert to the intended resettable type
Source§

### impl<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

Source§

#### type Target = T

🔬This is a nightly-only experimental API. (`arbitrary_self_types`)
The target type on which the method may be called.
Source§

### impl<T> ToOwned for T
where T: Clone,

Source§

#### type Owned = T

The resulting type after obtaining ownership.
Source§

#### fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

#### fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.