From fe71372de5d563f46dbf69196efaa9231be797f2 Mon Sep 17 00:00:00 2001 From: "Christoph J. Scherr" Date: Fri, 6 Sep 2024 13:13:53 +0200 Subject: [PATCH] docs: document the parser functions --- src/format.rs | 58 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 54 insertions(+), 4 deletions(-) diff --git a/src/format.rs b/src/format.rs index 6adc06b..797d442 100644 --- a/src/format.rs +++ b/src/format.rs @@ -352,12 +352,18 @@ impl Format { } } -/// Validates an unsigned integer value that can be one of [Format](format::Format). +/// Converts a &[str] into an unsigned integer value (like [u128]), according to one of the [Formats](Format) /// /// The number is assumed to be base-10 by default, it is parsed as a different -/// [Format](format::Format) if the number is prefixed with the [prefix](format::FormatOptions::prefix), -/// case sensitive. So if the user inputs `0b1100` then this is parsed as -/// [Binary](format::Format::Bin) and so on. +/// [Format] if the number is prefixed with the [prefix](FormatOptions::prefix), +/// for that [Format]. So if the user inputs `0b1100` then this is parsed as +/// [Binary](Format::Bin) and so on. +/// +/// If you also want to parse raw inputs, use [numf_parser]. +/// +/// # Returns +/// +/// This parser will only output unsigned integers, it cannot be used with signed integers. /// /// # Example /// @@ -394,6 +400,50 @@ where numf_parser(s.as_bytes()) } +/// Converts any data (as bytes) into an unsigned integer value `T` (like [u128]), according to one of the [Formats](Format) +/// +/// If you only want to parse text data, use [numf_parser_str] instead. +/// +/// The parser will first try to convert the data to a [String]. +/// +/// Then, the number is assumed to be base-10 by default, it is parsed as a different +/// [Format] if the number is prefixed with the [prefix](FormatOptions::prefix), +/// for that [Format]. So if the user inputs `0b1100` then this is parsed as +/// [Binary](Format::Bin) and so on. +/// +/// If none of the text [Formats](Format) matches, the data will be assumed to be raw and converted +/// to the ingeger type directly. +/// +/// # Errors +/// +/// If no text [Format] matches and the data is too long for the integer `T`. +/// +/// # Returns +/// +/// This parser will only output unsigned integers, it cannot be used with signed integers. +/// +/// # Example +/// +/// This allows base-10 addresses to be passed normally, or values formatted with any of the +/// [Formats](format::Format) defined by this crate to be passed when prefixed with the respective +/// prefix. +/// +/// ``` +/// use clap::Parser; +/// use numf::format::numf_parser; +/// +/// let data = &[0x15, 0x92, 0xff]; +/// let result: u64 = 0x1592ff; +/// assert_eq!(result, numf_parser(data).unwrap()); +/// +/// let data = b"0x1337"; +/// let result: u64 = 0x1337; +/// assert_eq!(result, numf_parser(data).unwrap()); +/// +/// let data = b"0b110011"; +/// let result: u64 = 0b110011; +/// assert_eq!(result, numf_parser(data).unwrap()); +/// ``` pub fn numf_parser(data: &[u8]) -> anyhow::Result where T: std::str::FromStr + std::convert::TryFrom,