Struct prelude::OsString

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.

Methods

impl OsString

fn new() -> OsString

Constructs a new empty OsString.

Examples

use std::ffi::OsString;

let os_string = OsString::new();

fn as_os_str(&self) -> &OsStr

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);

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.

Examples

use std::ffi::OsString;

let os_string = OsString::from("foo");
let string = os_string.into_string();
assert_eq!(string, Ok(String::from("foo")));

fn push<T>(&mut self, s: T) where
    T: AsRef<OsStr>, 

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");

fn with_capacity(capacity: usize) -> OsString

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());

fn clear(&mut self)

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, "");

fn capacity(&self) -> usize

Returns the capacity this OsString can hold without reallocating.

See OsString introduction for information about encoding.

Examples

use std::ffi::OsString;

let mut os_string = OsString::with_capacity(10);
assert!(os_string.capacity() >= 10);

fn 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.

Examples

use std::ffi::OsString;

let mut s = OsString::new();
s.reserve(10);
assert!(s.capacity() >= 10);

fn 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.

Examples

use std::ffi::OsString;

let mut s = OsString::new();
s.reserve_exact(10);
assert!(s.capacity() >= 10);

fn shrink_to_fit(&mut self)

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());

fn into_boxed_os_str(self) -> Box<OsStr>

Converts this OsString into a boxed OsStr.

Examples

use std::ffi::{OsString, OsStr};

let s = OsString::from("hello");

let b: Box<OsStr> = s.into_boxed_os_str();

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.

Examples

use std::ffi::OsStr;

let os_str = OsStr::new("foo");
assert_eq!(os_str.to_str(), Some("foo"));

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 valid unicode:

use std::ffi::OsStr;

let os_str = OsStr::new("foo");
assert_eq!(os_str.to_string_lossy(), "foo");

Had os_str contained invalid unicode, the to_string_lossy call might have returned "fo�".

fn to_os_string(&self) -> OsString

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"));

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());

fn 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.

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);

Trait Implementations

impl Borrow<OsStr> for OsString

fn borrow(&self) -> &OsStr

impl Debug for OsString

fn fmt(&self, formatter: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a, 'b> PartialEq<OsStr> for OsString

fn eq(&self, other: &OsStr) -> bool

impl<'a, 'b> PartialEq<&'a Path> for OsString

fn eq(&self, other: &&'a Path) -> bool

impl PartialEq<OsString> for OsString

fn eq(&self, other: &OsString) -> bool

impl PartialEq<str> for OsString

fn eq(&self, other: &str) -> bool

impl<'a, 'b> PartialEq<Cow<'a, Path>> for OsString

fn eq(&self, other: &Cow<'a, Path>) -> bool

impl<'a, 'b> PartialEq<Path> for OsString

fn eq(&self, other: &Path) -> bool

impl<'a, 'b> PartialEq<PathBuf> for OsString

fn eq(&self, other: &PathBuf) -> bool

impl<'a, 'b> PartialEq<&'a OsStr> for OsString

fn eq(&self, other: &&'a OsStr) -> bool

impl<'a, 'b> PartialEq<Cow<'a, OsStr>> for OsString

fn eq(&self, other: &Cow<'a, OsStr>) -> bool

impl Hash for OsString

fn hash<H>(&self, state: &mut H) where
    H: Hasher, 

impl AsRef<Path> for OsString

fn as_ref(&self) -> &Path

impl AsRef<OsStr> for OsString

fn as_ref(&self) -> &OsStr

impl Eq for OsString

impl Index<RangeFull> for OsString

type Output = OsStr

fn index(&self, _index: RangeFull) -> &OsStr

impl<'a, T> From<&'a T> for OsString where
    T: AsRef<OsStr> + ?Sized, 

fn from(s: &'a T) -> OsString

impl From<Box<OsStr>> for OsString

fn from(boxed: Box<OsStr>) -> OsString

impl From<String> for OsString

fn from(s: String) -> OsString

impl From<PathBuf> for OsString

fn from(path_buf: PathBuf) -> OsString

impl PartialOrd<OsString> for OsString

fn partial_cmp(&self, other: &OsString) -> Option<Ordering>

fn lt(&self, other: &OsString) -> bool

fn le(&self, other: &OsString) -> bool

fn gt(&self, other: &OsString) -> bool

fn ge(&self, other: &OsString) -> bool

impl<'a, 'b> PartialOrd<PathBuf> for OsString

fn partial_cmp(&self, other: &PathBuf) -> Option<Ordering>

impl PartialOrd<str> for OsString

fn partial_cmp(&self, other: &str) -> Option<Ordering>

impl<'a, 'b> PartialOrd<&'a Path> for OsString

fn partial_cmp(&self, other: &&'a Path) -> Option<Ordering>

impl<'a, 'b> PartialOrd<Cow<'a, OsStr>> for OsString

fn partial_cmp(&self, other: &Cow<'a, OsStr>) -> Option<Ordering>

impl<'a, 'b> PartialOrd<&'a OsStr> for OsString

fn partial_cmp(&self, other: &&'a OsStr) -> Option<Ordering>

impl<'a, 'b> PartialOrd<OsStr> for OsString

fn partial_cmp(&self, other: &OsStr) -> Option<Ordering>

impl<'a, 'b> PartialOrd<Path> for OsString

fn partial_cmp(&self, other: &Path) -> Option<Ordering>

impl<'a, 'b> PartialOrd<Cow<'a, Path>> for OsString

fn partial_cmp(&self, other: &Cow<'a, Path>) -> Option<Ordering>

impl OsStringExt for OsString

fn from_vec(vec: Vec<u8>) -> OsString

fn into_vec(self) -> Vec<u8>

impl Clone for OsString

fn clone(&self) -> OsString

impl Ord for OsString

fn cmp(&self, other: &OsString) -> Ordering

impl Deref for OsString

type Target = OsStr

The resulting type after dereferencing.

fn deref(&self) -> &OsStr

Dereferences the value.

impl Default for OsString

fn default() -> OsString

Constructs an empty OsString.