Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Net examples #37806

Merged
merged 2 commits into from
Nov 17, 2016
Merged

Net examples #37806

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
27acb5c
Add missing urls and improve internal doc representation
GuillaumeGomez Nov 16, 2016
976bfc0
Add examples for Ipv4Addr
GuillaumeGomez Nov 16, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 142 additions & 5 deletions src/libstd/net/ip.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,14 @@ impl Ipv4Addr {
/// Creates a new IPv4 address from four eight-bit octets.
///
/// The result will represent the IP address `a`.`b`.`c`.`d`.
///
/// # Examples
///
/// ```
/// use std::net::Ipv4Addr;
///
/// let addr = Ipv4Addr::new(127, 0, 0, 1);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn new(a: u8, b: u8, c: u8, d: u8) -> Ipv4Addr {
Ipv4Addr {
Expand All @@ -167,6 +175,15 @@ impl Ipv4Addr {
}

/// Returns the four eight-bit integers that make up this address.
///
/// # Examples
///
/// ```
/// use std::net::Ipv4Addr;
///
/// let addr = Ipv4Addr::new(127, 0, 0, 1);
/// assert_eq!(addr.octets(), [127, 0, 0, 1]);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn octets(&self) -> [u8; 4] {
let bits = ntoh(self.inner.s_addr);
Expand All @@ -176,8 +193,18 @@ impl Ipv4Addr {
/// 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]
/// W. Richard Stevens, p. 891; see also [ip7].
///
/// [ip7]: http://man7.org/linux/man-pages/man7/ip.7.html
///
/// # Examples
///
/// ```
/// use std::net::Ipv4Addr;
///
/// assert_eq!(Ipv4Addr::new(0, 0, 0, 0).is_unspecified(), true);
/// assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_unspecified(), false);
/// ```
#[stable(feature = "ip_shared", since = "1.12.0")]
pub fn is_unspecified(&self) -> bool {
self.inner.s_addr == 0
Expand All @@ -186,7 +213,17 @@ impl Ipv4Addr {
/// Returns true if this is a loopback address (127.0.0.0/8).
///
/// This property is defined by [RFC 1122].
///
/// [RFC 1122]: https://tools.ietf.org/html/rfc1122
///
/// # Examples
///
/// ```
/// use std::net::Ipv4Addr;
///
/// assert_eq!(Ipv4Addr::new(127, 0, 0, 1).is_loopback(), true);
/// assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_loopback(), false);
/// ```
#[stable(since = "1.7.0", feature = "ip_17")]
pub fn is_loopback(&self) -> bool {
self.octets()[0] == 127
Expand All @@ -195,11 +232,26 @@ impl Ipv4Addr {
/// Returns true if this is a private address.
///
/// The private address ranges are defined in [RFC 1918] and include:
/// [RFC 1918]: https://tools.ietf.org/html/rfc1918
///
/// - 10.0.0.0/8
/// - 172.16.0.0/12
/// - 192.168.0.0/16
///
/// [RFC 1918]: https://tools.ietf.org/html/rfc1918
///
/// # Examples
///
/// ```
/// use std::net::Ipv4Addr;
///
/// assert_eq!(Ipv4Addr::new(10, 0, 0, 1).is_private(), true);
/// assert_eq!(Ipv4Addr::new(10, 10, 10, 10).is_private(), true);
/// assert_eq!(Ipv4Addr::new(172, 16, 10, 10).is_private(), true);
/// assert_eq!(Ipv4Addr::new(172, 29, 45, 14).is_private(), true);
/// assert_eq!(Ipv4Addr::new(172, 32, 0, 2).is_private(), false);
/// assert_eq!(Ipv4Addr::new(192, 168, 0, 2).is_private(), true);
/// assert_eq!(Ipv4Addr::new(192, 169, 0, 2).is_private(), false);
/// ```
#[stable(since = "1.7.0", feature = "ip_17")]
pub fn is_private(&self) -> bool {
match (self.octets()[0], self.octets()[1]) {
Expand All @@ -213,15 +265,25 @@ impl Ipv4Addr {
/// Returns true if the address is link-local (169.254.0.0/16).
///
/// This property is defined by [RFC 3927].
///
/// [RFC 3927]: https://tools.ietf.org/html/rfc3927
///
/// # Examples
///
/// ```
/// use std::net::Ipv4Addr;
///
/// assert_eq!(Ipv4Addr::new(169, 254, 0, 0).is_link_local(), true);
/// assert_eq!(Ipv4Addr::new(169, 254, 10, 65).is_link_local(), true);
/// assert_eq!(Ipv4Addr::new(16, 89, 10, 65).is_link_local(), false);
/// ```
#[stable(since = "1.7.0", feature = "ip_17")]
pub fn is_link_local(&self) -> bool {
self.octets()[0] == 169 && self.octets()[1] == 254
}

/// Returns true if the address appears to be globally routable.
/// See [iana-ipv4-special-registry][ipv4-sr].
/// [ipv4-sr]: http://goo.gl/RaZ7lg
///
/// The following return false:
///
Expand All @@ -231,6 +293,24 @@ impl Ipv4Addr {
/// - the broadcast address (255.255.255.255/32)
/// - test addresses used for documentation (192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24)
/// - the unspecified address (0.0.0.0)
///
/// [ipv4-sr]: http://goo.gl/RaZ7lg
///
/// # Examples
///
/// ```
/// #![feature(ip)]
///
/// use std::net::Ipv4Addr;
///
/// fn main() {
/// assert_eq!(Ipv4Addr::new(10, 254, 0, 0).is_global(), false);
/// assert_eq!(Ipv4Addr::new(192, 168, 10, 65).is_global(), false);
/// assert_eq!(Ipv4Addr::new(172, 16, 10, 65).is_global(), false);
/// assert_eq!(Ipv4Addr::new(0, 0, 0, 0).is_global(), false);
/// assert_eq!(Ipv4Addr::new(80, 9, 12, 3).is_global(), true);
/// }
/// ```
pub fn is_global(&self) -> bool {
!self.is_private() && !self.is_loopback() && !self.is_link_local() &&
!self.is_broadcast() && !self.is_documentation() && !self.is_unspecified()
Expand All @@ -240,7 +320,18 @@ impl Ipv4Addr {
///
/// Multicast addresses have a most significant octet between 224 and 239,
/// and is defined by [RFC 5771].
///
/// [RFC 5771]: https://tools.ietf.org/html/rfc5771
///
/// # Examples
///
/// ```
/// use std::net::Ipv4Addr;
///
/// assert_eq!(Ipv4Addr::new(224, 254, 0, 0).is_multicast(), true);
/// assert_eq!(Ipv4Addr::new(236, 168, 10, 65).is_multicast(), true);
/// assert_eq!(Ipv4Addr::new(172, 16, 10, 65).is_multicast(), false);
/// ```
#[stable(since = "1.7.0", feature = "ip_17")]
pub fn is_multicast(&self) -> bool {
self.octets()[0] >= 224 && self.octets()[0] <= 239
Expand All @@ -249,7 +340,17 @@ impl Ipv4Addr {
/// 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].
///
/// [RFC 919]: https://tools.ietf.org/html/rfc919
///
/// # Examples
///
/// ```
/// use std::net::Ipv4Addr;
///
/// assert_eq!(Ipv4Addr::new(255, 255, 255, 255).is_broadcast(), true);
/// assert_eq!(Ipv4Addr::new(236, 168, 10, 65).is_broadcast(), false);
/// ```
#[stable(since = "1.7.0", feature = "ip_17")]
pub fn is_broadcast(&self) -> bool {
self.octets()[0] == 255 && self.octets()[1] == 255 &&
Expand All @@ -259,11 +360,23 @@ impl Ipv4Addr {
/// Returns true if this address is in a range designated for documentation.
///
/// This is defined in [RFC 5737]:
/// [RFC 5737]: https://tools.ietf.org/html/rfc5737
///
/// - 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
///
/// # Examples
///
/// ```
/// use std::net::Ipv4Addr;
///
/// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).is_documentation(), true);
/// assert_eq!(Ipv4Addr::new(198, 51, 100, 65).is_documentation(), true);
/// assert_eq!(Ipv4Addr::new(203, 0, 113, 6).is_documentation(), true);
/// assert_eq!(Ipv4Addr::new(193, 34, 17, 19).is_documentation(), false);
/// ```
#[stable(since = "1.7.0", feature = "ip_17")]
pub fn is_documentation(&self) -> bool {
match(self.octets()[0], self.octets()[1], self.octets()[2], self.octets()[3]) {
Expand All @@ -277,6 +390,15 @@ impl Ipv4Addr {
/// Converts this address to an IPv4-compatible IPv6 address.
///
/// a.b.c.d becomes ::a.b.c.d
///
/// # Examples
///
/// ```
/// use std::net::{Ipv4Addr, Ipv6Addr};
///
/// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).to_ipv6_compatible(),
/// Ipv6Addr::new(0, 0, 0, 0, 0, 0, 49152, 767));
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn to_ipv6_compatible(&self) -> Ipv6Addr {
Ipv6Addr::new(0, 0, 0, 0, 0, 0,
Expand All @@ -287,6 +409,15 @@ impl Ipv4Addr {
/// Converts this address to an IPv4-mapped IPv6 address.
///
/// a.b.c.d becomes ::ffff:a.b.c.d
///
/// # Examples
///
/// ```
/// use std::net::{Ipv4Addr, Ipv6Addr};
///
/// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).to_ipv6_mapped(),
/// Ipv6Addr::new(0, 0, 0, 0, 0, 65535, 49152, 767));
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn to_ipv6_mapped(&self) -> Ipv6Addr {
Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff,
Expand Down Expand Up @@ -425,6 +556,7 @@ impl Ipv6Addr {
/// Returns true for the special 'unspecified' address (::).
///
/// This property is defined in [RFC 4291].
///
/// [RFC 4291]: https://tools.ietf.org/html/rfc4291
#[stable(since = "1.7.0", feature = "ip_17")]
pub fn is_unspecified(&self) -> bool {
Expand All @@ -434,6 +566,7 @@ impl Ipv6Addr {
/// Returns true if this is a loopback address (::1).
///
/// This property is defined in [RFC 4291].
///
/// [RFC 4291]: https://tools.ietf.org/html/rfc4291
#[stable(since = "1.7.0", feature = "ip_17")]
pub fn is_loopback(&self) -> bool {
Expand All @@ -458,6 +591,7 @@ impl Ipv6Addr {
/// Returns true if this is a unique local address (fc00::/7).
///
/// This property is defined in [RFC 4193].
///
/// [RFC 4193]: https://tools.ietf.org/html/rfc4193
pub fn is_unique_local(&self) -> bool {
(self.segments()[0] & 0xfe00) == 0xfc00
Expand All @@ -466,6 +600,7 @@ impl Ipv6Addr {
/// Returns true if the address is unicast and link-local (fe80::/10).
///
/// This property is defined in [RFC 4291].
///
/// [RFC 4291]: https://tools.ietf.org/html/rfc4291
pub fn is_unicast_link_local(&self) -> bool {
(self.segments()[0] & 0xffc0) == 0xfe80
Expand All @@ -481,6 +616,7 @@ impl Ipv6Addr {
/// (2001:db8::/32).
///
/// This property is defined in [RFC 3849].
///
/// [RFC 3849]: https://tools.ietf.org/html/rfc3849
pub fn is_documentation(&self) -> bool {
(self.segments()[0] == 0x2001) && (self.segments()[1] == 0xdb8)
Expand Down Expand Up @@ -524,6 +660,7 @@ impl Ipv6Addr {
/// Returns true if this is a multicast address (ff00::/8).
///
/// This property is defined by [RFC 4291].
///
/// [RFC 4291]: https://tools.ietf.org/html/rfc4291
#[stable(since = "1.7.0", feature = "ip_17")]
pub fn is_multicast(&self) -> bool {
Expand Down
3 changes: 2 additions & 1 deletion src/libstd/net/tcp.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,11 +67,12 @@ 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
/// This iterator will infinitely yield [`Some`] of the accepted connections. It
/// is equivalent to calling `accept` in a loop.
///
/// This `struct` is created by the [`incoming`] method on [`TcpListener`].
///
/// [`Some`]: ../../std/option/enum.Option.html#variant.Some
/// [`incoming`]: struct.TcpListener.html#method.incoming
/// [`TcpListener`]: struct.TcpListener.html
#[stable(feature = "rust1", since = "1.0.0")]
Expand Down