Trait os_str_bytes::OsStrBytesExt

source ·

pub trait OsStrBytesExt: OsStrBytes {
Show 21 methods    // Required methods
    fn contains<P>(&self, pat: P) -> bool
       where P: Pattern;
    fn ends_with<P>(&self, pat: P) -> bool
       where P: Pattern;
    fn ends_with_os(&self, pat: &Self) -> bool;
    fn find<P>(&self, pat: P) -> Option<usize>
       where P: Pattern;
    unsafe fn get_unchecked<I>(&self, index: I) -> &Self
       where I: SliceIndex;
    fn index<I>(&self, index: I) -> &Self
       where I: SliceIndex;
    fn repeat(&self, n: usize) -> Self::Owned;
    fn rfind<P>(&self, pat: P) -> Option<usize>
       where P: Pattern;
    fn rsplit<P>(&self, pat: P) -> RSplit<'_, P> ⓘ
       where P: Pattern;
    fn rsplit_once<P>(&self, pat: P) -> Option<(&Self, &Self)>
       where P: Pattern;
    fn split<P>(&self, pat: P) -> Split<'_, P> ⓘ
       where P: Pattern;
    fn split_at(&self, mid: usize) -> (&Self, &Self);
    fn split_once<P>(&self, pat: P) -> Option<(&Self, &Self)>
       where P: Pattern;
    fn starts_with<P>(&self, pat: P) -> bool
       where P: Pattern;
    fn starts_with_os(&self, pat: &Self) -> bool;
    fn strip_prefix<P>(&self, pat: P) -> Option<&Self>
       where P: Pattern;
    fn strip_suffix<P>(&self, pat: P) -> Option<&Self>
       where P: Pattern;
    fn trim_end_matches<P>(&self, pat: P) -> &Self
       where P: Pattern;
    fn trim_matches<P>(&self, pat: P) -> &Self
       where P: Pattern;
    fn trim_start_matches<P>(&self, pat: P) -> &Self
       where P: Pattern;
    fn utf8_chunks(&self) -> Utf8Chunks<'_> ⓘ;
}

Expand description

An extension trait providing additional methods to OsStr.

In most cases, this trait will prevent needing to call OsStr::as_encoded_bytes and potentially violating invariants of the internal encoding for OsStr.

§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 are not currently possible to support safely and are generally not necessary. However, all indices returned by this trait can be passed to other methods.

§Complexity

All searching methods have worst-case multiplicative time complexity (i.e., O(self.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).

Required Methods§

source

fn contains(&self, pat: P) -> bool
where P: Pattern,

Equivalent to str::contains.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert!(os_string.contains("oo"));
assert!(!os_string.contains("of"));

source

fn ends_with(&self, pat: P) -> bool
where P: Pattern,

Equivalent to str::ends_with.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert!(os_string.ends_with("bar"));
assert!(!os_string.ends_with("foo"));

source

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

Available on crate feature conversions only.

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

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert!(os_string.ends_with_os(OsStr::new("bar")));
assert!(!os_string.ends_with_os(OsStr::new("foo")));

source

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

Equivalent to str::find.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert_eq!(Some(1), os_string.find("o"));
assert_eq!(None, os_string.find("of"));

source

unsafe fn get_unchecked(&self, index: I) -> &Self
where I: SliceIndex,

Equivalent to str::get_unchecked.

§Safety

The index must be a valid boundary.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert_eq!("foo", unsafe { os_string.get_unchecked(..3) });
assert_eq!("bar", unsafe { os_string.get_unchecked(3..) });

source

fn index(&self, index: I) -> &Self
where I: SliceIndex,

Equivalent to the Index::index implementation for str.

§Panics

Panics if the index is not a valid boundary.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert_eq!("foo", os_string.index(..3));
assert_eq!("bar", os_string.index(3..));

source

fn repeat(&self, n: usize) -> Self::Owned

Equivalent to str::repeat.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foo");
assert_eq!("foofoofoo", os_string.repeat(3));

source

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

Equivalent to str::rfind.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert_eq!(Some(2), os_string.rfind("o"));
assert_eq!(None, os_string.rfind("of"));

source

fn rsplit(&self, pat: P) -> RSplit<'_, P> ⓘ
where P: Pattern,

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

§Panics

Panics if the pattern is empty.

§Examples

use os_str_bytes::RawOsStr;

let raw = RawOsStr::new("foobar");
assert!(raw.rsplit("o").eq(["bar", "", "f"]));

source

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

Equivalent to str::rsplit_once.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert_eq!(
    Some((OsStr::new("fo"), OsStr::new("bar"))),
    os_string.rsplit_once("o"),
);
assert_eq!(None, os_string.rsplit_once("of"));

source

fn split(&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::new("foobar");
assert!(raw.split("o").eq(["f", "", "bar"]));

source

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 std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert_eq!(
    (OsStr::new("fo"), OsStr::new("obar")),
    os_string.split_at(2),
);

source

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

Equivalent to str::split_once.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert_eq!(
    Some((OsStr::new("f"), OsStr::new("obar"))),
    os_string.split_once("o"),
);
assert_eq!(None, os_string.split_once("of"));

source

fn starts_with(&self, pat: P) -> bool
where P: Pattern,

Equivalent to str::starts_with.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert!(os_string.starts_with("foo"));
assert!(!os_string.starts_with("bar"));

source

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

Available on crate feature conversions only.

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

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("foobar");
assert!(os_string.starts_with_os(OsStr::new("foo")));
assert!(!os_string.starts_with_os(OsStr::new("bar")));

source

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

Equivalent to str::strip_prefix.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("111foo1bar111");
assert_eq!(
    Some(OsStr::new("11foo1bar111")),
    os_string.strip_prefix("1"),
);
assert_eq!(None, os_string.strip_prefix("o"));

source

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

Equivalent to str::strip_suffix.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("111foo1bar111");
assert_eq!(
    Some(OsStr::new("111foo1bar11")),
    os_string.strip_suffix("1"),
);
assert_eq!(None, os_string.strip_suffix("o"));

source

fn trim_end_matches(&self, pat: P) -> &Self
where P: Pattern,

Equivalent to str::trim_end_matches.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("111foo1bar111");
assert_eq!("111foo1bar", os_string.trim_end_matches("1"));
assert_eq!("111foo1bar111", os_string.trim_end_matches("o"));

source

fn trim_matches(&self, pat: P) -> &Self
where P: Pattern,

Equivalent to str::trim_matches.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("111foo1bar111");
assert_eq!("foo1bar", os_string.trim_matches("1"));
assert_eq!("111foo1bar111", os_string.trim_matches("o"));

source

fn trim_start_matches(&self, pat: P) -> &Self
where P: Pattern,

Equivalent to str::trim_start_matches.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

let os_string = OsStr::new("111foo1bar111");
assert_eq!("foo1bar111", os_string.trim_start_matches("1"));
assert_eq!("111foo1bar111", os_string.trim_start_matches("o"));

source

fn utf8_chunks(&self) -> Utf8Chunks<'_> ⓘ

Splits this string into platform and UTF-8 substrings.

The iterator returned by this method is very similar to str::Utf8Chunks. However, the OsStr portion of each chunk precedes the str portion and has no length restrictions.

The OsStr portion of each chunk can be empty only at the start of a string, and the str portion at the end of a string. They will never be empty simultaneously.

§Examples

use std::ffi::OsStr;

use os_str_bytes::OsStrBytesExt;

fn to_str_lossy<F>(os_string: &OsStr, mut push: F)
where
    F: FnMut(&str),
{
    for (invalid, string) in os_string.utf8_chunks() {
        if !invalid.as_os_str().is_empty() {
            push("\u{FFFD}");
        }

        push(string);
    }
}

Object Safety§

This trait is not object safe.

Implementations on Foreign Types§

source §