Struct os_str_bytes::RawOsStr

#[repr(transparent)]
pub struct RawOsStr(_);

Available on crate feature raw_os_str only.

A container for borrowed byte strings converted by this crate.

This wrapper is intended to prevent violating the invariants of the unspecified encoding used by this crate and minimize encoding conversions.

Indices

Methods of this struct that accept indices require that the index lie on a UTF-8 boundary. Although it is possible to manipulate platform strings based on other indices, this crate currently does not support them for slicing methods. They would add significant complication to the implementation and are generally not necessary. However, all indices returned by this struct can be used for slicing.

On Unix, all indices are permitted, to avoid false positives. However, relying on this implementation detail is discouraged. Platform-specific indices are error-prone.

Complexity

All searching methods have worst-case multiplicative time complexity (i.e., O(self.raw_len() * pat.len())). Enabling the “memchr” feature allows these methods to instead run in linear time in the worst case (documented for memchr::memmem::find).

Safety

Although this type is annotated with #[repr(transparent)], the inner representation is not stable. Transmuting between this type and any other causes immediate undefined behavior.

Implementations

impl RawOsStr

pub fn new(string: &OsStr) -> Cow<'_, Self>

Converts a platform-native string into a representation that can be more easily manipulated.

This method performs the necessary conversion immediately, so it can be expensive to call. It is recommended to continue using the returned instance as long as possible (instead of the original OsStr), to avoid repeated conversions.

Examples

use std::env;

use os_str_bytes::RawOsStr;

let os_string = env::current_exe()?.into_os_string();
println!("{:?}", RawOsStr::new(&os_string));

pub fn from_str(string: &str) -> &Self

Wraps a string, without copying or encoding conversion.

This method is much more efficient than RawOsStr::new, since the encoding used by this crate is compatible with UTF-8.

Examples

use os_str_bytes::RawOsStr;

let string = "foobar";
let raw = RawOsStr::from_str(string);
assert_eq!(string, raw);

pub fn assert_from_raw_bytes(string: &[u8]) -> &Self

Wraps a byte string, without copying or encoding conversion.

Panics

Panics if the string is not valid for the unspecified encoding used by this crate.

Examples

use std::env;

use os_str_bytes::RawOsStr;

let os_string = env::current_exe()?.into_os_string();
let raw = RawOsStr::new(&os_string);
let raw_bytes = raw.as_raw_bytes();
assert_eq!(&*raw, RawOsStr::assert_from_raw_bytes(raw_bytes));

pub fn from_raw_bytes(string: &[u8]) -> Result<&Self, EncodingError>

Available on crate feature checked_conversions only.

Wraps a byte string, without copying or encoding conversion.

assert_from_raw_bytes should almost always be used instead. For more information, see EncodingError.

Errors

See documentation for EncodingError.

Examples

use std::env;

use os_str_bytes::RawOsStr;

let os_string = env::current_exe()?.into_os_string();
let raw = RawOsStr::new(&os_string);
assert_eq!(Ok(&*raw), RawOsStr::from_raw_bytes(raw.as_raw_bytes()));

pub unsafe fn from_raw_bytes_unchecked(string: &[u8]) -> &Self

Wraps a byte string, without copying or encoding conversion.

Safety

The string must be valid for the unspecified encoding used by this crate.

Examples

use std::env;

use os_str_bytes::RawOsStr;

let os_string = env::current_exe()?.into_os_string();
let raw = RawOsStr::new(&os_string);
let raw_bytes = raw.as_raw_bytes();
assert_eq!(&*raw, unsafe {
    RawOsStr::from_raw_bytes_unchecked(raw_bytes)
});

pub fn as_raw_bytes(&self) -> &[u8]

Returns the byte string stored by this container.

The returned string will use an unspecified encoding.

Examples

use os_str_bytes::RawOsStr;

let string = "foobar";
let raw = RawOsStr::from_str(string);
assert_eq!(string.as_bytes(), raw.as_raw_bytes());

pub fn contains<P>(&self, pat: P) -> boolwhere P: Pattern,

Equivalent to str::contains.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert!(raw.contains("oo"));
assert!(!raw.contains("of"));

pub fn ends_with<P>(&self, pat: P) -> boolwhere P: Pattern,

Equivalent to str::ends_with.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert!(raw.ends_with("bar"));
assert!(!raw.ends_with("foo"));

pub fn ends_with_os(&self, pat: &Self) -> bool

Equivalent to str::ends_with but accepts this type for the pattern.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert!(raw.ends_with_os(RawOsStr::from_str("bar")));
assert!(!raw.ends_with_os(RawOsStr::from_str("foo")));

pub fn find<P>(&self, pat: P) -> Option<usize>where P: Pattern,

Equivalent to str::find.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert_eq!(Some(1), raw.find("o"));
assert_eq!(None, raw.find("of"));

pub fn is_empty(&self) -> bool

Equivalent to str::is_empty.

Examples

use os_str_bytes::RawOsStr;

assert!(RawOsStr::from_str("").is_empty());
assert!(!RawOsStr::from_str("foobar").is_empty());

pub fn raw_len(&self) -> usize

Returns the length of the byte string stored by this container.

Only the following assumptions can be made about the result:

• The length of any Unicode character is the length of its UTF-8 representation (i.e., char::len_utf8).
• Splitting a string at a UTF-8 boundary will return two strings with lengths that sum to the length of the original string.

This method may return a different result than would OsStr::len when called on same string, since OsStr uses an unspecified encoding.

Examples

use os_str_bytes::RawOsStr;

assert_eq!(6, RawOsStr::from_str("foobar").raw_len());
assert_eq!(0, RawOsStr::from_str("").raw_len());

pub fn rfind<P>(&self, pat: P) -> Option<usize>where P: Pattern,

Equivalent to str::rfind.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert_eq!(Some(2), raw.rfind("o"));
assert_eq!(None, raw.rfind("of"));

pub fn rsplit_once<P>(&self, pat: P) -> Option<(&Self, &Self)>where P: Pattern,

Equivalent to str::rsplit_once.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert_eq!(
    Some((RawOsStr::from_str("fo"), RawOsStr::from_str("bar"))),
    raw.rsplit_once("o"),
);
assert_eq!(None, raw.rsplit_once("of"));

pub fn split<P>(&self, pat: P) -> Split<'_, P> where P: Pattern,

Equivalent to str::split, but empty patterns are not accepted.

Panics

Panics if the pattern is empty.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert_eq!(["f", "", "bar"], *raw.split("o").collect::<Vec<_>>());

pub fn split_at(&self, mid: usize) -> (&Self, &Self)

Equivalent to str::split_at.

Panics

Panics if the index is not a valid boundary.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert_eq!(
    ((RawOsStr::from_str("fo"), RawOsStr::from_str("obar"))),
    raw.split_at(2),
);

pub fn split_once<P>(&self, pat: P) -> Option<(&Self, &Self)>where P: Pattern,

Equivalent to str::split_once.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert_eq!(
    Some((RawOsStr::from_str("f"), RawOsStr::from_str("obar"))),
    raw.split_once("o"),
);
assert_eq!(None, raw.split_once("of"));

pub fn starts_with<P>(&self, pat: P) -> boolwhere P: Pattern,

Equivalent to str::starts_with.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert!(raw.starts_with("foo"));
assert!(!raw.starts_with("bar"));

pub fn starts_with_os(&self, pat: &Self) -> bool

Equivalent to str::starts_with but accepts this type for the pattern.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("foobar");
assert!(raw.starts_with_os(RawOsStr::from_str("foo")));
assert!(!raw.starts_with_os(RawOsStr::from_str("bar")));

pub fn strip_prefix<P>(&self, pat: P) -> Option<&Self>where P: Pattern,

Equivalent to str::strip_prefix.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("111foo1bar111");
assert_eq!(
    Some(RawOsStr::from_str("11foo1bar111")),
    raw.strip_prefix("1"),
);
assert_eq!(None, raw.strip_prefix("o"));

pub fn strip_suffix<P>(&self, pat: P) -> Option<&Self>where P: Pattern,

Equivalent to str::strip_suffix.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("111foo1bar111");
assert_eq!(
    Some(RawOsStr::from_str("111foo1bar11")),
    raw.strip_suffix("1"),
);
assert_eq!(None, raw.strip_suffix("o"));

pub fn to_os_str(&self) -> Cow<'_, OsStr>

Converts this representation back to a platform-native string.

When possible, use RawOsStrCow::into_os_str for a more efficient conversion on some platforms.

Examples

use std::env;

use os_str_bytes::RawOsStr;

let os_string = env::current_exe()?.into_os_string();
let raw = RawOsStr::new(&os_string);
assert_eq!(os_string, raw.to_os_str());

pub fn to_str(&self) -> Option<&str>

Equivalent to OsStr::to_str.

Examples

use os_str_bytes::RawOsStr;

let string = "foobar";
let raw = RawOsStr::from_str(string);
assert_eq!(Some(string), raw.to_str());

pub fn to_str_lossy(&self) -> Cow<'_, str>

Converts this string to the best UTF-8 representation possible.

Invalid sequences will be replaced with char::REPLACEMENT_CHARACTER.

This method may return a different result than would OsStr::to_string_lossy when called on same string, since OsStr uses an unspecified encoding.

Examples

use std::env;

use os_str_bytes::RawOsStr;

let os_string = env::current_exe()?.into_os_string();
let raw = RawOsStr::new(&os_string);
println!("{}", raw.to_str_lossy());

pub fn trim_end_matches<P>(&self, pat: P) -> &Selfwhere P: Pattern,

Equivalent to str::trim_end_matches.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("111foo1bar111");
assert_eq!("111foo1bar", raw.trim_end_matches("1"));
assert_eq!("111foo1bar111", raw.trim_end_matches("o"));

pub fn trim_matches<P>(&self, pat: P) -> &Selfwhere P: Pattern,

Equivalent to str::trim_matches.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("111foo1bar111");
assert_eq!("foo1bar", raw.trim_matches("1"));
assert_eq!("111foo1bar111", raw.trim_matches("o"));

pub fn trim_start_matches<P>(&self, pat: P) -> &Selfwhere P: Pattern,

Equivalent to str::trim_start_matches.

Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::from_str("111foo1bar111");
assert_eq!("foo1bar111", raw.trim_start_matches("1"));
assert_eq!("111foo1bar111", raw.trim_start_matches("o"));

Trait Implementations

impl AsRef<RawOsStr> for RawOsStr

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<RawOsStr> for RawOsString

fn as_ref(&self) -> &RawOsStr

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<RawOsStr> for String

fn as_ref(&self) -> &RawOsStr

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<RawOsStr> for str

fn as_ref(&self) -> &RawOsStr

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<RawOsStr> for RawOsString

fn borrow(&self) -> &RawOsStr

Immutably borrows from an owned value.

impl Debug for RawOsStr

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for &RawOsStr

fn default() -> Self

Returns the “default value” for a type.

impl<'a> From<&'a RawOsStr> for Cow<'a, RawOsStr>

fn from(value: &'a RawOsStr) -> Self

Converts to this type from the input type.

impl From<Box<str, Global>> for Box<RawOsStr>

fn from(value: Box<str>) -> Self

Converts to this type from the input type.

impl From<RawOsString> for Box<RawOsStr>

fn from(value: RawOsString) -> Self

Converts to this type from the input type.

impl Hash for RawOsStr

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

Feeds this value into the given Hasher.

impl Index<Range<usize>> for RawOsStr

type Output = RawOsStr

The returned type after indexing.

fn index(&self, idx: Range<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for RawOsStr

type Output = RawOsStr

The returned type after indexing.

fn index(&self, idx: RangeFrom<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFull> for RawOsStr

type Output = RawOsStr

The returned type after indexing.

fn index(&self, idx: RangeFull) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeInclusive<usize>> for RawOsStr

type Output = RawOsStr

The returned type after indexing.

fn index(&self, idx: RangeInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for RawOsStr

type Output = RawOsStr

The returned type after indexing.

fn index(&self, idx: RangeTo<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeToInclusive<usize>> for RawOsStr

type Output = RawOsStr

The returned type after indexing.

fn index(&self, idx: RangeToInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Ord for RawOsStr

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

This method returns an Ordering between self and other.

impl PartialEq<&RawOsStr> for RawOsString

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<&RawOsStr> for String

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<RawOsStr> for RawOsStr

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<RawOsStr> for RawOsString

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<RawOsStr> for String

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<RawOsStr> for str

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<RawOsString> for &RawOsStr

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<RawOsString> for RawOsStr

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<String> for &RawOsStr

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<String> for RawOsStr

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for RawOsStr

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<RawOsStr> for RawOsStr

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

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Quote for RawOsStr

Available on crate feature uniquote only.

fn escape(&self, f: &mut Formatter<'_>) -> Result

Escapes a string using the format described in the the module-level documentation, without the surrounding quotes.

fn quote(&self) -> Display<&Self>

Quotes a string using the format described in the the module-level documentation.

impl ToBytes for RawOsStr

Available on crate feature print_bytes only.

fn to_bytes(&self) -> ByteStr<'_>

Returns a byte string that will be used to represent the instance.

impl ToOwned for RawOsStr

type Owned = RawOsString

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl Eq for RawOsStr

impl StructuralEq for RawOsStr

impl StructuralPartialEq for RawOsStr