pub struct OsString { /* fields omitted */ }
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.
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.
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.
See the module's toplevel documentation about conversions for a discussion on
the traits which OsString
implements for conversions from/to native representations.
Constructs a new empty OsString
.
use std::ffi::OsString;
let os_string = OsString::new();
Converts to an OsStr
slice.
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);
Converts the OsString
into a String
if it contains valid Unicode data.
On failure, ownership of the original OsString
is returned.
use std::ffi::OsString;
let os_string = OsString::from("foo");
let string = os_string.into_string();
assert_eq!(string, Ok(String::from("foo")));
Extends the string with the given &OsStr
slice.
use std::ffi::OsString;
let mut os_string = OsString::from("foo");
os_string.push("bar");
assert_eq!(&os_string, "foobar");
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.
use std::ffi::OsString;
let mut os_string = OsString::with_capacity(10);
let capacity = os_string.capacity();
os_string.push("foo");
assert_eq!(capacity, os_string.capacity());
Truncates the OsString
to zero length.
use std::ffi::OsString;
let mut os_string = OsString::from("foo");
assert_eq!(&os_string, "foo");
os_string.clear();
assert_eq!(&os_string, "");
Returns the capacity this OsString
can hold without reallocating.
See OsString
introduction for information about encoding.
use std::ffi::OsString;
let mut os_string = OsString::with_capacity(10);
assert!(os_string.capacity() >= 10);
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.
use std::ffi::OsString;
let mut s = OsString::new();
s.reserve(10);
assert!(s.capacity() >= 10);
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.
use std::ffi::OsString;
let mut s = OsString::new();
s.reserve_exact(10);
assert!(s.capacity() >= 10);
Shrinks the capacity of the OsString
to match its length.
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());
🔬 This is a nightly-only experimental API. (shrink_to
)
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.
#![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);
Converts this OsString
into a boxed OsStr
.
use std::ffi::{OsString, OsStr};
let s = OsString::from("hello");
let b: Box<OsStr> = s.into_boxed_os_str();
Yields a &str
slice if the OsStr
is valid Unicode.
This conversion may entail doing a check for UTF-8 validity.
use std::ffi::OsStr;
let os_str = OsStr::new("foo");
assert_eq!(os_str.to_str(), Some("foo"));
Converts an OsStr
to a Cow
<
str
>
.
Any non-Unicode sequences are replaced with
U+FFFD REPLACEMENT CHARACTER
.
Calling to_string_lossy
on an OsStr
with invalid unicode:
#[cfg(any(unix, target_os = "redox"))] {
use std::ffi::OsStr;
use std::os::unix::ffi::OsStrExt;
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::*;
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");
}
Copies the slice into an owned OsString
.
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"));
Checks whether the OsStr
is empty.
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());
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.
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);
Performs copy-assignment from source
. Read more
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
This method tests for self
and other
values to be equal, and is used by ==
. Read more
This method tests for !=
.
The returned type after indexing.
Performs the indexing (container[index]
) operation.
Formats the value using the given formatter. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
The resulting type after dereferencing.
Immutably borrows from an owned value. Read more
Creates an [OsString
] from a byte vector. Read more
Yields the underlying byte vector of this [OsString
]. Read more
This method returns an Ordering
between self
and other
. Read more
fn max(self, other: Self) -> Self | 1.21.0 [src] |
Compares and returns the maximum of two values. Read more
fn min(self, other: Self) -> Self | 1.21.0 [src] |
Compares and returns the minimum of two values. Read more
Constructs an empty OsString
.
Feeds this value into the given [Hasher
]. Read more
Feeds a slice of this type into the given [Hasher
]. Read more
Converts a OsString
into a Rc
<OsStr>
without copying or allocating.
Converts a OsString
into a Arc
<OsStr>
without copying or allocating.
Converts a Box<OsStr>
into a OsString
without copying or allocating.
Converts a OsString
into a PathBuf
This conversion does not allocate or copy memory.
Converts a OsString
into a Box
<OsStr>
without copying or allocating.
Converts a PathBuf
into a OsString
This conversion does not allocate or copy memory.
Converts a String
into a [OsString
].
The conversion copies the data, and includes an allocation on the heap.
Creates owned data from borrowed data, usually by cloning. Read more
🔬 This is a nightly-only experimental API. (toowned_clone_into
)
recently added
Uses borrowed data to replace owned data, usually by cloning. Read more
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
type Error = <U as TryFrom<T>>::Error
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
🔬 This is a nightly-only experimental API. (get_type_id
)
this method will likely be replaced by an associated static