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`, `SocketAddrV4`, `SocketAddrV6` - `to_socket_addrs` is identity function.

- `(IpvNAddr, u16)` - `to_socket_addrs` constructs `SocketAddr` trivially.

- `(&str, u16)` - the string should be either a string representation of an IP address expected by `FromStr` implementation for `IpvNAddr` 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.

Some examples:

    use std::net::{SocketAddrV4, TcpStream, UdpSocket, TcpListener, Ipv4Addr};

    fn main() {
        let ip = Ipv4Addr::new(127, 0, 0, 1);
        let port = 12345;

        // The following lines are equivalent modulo possible "localhost" name
        // resolution differences
        let tcp_s = TcpStream::connect(SocketAddrV4::new(ip, port));
        let tcp_s = TcpStream::connect((ip, port));
        let tcp_s = TcpStream::connect(("127.0.0.1", port));
        let tcp_s = TcpStream::connect(("localhost", port));
        let tcp_s = TcpStream::connect("127.0.0.1:12345");
        let tcp_s = TcpStream::connect("localhost:12345");

        // TcpListener::bind(), UdpSocket::bind() and UdpSocket::send_to()
        // behave similarly
        let tcp_l = TcpListener::bind("localhost:12345");

        let mut udp_s = UdpSocket::bind(("127.0.0.1", port)).unwrap();
        udp_s.send_to(&[7], (ip, 23451)).unwrap();
    }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.

# Errors

Any errors encountered during resolution will be returned as an `Err`.

## Implementors

- `impl ToSocketAddrs for SocketAddr`
- `impl ToSocketAddrs for SocketAddrV4`
- `impl ToSocketAddrs for SocketAddrV6`
- `impl ToSocketAddrs for (IpAddr, u16)`
- `impl ToSocketAddrs for (Ipv4Addr, u16)`
- `impl ToSocketAddrs for (Ipv6Addr, u16)`
- `impl<'a> ToSocketAddrs for (&'a str, u16)`
- `impl ToSocketAddrs for str`
- `impl<'a> ToSocketAddrs for &'a [SocketAddr]`
- `impl<'a, T: ToSocketAddrs + ?Sized> ToSocketAddrs for &'a T`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  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`)