Struct os_str_bytes::RawOsStr

pub struct RawOsStr(/* private fields */);

A container for the byte strings converted by OsStrBytes.

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

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.

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

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 as_raw_bytes(&self) -> &[u8]

Returns the byte string stored by this container.

The result will match what would be returned by OsStrBytes::to_raw_bytes for the same string.

Examples

use std::env;

use os_str_bytes::OsStrBytes;
use os_str_bytes::RawOsStr;

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

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

where P: Pattern,

Equivalent to str::contains.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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

where P: Pattern,

Equivalent to str::ends_with.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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 a byte outside of the ASCII range or 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.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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

where P: Pattern,

Equivalent to str::starts_with.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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.

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) -> &Self

where P: Pattern,

Equivalent to str::trim_end_matches.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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_start_matches<P>(&self, pat: P) -> &Self

where P: Pattern,

Equivalent to str::trim_start_matches.

Panics

Panics if the pattern is a byte outside of the ASCII range.

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(other: &'a RawOsStr) -> 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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialEq for RawOsStr

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl PartialOrd 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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

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 StructuralPartialEq for RawOsStr