1.0.0[−][src]Struct std::ffi::OsString
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 if possible. A consequence
of this is that OsString
instances are not NUL
terminated; in order
to pass to e.g., Unix system call, you should create a CStr
.
OsString
is to &OsStr
as String
is to &str
: the former
in each pair are owned strings; the latter are borrowed
references.
Note, OsString
and OsStr
internally do not necessarily hold strings in
the form native to the platform; While on Unix, strings are stored as a
sequence of 8-bit values, on Windows, where strings are 16-bit value based
as just discussed, strings are also actually stored as a sequence of 8-bit
values, encoded in a less-strict variant of UTF-8. This is useful to
understand when handling capacity and length values.
Creating an OsString
From a Rust string: OsString
implements
From
<
String
>
, so you can use my_string.from
to
create an OsString
from a normal Rust string.
From slices: Just like you can start with an empty Rust
String
and then push_str
&str
sub-string slices into it, you can create an empty OsString
with
the new
method and then push string slices into it with the
push
method.
Extracting a borrowed reference to the whole OS string
You can use the as_os_str
method to get an &
OsStr
from
an OsString
; this is effectively a borrowed reference to the
whole string.
Conversions
See the module's toplevel documentation about conversions for a discussion on
the traits which OsString
implements for conversions from/to native representations.
Methods
impl OsString
[src]
pub fn new() -> OsString
[src]
Constructs a new empty OsString
.
Examples
use std::ffi::OsString; let os_string = OsString::new();Run
pub fn as_os_str(&self) -> &OsStr
[src]
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
pub fn into_string(self) -> Result<String, OsString>
[src]
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
pub fn push<T: AsRef<OsStr>>(&mut self, s: T)
[src]
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
pub fn with_capacity(capacity: usize) -> OsString
1.9.0[src]
Creates a new OsString
with the given capacity.
The string will be able to hold exactly capacity
length 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
pub fn clear(&mut self)
1.9.0[src]
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
pub fn capacity(&self) -> usize
1.9.0[src]
Returns the capacity this OsString
can hold without reallocating.
See OsString
introduction for information about encoding.
Examples
use std::ffi::OsString; let os_string = OsString::with_capacity(10); assert!(os_string.capacity() >= 10);Run
pub fn reserve(&mut self, additional: usize)
1.9.0[src]
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
pub fn reserve_exact(&mut self, additional: usize)
1.9.0[src]
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
pub fn shrink_to_fit(&mut self)
1.19.0[src]
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
pub fn shrink_to(&mut self, min_capacity: usize)
[src]
🔬 This is a nightly-only experimental API. (shrink_to
#56431)
new API
Shrinks the capacity of the OsString
with a lower bound.
The capacity will remain at least as large as both the length and the supplied value.
Panics if the current capacity is smaller than the supplied minimum capacity.
Examples
#![feature(shrink_to)] use std::ffi::OsString; let mut s = OsString::from("foo"); s.reserve(100); assert!(s.capacity() >= 100); s.shrink_to(10); assert!(s.capacity() >= 10); s.shrink_to(0); assert!(s.capacity() >= 3);Run
ⓘImportant traits for Box<I>pub fn into_boxed_os_str(self) -> Box<OsStr>
1.20.0[src]
Methods from Deref<Target = OsStr>
pub fn to_str(&self) -> Option<&str>
[src]
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
pub fn to_string_lossy(&self) -> Cow<str>
[src]
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(any(unix, target_os = "redox"))] { 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"); }Run
pub fn to_os_string(&self) -> OsString
[src]
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
pub fn is_empty(&self) -> bool
1.9.0[src]
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
pub fn len(&self) -> usize
1.9.0[src]
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.
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 OsStringExt for OsString
[src]
impl OsStringExt for OsString
[src]
impl From<String> for OsString
[src]
impl<'_, T: ?Sized + AsRef<OsStr>> From<&'_ T> for OsString
[src]
impl From<Box<OsStr>> for OsString
1.18.0[src]
impl From<OsString> for Box<OsStr>
1.20.0[src]
impl From<OsString> for Arc<OsStr>
1.24.0[src]
impl From<OsString> for Rc<OsStr>
1.24.0[src]
impl<'a> From<OsString> for Cow<'a, OsStr>
1.28.0[src]
impl<'a> From<&'a OsString> for Cow<'a, OsStr>
1.28.0[src]
impl<'a> From<Cow<'a, OsStr>> for OsString
1.28.0[src]
impl From<OsString> for PathBuf
[src]
fn from(s: OsString) -> PathBuf
[src]
Converts a OsString
into a PathBuf
This conversion does not allocate or copy memory.
impl From<PathBuf> for OsString
1.14.0[src]
fn from(path_buf: PathBuf) -> OsString
[src]
Converts a PathBuf
into a OsString
This conversion does not allocate or copy memory.
impl PartialEq<OsString> for OsString
[src]
impl PartialEq<str> for OsString
[src]
impl PartialEq<OsString> for str
[src]
impl<'_> PartialEq<&'_ str> for OsString
1.29.0[src]
impl<'a> PartialEq<OsString> for &'a str
1.29.0[src]
impl<'a, 'b> PartialEq<OsStr> for OsString
1.8.0[src]
impl<'a, 'b> PartialEq<OsString> for OsStr
1.8.0[src]
impl<'a, 'b> PartialEq<&'a OsStr> for OsString
1.8.0[src]
impl<'a, 'b> PartialEq<OsString> for &'a OsStr
1.8.0[src]
impl<'a, 'b> PartialEq<OsString> for Cow<'a, OsStr>
1.8.0[src]
impl<'a, 'b> PartialEq<Cow<'a, OsStr>> for OsString
1.8.0[src]
impl<'a, 'b> PartialEq<OsString> for PathBuf
1.8.0[src]
impl<'a, 'b> PartialEq<PathBuf> for OsString
1.8.0[src]
impl<'a, 'b> PartialEq<OsString> for Path
1.8.0[src]
impl<'a, 'b> PartialEq<Path> for OsString
1.8.0[src]
impl<'a, 'b> PartialEq<OsString> for &'a Path
1.8.0[src]
impl<'a, 'b> PartialEq<&'a Path> for OsString
1.8.0[src]
impl<'a, 'b> PartialEq<OsString> for Cow<'a, Path>
1.8.0[src]
impl<'a, 'b> PartialEq<Cow<'a, Path>> for OsString
1.8.0[src]
impl Eq for OsString
[src]
impl Ord for OsString
[src]
fn cmp(&self, other: &OsString) -> Ordering
[src]
fn max(self, other: Self) -> Self
1.21.0[src]
fn min(self, other: Self) -> Self
1.21.0[src]
fn clamp(self, min: Self, max: Self) -> Self
[src]
impl PartialOrd<OsString> for OsString
[src]
fn partial_cmp(&self, other: &OsString) -> Option<Ordering>
[src]
fn lt(&self, other: &OsString) -> bool
[src]
fn le(&self, other: &OsString) -> bool
[src]
fn gt(&self, other: &OsString) -> bool
[src]
fn ge(&self, other: &OsString) -> bool
[src]
impl PartialOrd<str> for OsString
[src]
fn partial_cmp(&self, other: &str) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<OsStr> for OsString
1.8.0[src]
fn partial_cmp(&self, other: &OsStr) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<OsString> for OsStr
1.8.0[src]
fn partial_cmp(&self, other: &OsString) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<&'a OsStr> for OsString
1.8.0[src]
fn partial_cmp(&self, other: &&'a OsStr) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<OsString> for &'a OsStr
1.8.0[src]
fn partial_cmp(&self, other: &OsString) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<OsString> for Cow<'a, OsStr>
1.8.0[src]
fn partial_cmp(&self, other: &OsString) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<Cow<'a, OsStr>> for OsString
1.8.0[src]
fn partial_cmp(&self, other: &Cow<'a, OsStr>) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<OsString> for PathBuf
1.8.0[src]
fn partial_cmp(&self, other: &OsString) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<PathBuf> for OsString
1.8.0[src]
fn partial_cmp(&self, other: &PathBuf) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<OsString> for Path
1.8.0[src]
fn partial_cmp(&self, other: &OsString) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<Path> for OsString
1.8.0[src]
fn partial_cmp(&self, other: &Path) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<OsString> for &'a Path
1.8.0[src]
fn partial_cmp(&self, other: &OsString) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<&'a Path> for OsString
1.8.0[src]
fn partial_cmp(&self, other: &&'a Path) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<OsString> for Cow<'a, Path>
1.8.0[src]
fn partial_cmp(&self, other: &OsString) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl<'a, 'b> PartialOrd<Cow<'a, Path>> for OsString
1.8.0[src]
fn partial_cmp(&self, other: &Cow<'a, Path>) -> Option<Ordering>
[src]
#[must_use]
fn lt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn le(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn gt(&self, other: &Rhs) -> bool
[src]
#[must_use]
fn ge(&self, other: &Rhs) -> bool
[src]
impl Hash for OsString
[src]
fn hash<H: Hasher>(&self, state: &mut H)
[src]
fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0[src]
H: Hasher,
impl Deref for OsString
[src]
impl Index<RangeFull> for OsString
[src]
type Output = OsStr
The returned type after indexing.
fn index(&self, _index: RangeFull) -> &OsStr
[src]
impl Debug for OsString
[src]
impl AsRef<OsStr> for OsString
[src]
impl AsRef<Path> for OsString
[src]
impl Clone for OsString
[src]
impl Default for OsString
1.9.0[src]
impl Borrow<OsStr> for OsString
[src]
Auto Trait Implementations
impl UnwindSafe for OsString
impl RefUnwindSafe for OsString
impl Unpin for OsString
impl Send for OsString
impl Sync for OsString
Blanket Implementations
impl<T> From<T> for T
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
ⓘImportant traits for &'_ mut Ffn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,