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§
Methods from Deref<Target = OsStr>§
1.0.0 · sourcepub fn to_string_lossy(&self) -> Cow<'_, str>
pub 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 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 · sourcepub fn to_os_string(&self) -> OsString
pub fn to_os_string(&self) -> OsString
1.9.0 · sourcepub fn is_empty(&self) -> bool
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 · sourcepub fn len(&self) -> usize
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);
1.74.0 · sourcepub fn as_encoded_bytes(&self) -> &[u8] ⓘ
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.
sourcepub fn slice_encoded_bytes<R>(&self, range: R) -> &OsStrwhere
R: RangeBounds<usize>,
🔬This is a nightly-only experimental API. (os_str_slice
)
pub fn slice_encoded_bytes<R>(&self, range: R) -> &OsStrwhere
R: RangeBounds<usize>,
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 · sourcepub fn to_ascii_lowercase(&self) -> OsString
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 · sourcepub fn to_ascii_uppercase(&self) -> OsString
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 · sourcepub fn is_ascii(&self) -> bool
pub fn is_ascii(&self) -> bool
Checks if all characters in this string are within the ASCII range.
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 · sourcepub fn eq_ignore_ascii_case<S>(&self, other: S) -> bool
pub fn eq_ignore_ascii_case<S>(&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"));
Trait Implementations§
source§impl IntoResettable<OsStr> for Option<&'static str>
impl IntoResettable<OsStr> for Option<&'static str>
source§fn into_resettable(self) -> Resettable<OsStr>
fn into_resettable(self) -> Resettable<OsStr>
source§impl Ord for OsStr
impl Ord for OsStr
source§impl PartialEq<&OsStr> for OsStr
impl PartialEq<&OsStr> for OsStr
source§impl PartialEq<&str> for OsStr
impl PartialEq<&str> for OsStr
source§impl PartialEq<OsStr> for &OsStr
impl PartialEq<OsStr> for &OsStr
source§impl PartialEq<OsStr> for &str
impl PartialEq<OsStr> for &str
source§impl PartialEq<OsStr> for str
impl PartialEq<OsStr> for str
source§impl PartialEq<OsString> for OsStr
impl PartialEq<OsString> for OsStr
source§impl PartialEq<String> for OsStr
impl PartialEq<String> for OsStr
source§impl PartialEq for OsStr
impl PartialEq for OsStr
source§impl PartialOrd for OsStr
impl PartialOrd for OsStr
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more