Trait clap_lex::OsStrExt

source ·
pub trait OsStrExt: Sealed {
    // Required methods
    fn try_str(&self) -> Result<&str, Utf8Error>;
    fn contains(&self, needle: &str) -> bool;
    fn find(&self, needle: &str) -> Option<usize>;
    fn strip_prefix(&self, prefix: &str) -> Option<&OsStr>;
    fn starts_with(&self, prefix: &str) -> bool;
    fn split<'s, 'n>(&'s self, needle: &'n str) -> Split<'s, 'n>;
    fn split_once(&self, needle: &str) -> Option<(&OsStr, &OsStr)>;
}
Expand description

String-like methods for OsStr

Required Methods§

source

fn try_str(&self) -> Result<&str, Utf8Error>

Converts to a string slice.

The Utf8Error is guaranteed to have a valid UTF8 boundary in its valid_up_to()

source

fn contains(&self, needle: &str) -> bool

Returns true if the given pattern matches a sub-slice of this string slice.

Returns false if it does not.

§Examples
use clap_lex::OsStrExt as _;
let bananas = std::ffi::OsStr::new("bananas");

assert!(bananas.contains("nana"));
assert!(!bananas.contains("apples"));
source

fn find(&self, needle: &str) -> Option<usize>

Returns the byte index of the first character of this string slice that matches the pattern.

Returns None if the pattern doesn’t match.

§Examples
use clap_lex::OsStrExt as _;
let s = std::ffi::OsStr::new("Löwe 老虎 Léopard Gepardi");

assert_eq!(s.find("L"), Some(0));
assert_eq!(s.find("é"), Some(14));
assert_eq!(s.find("par"), Some(17));

Not finding the pattern:

use clap_lex::OsStrExt as _;
let s = std::ffi::OsStr::new("Löwe 老虎 Léopard");

assert_eq!(s.find("1"), None);
source

fn strip_prefix(&self, prefix: &str) -> Option<&OsStr>

Returns a string slice with the prefix removed.

If the string starts with the pattern prefix, returns substring after the prefix, wrapped in Some.

If the string does not start with prefix, returns None.

§Examples
use std::ffi::OsStr;
use clap_lex::OsStrExt as _;
assert_eq!(OsStr::new("foo:bar").strip_prefix("foo:"), Some(OsStr::new("bar")));
assert_eq!(OsStr::new("foo:bar").strip_prefix("bar"), None);
assert_eq!(OsStr::new("foofoo").strip_prefix("foo"), Some(OsStr::new("foo")));
source

fn starts_with(&self, prefix: &str) -> bool

Returns true if the given pattern matches a prefix of this string slice.

Returns false if it does not.

§Examples
use clap_lex::OsStrExt as _;
let bananas = std::ffi::OsStr::new("bananas");

assert!(bananas.starts_with("bana"));
assert!(!bananas.starts_with("nana"));
source

fn split<'s, 'n>(&'s self, needle: &'n str) -> Split<'s, 'n>

An iterator over substrings of this string slice, separated by characters matched by a pattern.

§Examples

Simple patterns:

use std::ffi::OsStr;
use clap_lex::OsStrExt as _;
let v: Vec<_> = OsStr::new("Mary had a little lamb").split(" ").collect();
assert_eq!(v, [OsStr::new("Mary"), OsStr::new("had"), OsStr::new("a"), OsStr::new("little"), OsStr::new("lamb")]);

let v: Vec<_> = OsStr::new("").split("X").collect();
assert_eq!(v, [OsStr::new("")]);

let v: Vec<_> = OsStr::new("lionXXtigerXleopard").split("X").collect();
assert_eq!(v, [OsStr::new("lion"), OsStr::new(""), OsStr::new("tiger"), OsStr::new("leopard")]);

let v: Vec<_> = OsStr::new("lion::tiger::leopard").split("::").collect();
assert_eq!(v, [OsStr::new("lion"), OsStr::new("tiger"), OsStr::new("leopard")]);

If a string contains multiple contiguous separators, you will end up with empty strings in the output:

use std::ffi::OsStr;
use clap_lex::OsStrExt as _;
let x = OsStr::new("||||a||b|c");
let d: Vec<_> = x.split("|").collect();

assert_eq!(d, &[OsStr::new(""), OsStr::new(""), OsStr::new(""), OsStr::new(""), OsStr::new("a"), OsStr::new(""), OsStr::new("b"), OsStr::new("c")]);

Contiguous separators are separated by the empty string.

use std::ffi::OsStr;
use clap_lex::OsStrExt as _;
let x = OsStr::new("(///)");
let d: Vec<_> = x.split("/").collect();

assert_eq!(d, &[OsStr::new("("), OsStr::new(""), OsStr::new(""), OsStr::new(")")]);

Separators at the start or end of a string are neighbored by empty strings.

use std::ffi::OsStr;
use clap_lex::OsStrExt as _;
let d: Vec<_> = OsStr::new("010").split("0").collect();
assert_eq!(d, &[OsStr::new(""), OsStr::new("1"), OsStr::new("")]);

When the empty string is used as a separator, it panics

use std::ffi::OsStr;
use clap_lex::OsStrExt as _;
let f: Vec<_> = OsStr::new("rust").split("").collect();
assert_eq!(f, &[OsStr::new(""), OsStr::new("r"), OsStr::new("u"), OsStr::new("s"), OsStr::new("t"), OsStr::new("")]);

Contiguous separators can lead to possibly surprising behavior when whitespace is used as the separator. This code is correct:

use std::ffi::OsStr;
use clap_lex::OsStrExt as _;
let x = OsStr::new("    a  b c");
let d: Vec<_> = x.split(" ").collect();

assert_eq!(d, &[OsStr::new(""), OsStr::new(""), OsStr::new(""), OsStr::new(""), OsStr::new("a"), OsStr::new(""), OsStr::new("b"), OsStr::new("c")]);

It does not give you:

assert_eq!(d, &[OsStr::new("a"), OsStr::new("b"), OsStr::new("c")]);

Use split_whitespace for this behavior.

source

fn split_once(&self, needle: &str) -> Option<(&OsStr, &OsStr)>

Splits the string on the first occurrence of the specified delimiter and returns prefix before delimiter and suffix after delimiter.

§Examples
use std::ffi::OsStr;
use clap_lex::OsStrExt as _;
assert_eq!(OsStr::new("cfg").split_once("="), None);
assert_eq!(OsStr::new("cfg=").split_once("="), Some((OsStr::new("cfg"), OsStr::new(""))));
assert_eq!(OsStr::new("cfg=foo").split_once("="), Some((OsStr::new("cfg"), OsStr::new("foo"))));
assert_eq!(OsStr::new("cfg=foo=bar").split_once("="), Some((OsStr::new("cfg"), OsStr::new("foo=bar"))));

Implementations on Foreign Types§

source§

impl OsStrExt for OsStr

source§

fn try_str(&self) -> Result<&str, Utf8Error>

source§

fn contains(&self, needle: &str) -> bool

source§

fn find(&self, needle: &str) -> Option<usize>

source§

fn strip_prefix(&self, prefix: &str) -> Option<&OsStr>

source§

fn starts_with(&self, prefix: &str) -> bool

source§

fn split<'s, 'n>(&'s self, needle: &'n str) -> Split<'s, 'n>

source§

fn split_once(&self, needle: &str) -> Option<(&OsStr, &OsStr)>

Implementors§