From 93382cd79aadb1cc492ce5fa4377f6dee66e85eb Mon Sep 17 00:00:00 2001 From: Thayne McCombs Date: Wed, 9 Mar 2022 21:26:49 -0700 Subject: [PATCH] Add documentation for grouped_values_of Relates to #2924 --- src/parse/matches/arg_matches.rs | 34 +++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/src/parse/matches/arg_matches.rs b/src/parse/matches/arg_matches.rs index 2941b3c340a..c5b74e57372 100644 --- a/src/parse/matches/arg_matches.rs +++ b/src/parse/matches/arg_matches.rs @@ -293,7 +293,39 @@ impl ArgMatches { Some(v) } - /// Placeholder documentation. + /// Get an [`Iterator`] over groups of values of a specific option. + /// + /// specifically grouped by the occurances of the options. + /// + /// Each group is a `Vec<&str>` containing the arguments passed to a single occurance + /// of the option. + /// + /// If the option doesn't support multiple occurances, or there was only a single occurance, + /// the iterator will only contain a single item. + /// + /// Returns `None` if the option wasn't present. + /// + /// # Panics + /// + /// If the value is invalid UTF-8. + /// + /// If `id` is not a valid argument or group name. + /// + /// # Examples + /// ```rust + /// # use clap::{Command,Args}; + /// let m = Command::new("myprog") + /// .args(Arg::new("exec") + /// .short('x') + /// .min_values(1) + /// .multiple_occurrences(true) + /// .value_terminator(";")) + /// .get_matches_from(vec![ + /// "myprog", "-x", "echo", "hi", ";", "-x", "echo", "bye"]); + /// let vals: Vec> = m.grouped_values_of("exec").unwrap().collect(); + /// assert_eq!(vals, [["echo", "hi"], ["echo", "bye"]]); + /// ``` + /// [`Iterator`]: std::iter::Iterator #[cfg(feature = "unstable-grouped")] #[cfg_attr(debug_assertions, track_caller)] pub fn grouped_values_of(&self, id: T) -> Option {