@@ -705,30 +705,74 @@ impl hash::Hash for SocketAddrV6 {
705705///
706706/// # Examples
707707///
708+ /// Creating a [`SocketAddr`] iterator that yields one item:
709+ ///
710+ /// ```
711+ /// use std::net::{ToSocketAddrs, SocketAddr};
712+ ///
713+ /// let addr = SocketAddr::from(([127, 0, 0, 1], 443));
714+ /// let mut addrs_iter = addr.to_socket_addrs().unwrap();
715+ ///
716+ /// assert_eq!(Some(addr), addrs_iter.next());
717+ /// assert!(addrs_iter.next().is_none());
718+ /// ```
719+ ///
720+ /// Creating a [`SocketAddr`] iterator from a hostname:
721+ ///
708722/// ```no_run
709- /// use std::net::{SocketAddrV4, TcpStream, UdpSocket, TcpListener, Ipv4Addr};
710- ///
711- /// fn main() {
712- /// let ip = Ipv4Addr::new(127, 0, 0, 1);
713- /// let port = 12345;
714- ///
715- /// // The following lines are equivalent modulo possible "localhost" name
716- /// // resolution differences
717- /// let tcp_s = TcpStream::connect(SocketAddrV4::new(ip, port));
718- /// let tcp_s = TcpStream::connect((ip, port));
719- /// let tcp_s = TcpStream::connect(("127.0.0.1", port));
720- /// let tcp_s = TcpStream::connect(("localhost", port));
721- /// let tcp_s = TcpStream::connect("127.0.0.1:12345");
722- /// let tcp_s = TcpStream::connect("localhost:12345");
723- ///
724- /// // TcpListener::bind(), UdpSocket::bind() and UdpSocket::send_to()
725- /// // behave similarly
726- /// let tcp_l = TcpListener::bind("localhost:12345");
727- ///
728- /// let mut udp_s = UdpSocket::bind(("127.0.0.1", port)).unwrap();
729- /// udp_s.send_to(&[7], (ip, 23451)).unwrap();
730- /// }
723+ /// use std::net::{SocketAddr, ToSocketAddrs};
724+ ///
725+ /// // assuming 'localhost' resolves to 127.0.0.1
726+ /// let mut addrs_iter = "localhost:443".to_socket_addrs().unwrap();
727+ /// assert_eq!(addrs_iter.next(), Some(SocketAddr::from(([127, 0, 0, 1], 443))));
728+ /// assert!(addrs_iter.next().is_none());
729+ ///
730+ /// // assuming 'foo' does not resolve
731+ /// assert!("foo:443".to_socket_addrs().is_err());
731732/// ```
733+ ///
734+ /// Creating a [`SocketAddr`] iterator that yields multiple items:
735+ ///
736+ /// ```
737+ /// use std::net::{SocketAddr, ToSocketAddrs};
738+ ///
739+ /// let addr1 = SocketAddr::from(([0, 0, 0, 0], 80));
740+ /// let addr2 = SocketAddr::from(([127, 0, 0, 1], 443));
741+ /// let addrs = vec![addr1, addr2];
742+ ///
743+ /// let mut addrs_iter = (&addrs[..]).to_socket_addrs().unwrap();
744+ ///
745+ /// assert_eq!(Some(addr1), addrs_iter.next());
746+ /// assert_eq!(Some(addr2), addrs_iter.next());
747+ /// assert!(addrs_iter.next().is_none());
748+ /// ```
749+ ///
750+ /// Attempting to create a [`SocketAddr`] iterator from an improperly formatted
751+ /// socket address `&str` (missing the port):
752+ ///
753+ /// ```
754+ /// use std::io;
755+ /// use std::net::ToSocketAddrs;
756+ ///
757+ /// let err = "127.0.0.1".to_socket_addrs().unwrap_err();
758+ /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput);
759+ /// ```
760+ ///
761+ /// [`TcpStream::connect`] is an example of an function that utilizes
762+ /// `ToSocketsAddr` as a trait bound on its parameter in order to accept
763+ /// different types:
764+ ///
765+ /// ```no_run
766+ /// use std::net::{TcpStream, Ipv4Addr};
767+ ///
768+ /// let stream = TcpStream::connect(("127.0.0.1", 443));
769+ /// // or
770+ /// let stream = TcpStream::connect("127.0.0.1.443");
771+ /// // or
772+ /// let stream = TcpStream::connect((Ipv4Addr::new(127, 0, 0, 1), 443));
773+ /// ```
774+ ///
775+ /// [`TcpStream::connect`]: ../../std/net/struct.TcpStream.html#method.connect
732776#[ stable( feature = "rust1" , since = "1.0.0" ) ]
733777pub trait ToSocketAddrs {
734778 /// Returned iterator over socket addresses which this type may correspond
0 commit comments