RFC: A new approach to OsStr support

README.md

@@ -22,17 +22,18 @@ you do with it.
 * Required or optional explicit values `-eVALUE` and `--explicit=VALUE`
 * Positional arguments and `--`
 * Parse options at the beginning of the argument list, or anywhere
+* Optionally parse negative numbers as positional arguments
 
 ## Benefits
 
 * Zero cost
 * Zero copy
-* Zero unsafe code
+* Zero unsafe code except for `&OsStr`
 * Zero dependencies
 * Zero allocation
 * Simple to use yet versatile
-* `#![no_std]`-compatible
-* Compatible with `&str` and `&[u8]`
+* `#![no_std]`-compatible except for `&OsStr`
+* Compatible with `&str`, `&[u8]` and `&OsStr`
 
 ## Performance
 

bench/examples/ridiculous_argument.rs

@@ -1,5 +1,3 @@
-#![feature(bench_black_box)]
-
 use std::hint::black_box;
 use getargs::Argument;
 
@@ -20,27 +18,27 @@ fn dash_ends_opts() -> bool {
 
 #[inline(never)]
 fn long_flag() -> Option<(&'static str, Option<&'static str>)> {
-    black_box("--long-flag-with-no-value").parse_long_opt()
+    black_box("--long-flag-with-no-value").parse_long_opt().unwrap()
 }
 
 #[inline(never)]
 fn long_flag_blank_value() -> Option<(&'static str, Option<&'static str>)> {
-    black_box("--long-flag-with-blank-value=").parse_long_opt()
+    black_box("--long-flag-with-blank-value=").parse_long_opt().unwrap()
 }
 
 #[inline(never)]
 fn long_flag_value() -> Option<(&'static str, Option<&'static str>)> {
-    black_box("--long-flag-with-long-value=this-is-a-pretty-longish-value").parse_long_opt()
+    black_box("--long-flag-with-long-value=this-is-a-pretty-longish-value").parse_long_opt().unwrap()
 }
 
 #[inline(never)]
 fn short_flag_cluster() -> Option<&'static str> {
-    black_box("-verylongshortflagcluster").parse_short_cluster()
+    black_box("-verylongshortflagcluster").parse_short_cluster(true)
 }
 
 #[inline(never)]
 fn short_flag_cluster_opt() -> (char, Option<&'static str>) {
-    black_box("verylongshortflagcluster").consume_short_opt()
+    black_box("verylongshortflagcluster").consume_short_opt().unwrap()
 }
 
 #[inline(never)]
@@ -64,28 +62,28 @@ fn bytes_dash_ends_opts() -> bool {
 }
 
 #[inline(never)]
-fn bytes_long_flag() -> Option<(&'static [u8], Option<&'static [u8]>)> {
-    black_box(b"--long-flag-with-no-value").parse_long_opt()
+fn bytes_long_flag() -> Option<(&'static str, Option<&'static [u8]>)> {
+    black_box(b"--long-flag-with-no-value").parse_long_opt().unwrap()
 }
 
 #[inline(never)]
-fn bytes_long_flag_blank_value() -> Option<(&'static [u8], Option<&'static [u8]>)> {
-    black_box(b"--long-flag-with-blank-value=").parse_long_opt()
+fn bytes_long_flag_blank_value() -> Option<(&'static str, Option<&'static [u8]>)> {
+    black_box(b"--long-flag-with-blank-value=").parse_long_opt().unwrap()
 }
 
 #[inline(never)]
-fn bytes_long_flag_value() -> Option<(&'static [u8], Option<&'static [u8]>)> {
-    black_box(b"--long-flag-with-long-value=this-is-a-pretty-longish-value").parse_long_opt()
+fn bytes_long_flag_value() -> Option<(&'static str, Option<&'static [u8]>)> {
+    black_box(b"--long-flag-with-long-value=this-is-a-pretty-longish-value").parse_long_opt().unwrap()
 }
 
 #[inline(never)]
 fn bytes_short_flag_cluster() -> Option<&'static [u8]> {
-    black_box(b"-verylongshortflagcluster").parse_short_cluster()
+    black_box(b"-verylongshortflagcluster").parse_short_cluster(true)
 }
 
 #[inline(never)]
-fn bytes_short_flag_cluster_opt() -> (u8, Option<&'static [u8]>) {
-    black_box(b"verylongshortflagcluster").consume_short_opt()
+fn bytes_short_flag_cluster_opt() -> (char, Option<&'static [u8]>) {
+    black_box(b"verylongshortflagcluster").consume_short_opt().unwrap()
 }
 
 #[inline(never)]

bench/examples/ridiculous_flags.rs

@@ -1,5 +1,3 @@
-#![feature(bench_black_box)]
-
 use getargs::Options;
 use std::hint::black_box;
 

bench/examples/vs.rs

@@ -1,7 +1,6 @@
-#![feature(bench_black_box)]
-
 use bench::{ARGS, ARGS_BYTES};
 use getargs::Argument;
+use std::ffi::OsStr;
 use std::hint::black_box;
 use std::time::Instant;
 
@@ -87,18 +86,46 @@ fn getargs5b<'arg, I: Iterator<Item = &'arg [u8]>>(iter: I) -> Settings<&'arg [u
 
     while let Some(opt) = opts.next_opt().unwrap() {
         match opt {
-            Opt::Short(b'1') => settings.short_present1 = true,
-            Opt::Short(b'2') => settings.short_present2 = true,
-            Opt::Short(b'3') => settings.short_present3 = true,
-            Opt::Long(b"present1") => settings.long_present1 = true,
-            Opt::Long(b"present2") => settings.long_present2 = true,
-            Opt::Long(b"present3") => settings.long_present3 = true,
-            Opt::Short(b'4') => settings.short_value1 = Some(opts.value().unwrap()),
-            Opt::Short(b'5') => settings.short_value2 = Some(opts.value().unwrap()),
-            Opt::Short(b'6') => settings.short_value3 = Some(opts.value().unwrap()),
-            Opt::Long(b"val1") => settings.long_value1 = Some(opts.value().unwrap()),
-            Opt::Long(b"val2") => settings.long_value2 = Some(opts.value().unwrap()),
-            Opt::Long(b"val3") => settings.long_value3 = Some(opts.value().unwrap()),
+            Opt::Short('1') => settings.short_present1 = true,
+            Opt::Short('2') => settings.short_present2 = true,
+            Opt::Short('3') => settings.short_present3 = true,
+            Opt::Long("present1") => settings.long_present1 = true,
+            Opt::Long("present2") => settings.long_present2 = true,
+            Opt::Long("present3") => settings.long_present3 = true,
+            Opt::Short('4') => settings.short_value1 = Some(opts.value().unwrap()),
+            Opt::Short('5') => settings.short_value2 = Some(opts.value().unwrap()),
+            Opt::Short('6') => settings.short_value3 = Some(opts.value().unwrap()),
+            Opt::Long("val1") => settings.long_value1 = Some(opts.value().unwrap()),
+            Opt::Long("val2") => settings.long_value2 = Some(opts.value().unwrap()),
+            Opt::Long("val3") => settings.long_value3 = Some(opts.value().unwrap()),
+            _ => {}
+        }
+    }
+
+    settings
+}
+
+#[inline(never)]
+fn getargs5o<'arg, I: Iterator<Item = &'arg OsStr>>(iter: I) -> Settings<&'arg OsStr> {
+    use getargs::{Opt, Options};
+
+    let mut settings = Settings::default();
+    let mut opts = Options::new(iter);
+
+    while let Some(opt) = opts.next_opt().unwrap() {
+        match opt {
+            Opt::Short('1') => settings.short_present1 = true,
+            Opt::Short('2') => settings.short_present2 = true,
+            Opt::Short('3') => settings.short_present3 = true,
+            Opt::Long("present1") => settings.long_present1 = true,
+            Opt::Long("present2") => settings.long_present2 = true,
+            Opt::Long("present3") => settings.long_present3 = true,
+            Opt::Short('4') => settings.short_value1 = Some(opts.value().unwrap()),
+            Opt::Short('5') => settings.short_value2 = Some(opts.value().unwrap()),
+            Opt::Short('6') => settings.short_value3 = Some(opts.value().unwrap()),
+            Opt::Long("val1") => settings.long_value1 = Some(opts.value().unwrap()),
+            Opt::Long("val2") => settings.long_value2 = Some(opts.value().unwrap()),
+            Opt::Long("val3") => settings.long_value3 = Some(opts.value().unwrap()),
             _ => {}
         }
     }
@@ -129,7 +156,14 @@ fn main() {
 
     let d = Instant::now();
 
+    for _ in 0..ITERATIONS {
+        black_box(getargs5o(ARGS.iter().copied().map(AsRef::as_ref)));
+    }
+
+    let e = Instant::now();
+
     eprintln!("getargs4:  {}ns", (b - a).as_nanos() / ITERATIONS as u128);
     eprintln!("getargs5:  {}ns", (c - b).as_nanos() / ITERATIONS as u128);
     eprintln!("getargs5b: {}ns", (d - c).as_nanos() / ITERATIONS as u128);
+    eprintln!("getargs5o: {}ns", (e - d).as_nanos() / ITERATIONS as u128);
 }

bench/src/evolution.rs

@@ -1,5 +1,7 @@
 #![allow(non_snake_case)]
 
+use std::ffi::OsStr;
+
 use crate::{ARGS, ARGS_BYTES};
 use getargs::Argument;
 use test::Bencher;
@@ -142,18 +144,46 @@ fn getargsLb<'arg, I: Iterator<Item = &'arg [u8]>>(iter: I) -> Settings<&'arg [u
 
     while let Some(opt) = opts.next_opt().unwrap() {
         match opt {
-            Opt::Short(b'1') => settings.short_present1 = true,
-            Opt::Short(b'2') => settings.short_present2 = true,
-            Opt::Short(b'3') => settings.short_present3 = true,
-            Opt::Long(b"present1") => settings.long_present1 = true,
-            Opt::Long(b"present2") => settings.long_present2 = true,
-            Opt::Long(b"present3") => settings.long_present3 = true,
-            Opt::Short(b'4') => settings.short_value1 = Some(opts.value().unwrap()),
-            Opt::Short(b'5') => settings.short_value2 = Some(opts.value().unwrap()),
-            Opt::Short(b'6') => settings.short_value3 = Some(opts.value().unwrap()),
-            Opt::Long(b"val1") => settings.long_value1 = Some(opts.value().unwrap()),
-            Opt::Long(b"val2") => settings.long_value2 = Some(opts.value().unwrap()),
-            Opt::Long(b"val3") => settings.long_value3 = Some(opts.value().unwrap()),
+            Opt::Short('1') => settings.short_present1 = true,
+            Opt::Short('2') => settings.short_present2 = true,
+            Opt::Short('3') => settings.short_present3 = true,
+            Opt::Long("present1") => settings.long_present1 = true,
+            Opt::Long("present2") => settings.long_present2 = true,
+            Opt::Long("present3") => settings.long_present3 = true,
+            Opt::Short('4') => settings.short_value1 = Some(opts.value().unwrap()),
+            Opt::Short('5') => settings.short_value2 = Some(opts.value().unwrap()),
+            Opt::Short('6') => settings.short_value3 = Some(opts.value().unwrap()),
+            Opt::Long("val1") => settings.long_value1 = Some(opts.value().unwrap()),
+            Opt::Long("val2") => settings.long_value2 = Some(opts.value().unwrap()),
+            Opt::Long("val3") => settings.long_value3 = Some(opts.value().unwrap()),
+            _ => {}
+        }
+    }
+
+    settings
+}
+
+#[inline(always)]
+fn getargsLo<'arg, I: Iterator<Item = &'arg OsStr>>(iter: I) -> Settings<&'arg OsStr> {
+    use getargs::{Opt, Options};
+
+    let mut settings = Settings::default();
+    let mut opts = Options::new(iter);
+
+    while let Some(opt) = opts.next_opt().unwrap() {
+        match opt {
+            Opt::Short('1') => settings.short_present1 = true,
+            Opt::Short('2') => settings.short_present2 = true,
+            Opt::Short('3') => settings.short_present3 = true,
+            Opt::Long("present1") => settings.long_present1 = true,
+            Opt::Long("present2") => settings.long_present2 = true,
+            Opt::Long("present3") => settings.long_present3 = true,
+            Opt::Short('4') => settings.short_value1 = Some(opts.value().unwrap()),
+            Opt::Short('5') => settings.short_value2 = Some(opts.value().unwrap()),
+            Opt::Short('6') => settings.short_value3 = Some(opts.value().unwrap()),
+            Opt::Long("val1") => settings.long_value1 = Some(opts.value().unwrap()),
+            Opt::Long("val2") => settings.long_value2 = Some(opts.value().unwrap()),
+            Opt::Long("val3") => settings.long_value3 = Some(opts.value().unwrap()),
             _ => {}
         }
     }
@@ -191,6 +221,13 @@ fn getargsLb_varied_small(bencher: &mut Bencher) {
     bencher.iter(|| getargsLb(ARGS_BYTES.iter().copied()));
 }
 
+#[bench]
+#[inline(never)]
+fn getargsLo_varied_small(bencher: &mut Bencher) {
+    let args_os: Box<[&OsStr]> = ARGS.iter().copied().map(AsRef::as_ref).collect();
+    bencher.iter(|| getargsLo(args_os.iter().copied()));
+}
+
 pub const ARGS_LONG: [&str; 1000] = ["--dsfigadsjfdgsfjkasbfjksdfabsdbfdaf"; 1000];
 pub const ARGS_LONG_BYTES: [&[u8]; 1000] = [b"--dsfigadsjfdgsfjkasbfjksdfabsdbfdaf"; 1000];
 
@@ -224,6 +261,13 @@ fn getargsLb_long(bencher: &mut Bencher) {
     bencher.iter(|| getargsLb(ARGS_LONG_BYTES.iter().copied()));
 }
 
+#[bench]
+#[inline(never)]
+fn getargsLo_long(bencher: &mut Bencher) {
+    let args_os: Vec<&OsStr> = ARGS_LONG.iter().copied().map(AsRef::as_ref).collect();
+    bencher.iter(|| getargsLo(args_os.iter().copied()));
+}
+
 pub const ARGS_SHORT_CLUSTER: [&str; 1000] =
     ["-rjryets8kzrlxu7lzvnmsooiac8u9lxluphwrfudxaitfdomtce78grull9cpcvk7lyi07mdoclybtolssg7w7kwei79k"; 1000];
 
@@ -260,6 +304,13 @@ fn getargsLb_short_cluster(bencher: &mut Bencher) {
     bencher.iter(|| getargsLb(ARGS_SHORT_CLUSTER_BYTES.iter().copied()));
 }
 
+#[bench]
+#[inline(never)]
+fn getargsLo_short_cluster(bencher: &mut Bencher) {
+    let args_os: Vec<&OsStr> = ARGS_SHORT_CLUSTER.iter().copied().map(AsRef::as_ref).collect();
+    bencher.iter(|| getargsLo(args_os.iter().copied()));
+}
+
 pub const ARGS_SHORT_EVALUE: [&str; 1000] =
     ["-rjryets8kzrlxu7lzvnmso4oiac8u9lxluphwrfudxaitfdomtce78grull9cpcvk7lyi07mdoclybtolssg7w7kwei79k"; 1000];
 
@@ -296,6 +347,13 @@ fn getargsLb_short_evalue(bencher: &mut Bencher) {
     bencher.iter(|| getargsLb(ARGS_SHORT_EVALUE_BYTES.iter().copied()));
 }
 
+#[bench]
+#[inline(never)]
+fn getargsLo_short_evalue(bencher: &mut Bencher) {
+    let args_os: Vec<&OsStr> = ARGS_SHORT_EVALUE.iter().copied().map(AsRef::as_ref).collect();
+    bencher.iter(|| getargsLo(args_os.iter().copied()));
+}
+
 pub const ARGS_SHORT_IVALUE: [&str; 1000] =
     ["-rjryets8kzrlxu7lzvnmsooiac8u9lxluphwrfudxaitfdomtce78grull9cpcvk7lyi07mdoclybtolssg7w7kwei79k4"; 1000];
 
@@ -332,6 +390,13 @@ fn getargsLb_short_ivalue(bencher: &mut Bencher) {
     bencher.iter(|| getargsLb(ARGS_SHORT_IVALUE_BYTES.iter().copied()));
 }
 
+#[bench]
+#[inline(never)]
+fn getargsLo_short_ivalue(bencher: &mut Bencher) {
+    let args_os: Vec<&OsStr> = ARGS_SHORT_IVALUE.iter().copied().map(AsRef::as_ref).collect();
+    bencher.iter(|| getargsLo(args_os.iter().copied()));
+}
+
 pub const ARGS_LONG_EVALUE: [&str; 1000] =
     ["--val1=rjryets8kzrlxu7lzvnms4ooiac8u9lxluphwrfudxaitfdomtce78grull9cpcvk7lyi07mdoclybtolssg7w7kwei79k"; 1000];
 
@@ -368,6 +433,13 @@ fn getargsLb_long_evalue(bencher: &mut Bencher) {
     bencher.iter(|| getargsLb(ARGS_LONG_EVALUE_BYTES.iter().copied()));
 }
 
+#[bench]
+#[inline(never)]
+fn getargsLo_long_evalue(bencher: &mut Bencher) {
+    let args_os: Vec<&OsStr> = ARGS_LONG_EVALUE.iter().copied().map(AsRef::as_ref).collect();
+    bencher.iter(|| getargsLo(args_os.iter().copied()));
+}
+
 pub const ARGS_LONG_IVALUE: [&str; 1000] = ["--val1"; 1000];
 pub const ARGS_LONG_IVALUE_BYTES: [&[u8]; 1000] = [b"--val1"; 1000];
 
@@ -400,3 +472,10 @@ fn getargsL_long_ivalue(bencher: &mut Bencher) {
 fn getargsLb_long_ivalue(bencher: &mut Bencher) {
     bencher.iter(|| getargsLb(ARGS_LONG_IVALUE_BYTES.iter().copied()));
 }
+
+#[bench]
+#[inline(never)]
+fn getargsLo_long_ivalue(bencher: &mut Bencher) {
+    let args_os: Vec<&OsStr> = ARGS_LONG_IVALUE.iter().copied().map(AsRef::as_ref).collect();
+    bencher.iter(|| getargsLo(args_os.iter().copied()));
+}

examples/complete.rs

@@ -9,17 +9,17 @@ enum UsageError<'a> {
     Help,
     /// Error from getargs
     #[error("{0}")]
-    Getargs(getargs::Error<&'a str>),
+    Getargs(getargs::Error<'a, &'a str>),
     #[error("unknown option {0}")]
-    UnknownOption(Opt<&'a str>),
+    UnknownOption(Opt<'a>),
     #[error("unknown subcommand {0:?}")]
     UnknownSubcommand(&'a str),
     #[error("missing subcommand")]
     MissingSubcommand,
 }
 
-impl<'a> From<getargs::Error<&'a str>> for UsageError<'a> {
-    fn from(e: Error<&'a str>) -> Self {
+impl<'a> From<getargs::Error<'a, &'a str>> for UsageError<'a> {
+    fn from(e: Error<'a, &'a str>) -> Self {
         UsageError::Getargs(e)
     }
 }
@@ -46,7 +46,7 @@ enum Subcommand<'a> {
 
 /// Parse all the arguments
 fn parse_args<'a, I: Iterator<Item = &'a str>>(
-    opts: &mut Options<&'a str, I>,
+    opts: &mut Options<'a, &'a str, I>,
 ) -> Result<Arguments<'a>, UsageError<'a>> {
     let mut verbosity = 0;
 
@@ -76,7 +76,7 @@ fn parse_args<'a, I: Iterator<Item = &'a str>>(
 
 /// Parse the arguments for the 'create' subcommand
 fn parse_create_args<'a, I: Iterator<Item = &'a str>>(
-    opts: &mut Options<&'a str, I>,
+    opts: &mut Options<'a, &'a str, I>,
 ) -> Result<Subcommand<'a>, UsageError<'a>> {
     let mut output = None;
     while let Some(opt) = opts.next_opt()? {
@@ -92,7 +92,7 @@ fn parse_create_args<'a, I: Iterator<Item = &'a str>>(
 
 /// Parse the arguments for the 'delete' subcommand
 fn parse_delete_args<'a, I: Iterator<Item = &'a str>>(
-    opts: &mut Options<&'a str, I>,
+    opts: &mut Options<'a, &'a str, I>,
 ) -> Result<Subcommand<'a>, UsageError<'a>> {
     let mut backup = None;
     while let Some(opt) = opts.next_opt()? {