Trait sscanf::RegexRepresentation

pub trait RegexRepresentation {
    const REGEX: &'static str;
}

A Trait used by sscanf to obtain the Regex of a Type

Has one associated Constant: REGEX, which should be set to a regular Expression. Implement this trait for a Type that you want to be parsed using sscanf.

The Regular Expression should match the string representation as exactly as possible. Any incorrect matches might be caught in the from_str parsing, but that might cause this regex to take characters that could have been matched by other placeholders, leading to unexpected parsing failures.

Implementing the Trait

A manual implementation of this trait is only necessary if you

• want to use a custom Type that is not supported by default AND
• cannot use #[derive(FromScanf)] on your Type

Deriving FromScanf will automatically implement this trait for your Type, and should be preferred in most cases.

If you do need to implement this trait yourself, note the following:

• The regex cannot contain any capture groups (round brackets). If you need to use ( ) in your regex, use (?: ) instead to make it non-capturing.
• Using a raw string literal (r"...") is recommended to avoid having to escape backslashes.
• The const_format crate can be used to combine multiple strings into one, which is useful for complex regexes. This can also be used to combine the existing regex implementation of other types. sscanf internally uses const_format as well, so a version of it is re-exported under sscanf::const_format.

Example

Let’s say we want to add a Fraction parser

struct Fraction(isize, usize);

Which can be obtained from any string of the kind ±X/Y or just X

impl sscanf::RegexRepresentation for Fraction {
    /// matches an optional '-' or '+' followed by a number.
    /// possibly with a '/' and another Number
    const REGEX: &'static str = r"[-+]?\d+(?:/\d+)?";
    //                                     ^^ escapes the group. Has to be used on any ( ) in a regex.

    // alternatively, we could use const_format to reuse existing regexes:
    // REGEX = const_format::concatcp!(isize::REGEX, "(?:", "/", usize::REGEX, ")?");
}
impl std::str::FromStr for Fraction {
    type Err = std::num::ParseIntError;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let mut iter = s.split('/');
        let num = iter.next().unwrap().parse()?;
        let mut denom = 1;
        if let Some(d) = iter.next() {
            denom = d.parse()?;
        };
        Ok(Fraction(num, denom))
    }
}

Now we can use this Fraction struct in sscanf:

let output = sscanf!("2/5", "{}", Fraction);
assert_eq!(output.unwrap(), Fraction(2, 5));

let output = sscanf!("-25/3", "{}", Fraction);
assert_eq!(output.unwrap(), Fraction(-25, 3));

let output = sscanf!("8", "{}", Fraction);
assert_eq!(output.unwrap(), Fraction(8, 1));

let output = sscanf!("6e/3", "{}", Fraction);
assert!(output.is_err());

let output = sscanf!("6/-3", "{}", Fraction);
assert!(output.is_err()); // only first number can be negative

let output = sscanf!("6/3", "{}", Fraction);
assert_eq!(output.unwrap(), Fraction(6, 3));

Required Associated Constants

const REGEX: &'static str

A regular Expression that exactly matches any String representation of the implementing Type

Implementations on Foreign Types

impl RegexRepresentation for usize

const REGEX: &'static str = _

Matches any positive number with up to 20 digits

assert_eq!(usize::REGEX, r"\+?\d{1,20}");

impl RegexRepresentation for u16

const REGEX: &'static str = _

Matches any positive number with up to 5 digits

assert_eq!(u16::REGEX, r"\+?\d{1,5}");

impl RegexRepresentation for bool

const REGEX: &'static str = r"true|false"

Matches true or false.

assert_eq!(bool::REGEX, r"true|false")

impl RegexRepresentation for char

const REGEX: &'static str = r"."

Matches a single Character.

assert_eq!(char::REGEX, r".")

impl RegexRepresentation for NonZeroI8

const REGEX: &'static str = _

Matches any non-zero number with up to 3 digits

assert_eq!(NonZeroI8::REGEX, r"[-+]?[1-9]\d{0,2}");

impl RegexRepresentation for u128

const REGEX: &'static str = _

Matches any positive number with up to 39 digits

assert_eq!(u128::REGEX, r"\+?\d{1,39}");

impl RegexRepresentation for NonZeroIsize

const REGEX: &'static str = _

Matches any non-zero number with up to 20 digits

assert_eq!(NonZeroIsize::REGEX, r"[-+]?[1-9]\d{0,19}");

impl RegexRepresentation for i128

const REGEX: &'static str = _

Matches any number with up to 39 digits

assert_eq!(i128::REGEX, r"[-+]?\d{1,39}");

impl RegexRepresentation for NonZeroUsize

const REGEX: &'static str = _

Matches any positive non-zero number with up to 20 digits

assert_eq!(NonZeroUsize::REGEX, r"\+?[1-9]\d{0,19}");

impl RegexRepresentation for NonZeroU32

const REGEX: &'static str = _

Matches any positive non-zero number with up to 10 digits

assert_eq!(NonZeroU32::REGEX, r"\+?[1-9]\d{0,9}");

impl RegexRepresentation for NonZeroU16

const REGEX: &'static str = _

Matches any positive non-zero number with up to 5 digits

assert_eq!(NonZeroU16::REGEX, r"\+?[1-9]\d{0,4}");

impl RegexRepresentation for NonZeroU8

const REGEX: &'static str = _

Matches any positive non-zero number with up to 3 digits

assert_eq!(NonZeroU8::REGEX, r"\+?[1-9]\d{0,2}");

impl RegexRepresentation for u64

const REGEX: &'static str = _

Matches any positive number with up to 20 digits

assert_eq!(u64::REGEX, r"\+?\d{1,20}");

impl RegexRepresentation for String

const REGEX: &'static str = r".+?"

Matches any sequence of Characters.

Note that this clones part of the input string, which is usually not necessary. Use str unless you explicitly need ownership.

assert_eq!(String::REGEX, r".+?")

impl RegexRepresentation for i32

const REGEX: &'static str = _

Matches any number with up to 10 digits

assert_eq!(i32::REGEX, r"[-+]?\d{1,10}");

impl RegexRepresentation for isize

const REGEX: &'static str = _

Matches any number with up to 20 digits

assert_eq!(isize::REGEX, r"[-+]?\d{1,20}");

impl RegexRepresentation for i16

const REGEX: &'static str = _

Matches any number with up to 5 digits

assert_eq!(i16::REGEX, r"[-+]?\d{1,5}");

impl RegexRepresentation for str

const REGEX: &'static str = r".+?"

Matches any sequence of Characters.

Note that this is the non-borrowed form of the usual &str. This is the type that should be used when calling sscanf!() because of proc-macro limitations. The type returned by sscanf!() is &str as one would expect.

This is also currently the only type that borrows part of the input string, so you need to keep lifetimes in mind when using this type. If the input string doesn’t live long enough, use String instead.

assert_eq!(str::REGEX, r".+?")

impl RegexRepresentation for NonZeroI128

const REGEX: &'static str = _

Matches any non-zero number with up to 39 digits

assert_eq!(NonZeroI128::REGEX, r"[-+]?[1-9]\d{0,38}");

impl RegexRepresentation for u32

const REGEX: &'static str = _

Matches any positive number with up to 10 digits

assert_eq!(u32::REGEX, r"\+?\d{1,10}");

impl RegexRepresentation for NonZeroI16

const REGEX: &'static str = _

Matches any non-zero number with up to 5 digits

assert_eq!(NonZeroI16::REGEX, r"[-+]?[1-9]\d{0,4}");

impl RegexRepresentation for NonZeroU64

const REGEX: &'static str = _

Matches any positive non-zero number with up to 20 digits

assert_eq!(NonZeroU64::REGEX, r"\+?[1-9]\d{0,19}");

impl RegexRepresentation for i8

const REGEX: &'static str = _

Matches any number with up to 3 digits

assert_eq!(i8::REGEX, r"[-+]?\d{1,3}");

impl RegexRepresentation for NonZeroU128

const REGEX: &'static str = _

Matches any positive non-zero number with up to 39 digits

assert_eq!(NonZeroU128::REGEX, r"\+?[1-9]\d{0,38}");

impl RegexRepresentation for NonZeroI32

const REGEX: &'static str = _

Matches any non-zero number with up to 10 digits

assert_eq!(NonZeroI32::REGEX, r"[-+]?[1-9]\d{0,9}");

impl RegexRepresentation for PathBuf

const REGEX: &'static str = r".+"

Matches any sequence of Characters.

Paths in std don’t actually have any restrictions on what they can contain, so anything is valid.

assert_eq!(PathBuf::REGEX, r".+")

impl RegexRepresentation for i64

const REGEX: &'static str = _

Matches any number with up to 20 digits

assert_eq!(i64::REGEX, r"[-+]?\d{1,20}");

impl RegexRepresentation for f64

const REGEX: &'static str = FLOAT

Matches any floating point number

See See FromStr on f64 for details

assert_eq!(f64::REGEX, r"[+-]?(?i:inf|infinity|nan|(?:\d+|\d+\.\d*|\d*\.\d+)(?:e[+-]?\d+)?)");

impl RegexRepresentation for u8

const REGEX: &'static str = _

Matches any positive number with up to 3 digits

assert_eq!(u8::REGEX, r"\+?\d{1,3}");

impl RegexRepresentation for NonZeroI64

const REGEX: &'static str = _

Matches any non-zero number with up to 20 digits

assert_eq!(NonZeroI64::REGEX, r"[-+]?[1-9]\d{0,19}");

impl RegexRepresentation for f32

const REGEX: &'static str = FLOAT

Matches any floating point number

See See FromStr on f32 for details

assert_eq!(f32::REGEX, r"[+-]?(?i:inf|infinity|nan|(?:\d+|\d+\.\d*|\d*\.\d+)(?:e[+-]?\d+)?)");

Implementors

impl RegexRepresentation for FullF32

const REGEX: &'static str = <f32 as RegexRepresentation>::REGEX

impl RegexRepresentation for FullF64

const REGEX: &'static str = <f64 as RegexRepresentation>::REGEX

impl RegexRepresentation for HexNumber

const REGEX: &'static str = r"0[xX][0-9a-fA-F]+|[0-9a-fA-F]+"