Trait lunatic::net::ToSocketAddrs
source · pub trait ToSocketAddrs {
type Iter: Iterator<Item = SocketAddr>;
// Required method
fn to_socket_addrs(&self) -> Result<Self::Iter>;
}Expand description
A trait for objects which can be converted or resolved to one or more
SocketAddr values.
Currently, this trait is only used as an argument to lunatic functions
that need to reference a target socket address. To perform a SocketAddr
conversion directly, use resolve. By default, it is implemented
for the following types:
-
SocketAddr:to_socket_addrsis the identity function. -
SocketAddrV4,SocketAddrV6,(IpAddr,u16),(Ipv4Addr,u16),(Ipv6Addr,u16):to_socket_addrsconstructs aSocketAddrtrivially. -
&str: the string should be either a string representation of aSocketAddras expected by itsFromStrimplementation or a string like<host_name>:<port>pair where<port>is au16value.
This trait allows constructing network objects like TcpStream 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 lunatic::net::ToSocketAddrs;
use std::net::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());Creating a SocketAddr iterator from a hostname:
use std::net::SocketAddr;
use lunatic::net::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());Creating a SocketAddr iterator that yields multiple items:
use std::net::SocketAddr;
use lunatic::net::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());Attempting to create a SocketAddr iterator from an improperly formatted
socket address &str (missing the port):
use std::io;
use lunatic::net::ToSocketAddrs;
let err = "127.0.0.1".to_socket_addrs().unwrap_err();
assert_eq!(err.kind(), io::ErrorKind::InvalidInput);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 lunatic::net::TcpStream;
use std::net::Ipv4Addr;
// or
let stream = TcpStream::connect("127.0.0.1:443");
// or
let stream = TcpStream::connect((Ipv4Addr::new(127, 0, 0, 1), 443));