std::net::ToSocketAddrs - Rust
Description: API documentation for the Rust `ToSocketAddrs` trait in crate `std`.
Keywords: rust, rustlang, rust-lang, ToSocketAddrs

# Trait std::net::ToSocketAddrs 1.0.0 [−] [src]

    pub trait ToSocketAddrs {
        type Iter: Iterator<Item = SocketAddr>;
        fn to_socket_addrs(&self) -> Result<Self::Iter>;
    }

A trait for objects which can be converted or resolved to one or more `SocketAddr` values.

This trait is used for generic address resolution when constructing network objects. By default it is implemented for the following types:

- `SocketAddr`: `to_socket_addrs` is the identity function.

- `SocketAddrV4`, `SocketAddrV6`, `(``IpAddr``,``u16``)`, `(``Ipv4Addr``,``u16``)`, `(``Ipv6Addr``,``u16``)`: `to_socket_addrs` constructs a `SocketAddr` trivially.

- `(``&str``,``u16``)`: the string should be either a string representation of an `IpAddr` address as expected by `FromStr` implementation or a host name.

- `&str`: the string should be either a string representation of a `SocketAddr` as expected by its `FromStr` implementation or a string like `<host_name>:<port>` pair where `<port>` is a `u16` value.

This trait allows constructing network objects like `TcpStream` or `UdpSocket` easily with values of various types for the bind/connection address. It is needed because sometimes one type is more appropriate than the other: for simple uses a string like `"localhost:12345"` is much nicer than manual construction of the corresponding `SocketAddr`, but sometimes `SocketAddr` value is the main source of the address, and converting it to some other type (e.g. a string) just for it to be converted back to `SocketAddr` in constructor methods is pointless.

Addresses returned by the operating system that are not IP addresses are silently ignored.

# Examples

Creating a `SocketAddr` iterator that yields one item:

    use std::net::{ToSocketAddrs, SocketAddr};

    let addr = SocketAddr::from(([127, 0, 0, 1], 443));
    let mut addrs_iter = addr.to_socket_addrs().unwrap();

    assert_eq!(Some(addr), addrs_iter.next());
    assert!(addrs_iter.next().is_none());Run

Creating a `SocketAddr` iterator from a hostname:

    use std::net::{SocketAddr, ToSocketAddrs};

    // assuming 'localhost' resolves to 127.0.0.1
    let mut addrs_iter = "localhost:443".to_socket_addrs().unwrap();
    assert_eq!(addrs_iter.next(), Some(SocketAddr::from(([127, 0, 0, 1], 443))));
    assert!(addrs_iter.next().is_none());

    // assuming 'foo' does not resolve
    assert!("foo:443".to_socket_addrs().is_err());Run

Creating a `SocketAddr` iterator that yields multiple items:

    use std::net::{SocketAddr, ToSocketAddrs};

    let addr1 = SocketAddr::from(([0, 0, 0, 0], 80));
    let addr2 = SocketAddr::from(([127, 0, 0, 1], 443));
    let addrs = vec![addr1, addr2];

    let mut addrs_iter = (&addrs[..]).to_socket_addrs().unwrap();

    assert_eq!(Some(addr1), addrs_iter.next());
    assert_eq!(Some(addr2), addrs_iter.next());
    assert!(addrs_iter.next().is_none());Run

Attempting to create a `SocketAddr` iterator from an improperly formatted socket address `&str` (missing the port):

    use std::io;
    use std::net::ToSocketAddrs;

    let err = "127.0.0.1".to_socket_addrs().unwrap_err();
    assert_eq!(err.kind(), io::ErrorKind::InvalidInput);Run

`TcpStream::connect` is an example of an function that utilizes `ToSocketAddrs` as a trait bound on its parameter in order to accept different types:

    use std::net::{TcpStream, Ipv4Addr};

    let stream = TcpStream::connect(("127.0.0.1", 443));
    // or
    let stream = TcpStream::connect("127.0.0.1:443");
    // or
    let stream = TcpStream::connect((Ipv4Addr::new(127, 0, 0, 1), 443));Run

## Associated Types

### `type Iter: Iterator<Item = SocketAddr>`

Returned iterator over socket addresses which this type may correspond to.

## Required Methods

### `fn to_socket_addrs(&self) -> Result<Self::Iter>`

Converts this object to an iterator of resolved `SocketAddr`s.

The returned iterator may not actually yield any values depending on the outcome of any resolution performed.

Note that this function may block the current thread while resolution is performed.

## Implementors

- [src]
  `impl ToSocketAddrs for SocketAddr type Iter = IntoIter<SocketAddr>;`
- [src]
  `impl ToSocketAddrs for SocketAddrV4 type Iter = IntoIter<SocketAddr>;`
- [src]
  `impl ToSocketAddrs for SocketAddrV6 type Iter = IntoIter<SocketAddr>;`
- [src]
  `impl ToSocketAddrs for (IpAddr, u16) type Iter = IntoIter<SocketAddr>;`
- [src]
  `impl ToSocketAddrs for (Ipv4Addr, u16) type Iter = IntoIter<SocketAddr>;`
- [src]
  `impl ToSocketAddrs for (Ipv6Addr, u16) type Iter = IntoIter<SocketAddr>;`
- [src]
  `impl<'a> ToSocketAddrs for (&'a str, u16) type Iter = IntoIter<SocketAddr>;`
- [src]
  `impl ToSocketAddrs for str type Iter = IntoIter<SocketAddr>;`
- [src]
  `impl<'a> ToSocketAddrs for &'a [SocketAddr] type Iter = Cloned<Iter<'a, SocketAddr>>;`
- [src]
  `impl<'a, T: ToSocketAddrs + ?Sized> ToSocketAddrs for &'a T type Iter = T::Iter;`
- [src]
  `impl ToSocketAddrs for String type Iter = IntoIter<SocketAddr>;`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
↑
  Move up in search results
↓
  Move down in search results
↹
  Switch tab
⏎
  Go to active search result
+ / -
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)