Trait FromStr

1.0.0 (const: unstable) · Source

pub trait FromStr: Sized {
    type Err;

    // Required method
    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.

§Input format and round-tripping

The input format expected by a type’s FromStr implementation depends on the type. Check the type’s documentation for the input formats it knows how to parse. Note that the input format of a type’s FromStr implementation might not necessarily accept the output format of its Display implementation, and even if it does, the Display implementation may not be lossless so the round-trip may lose information.

However, if a type has a lossless Display implementation whose output is meant to be conveniently machine-parseable and not just meant for human consumption, then the type may wish to accept the same format in FromStr, and document that usage. Having both Display and FromStr implementations where the result of Display cannot be parsed with FromStr may surprise users.

§Examples

Basic implementation of FromStr on an example Point type:

use std::str::FromStr;

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

#[derive(Debug, PartialEq, Eq)]
struct ParsePointError;

impl FromStr for Point {
    type Err = ParsePointError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let (x, y) = s
            .strip_prefix('(')
            .and_then(|s| s.strip_suffix(')'))
            .and_then(|s| s.split_once(','))
            .ok_or(ParsePointError)?;

        let x_fromstr = x.parse::<i32>().map_err(|_| ParsePointError)?;
        let y_fromstr = y.parse::<i32>().map_err(|_| ParsePointError)?;

        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);
// Invalid input string
assert!(Point::from_str("(1 2)").is_err());

Required Associated Types§

1.0.0 · Source

type Err

The associated error which can be returned from parsing.

Required Methods§

1.0.0 · Source

fn from_str(s: &str) -> Result<Self, Self::Err>

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);

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§

1.7.0 · Source§

Trait FromStr Copy item path

§Input format and round-tripping

§Examples

Required Associated Types§

type Err

Required Methods§

fn from_str(s: &str) -> Result<Self, Self::Err>

§Examples

Dyn Compatibility§

Implementors§

impl FromStr for IpAddr

type Err = AddrParseError

impl FromStr for SocketAddr

type Err = AddrParseError

impl FromStr for AppSettings

type Err = String

impl FromStr for ArgSettings

type Err = String

impl FromStr for Shell

type Err = String

impl FromStr for hyper_old_types::header::common::accept_ranges::RangeUnit

type Err = Error

impl FromStr for hyper_old_types::header::common::cache_control::CacheDirective

type Err = Option<<u32 as FromStr>::Err>

impl FromStr for hyper_old_types::header::common::connection::ConnectionOption

type Err = ()

impl FromStr for hyper_old_types::header::common::content_range::ContentRangeSpec

type Err = Error

impl FromStr for hyper_old_types::header::common::link::MediaDesc

type Err = Error

impl FromStr for hyper_old_types::header::common::link::RelationType

type Err = Error

impl FromStr for hyper_old_types::header::common::prefer::Preference

type Err = Option<<u32 as FromStr>::Err>

impl FromStr for hyper_old_types::header::common::range::ByteRangeSpec

type Err = Error

impl FromStr for hyper_old_types::header::common::range::Range

type Err = Error

impl FromStr for hyper_old_types::header::common::upgrade::ProtocolName

type Err = ()

impl FromStr for hyper_old_types::header::shared::charset::Charset

type Err = Error

impl FromStr for hyper_old_types::header::shared::encoding::Encoding

type Err = Error

impl FromStr for hyper_old_types::method::Method

type Err = Error

impl FromStr for hyper_old_types::version::HttpVersion

type Err = Error

impl FromStr for hyper::header::common::accept_ranges::RangeUnit

type Err = Error

impl FromStr for hyper::header::common::cache_control::CacheDirective

type Err = Option<<u32 as FromStr>::Err>

impl FromStr for hyper::header::common::connection::ConnectionOption

type Err = ()

impl FromStr for hyper::header::common::content_range::ContentRangeSpec

type Err = Error

impl FromStr for hyper::header::common::link::MediaDesc

type Err = Error

impl FromStr for hyper::header::common::link::RelationType

type Err = Error

impl FromStr for hyper::header::common::prefer::Preference

type Err = Option<<u32 as FromStr>::Err>

impl FromStr for hyper::header::common::range::ByteRangeSpec

type Err = Error

impl FromStr for hyper::header::common::range::Range

type Err = Error

impl FromStr for hyper::header::common::upgrade::ProtocolName

type Err = ()

impl FromStr for hyper::header::shared::charset::Charset

type Err = Error

impl FromStr for hyper::header::shared::encoding::Encoding

type Err = Error

impl FromStr for hyper::method::Method

type Err = Error

impl FromStr for RequestUri

type Err = Error

impl FromStr for hyper::version::HttpVersion

type Err = Error

impl FromStr for Level

type Err = ParseLevelError

Trait FromStr