pub struct OsStr { /* private fields */ }os_str_display #120048)Expand description
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§
Source§impl OsStr
impl OsStr
Sourcepub fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &OsStr
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &OsStr
os_str_display #120048)Sourcepub unsafe fn from_encoded_bytes_unchecked(bytes: &[u8]) -> &Self
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub unsafe fn from_encoded_bytes_unchecked(bytes: &[u8]) -> &Self
os_str_display #120048)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();Sourcepub fn to_str(&self) -> Option<&str>
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn to_str(&self) -> Option<&str>
os_str_display #120048)Sourcepub fn to_string_lossy(&self) -> Cow<'_, str>
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn to_string_lossy(&self) -> Cow<'_, str>
os_str_display #120048)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");
}Sourcepub fn to_os_string(&self) -> OsString
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn to_os_string(&self) -> OsString
os_str_display #120048)Sourcepub fn is_empty(&self) -> bool
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn is_empty(&self) -> bool
os_str_display #120048)Checks whether the OsStr is empty.
§Examples
Sourcepub fn len(&self) -> usize
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn len(&self) -> usize
os_str_display #120048)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
Sourcepub fn into_os_string(self: Box<OsStr>) -> OsString
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn into_os_string(self: Box<OsStr>) -> OsString
os_str_display #120048)Sourcepub fn as_encoded_bytes(&self) -> &[u8] ⓘ
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn as_encoded_bytes(&self) -> &[u8] ⓘ
os_str_display #120048)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.
Sourcepub fn slice_encoded_bytes<R: RangeBounds<usize>>(&self, range: R) -> &Self
🔬This is a nightly-only experimental API. (os_str_slice #118485)
pub fn slice_encoded_bytes<R: RangeBounds<usize>>(&self, range: R) -> &Self
os_str_slice #118485)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");
}Sourcepub fn make_ascii_lowercase(&mut self)
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn make_ascii_lowercase(&mut self)
os_str_display #120048)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
Sourcepub fn make_ascii_uppercase(&mut self)
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn make_ascii_uppercase(&mut self)
os_str_display #120048)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
Sourcepub fn to_ascii_lowercase(&self) -> OsString
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn to_ascii_lowercase(&self) -> OsString
os_str_display #120048)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
Sourcepub fn to_ascii_uppercase(&self) -> OsString
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn to_ascii_uppercase(&self) -> OsString
os_str_display #120048)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
Sourcepub fn is_ascii(&self) -> bool
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn is_ascii(&self) -> bool
os_str_display #120048)Checks if all characters in this string are within the ASCII range.
§Examples
Sourcepub fn eq_ignore_ascii_case<S: AsRef<OsStr>>(&self, other: S) -> bool
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn eq_ignore_ascii_case<S: AsRef<OsStr>>(&self, other: S) -> bool
os_str_display #120048)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
Sourcepub fn display(&self) -> Display<'_>
🔬This is a nightly-only experimental API. (os_str_display #120048)
pub fn display(&self) -> Display<'_>
os_str_display #120048)Trait Implementations§
1.0.0 · Source§impl AsRef<OsStr> for Components<'_>
impl AsRef<OsStr> for Components<'_>
Source§impl CloneToUninit for OsStr
impl CloneToUninit for OsStr
1.52.0 · Source§impl<'a> Extend<&'a OsStr> for OsString
impl<'a> Extend<&'a OsStr> for OsString
Source§fn extend<T: IntoIterator<Item = &'a OsStr>>(&mut self, iter: T)
fn extend<T: IntoIterator<Item = &'a OsStr>>(&mut self, iter: T)
Source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one #72631)1.52.0 · Source§impl<'a> FromIterator<&'a OsStr> for OsString
impl<'a> FromIterator<&'a OsStr> for OsString
1.0.0 · Source§impl OsStrExt for OsStr
Available on Windows only.
impl OsStrExt for OsStr
Source§fn encode_wide(&self) -> EncodeWide<'_> ⓘ
fn encode_wide(&self) -> EncodeWide<'_> ⓘ
OsStr as a wide character sequence, i.e., potentially
ill-formed UTF-16. Read more