Struct std::ffi::OsString
[−]
[src]
pub struct OsString {
// some fields omitted
}1.0.0A 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, but 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.
Methods
impl OsString
fn new() -> OsString
Constructs a new empty OsString.
fn as_os_str(&self) -> &OsStr
Converts to an OsStr slice.
fn into_string(self) -> Result<String, OsString>
Converts the OsString into a String if it contains valid Unicode data.
On failure, ownership of the original OsString is returned.
fn push<T: AsRef<OsStr>>(&mut self, s: T)
Extends the string with the given &OsStr slice.
1.9.0fn with_capacity(capacity: usize) -> OsString
Creates a new OsString with the given capacity.
The string will be able to hold exactly capacity lenth units of other
OS strings without reallocating. If capacity is 0, the string will not
allocate.
See main OsString documentation information about encoding.
1.9.0fn clear(&mut self)
Truncates the OsString to zero length.
1.9.0fn capacity(&self) -> usize
Returns the capacity this OsString can hold without reallocating.
See OsString introduction for information about encoding.
1.9.0fn reserve(&mut self, additional: usize)
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.
1.9.0fn reserve_exact(&mut self, additional: usize)
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.
Methods from Deref<Target=OsStr>
fn to_str(&self) -> Option<&str>
Yields a &str slice if the OsStr is valid Unicode.
This conversion may entail doing a check for UTF-8 validity.
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.
fn to_os_string(&self) -> OsString
Copies the slice into an owned OsString.
1.9.0fn is_empty(&self) -> bool
Checks whether the OsStr is empty.
1.9.0fn len(&self) -> usize
Returns the length of this OsStr.
Note that this does not return the number of bytes in this string
as, for example, OS strings on Windows are encoded as a list of u16
rather than a list of bytes. This number is simply useful for passing to
other methods like OsString::with_capacity to avoid reallocations.
See OsStr introduction for more information about encoding.