A trait for objects which can be converted or resolved to one or moreSocketAddr values.

This trait is used for generic address resolution when constructing networkobjects. 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 aSocketAddr trivially.

• (&str,u16):&str should be either a string representationof anIpAddr address as expected byFromStr implementation or a hostname.u16 is the port number.

• &str: the string should be either a string representation of aSocketAddr as expected by itsFromStr implementation or a string like<host_name>:<port> pair where<port> is au16 value.

• &[SocketAddr]: allSocketAddr values in the slice will be used.

This trait allows constructing network objects likeTcpStream orUdpSocket easily with values of various types for the bind/connectionaddress. It is needed because sometimes one type is more appropriate thanthe other: for simple uses a string like"localhost:12345" is much nicerthan manual construction of the correspondingSocketAddr, but sometimesSocketAddr value isthe main source of the address, and converting it tosome other type (e.g., a string) just for it to be converted back toSocketAddr in constructor methods is pointless.

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

§Examples

Creating aSocketAddr iterator that yields one item:

usestd::net::{ToSocketAddrs, SocketAddr};letaddr = SocketAddr::from(([127,0,0,1],443));letmutaddrs_iter = addr.to_socket_addrs().unwrap();assert_eq!(Some(addr), addrs_iter.next());assert!(addrs_iter.next().is_none());

Creating aSocketAddr iterator from a hostname:

usestd::net::{SocketAddr, ToSocketAddrs};// assuming 'localhost' resolves to 127.0.0.1letmutaddrs_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 resolveassert!("foo:443".to_socket_addrs().is_err());

Creating aSocketAddr iterator that yields multiple items:

usestd::net::{SocketAddr, ToSocketAddrs};letaddr1 = SocketAddr::from(([0,0,0,0],80));letaddr2 = SocketAddr::from(([127,0,0,1],443));letaddrs =vec![addr1, addr2];letmutaddrs_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());

Attempting to create aSocketAddr iterator from an improperly formattedsocket address&str (missing the port):

usestd::io;usestd::net::ToSocketAddrs;leterr ="127.0.0.1".to_socket_addrs().unwrap_err();assert_eq!(err.kind(), io::ErrorKind::InvalidInput);

TcpStream::connect is an example of a function that utilizesToSocketAddrs as a trait bound on its parameter in order to acceptdifferent types:

usestd::net::{TcpStream, Ipv4Addr};letstream = TcpStream::connect(("127.0.0.1",443));// orletstream = TcpStream::connect("127.0.0.1:443");// orletstream = TcpStream::connect((Ipv4Addr::new(127,0,0,1),443));