Trait sugar_cli::common::FromStr

1.0.0 · source · [−]
pub trait FromStr {
    type Err;

    fn from_str(s: &str) -> Result<Self, Self::Err>;
}
Expand description

Parse a value from a string

FromStr’s from_str method is often used implicitly, through str’s parse method. See parse’s documentation for examples.

FromStr does not have a lifetime parameter, and so you can only parse types that do not contain a lifetime parameter themselves. In other words, you can parse an i32 with FromStr, but not a &i32. You can parse a struct that contains an i32, but not one that contains an &i32.

Examples

Basic implementation of FromStr on an example Point type:

use std::str::FromStr;
use std::num::ParseIntError;

#[derive(Debug, PartialEq)]
struct Point {
    x: i32,
    y: i32
}

impl FromStr for Point {
    type Err = ParseIntError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let coords: Vec<&str> = s.trim_matches(|p| p == '(' || p == ')' )
                                 .split(',')
                                 .collect();

        let x_fromstr = coords[0].parse::<i32>()?;
        let y_fromstr = coords[1].parse::<i32>()?;

        Ok(Point { x: x_fromstr, y: y_fromstr })
    }
}

let expected = Ok(Point { x: 1, y: 2 });
// Explicit call
assert_eq!(Point::from_str("(1,2)"), expected);
// Implicit calls, through parse
assert_eq!("(1,2)".parse(), expected);
assert_eq!("(1,2)".parse::<Point>(), expected);

Required Associated Types

The associated error which can be returned from parsing.

Required Methods

Parses a string s to return a value of this type.

If parsing succeeds, return the value inside Ok, otherwise when the string is ill-formatted return an error specific to the inside Err. The error type is specific to the implementation of the trait.

Examples

Basic usage with i32, a type that implements FromStr:

use std::str::FromStr;

let s = "5";
let x = i32::from_str(s).unwrap();

assert_eq!(5, x);

Implementations on Foreign Types

Converts a string in base 10 to a float. Accepts an optional decimal exponent.

This function accepts strings such as

  • ‘3.14’
  • ‘-3.14’
  • ‘2.5E10’, or equivalently, ‘2.5e10’
  • ‘2.5E-10’
  • ‘5.’
  • ‘.5’, or, equivalently, ‘0.5’
  • ‘inf’, ‘-inf’, ‘+infinity’, ‘NaN’

Note that alphabetical characters are not case-sensitive.

Leading and trailing whitespace represent an error.

Grammar

All strings that adhere to the following EBNF grammar when lowercased will result in an Ok being returned:

Float  ::= Sign? ( 'inf' | 'infinity' | 'nan' | Number )
Number ::= ( Digit+ |
             '.' Digit* |
             Digit+ '.' Digit* |
             Digit* '.' Digit+ ) Exp?
Exp    ::= 'e' Sign? Digit+
Sign   ::= [+-]
Digit  ::= [0-9]
Arguments
  • src - A string
Return value

Err(ParseFloatError) if the string did not represent a valid number. Otherwise, Ok(n) where n is the closest representable floating-point number to the number represented by src (following the same rules for rounding as for the results of primitive operations).

Parse a bool from a string.

Yields a Result<bool, ParseBoolError>, because s may or may not actually be parseable.

Examples
use std::str::FromStr;

assert_eq!(FromStr::from_str("true"), Ok(true));
assert_eq!(FromStr::from_str("false"), Ok(false));
assert!(<bool as FromStr>::from_str("not even a boolean").is_err());

Note, in many cases, the .parse() method on str is more proper.

assert_eq!("true".parse(), Ok(true));
assert_eq!("false".parse(), Ok(false));
assert!("not even a boolean".parse::<bool>().is_err());

Converts a string in base 10 to a float. Accepts an optional decimal exponent.

This function accepts strings such as

  • ‘3.14’
  • ‘-3.14’
  • ‘2.5E10’, or equivalently, ‘2.5e10’
  • ‘2.5E-10’
  • ‘5.’
  • ‘.5’, or, equivalently, ‘0.5’
  • ‘inf’, ‘-inf’, ‘+infinity’, ‘NaN’

Note that alphabetical characters are not case-sensitive.

Leading and trailing whitespace represent an error.

Grammar

All strings that adhere to the following EBNF grammar when lowercased will result in an Ok being returned:

Float  ::= Sign? ( 'inf' | 'infinity' | 'nan' | Number )
Number ::= ( Digit+ |
             '.' Digit* |
             Digit+ '.' Digit* |
             Digit* '.' Digit+ ) Exp?
Exp    ::= 'e' Sign? Digit+
Sign   ::= [+-]
Digit  ::= [0-9]
Arguments
  • src - A string
Return value

Err(ParseFloatError) if the string did not represent a valid number. Otherwise, Ok(n) where n is the closest representable floating-point number to the number represented by src (following the same rules for rounding as for the results of primitive operations).

Attempts to parse a string into a regular expression

Attempts to parse a string into a regular expression

Parsing a str into a NaiveTime uses the same format, %H:%M:%S%.f, as in Debug and Display.

Example

use chrono::NaiveTime;

let t = NaiveTime::from_hms(23, 56, 4);
assert_eq!("23:56:04".parse::<NaiveTime>(), Ok(t));

let t = NaiveTime::from_hms_nano(23, 56, 4, 12_345_678);
assert_eq!("23:56:4.012345678".parse::<NaiveTime>(), Ok(t));

let t = NaiveTime::from_hms_nano(23, 59, 59, 1_234_567_890); // leap second
assert_eq!("23:59:60.23456789".parse::<NaiveTime>(), Ok(t));

assert!("foo".parse::<NaiveTime>().is_err());

Parsing a str into a Weekday uses the format %W.

Example

use chrono::Weekday;

assert_eq!("Sunday".parse::<Weekday>(), Ok(Weekday::Sun));
assert!("any day".parse::<Weekday>().is_err());

The parsing is case-insensitive.

assert_eq!("mON".parse::<Weekday>(), Ok(Weekday::Mon));

Only the shortest form (e.g. sun) and the longest form (e.g. sunday) is accepted.

assert!("thurs".parse::<Weekday>().is_err());

Parsing a str into a Month uses the format %W.

Example

use chrono::Month;

assert_eq!("January".parse::<Month>(), Ok(Month::January));
assert!("any day".parse::<Month>().is_err());

The parsing is case-insensitive.

assert_eq!("fEbruARy".parse::<Month>(), Ok(Month::February));

Only the shortest form (e.g. jan) and the longest form (e.g. january) is accepted.

assert!("septem".parse::<Month>().is_err());
assert!("Augustin".parse::<Month>().is_err());

Parsing a str into a NaiveDate uses the same format, %Y-%m-%d, as in Debug and Display.

Example

use chrono::NaiveDate;

let d = NaiveDate::from_ymd(2015, 9, 18);
assert_eq!("2015-09-18".parse::<NaiveDate>(), Ok(d));

let d = NaiveDate::from_ymd(12345, 6, 7);
assert_eq!("+12345-6-7".parse::<NaiveDate>(), Ok(d));

assert!("foo".parse::<NaiveDate>().is_err());

Parsing a str into a NaiveDateTime uses the same format, %Y-%m-%dT%H:%M:%S%.f, as in Debug.

Example

use chrono::{NaiveDateTime, NaiveDate};

let dt = NaiveDate::from_ymd(2015, 9, 18).and_hms(23, 56, 4);
assert_eq!("2015-09-18T23:56:04".parse::<NaiveDateTime>(), Ok(dt));

let dt = NaiveDate::from_ymd(12345, 6, 7).and_hms_milli(7, 59, 59, 1_500); // leap second
assert_eq!("+12345-6-7T7:59:60.5".parse::<NaiveDateTime>(), Ok(dt));

assert!("foo".parse::<NaiveDateTime>().is_err());

Decode a signature from hexadecimal.

Upper and lower case hexadecimal are both accepted, however mixed case is rejected.

Parse a string as an URL, without a base URL or encoding override.

Implementors