Struct OsStr

struct OsStr { ... }

Borrowed reference to an OS string (see OsString).

This type represents a borrowed reference to a string in the operating system's preferred representation.

&OsStr is to OsString as &[str] is to [String]: the former in each pair are borrowed references; the latter are owned strings.

See the module's toplevel documentation about conversions for a discussion on the traits which OsStr implements for conversions from/to native representations.

Implementations

impl OsStr

const fn new<S: ~const AsRef<OsStr> + ?Sized>(s: &S) -> &OsStr

Coerces into an OsStr slice.

Examples

use std::ffi::OsStr;

let os_str = OsStr::new("foo");

unsafe fn from_encoded_bytes_unchecked(bytes: &[u8]) -> &Self

Converts a slice of bytes to an OS string slice without checking that the string contains valid OsStr-encoded data.

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.

See the module's toplevel documentation about conversions for safe, cross-platform conversions from/to native representations.

Safety

As the encoding is unspecified, callers must pass in bytes that originated as a mixture of validated UTF-8 and bytes from OsStr::as_encoded_bytes from within the same Rust version built for the same target platform. For example, reconstructing an OsStr from bytes sent over the network or stored in a file will likely violate these safety rules.

Due to the encoding being self-synchronizing, the bytes from OsStr::as_encoded_bytes can be split either immediately before or immediately after any valid non-empty UTF-8 substring.

Example

use std::ffi::OsStr;

let os_str = OsStr::new("Mary had a little lamb");
let bytes = os_str.as_encoded_bytes();
let words = bytes.split(|b| *b == b' ');
let words: Vec<&OsStr> = words.map(|word| {
    // SAFETY:
    // - Each `word` only contains content that originated from `OsStr::as_encoded_bytes`
    // - Only split with ASCII whitespace which is a non-empty UTF-8 substring
    unsafe { OsStr::from_encoded_bytes_unchecked(word) }
}).collect();

fn to_str(self: &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"));

fn to_string_lossy(self: &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");
}

fn to_os_string(self: &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"));

fn is_empty(self: &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());

fn len(self: &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);

fn into_os_string(self: Box<Self>) -> OsString

Converts a [Box]<[OsStr]> into an OsString without copying or allocating.

fn as_encoded_bytes(self: &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.

fn slice_encoded_bytes<R: ops::RangeBounds<usize>>(self: &Self, range: R) -> &Self

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");
}

fn make_ascii_lowercase(self: &mut Self)

Converts this string to its ASCII lower case equivalent in-place.

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

To return a new lowercased value without modifying the existing one, use OsStr::to_ascii_lowercase.

Examples

use std::ffi::OsString;

let mut s = OsString::from("GRÜßE, JÜRGEN ❤");

s.make_ascii_lowercase();

assert_eq!("grÜße, jÜrgen ❤", s);

fn make_ascii_uppercase(self: &mut Self)

Converts this string to its ASCII upper case equivalent in-place.

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

To return a new uppercased value without modifying the existing one, use OsStr::to_ascii_uppercase.

Examples

use std::ffi::OsString;

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

s.make_ascii_uppercase();

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

fn to_ascii_lowercase(self: &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());

fn to_ascii_uppercase(self: &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());

fn is_ascii(self: &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());

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

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

fn display(self: &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());

const fn as_os_str(self: &Self) -> &OsStr

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

impl AsRef for OsStr

fn as_ref(self: &Self) -> &OsStr

impl AsRef for crate::ffi::OsStr

fn as_ref(self: &Self) -> &Path

impl CloneToUninit for OsStr

unsafe fn clone_to_uninit(self: &Self, dst: *mut u8)

impl Debug for OsStr

fn fmt(self: &Self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result

impl Eq for OsStr

impl Freeze for OsStr

impl Hash for OsStr

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

impl Ord for OsStr

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

impl OsStrExt for crate::ffi::OsStr

fn from_bytes(slice: &[u8]) -> &OsStr
fn as_bytes(self: &Self) -> &[u8]

impl OsStrExt for crate::ffi::OsStr

fn encode_wide(self: &Self) -> EncodeWide<'_>

impl OsStrExt for crate::ffi::OsStr

fn from_bytes(slice: &[u8]) -> &OsStr
fn as_bytes(self: &Self) -> &[u8]

impl PartialEq for OsStr

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

impl PartialEq for OsStr

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

impl PartialEq for crate::ffi::OsStr

fn eq(self: &Self, other: &Path) -> bool

impl PartialEq for crate::ffi::OsStr

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

impl PartialOrd for OsStr

fn partial_cmp(self: &Self, other: &str) -> Option<cmp::Ordering>

impl PartialOrd for OsStr

fn partial_cmp(self: &Self, other: &OsStr) -> Option<cmp::Ordering>
fn lt(self: &Self, other: &OsStr) -> bool
fn le(self: &Self, other: &OsStr) -> bool
fn gt(self: &Self, other: &OsStr) -> bool
fn ge(self: &Self, other: &OsStr) -> bool

impl PartialOrd for crate::ffi::OsStr

fn partial_cmp(self: &Self, other: &Path) -> Option<cmp::Ordering>

impl PartialOrd for crate::ffi::OsStr

fn partial_cmp(self: &Self, other: &PathBuf) -> Option<cmp::Ordering>

impl RefUnwindSafe for OsStr

impl Send for OsStr

impl Sized for OsStr

impl Sync for OsStr

impl ToOwned for OsStr

fn to_owned(self: &Self) -> OsString
fn clone_into(self: &Self, target: &mut OsString)

impl Unpin for OsStr

impl UnwindSafe for OsStr

impl<'a> PartialEq for crate::ffi::OsStr

fn eq(self: &Self, other: &Cow<'a, Path>) -> bool

impl<'a> PartialEq for crate::ffi::OsStr

fn eq(self: &Self, other: &&'a Path) -> bool

impl<'a> PartialOrd for crate::ffi::OsStr

fn partial_cmp(self: &Self, other: &&'a Path) -> Option<cmp::Ordering>

impl<'a> PartialOrd for crate::ffi::OsStr

fn partial_cmp(self: &Self, other: &Cow<'a, Path>) -> Option<cmp::Ordering>

impl<'a, 'b> PartialEq for OsStr

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

impl<'a, 'b> PartialEq for OsStr

fn eq(self: &Self, other: &Cow<'a, OsStr>) -> bool

impl<'a, 'b> PartialOrd for OsStr

fn partial_cmp(self: &Self, other: &Cow<'a, OsStr>) -> Option<cmp::Ordering>

impl<'a, 'b> PartialOrd for OsStr

fn partial_cmp(self: &Self, other: &OsString) -> Option<cmp::Ordering>

impl<T> Any for OsStr

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for OsStr

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for OsStr

fn borrow_mut(self: &mut Self) -> &mut T