Skip to main content

## FromStr

# Trait FromStr

1.36.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§

### impl FromStr for IpAddr

Source§

#### type Err = AddrParseError

1.0.0 · Source§

### impl FromStr for SocketAddr

Source§

#### type Err = AddrParseError

1.0.0 · Source§

### impl FromStr for bool

Source§

#### type Err = ParseBoolError

1.20.0 · Source§

### impl FromStr for char

Source§

#### type Err = ParseCharError

1.0.0 · Source§

### impl FromStr for f16

Source§

#### type Err = ParseFloatError

1.0.0 · Source§

### impl FromStr for f32

Source§

#### type Err = ParseFloatError

1.0.0 · Source§

### impl FromStr for f64

Source§

#### type Err = ParseFloatError

1.0.0 (const: unstable) · Source§

### impl FromStr for i8

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for i16

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for i32

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for i64

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for i128

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for isize

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for u8

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for u16

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for u32

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for u64

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for u128

Source§

#### type Err = ParseIntError

1.0.0 (const: unstable) · Source§

### impl FromStr for usize

Source§

#### type Err = ParseIntError

1.0.0 · Source§

### impl FromStr for Ipv4Addr

Source§

#### type Err = AddrParseError

1.0.0 · Source§

### impl FromStr for Ipv6Addr

Source§

#### type Err = AddrParseError

1.5.0 · Source§

### impl FromStr for SocketAddrV4

Source§

#### type Err = AddrParseError

1.5.0 · Source§

### impl FromStr for SocketAddrV6

Source§

#### type Err = AddrParseError

1.35.0 · Source§

### impl FromStr for NonZero<i8>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<i16>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<i32>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<i64>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<i128>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<isize>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<u8>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<u16>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<u32>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<u64>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<u128>

Source§

#### type Err = ParseIntError

1.35.0 · Source§

### impl FromStr for NonZero<usize>

Source§

#### type Err = ParseIntError

Source§

### impl FromStr for ByteString

Source§

#### type Err = Infallible

1.85.0 · Source§

### impl FromStr for CString

Source§

#### type Err = NulError

1.0.0 · Source§

### impl FromStr for String

Source§

#### type Err = Infallible