Auto merge of #40889 - frewsxcv:rollup, r=frewsxcv
Rollup of 5 pull requests - Successful merges: #40682, #40731, #40783, #40838, #40864 - Failed merges:
This commit is contained in:
bors
commit
4465f22ef6
@ -1 +1 @@
|
||||
Subproject commit 9bd223ca406b1170a24942d6474f9e8a56f4a420
|
||||
Subproject commit a2c56870d4dc589237102cc5e0fe7b9ebd0d14a1
|
||||
@ -1 +1 @@
|
||||
Subproject commit d08fe97d12b41c1ed8cc7701e545864132783941
|
||||
Subproject commit 616b98444ff4eb5260deee95ee3e090dfd98b947
|
||||
@ -1 +1 @@
|
||||
Subproject commit 516549972d61c8946542d1a34afeae97167ff77b
|
||||
Subproject commit acedc32cacae80cf2f4925753a4ce7f7ffd7c86a
|
||||
@ -10,9 +10,28 @@
|
||||
|
||||
//! Unicode string slices.
|
||||
//!
|
||||
//! The `&str` type is one of the two main string types, the other being `String`.
|
||||
//! Unlike its `String` counterpart, its contents are borrowed.
|
||||
//!
|
||||
//! # Basic Usage
|
||||
//!
|
||||
//! A basic string declaration of `&str` type:
|
||||
//!
|
||||
//! ```
|
||||
//! let hello_world = "Hello, World!";
|
||||
//! ```
|
||||
//!
|
||||
//! Here we have declared a string literal, also known as a string slice.
|
||||
//! String literals have a static lifetime, which means the string `hello_world`
|
||||
//! is guaranteed to be valid for the duration of the entire program.
|
||||
//! We can explicitly specify `hello_world`'s lifetime as well:
|
||||
//!
|
||||
//! ```
|
||||
//! let hello_world: &'static str = "Hello, world!";
|
||||
//! ```
|
||||
//!
|
||||
//! *[See also the `str` primitive type](../../std/primitive.str.html).*
|
||||
|
||||
|
||||
#![stable(feature = "rust1", since = "1.0.0")]
|
||||
|
||||
// Many of the usings in this module are only used in the test configuration.
|
||||
|
||||
@ -1563,7 +1563,7 @@ impl<T> ops::DerefMut for Vec<T> {
|
||||
impl<T> FromIterator<T> for Vec<T> {
|
||||
#[inline]
|
||||
fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Vec<T> {
|
||||
<Self as SpecExtend<_, _>>::from_iter(iter.into_iter())
|
||||
<Self as SpecExtend<T, I::IntoIter>>::from_iter(iter.into_iter())
|
||||
}
|
||||
}
|
||||
|
||||
@ -1631,7 +1631,7 @@ impl<'a, T> IntoIterator for &'a mut Vec<T> {
|
||||
impl<T> Extend<T> for Vec<T> {
|
||||
#[inline]
|
||||
fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) {
|
||||
self.spec_extend(iter.into_iter())
|
||||
<Self as SpecExtend<T, I::IntoIter>>::spec_extend(self, iter.into_iter())
|
||||
}
|
||||
}
|
||||
|
||||
@ -1662,7 +1662,7 @@ impl<T, I> SpecExtend<T, I> for Vec<T>
|
||||
vector
|
||||
}
|
||||
};
|
||||
vector.spec_extend(iterator);
|
||||
<Vec<T> as SpecExtend<T, I>>::spec_extend(&mut vector, iterator);
|
||||
vector
|
||||
}
|
||||
|
||||
@ -1674,7 +1674,7 @@ impl<T, I> SpecExtend<T, I> for Vec<T>
|
||||
impl<T, I> SpecExtend<T, I> for Vec<T>
|
||||
where I: TrustedLen<Item=T>,
|
||||
{
|
||||
fn from_iter(iterator: I) -> Self {
|
||||
default fn from_iter(iterator: I) -> Self {
|
||||
let mut vector = Vec::new();
|
||||
vector.spec_extend(iterator);
|
||||
vector
|
||||
@ -1706,6 +1706,27 @@ impl<T, I> SpecExtend<T, I> for Vec<T>
|
||||
}
|
||||
}
|
||||
|
||||
impl<T> SpecExtend<T, IntoIter<T>> for Vec<T> {
|
||||
fn from_iter(iterator: IntoIter<T>) -> Self {
|
||||
// A common case is passing a vector into a function which immediately
|
||||
// re-collects into a vector. We can short circuit this if the IntoIter
|
||||
// has not been advanced at all.
|
||||
if *iterator.buf == iterator.ptr as *mut T {
|
||||
unsafe {
|
||||
let vec = Vec::from_raw_parts(*iterator.buf as *mut T,
|
||||
iterator.len(),
|
||||
iterator.cap);
|
||||
mem::forget(iterator);
|
||||
vec
|
||||
}
|
||||
} else {
|
||||
let mut vector = Vec::new();
|
||||
vector.spec_extend(iterator);
|
||||
vector
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl<'a, T: 'a, I> SpecExtend<&'a T, I> for Vec<T>
|
||||
where I: Iterator<Item=&'a T>,
|
||||
T: Clone,
|
||||
|
||||
@ -680,3 +680,19 @@ fn test_placement_panic() {
|
||||
let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| { vec.place_back() <- mkpanic(); }));
|
||||
assert_eq!(vec.len(), 3);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn from_into_inner() {
|
||||
let vec = vec![1, 2, 3];
|
||||
let ptr = vec.as_ptr();
|
||||
let vec = vec.into_iter().collect::<Vec<_>>();
|
||||
assert_eq!(vec, [1, 2, 3]);
|
||||
assert_eq!(vec.as_ptr(), ptr);
|
||||
|
||||
let ptr = &vec[1] as *const _;
|
||||
let mut it = vec.into_iter();
|
||||
it.next().unwrap();
|
||||
let vec = it.collect::<Vec<_>>();
|
||||
assert_eq!(vec, [2, 3]);
|
||||
assert!(ptr != vec.as_ptr());
|
||||
}
|
||||
|
||||
@ -89,6 +89,10 @@ pub struct Cursor<T> {
|
||||
impl<T> Cursor<T> {
|
||||
/// Creates a new cursor wrapping the provided underlying I/O object.
|
||||
///
|
||||
/// Cursor initial position is `0` even if underlying object (e.
|
||||
/// g. `Vec`) is not empty. So writing to cursor starts with
|
||||
/// overwriting `Vec` content, not with appending to it.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
|
||||
@ -20,15 +20,31 @@ use vec;
|
||||
use iter;
|
||||
use slice;
|
||||
|
||||
/// Representation of a socket address for networking applications.
|
||||
/// An internet socket address, either IPv4 or IPv6.
|
||||
///
|
||||
/// A socket address can either represent the IPv4 or IPv6 protocol and is
|
||||
/// paired with at least a port number as well. Each protocol may have more
|
||||
/// specific information about the address available to it as well.
|
||||
/// Internet socket addresses consist of an [IP address], a 16-bit port number, as well
|
||||
/// as possibly some version-dependent additional information. See [`SocketAddrV4`]'s and
|
||||
/// [`SocketAddrV6`]'s respective documentation for more details.
|
||||
///
|
||||
/// [IP address]: ../../std/net/enum.IpAddr.html
|
||||
/// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
|
||||
/// [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::net::{IpAddr, Ipv4Addr, SocketAddr};
|
||||
///
|
||||
/// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
|
||||
///
|
||||
/// assert_eq!("127.0.0.1:8080".parse(), Ok(socket));
|
||||
/// assert_eq!(socket.port(), 8080);
|
||||
/// assert_eq!(socket.is_ipv4(), true);
|
||||
/// ```
|
||||
#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub enum SocketAddr {
|
||||
/// An IPv4 socket address which is a (ip, port) combination.
|
||||
/// An IPv4 socket address.
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
V4(#[stable(feature = "rust1", since = "1.0.0")] SocketAddrV4),
|
||||
/// An IPv6 socket address.
|
||||
@ -36,18 +52,63 @@ pub enum SocketAddr {
|
||||
V6(#[stable(feature = "rust1", since = "1.0.0")] SocketAddrV6),
|
||||
}
|
||||
|
||||
/// An IPv4 socket address which is a (ip, port) combination.
|
||||
/// An IPv4 socket address.
|
||||
///
|
||||
/// IPv4 socket addresses consist of an [IPv4 address] and a 16-bit port number, as
|
||||
/// stated in [IETF RFC 793].
|
||||
///
|
||||
/// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses.
|
||||
///
|
||||
/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
|
||||
/// [IPv4 address]: ../../std/net/struct.Ipv4Addr.html
|
||||
/// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::net::{Ipv4Addr, SocketAddrV4};
|
||||
///
|
||||
/// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080);
|
||||
///
|
||||
/// assert_eq!("127.0.0.1:8080".parse(), Ok(socket));
|
||||
/// assert_eq!(socket.ip(), &Ipv4Addr::new(127, 0, 0, 1));
|
||||
/// assert_eq!(socket.port(), 8080);
|
||||
/// ```
|
||||
#[derive(Copy)]
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub struct SocketAddrV4 { inner: c::sockaddr_in }
|
||||
|
||||
/// An IPv6 socket address.
|
||||
///
|
||||
/// IPv6 socket addresses consist of an [Ipv6 address], a 16-bit port number, as well
|
||||
/// as fields containing the traffic class, the flow label, and a scope identifier
|
||||
/// (see [IETF RFC 2553, Section 3.3] for more details).
|
||||
///
|
||||
/// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses.
|
||||
///
|
||||
/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
|
||||
/// [IPv6 address]: ../../std/net/struct.Ipv6Addr.html
|
||||
/// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::net::{Ipv6Addr, SocketAddrV6};
|
||||
///
|
||||
/// let socket = SocketAddrV6::new(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1), 8080, 0, 0);
|
||||
///
|
||||
/// assert_eq!("[2001:db8::1]:8080".parse(), Ok(socket));
|
||||
/// assert_eq!(socket.ip(), &Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1));
|
||||
/// assert_eq!(socket.port(), 8080);
|
||||
/// ```
|
||||
#[derive(Copy)]
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub struct SocketAddrV6 { inner: c::sockaddr_in6 }
|
||||
|
||||
impl SocketAddr {
|
||||
/// Creates a new socket address from the (ip, port) pair.
|
||||
/// Creates a new socket address from an [IP address] and a port number.
|
||||
///
|
||||
/// [IP address]: ../../std/net/enum.IpAddr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -84,7 +145,7 @@ impl SocketAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Change the IP address associated with this socket address.
|
||||
/// Changes the IP address associated with this socket address.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -123,7 +184,7 @@ impl SocketAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Change the port number associated with this socket address.
|
||||
/// Changes the port number associated with this socket address.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -142,8 +203,13 @@ impl SocketAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if the IP in this `SocketAddr` is a valid IPv4 address,
|
||||
/// false if it's a valid IPv6 address.
|
||||
/// Returns [`true`] if the [IP address] in this `SocketAddr` is an
|
||||
/// [IPv4 address], and [`false`] otherwise.
|
||||
///
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
/// [`false`]: ../../std/primitive.bool.html
|
||||
/// [IP address]: ../../std/net/enum.IpAddr.html
|
||||
/// [IPv4 address]: ../../std/net/enum.IpAddr.html#variant.V4
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -164,8 +230,13 @@ impl SocketAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if the IP in this `SocketAddr` is a valid IPv6 address,
|
||||
/// false if it's a valid IPv4 address.
|
||||
/// Returns [`true`] if the [IP address] in this `SocketAddr` is an
|
||||
/// [IPv6 address], and [`false`] otherwise.
|
||||
///
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
/// [`false`]: ../../std/primitive.bool.html
|
||||
/// [IP address]: ../../std/net/enum.IpAddr.html
|
||||
/// [IPv6 address]: ../../std/net/enum.IpAddr.html#variant.V6
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -189,7 +260,9 @@ impl SocketAddr {
|
||||
}
|
||||
|
||||
impl SocketAddrV4 {
|
||||
/// Creates a new socket address from the (ip, port) pair.
|
||||
/// Creates a new socket address from an [IPv4 address] and a port number.
|
||||
///
|
||||
/// [IPv4 address]: ../../std/net/struct.Ipv4Addr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -227,7 +300,7 @@ impl SocketAddrV4 {
|
||||
}
|
||||
}
|
||||
|
||||
/// Change the IP address associated with this socket address.
|
||||
/// Changes the IP address associated with this socket address.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -258,7 +331,7 @@ impl SocketAddrV4 {
|
||||
ntoh(self.inner.sin_port)
|
||||
}
|
||||
|
||||
/// Change the port number associated with this socket address.
|
||||
/// Changes the port number associated with this socket address.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -276,8 +349,14 @@ impl SocketAddrV4 {
|
||||
}
|
||||
|
||||
impl SocketAddrV6 {
|
||||
/// Creates a new socket address from the ip/port/flowinfo/scope_id
|
||||
/// components.
|
||||
/// Creates a new socket address from an [IPv6 address], a 16-bit port number,
|
||||
/// and the `flowinfo` and `scope_id` fields.
|
||||
///
|
||||
/// For more information on the meaning and layout of the `flowinfo` and `scope_id`
|
||||
/// parameters, see [IETF RFC 2553, Section 3.3].
|
||||
///
|
||||
/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
|
||||
/// [IPv6 address]: ../../std/net/struct.Ipv6Addr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -318,7 +397,7 @@ impl SocketAddrV6 {
|
||||
}
|
||||
}
|
||||
|
||||
/// Change the IP address associated with this socket address.
|
||||
/// Changes the IP address associated with this socket address.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -349,7 +428,7 @@ impl SocketAddrV6 {
|
||||
ntoh(self.inner.sin6_port)
|
||||
}
|
||||
|
||||
/// Change the port number associated with this socket address.
|
||||
/// Changes the port number associated with this socket address.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -365,8 +444,17 @@ impl SocketAddrV6 {
|
||||
self.inner.sin6_port = hton(new_port);
|
||||
}
|
||||
|
||||
/// Returns the flow information associated with this address,
|
||||
/// corresponding to the `sin6_flowinfo` field in C.
|
||||
/// Returns the flow information associated with this address.
|
||||
///
|
||||
/// This information corresponds to the `sin6_flowinfo` field in C's `netinet/in.h`,
|
||||
/// as specified in [IETF RFC 2553, Section 3.3].
|
||||
/// It combines information about the flow label and the traffic class as specified
|
||||
/// in [IETF RFC 2460], respectively [Section 6] and [Section 7].
|
||||
///
|
||||
/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
|
||||
/// [IETF RFC 2460]: https://tools.ietf.org/html/rfc2460
|
||||
/// [Section 6]: https://tools.ietf.org/html/rfc2460#section-6
|
||||
/// [Section 7]: https://tools.ietf.org/html/rfc2460#section-7
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -381,7 +469,11 @@ impl SocketAddrV6 {
|
||||
self.inner.sin6_flowinfo
|
||||
}
|
||||
|
||||
/// Change the flow information associated with this socket address.
|
||||
/// Changes the flow information associated with this socket address.
|
||||
///
|
||||
/// See the [`flowinfo`] method's documentation for more details.
|
||||
///
|
||||
/// [`flowinfo`]: #method.flowinfo
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -397,8 +489,12 @@ impl SocketAddrV6 {
|
||||
self.inner.sin6_flowinfo = new_flowinfo;
|
||||
}
|
||||
|
||||
/// Returns the scope ID associated with this address,
|
||||
/// corresponding to the `sin6_scope_id` field in C.
|
||||
/// Returns the scope ID associated with this address.
|
||||
///
|
||||
/// This information corresponds to the `sin6_scope_id` field in C's `netinet/in.h`,
|
||||
/// as specified in [IETF RFC 2553, Section 3.3].
|
||||
///
|
||||
/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -415,6 +511,10 @@ impl SocketAddrV6 {
|
||||
|
||||
/// Change the scope ID associated with this socket address.
|
||||
///
|
||||
/// See the [`scope_id`] method's documentation for more details.
|
||||
///
|
||||
/// [`scope_id`]: #method.scope_id
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -559,37 +659,51 @@ impl hash::Hash for SocketAddrV6 {
|
||||
}
|
||||
|
||||
/// A trait for objects which can be converted or resolved to one or more
|
||||
/// `SocketAddr` values.
|
||||
/// [`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.
|
||||
/// * [`SocketAddr`]: [`to_socket_addrs`] is the identity function.
|
||||
///
|
||||
/// * `(IpvNAddr, u16)` - `to_socket_addrs` constructs `SocketAddr` trivially.
|
||||
/// * [`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
|
||||
/// IP address expected by `FromStr` implementation for `IpvNAddr` or a host
|
||||
/// * `(`[`&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.
|
||||
/// * [`&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
|
||||
/// 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
|
||||
/// 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.
|
||||
/// [`SocketAddr`] in constructor methods is pointless.
|
||||
///
|
||||
/// Addresses returned by the operating system that are not IP addresses are
|
||||
/// silently ignored.
|
||||
///
|
||||
/// Some examples:
|
||||
/// [`FromStr`]: ../../std/str/trait.FromStr.html
|
||||
/// [`IpAddr`]: ../../std/net/enum.IpAddr.html
|
||||
/// [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html
|
||||
/// [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html
|
||||
/// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
|
||||
/// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
|
||||
/// [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
|
||||
/// [`&str`]: ../../std/primitive.str.html
|
||||
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
|
||||
/// [`to_socket_addrs`]: #tymethod.to_socket_addrs
|
||||
/// [`UdpSocket`]: ../../std/net/struct.UdpSocket.html
|
||||
/// [`u16`]: ../../std/primitive.u16.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```no_run
|
||||
/// use std::net::{SocketAddrV4, TcpStream, UdpSocket, TcpListener, Ipv4Addr};
|
||||
@ -629,10 +743,6 @@ pub trait ToSocketAddrs {
|
||||
///
|
||||
/// 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`.
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
fn to_socket_addrs(&self) -> io::Result<Self::Iter>;
|
||||
}
|
||||
|
||||
@ -21,44 +21,100 @@ use net::{hton, ntoh};
|
||||
use sys::net::netc as c;
|
||||
use sys_common::{AsInner, FromInner};
|
||||
|
||||
/// An IP address, either an IPv4 or IPv6 address.
|
||||
/// An IP address, either IPv4 or IPv6.
|
||||
///
|
||||
/// This enum can contain either an [`Ipv4Addr`] or an [`Ipv6Addr`], see their
|
||||
/// respective documentation for more details.
|
||||
///
|
||||
/// [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html
|
||||
/// [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// Constructing an IPv4 address:
|
||||
///
|
||||
/// ```
|
||||
/// use std::net::{IpAddr, Ipv4Addr};
|
||||
/// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
|
||||
///
|
||||
/// IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1));
|
||||
/// ```
|
||||
/// let localhost_v4 = IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1));
|
||||
/// let localhost_v6 = IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1));
|
||||
///
|
||||
/// Constructing an IPv6 address:
|
||||
/// assert_eq!("127.0.0.1".parse(), Ok(localhost_v4));
|
||||
/// assert_eq!("::1".parse(), Ok(localhost_v6));
|
||||
///
|
||||
/// ```
|
||||
/// use std::net::{IpAddr, Ipv6Addr};
|
||||
///
|
||||
/// IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1));
|
||||
/// assert_eq!(localhost_v4.is_ipv6(), false);
|
||||
/// assert_eq!(localhost_v4.is_ipv4(), true);
|
||||
/// ```
|
||||
#[stable(feature = "ip_addr", since = "1.7.0")]
|
||||
#[derive(Copy, Clone, Eq, PartialEq, Debug, Hash, PartialOrd, Ord)]
|
||||
pub enum IpAddr {
|
||||
/// Representation of an IPv4 address.
|
||||
/// An IPv4 address.
|
||||
#[stable(feature = "ip_addr", since = "1.7.0")]
|
||||
V4(#[stable(feature = "ip_addr", since = "1.7.0")] Ipv4Addr),
|
||||
/// Representation of an IPv6 address.
|
||||
/// An IPv6 address.
|
||||
#[stable(feature = "ip_addr", since = "1.7.0")]
|
||||
V6(#[stable(feature = "ip_addr", since = "1.7.0")] Ipv6Addr),
|
||||
}
|
||||
|
||||
/// Representation of an IPv4 address.
|
||||
/// An IPv4 address.
|
||||
///
|
||||
/// IPv4 addresses are defined as 32-bit integers in [IETF RFC 791].
|
||||
/// They are usually represented as four octets.
|
||||
///
|
||||
/// See [`IpAddr`] for a type encompassing both IPv4 and IPv6 addresses.
|
||||
///
|
||||
/// [IETF RFC 791]: https://tools.ietf.org/html/rfc791
|
||||
/// [`IpAddr`]: ../../std/net/enum.IpAddr.html
|
||||
///
|
||||
/// # Textual representation
|
||||
///
|
||||
/// `Ipv4Addr` provides a [`FromStr`] implementation. The four octets are in decimal
|
||||
/// notation, divided by `.` (this is called "dot-decimal notation").
|
||||
///
|
||||
/// [`FromStr`]: ../../std/str/trait.FromStr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::net::Ipv4Addr;
|
||||
///
|
||||
/// let localhost = Ipv4Addr::new(127, 0, 0, 1);
|
||||
/// assert_eq!("127.0.0.1".parse(), Ok(localhost));
|
||||
/// assert_eq!(localhost.is_loopback(), true);
|
||||
/// ```
|
||||
#[derive(Copy)]
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub struct Ipv4Addr {
|
||||
inner: c::in_addr,
|
||||
}
|
||||
|
||||
/// Representation of an IPv6 address.
|
||||
/// An IPv6 address.
|
||||
///
|
||||
/// IPv6 addresses are defined as 128-bit integers in [IETF RFC 4291].
|
||||
/// They are usually represented as eight 16-bit segments.
|
||||
///
|
||||
/// See [`IpAddr`] for a type encompassing both IPv4 and IPv6 addresses.
|
||||
///
|
||||
/// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291
|
||||
/// [`IpAddr`]: ../../std/net/enum.IpAddr.html
|
||||
///
|
||||
/// # Textual representation
|
||||
///
|
||||
/// `Ipv6Addr` provides a [`FromStr`] implementation. There are many ways to represent
|
||||
/// an IPv6 address in text, but in general, each segments is written in hexadecimal
|
||||
/// notation, and segments are separated by `:`. For more information, see
|
||||
/// [IETF RFC 5952].
|
||||
///
|
||||
/// [`FromStr`]: ../../std/str/trait.FromStr.html
|
||||
/// [IETF RFC 5952]: https://tools.ietf.org/html/rfc5952
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::net::Ipv6Addr;
|
||||
///
|
||||
/// let localhost = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1);
|
||||
/// assert_eq!("::1".parse(), Ok(localhost));
|
||||
/// assert_eq!(localhost.is_loopback(), true);
|
||||
/// ```
|
||||
#[derive(Copy)]
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub struct Ipv6Addr {
|
||||
@ -78,10 +134,14 @@ pub enum Ipv6MulticastScope {
|
||||
}
|
||||
|
||||
impl IpAddr {
|
||||
/// Returns true for the special 'unspecified' address ([IPv4], [IPv6]).
|
||||
/// Returns [`true`] for the special 'unspecified' address.
|
||||
///
|
||||
/// See the documentation for [`Ipv4Addr::is_unspecified`][IPv4] and
|
||||
/// [`Ipv6Addr::is_unspecified`][IPv6] for more details.
|
||||
///
|
||||
/// [IPv4]: ../../std/net/struct.Ipv4Addr.html#method.is_unspecified
|
||||
/// [IPv6]: ../../std/net/struct.Ipv6Addr.html#method.is_unspecified
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -99,10 +159,14 @@ impl IpAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if this is a loopback address ([IPv4], [IPv6]).
|
||||
/// Returns [`true`] if this is a loopback address.
|
||||
///
|
||||
/// See the documentation for [`Ipv4Addr::is_loopback`][IPv4] and
|
||||
/// [`Ipv6Addr::is_loopback`][IPv6] for more details.
|
||||
///
|
||||
/// [IPv4]: ../../std/net/struct.Ipv4Addr.html#method.is_loopback
|
||||
/// [IPv6]: ../../std/net/struct.Ipv6Addr.html#method.is_loopback
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -120,10 +184,14 @@ impl IpAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if the address appears to be globally routable ([IPv4], [IPv6]).
|
||||
/// Returns [`true`] if the address appears to be globally routable.
|
||||
///
|
||||
/// See the documentation for [`Ipv4Addr::is_global`][IPv4] and
|
||||
/// [`Ipv6Addr::is_global`][IPv6] for more details.
|
||||
///
|
||||
/// [IPv4]: ../../std/net/struct.Ipv4Addr.html#method.is_global
|
||||
/// [IPv6]: ../../std/net/struct.Ipv6Addr.html#method.is_global
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -145,10 +213,14 @@ impl IpAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if this is a multicast address ([IPv4], [IPv6]).
|
||||
/// Returns [`true`] if this is a multicast address.
|
||||
///
|
||||
/// See the documentation for [`Ipv4Addr::is_multicast`][IPv4] and
|
||||
/// [`Ipv6Addr::is_multicast`][IPv6] for more details.
|
||||
///
|
||||
/// [IPv4]: ../../std/net/struct.Ipv4Addr.html#method.is_multicast
|
||||
/// [IPv6]: ../../std/net/struct.Ipv6Addr.html#method.is_multicast
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -166,10 +238,14 @@ impl IpAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if this address is in a range designated for documentation ([IPv4], [IPv6]).
|
||||
/// Returns [`true`] if this address is in a range designated for documentation.
|
||||
///
|
||||
/// See the documentation for [`Ipv4Addr::is_documentation`][IPv4] and
|
||||
/// [`Ipv6Addr::is_documentation`][IPv6] for more details.
|
||||
///
|
||||
/// [IPv4]: ../../std/net/struct.Ipv4Addr.html#method.is_documentation
|
||||
/// [IPv6]: ../../std/net/struct.Ipv6Addr.html#method.is_documentation
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -191,7 +267,11 @@ impl IpAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if this address is a valid IPv4 address, false if it's a valid IPv6 address.
|
||||
/// Returns [`true`] if this address is an [IPv4 address], and [`false`] otherwise.
|
||||
///
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
/// [`false`]: ../../std/primitive.bool.html
|
||||
/// [IPv4 address]: #variant.V4
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -212,7 +292,11 @@ impl IpAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if this address is a valid IPv6 address, false if it's a valid IPv4 address.
|
||||
/// Returns [`true`] if this address is an [IPv6 address], and [`false`] otherwise.
|
||||
///
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
/// [`false`]: ../../std/primitive.bool.html
|
||||
/// [IPv6 address]: #variant.V6
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -274,12 +358,13 @@ impl Ipv4Addr {
|
||||
[(bits >> 24) as u8, (bits >> 16) as u8, (bits >> 8) as u8, bits as u8]
|
||||
}
|
||||
|
||||
/// Returns true for the special 'unspecified' address (0.0.0.0).
|
||||
/// Returns [`true`] for the special 'unspecified' address (0.0.0.0).
|
||||
///
|
||||
/// This property is defined in _UNIX Network Programming, Second Edition_,
|
||||
/// W. Richard Stevens, p. 891; see also [ip7].
|
||||
///
|
||||
/// [ip7]: http://man7.org/linux/man-pages/man7/ip.7.html
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -294,11 +379,12 @@ impl Ipv4Addr {
|
||||
self.inner.s_addr == 0
|
||||
}
|
||||
|
||||
/// Returns true if this is a loopback address (127.0.0.0/8).
|
||||
/// Returns [`true`] if this is a loopback address (127.0.0.0/8).
|
||||
///
|
||||
/// This property is defined by [RFC 1122].
|
||||
/// This property is defined by [IETF RFC 1122].
|
||||
///
|
||||
/// [RFC 1122]: https://tools.ietf.org/html/rfc1122
|
||||
/// [IETF RFC 1122]: https://tools.ietf.org/html/rfc1122
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -313,15 +399,16 @@ impl Ipv4Addr {
|
||||
self.octets()[0] == 127
|
||||
}
|
||||
|
||||
/// Returns true if this is a private address.
|
||||
/// Returns [`true`] if this is a private address.
|
||||
///
|
||||
/// The private address ranges are defined in [RFC 1918] and include:
|
||||
/// The private address ranges are defined in [IETF RFC 1918] and include:
|
||||
///
|
||||
/// - 10.0.0.0/8
|
||||
/// - 172.16.0.0/12
|
||||
/// - 192.168.0.0/16
|
||||
///
|
||||
/// [RFC 1918]: https://tools.ietf.org/html/rfc1918
|
||||
/// [IETF RFC 1918]: https://tools.ietf.org/html/rfc1918
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -346,11 +433,12 @@ impl Ipv4Addr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if the address is link-local (169.254.0.0/16).
|
||||
/// Returns [`true`] if the address is link-local (169.254.0.0/16).
|
||||
///
|
||||
/// This property is defined by [RFC 3927].
|
||||
/// This property is defined by [IETF RFC 3927].
|
||||
///
|
||||
/// [RFC 3927]: https://tools.ietf.org/html/rfc3927
|
||||
/// [IETF RFC 3927]: https://tools.ietf.org/html/rfc3927
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -366,7 +454,7 @@ impl Ipv4Addr {
|
||||
self.octets()[0] == 169 && self.octets()[1] == 254
|
||||
}
|
||||
|
||||
/// Returns true if the address appears to be globally routable.
|
||||
/// Returns [`true`] if the address appears to be globally routable.
|
||||
/// See [iana-ipv4-special-registry][ipv4-sr].
|
||||
///
|
||||
/// The following return false:
|
||||
@ -379,6 +467,7 @@ impl Ipv4Addr {
|
||||
/// - the unspecified address (0.0.0.0)
|
||||
///
|
||||
/// [ipv4-sr]: http://goo.gl/RaZ7lg
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -400,12 +489,13 @@ impl Ipv4Addr {
|
||||
!self.is_broadcast() && !self.is_documentation() && !self.is_unspecified()
|
||||
}
|
||||
|
||||
/// Returns true if this is a multicast address (224.0.0.0/4).
|
||||
/// Returns [`true`] if this is a multicast address (224.0.0.0/4).
|
||||
///
|
||||
/// Multicast addresses have a most significant octet between 224 and 239,
|
||||
/// and is defined by [RFC 5771].
|
||||
/// and is defined by [IETF RFC 5771].
|
||||
///
|
||||
/// [RFC 5771]: https://tools.ietf.org/html/rfc5771
|
||||
/// [IETF RFC 5771]: https://tools.ietf.org/html/rfc5771
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -421,11 +511,12 @@ impl Ipv4Addr {
|
||||
self.octets()[0] >= 224 && self.octets()[0] <= 239
|
||||
}
|
||||
|
||||
/// Returns true if this is a broadcast address (255.255.255.255).
|
||||
/// Returns [`true`] if this is a broadcast address (255.255.255.255).
|
||||
///
|
||||
/// A broadcast address has all octets set to 255 as defined in [RFC 919].
|
||||
/// A broadcast address has all octets set to 255 as defined in [IETF RFC 919].
|
||||
///
|
||||
/// [RFC 919]: https://tools.ietf.org/html/rfc919
|
||||
/// [IETF RFC 919]: https://tools.ietf.org/html/rfc919
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -441,15 +532,16 @@ impl Ipv4Addr {
|
||||
self.octets()[2] == 255 && self.octets()[3] == 255
|
||||
}
|
||||
|
||||
/// Returns true if this address is in a range designated for documentation.
|
||||
/// Returns [`true`] if this address is in a range designated for documentation.
|
||||
///
|
||||
/// This is defined in [RFC 5737]:
|
||||
/// This is defined in [IETF RFC 5737]:
|
||||
///
|
||||
/// - 192.0.2.0/24 (TEST-NET-1)
|
||||
/// - 198.51.100.0/24 (TEST-NET-2)
|
||||
/// - 203.0.113.0/24 (TEST-NET-3)
|
||||
///
|
||||
/// [RFC 5737]: https://tools.ietf.org/html/rfc5737
|
||||
/// [IETF RFC 5737]: https://tools.ietf.org/html/rfc5737
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -471,10 +563,12 @@ impl Ipv4Addr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Converts this address to an IPv4-compatible IPv6 address.
|
||||
/// Converts this address to an IPv4-compatible [IPv6 address].
|
||||
///
|
||||
/// a.b.c.d becomes ::a.b.c.d
|
||||
///
|
||||
/// [IPv6 address]: ../../std/net/struct.Ipv6Addr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -490,10 +584,12 @@ impl Ipv4Addr {
|
||||
((self.octets()[2] as u16) << 8) | self.octets()[3] as u16)
|
||||
}
|
||||
|
||||
/// Converts this address to an IPv4-mapped IPv6 address.
|
||||
/// Converts this address to an IPv4-mapped [IPv6 address].
|
||||
///
|
||||
/// a.b.c.d becomes ::ffff:a.b.c.d
|
||||
///
|
||||
/// [IPv6 address]: ../../std/net/struct.Ipv6Addr.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -717,11 +813,12 @@ impl Ipv6Addr {
|
||||
]
|
||||
}
|
||||
|
||||
/// Returns true for the special 'unspecified' address (::).
|
||||
/// Returns [`true`] for the special 'unspecified' address (::).
|
||||
///
|
||||
/// This property is defined in [RFC 4291].
|
||||
/// This property is defined in [IETF RFC 4291].
|
||||
///
|
||||
/// [RFC 4291]: https://tools.ietf.org/html/rfc4291
|
||||
/// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -736,11 +833,12 @@ impl Ipv6Addr {
|
||||
self.segments() == [0, 0, 0, 0, 0, 0, 0, 0]
|
||||
}
|
||||
|
||||
/// Returns true if this is a loopback address (::1).
|
||||
/// Returns [`true`] if this is a loopback address (::1).
|
||||
///
|
||||
/// This property is defined in [RFC 4291].
|
||||
/// This property is defined in [IETF RFC 4291].
|
||||
///
|
||||
/// [RFC 4291]: https://tools.ietf.org/html/rfc4291
|
||||
/// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -755,14 +853,17 @@ impl Ipv6Addr {
|
||||
self.segments() == [0, 0, 0, 0, 0, 0, 0, 1]
|
||||
}
|
||||
|
||||
/// Returns true if the address appears to be globally routable.
|
||||
/// Returns [`true`] if the address appears to be globally routable.
|
||||
///
|
||||
/// The following return false:
|
||||
/// The following return [`false`]:
|
||||
///
|
||||
/// - the loopback address
|
||||
/// - link-local, site-local, and unique local unicast addresses
|
||||
/// - interface-, link-, realm-, admin- and site-local multicast addresses
|
||||
///
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
/// [`false`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -784,11 +885,12 @@ impl Ipv6Addr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if this is a unique local address (fc00::/7).
|
||||
/// Returns [`true`] if this is a unique local address (fc00::/7).
|
||||
///
|
||||
/// This property is defined in [RFC 4193].
|
||||
/// This property is defined in [IETF RFC 4193].
|
||||
///
|
||||
/// [RFC 4193]: https://tools.ietf.org/html/rfc4193
|
||||
/// [IETF RFC 4193]: https://tools.ietf.org/html/rfc4193
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -807,11 +909,12 @@ impl Ipv6Addr {
|
||||
(self.segments()[0] & 0xfe00) == 0xfc00
|
||||
}
|
||||
|
||||
/// Returns true if the address is unicast and link-local (fe80::/10).
|
||||
/// Returns [`true`] if the address is unicast and link-local (fe80::/10).
|
||||
///
|
||||
/// This property is defined in [RFC 4291].
|
||||
/// This property is defined in [IETF RFC 4291].
|
||||
///
|
||||
/// [RFC 4291]: https://tools.ietf.org/html/rfc4291
|
||||
/// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -830,9 +933,11 @@ impl Ipv6Addr {
|
||||
(self.segments()[0] & 0xffc0) == 0xfe80
|
||||
}
|
||||
|
||||
/// Returns true if this is a deprecated unicast site-local address
|
||||
/// Returns [`true`] if this is a deprecated unicast site-local address
|
||||
/// (fec0::/10).
|
||||
///
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -850,12 +955,13 @@ impl Ipv6Addr {
|
||||
(self.segments()[0] & 0xffc0) == 0xfec0
|
||||
}
|
||||
|
||||
/// Returns true if this is an address reserved for documentation
|
||||
/// Returns [`true`] if this is an address reserved for documentation
|
||||
/// (2001:db8::/32).
|
||||
///
|
||||
/// This property is defined in [RFC 3849].
|
||||
/// This property is defined in [IETF RFC 3849].
|
||||
///
|
||||
/// [RFC 3849]: https://tools.ietf.org/html/rfc3849
|
||||
/// [IETF RFC 3849]: https://tools.ietf.org/html/rfc3849
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -874,7 +980,7 @@ impl Ipv6Addr {
|
||||
(self.segments()[0] == 0x2001) && (self.segments()[1] == 0xdb8)
|
||||
}
|
||||
|
||||
/// Returns true if the address is a globally routable unicast address.
|
||||
/// Returns [`true`] if the address is a globally routable unicast address.
|
||||
///
|
||||
/// The following return false:
|
||||
///
|
||||
@ -885,6 +991,8 @@ impl Ipv6Addr {
|
||||
/// - the unspecified address
|
||||
/// - the address range reserved for documentation
|
||||
///
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -937,11 +1045,13 @@ impl Ipv6Addr {
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns true if this is a multicast address (ff00::/8).
|
||||
/// Returns [`true`] if this is a multicast address (ff00::/8).
|
||||
///
|
||||
/// This property is defined by [RFC 4291].
|
||||
/// This property is defined by [IETF RFC 4291].
|
||||
///
|
||||
/// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291
|
||||
/// [`true`]: ../../std/primitive.bool.html
|
||||
///
|
||||
/// [RFC 4291]: https://tools.ietf.org/html/rfc4291
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
@ -955,11 +1065,16 @@ impl Ipv6Addr {
|
||||
(self.segments()[0] & 0xff00) == 0xff00
|
||||
}
|
||||
|
||||
/// Converts this address to an IPv4 address. Returns None if this address is
|
||||
/// Converts this address to an [IPv4 address]. Returns [`None`] if this address is
|
||||
/// neither IPv4-compatible or IPv4-mapped.
|
||||
///
|
||||
/// ::a.b.c.d and ::ffff:a.b.c.d become a.b.c.d
|
||||
///
|
||||
/// [IPv4 address]: ../../std/net/struct.Ipv4Addr.html
|
||||
/// [`None`]: ../../std/option/enum.Option.html#variant.None
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```
|
||||
/// use std::net::{Ipv4Addr, Ipv6Addr};
|
||||
///
|
||||
|
||||
@ -9,6 +9,32 @@
|
||||
// except according to those terms.
|
||||
|
||||
//! Networking primitives for TCP/UDP communication.
|
||||
//!
|
||||
//! This module provides networking functionality for the Transmission Control and User
|
||||
//! Datagram Protocols, as well as types for IP and socket addresses.
|
||||
//!
|
||||
//! # Organization
|
||||
//!
|
||||
//! * [`TcpListener`] and [`TcpStream`] provide functionality for communication over TCP
|
||||
//! * [`UdpSocket`] provides functionality for communication over UDP
|
||||
//! * [`IpAddr`] represents IP addresses of either IPv4 or IPv6; [`Ipv4Addr`] and
|
||||
//! [`Ipv6Addr`] are respectively IPv4 and IPv6 addresses
|
||||
//! * [`SocketAddr`] represents socket addresses of either IPv4 or IPv6; [`SocketAddrV4`]
|
||||
//! and [`SocketAddrV6`] are respectively IPv4 and IPv6 socket addresses
|
||||
//! * [`ToSocketAddrs`] is a trait that used for generic address resolution when interacting
|
||||
//! with networking objects like [`TcpListener`], [`TcpStream`] or [`UdpSocket`]
|
||||
//! * Other types are return or parameter types for various methods in this module
|
||||
//!
|
||||
//! [`IpAddr`]: ../../std/net/enum.IpAddr.html
|
||||
//! [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html
|
||||
//! [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html
|
||||
//! [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
|
||||
//! [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
|
||||
//! [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
|
||||
//! [`TcpListener`]: ../../std/net/struct.TcpListener.html
|
||||
//! [`TcpStream`]: ../../std/net/struct.TcpStream.html
|
||||
//! [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
|
||||
//! [`UdpSocket`]: ../../std/net/struct.UdpSocket.html
|
||||
|
||||
#![stable(feature = "rust1", since = "1.0.0")]
|
||||
|
||||
@ -43,17 +69,30 @@ mod test;
|
||||
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub enum Shutdown {
|
||||
/// Indicates that the reading portion of this stream/socket should be shut
|
||||
/// down. All currently blocked and future reads will return `Ok(0)`.
|
||||
/// The reading portion of the [`TcpStream`] should be shut down.
|
||||
///
|
||||
/// All currently blocked and future [reads] will return [`Ok(0)`].
|
||||
///
|
||||
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
|
||||
/// [reads]: ../../std/io/trait.Read.html
|
||||
/// [`Ok(0)`]: ../../std/result/enum.Result.html#variant.Ok
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
Read,
|
||||
/// Indicates that the writing portion of this stream/socket should be shut
|
||||
/// down. All currently blocked and future writes will return an error.
|
||||
/// The writing portion of the [`TcpStream`] should be shut down.
|
||||
///
|
||||
/// All currently blocked and future [writes] will return an error.
|
||||
///
|
||||
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
|
||||
/// [writes]: ../../std/io/trait.Write.html
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
Write,
|
||||
/// Shut down both the reading and writing portions of this stream.
|
||||
/// Both the reading and the writing portions of the [`TcpStream`] should be shut down.
|
||||
///
|
||||
/// See `Shutdown::Read` and `Shutdown::Write` for more information.
|
||||
/// See [`Shutdown::Read`] and [`Shutdown::Write`] for more information.
|
||||
///
|
||||
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
|
||||
/// [`Shutdown::Read`]: #variant.Read
|
||||
/// [`Shutdown::Write`]: #variant.Write
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
Both,
|
||||
}
|
||||
|
||||
@ -368,7 +368,19 @@ impl FromStr for SocketAddr {
|
||||
}
|
||||
}
|
||||
|
||||
/// An error returned when parsing an IP address or a socket address.
|
||||
/// An error which can be returned when parsing an IP address or a socket address.
|
||||
///
|
||||
/// This error is used as the error type for the [`FromStr`] implementation for
|
||||
/// [`IpAddr`], [`Ipv4Addr`], [`Ipv6Addr`], [`SocketAddr`], [`SocketAddrV4`], and
|
||||
/// [`SocketAddrV6`].
|
||||
///
|
||||
/// [`FromStr`]: ../../std/str/trait.FromStr.html
|
||||
/// [`IpAddr`]: ../../std/net/enum.IpAddr.html
|
||||
/// [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html
|
||||
/// [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html
|
||||
/// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
|
||||
/// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
|
||||
/// [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct AddrParseError(());
|
||||
|
||||
@ -17,10 +17,25 @@ use sys_common::net as net_imp;
|
||||
use sys_common::{AsInner, FromInner, IntoInner};
|
||||
use time::Duration;
|
||||
|
||||
/// A structure which represents a TCP stream between a local socket and a
|
||||
/// remote socket.
|
||||
/// A TCP stream between a local and a remote socket.
|
||||
///
|
||||
/// The socket will be closed when the value is dropped.
|
||||
/// After creating a `TcpStream` by either [`connect`]ing to a remote host or
|
||||
/// [`accept`]ing a connection on a [`TcpListener`], data can be transmitted
|
||||
/// by [reading] and [writing] to it.
|
||||
///
|
||||
/// The connection will be closed when the value is dropped. The reading and writing
|
||||
/// portions of the connection can also be shut down individually with the [`shutdown`]
|
||||
/// method.
|
||||
///
|
||||
/// The Transmission Control Protocol is specified in [IETF RFC 793].
|
||||
///
|
||||
/// [`accept`]: ../../std/net/struct.TcpListener.html#method.accept
|
||||
/// [`connect`]: #method.connect
|
||||
/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
|
||||
/// [reading]: ../../std/io/trait.Read.html
|
||||
/// [`shutdown`]: #method.shutdown
|
||||
/// [`TcpListener`]: ../../std/net/struct.TcpListener.html
|
||||
/// [writing]: ../../std/io/trait.Write.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -39,7 +54,21 @@ use time::Duration;
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub struct TcpStream(net_imp::TcpStream);
|
||||
|
||||
/// A structure representing a socket server.
|
||||
/// A TCP socket server, listening for connections.
|
||||
///
|
||||
/// After creating a `TcpListener` by [`bind`]ing it to a socket address, it listens
|
||||
/// for incoming TCP connections. These can be accepted by calling [`accept`] or by
|
||||
/// iterating over the [`Incoming`] iterator returned by [`incoming`].
|
||||
///
|
||||
/// The socket will be closed when the value is dropped.
|
||||
///
|
||||
/// The Transmission Control Protocol is specified in [IETF RFC 793].
|
||||
///
|
||||
/// [`accept`]: #method.accept
|
||||
/// [`bind`]: #method.bind
|
||||
/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
|
||||
/// [`Incoming`]: ../../std/net/struct.Incoming.html
|
||||
/// [`incoming`]: #method.incoming
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -65,16 +94,14 @@ pub struct TcpStream(net_imp::TcpStream);
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
pub struct TcpListener(net_imp::TcpListener);
|
||||
|
||||
/// An infinite iterator over the connections from a `TcpListener`.
|
||||
///
|
||||
/// This iterator will infinitely yield [`Some`] of the accepted connections. It
|
||||
/// is equivalent to calling `accept` in a loop.
|
||||
/// An iterator that infinitely [`accept`]s connections on a [`TcpListener`].
|
||||
///
|
||||
/// This `struct` is created by the [`incoming`] method on [`TcpListener`].
|
||||
/// See its documentation for more.
|
||||
///
|
||||
/// [`Some`]: ../../std/option/enum.Option.html#variant.Some
|
||||
/// [`incoming`]: struct.TcpListener.html#method.incoming
|
||||
/// [`TcpListener`]: struct.TcpListener.html
|
||||
/// [`accept`]: ../../std/net/struct.TcpListener.html#method.accept
|
||||
/// [`incoming`]: ../../std/net/struct.TcpListener.html#method.incoming
|
||||
/// [`TcpListener`]: ../../std/net/struct.TcpListener.html
|
||||
#[stable(feature = "rust1", since = "1.0.0")]
|
||||
#[derive(Debug)]
|
||||
pub struct Incoming<'a> { listener: &'a TcpListener }
|
||||
@ -83,11 +110,15 @@ impl TcpStream {
|
||||
/// Opens a TCP connection to a remote host.
|
||||
///
|
||||
/// `addr` is an address of the remote host. Anything which implements
|
||||
/// `ToSocketAddrs` trait can be supplied for the address; see this trait
|
||||
/// [`ToSocketAddrs`] trait can be supplied for the address; see this trait
|
||||
/// documentation for concrete examples.
|
||||
/// In case `ToSocketAddrs::to_socket_addrs()` returns more than one entry,
|
||||
/// In case [`ToSocketAddrs::to_socket_addrs()`] returns more than one entry,
|
||||
/// then the first valid and reachable address is used.
|
||||
///
|
||||
/// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
|
||||
/// [`ToSocketAddrs::to_socket_addrs()`]:
|
||||
/// ../../std/net/trait.ToSocketAddrs.html#tymethod.to_socket_addrs
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```no_run
|
||||
@ -494,11 +525,14 @@ impl TcpListener {
|
||||
///
|
||||
/// Binding with a port number of 0 will request that the OS assigns a port
|
||||
/// to this listener. The port allocated can be queried via the
|
||||
/// `local_addr` method.
|
||||
/// [`local_addr`] method.
|
||||
///
|
||||
/// The address type can be any implementor of `ToSocketAddrs` trait. See
|
||||
/// The address type can be any implementor of [`ToSocketAddrs`] trait. See
|
||||
/// its documentation for concrete examples.
|
||||
///
|
||||
/// [`local_addr`]: #method.local_addr
|
||||
/// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```no_run
|
||||
@ -529,10 +563,12 @@ impl TcpListener {
|
||||
|
||||
/// Creates a new independently owned handle to the underlying socket.
|
||||
///
|
||||
/// The returned `TcpListener` is a reference to the same socket that this
|
||||
/// The returned [`TcpListener`] is a reference to the same socket that this
|
||||
/// object references. Both handles can be used to accept incoming
|
||||
/// connections and options set on one listener will affect the other.
|
||||
///
|
||||
/// [`TcpListener`]: ../../std/net/struct.TcpListener.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```no_run
|
||||
@ -549,9 +585,11 @@ impl TcpListener {
|
||||
/// Accept a new incoming connection from this listener.
|
||||
///
|
||||
/// This function will block the calling thread until a new TCP connection
|
||||
/// is established. When established, the corresponding `TcpStream` and the
|
||||
/// is established. When established, the corresponding [`TcpStream`] and the
|
||||
/// remote peer's address will be returned.
|
||||
///
|
||||
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```no_run
|
||||
@ -572,10 +610,12 @@ impl TcpListener {
|
||||
/// listener.
|
||||
///
|
||||
/// The returned iterator will never return [`None`] and will also not yield
|
||||
/// the peer's [`SocketAddr`] structure.
|
||||
/// the peer's [`SocketAddr`] structure. Iterating over it is equivalent to
|
||||
/// calling [`accept`] in a loop.
|
||||
///
|
||||
/// [`None`]: ../../std/option/enum.Option.html#variant.None
|
||||
/// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
|
||||
/// [`accept`]: #method.accept
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
||||
@ -15,11 +15,29 @@ use sys_common::net as net_imp;
|
||||
use sys_common::{AsInner, FromInner, IntoInner};
|
||||
use time::Duration;
|
||||
|
||||
/// A User Datagram Protocol socket.
|
||||
/// A UDP socket.
|
||||
///
|
||||
/// This is an implementation of a bound UDP socket. This supports both IPv4 and
|
||||
/// IPv6 addresses, and there is no corresponding notion of a server because UDP
|
||||
/// is a datagram protocol.
|
||||
/// After creating a `UdpSocket` by [`bind`]ing it to a socket address, data can be
|
||||
/// [sent to] and [received from] any other socket address.
|
||||
///
|
||||
/// Although UDP is a connectionless protocol, this implementation provides an interface
|
||||
/// to set an address where data should be sent and received from. After setting a remote
|
||||
/// address with [`connect`], data can be sent to and received from that address with
|
||||
/// [`send`] and [`recv`].
|
||||
///
|
||||
/// As stated in the User Datagram Protocol's specification in [IETF RFC 768], UDP is
|
||||
/// an unordered, unreliable protocol; refer to [`TcpListener`] and [`TcpStream`] for TCP
|
||||
/// primitives.
|
||||
///
|
||||
/// [`bind`]: #method.bind
|
||||
/// [`connect`]: #method.connect
|
||||
/// [IETF RFC 768]: https://tools.ietf.org/html/rfc768
|
||||
/// [`recv`]: #method.recv
|
||||
/// [received from]: #method.recv_from
|
||||
/// [`send`]: #method.send
|
||||
/// [sent to]: #method.send_to
|
||||
/// [`TcpListener`]: ../../std/net/struct.TcpListener.html
|
||||
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
@ -582,9 +600,11 @@ impl UdpSocket {
|
||||
/// Receives data on the socket from the remote address to which it is
|
||||
/// connected.
|
||||
///
|
||||
/// The `connect` method will connect this socket to a remote address. This
|
||||
/// The [`connect`] method will connect this socket to a remote address. This
|
||||
/// method will fail if the socket is not connected.
|
||||
///
|
||||
/// [`connect`]: #method.connect
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ```no_run
|
||||
|
||||
Loading…
Reference in New Issue
Block a user