os_str_bytes

Trait 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<P>(&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<P>(&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<P>(&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<I>(&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<I>(&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<P>(&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<P>(&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<P>(&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<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::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<P>(&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<P>(&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<P>(&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<P>(&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<P>(&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<P>(&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<P>(&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);
    }
}

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types§

Source§

impl OsStrBytesExt for OsStr

Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate features raw_os_str and conversions only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate features raw_os_str and conversions only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.
Source§

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

Available on crate feature raw_os_str only.

Implementors§