From 27151017e987044a35ae45f8c9bd8530af9e5f47 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 21 Mar 2017 16:23:27 +0100 Subject: Add missing urls in ptr docs --- src/libstd/primitive_docs.rs | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs index 7d6d16f4748..ba14a3d6b47 100644 --- a/src/libstd/primitive_docs.rs +++ b/src/libstd/primitive_docs.rs @@ -183,9 +183,9 @@ mod prim_unit { } /// Working with raw pointers in Rust is uncommon, /// typically limited to a few patterns. /// -/// Use the `null` function to create null pointers, and the `is_null` method +/// Use the [`null`] function to create null pointers, and the [`is_null`] method /// of the `*const T` type to check for null. The `*const T` type also defines -/// the `offset` method, for pointer math. +/// the [`offset`] method, for pointer math. /// /// # Common ways to create raw pointers /// @@ -213,7 +213,7 @@ mod prim_unit { } /// /// ## 2. Consume a box (`Box`). /// -/// The `into_raw` function consumes a box and returns +/// The [`into_raw`] function consumes a box and returns /// the raw pointer. It doesn't destroy `T` or deallocate any memory. /// /// ``` @@ -227,7 +227,7 @@ mod prim_unit { } /// } /// ``` /// -/// Note that here the call to `drop` is for clarity - it indicates +/// Note that here the call to [`drop`] is for clarity - it indicates /// that we are done with the given value and it should be destroyed. /// /// ## 3. Get it from C. @@ -255,6 +255,11 @@ mod prim_unit { } /// /// *[See also the `std::ptr` module](ptr/index.html).* /// +/// [`null`]: ../std/ptr/fn.null.html +/// [`is_null`]: ../std/primitive.pointer.html#method.is_null +/// [`offset`]: ../std/primitive.pointer.html#method.offset +/// [`into_raw`]: ../std/boxed/struct.Box.html#method.into_raw +/// [`drop`]: ../std/mem/fn.drop.html #[stable(feature = "rust1", since = "1.0.0")] mod prim_pointer { } -- cgit 1.4.1-3-g733a5 From a033f1a8eeb55bdf93749a5d0c4d803bbe0d8dfc Mon Sep 17 00:00:00 2001 From: Josh Stone Date: Wed, 22 Mar 2017 10:32:38 -0700 Subject: Simplify hash table drops This replaces the `std::collections::hash::table::RevMoveBuckets` iterator with a simpler `while` loop. This iterator was only used for dropping the remaining elements of a `RawTable`, so instead we can just loop through directly and drop them in place. This should be functionally equivalent to the former code, but a little easier to read. I was hoping it might have some performance benefit too, but it seems the optimizer was already good enough to see through the iterator -- the generated code is nearly the same. Maybe it will still help if an element type has more complicated drop code. --- src/libstd/collections/hash/table.rs | 65 ++++++++++-------------------------- 1 file changed, 18 insertions(+), 47 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/collections/hash/table.rs b/src/libstd/collections/hash/table.rs index 211605bef1e..da5fb1a4733 100644 --- a/src/libstd/collections/hash/table.rs +++ b/src/libstd/collections/hash/table.rs @@ -896,15 +896,23 @@ impl RawTable { } } - /// Returns an iterator that copies out each entry. Used while the table - /// is being dropped. - unsafe fn rev_move_buckets(&mut self) -> RevMoveBuckets { - let raw_bucket = self.first_bucket_raw(); - RevMoveBuckets { - raw: raw_bucket.offset(self.capacity as isize), - hashes_end: raw_bucket.hash, - elems_left: self.size, - marker: marker::PhantomData, + /// Drops buckets in reverse order. It leaves the table in an inconsistent + /// state and should only be used for dropping the table's remaining + /// entries. It's used in the implementation of Drop. + unsafe fn rev_drop_buckets(&mut self) { + let first_raw = self.first_bucket_raw(); + let mut raw = first_raw.offset(self.capacity as isize); + let mut elems_left = self.size; + + while elems_left != 0 { + debug_assert!(raw.hash != first_raw.hash); + + raw = raw.offset(-1); + + if *raw.hash != EMPTY_BUCKET { + elems_left -= 1; + ptr::drop_in_place(raw.pair as *mut (K, V)); + } } } @@ -964,43 +972,6 @@ impl<'a, K, V> Iterator for RawBuckets<'a, K, V> { } } -/// An iterator that moves out buckets in reverse order. It leaves the table -/// in an inconsistent state and should only be used for dropping -/// the table's remaining entries. It's used in the implementation of Drop. -struct RevMoveBuckets<'a, K, V> { - raw: RawBucket, - hashes_end: *mut HashUint, - elems_left: usize, - - // As above, `&'a (K,V)` would seem better, but we often use - // 'static for the lifetime, and this is not a publicly exposed - // type. - marker: marker::PhantomData<&'a ()>, -} - -impl<'a, K, V> Iterator for RevMoveBuckets<'a, K, V> { - type Item = (K, V); - - fn next(&mut self) -> Option<(K, V)> { - if self.elems_left == 0 { - return None; - } - - loop { - debug_assert!(self.raw.hash != self.hashes_end); - - unsafe { - self.raw = self.raw.offset(-1); - - if *self.raw.hash != EMPTY_BUCKET { - self.elems_left -= 1; - return Some(ptr::read(self.raw.pair)); - } - } - } - } -} - /// Iterator over shared references to entries in a table. pub struct Iter<'a, K: 'a, V: 'a> { iter: RawBuckets<'a, K, V>, @@ -1227,7 +1198,7 @@ unsafe impl<#[may_dangle] K, #[may_dangle] V> Drop for RawTable { unsafe { if needs_drop::<(K, V)>() { // avoid linear runtime for types that don't need drop - for _ in self.rev_move_buckets() {} + self.rev_drop_buckets(); } } -- cgit 1.4.1-3-g733a5 From 5ca8a735ca36219abbf601624606c41148b95210 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Mon, 13 Mar 2017 22:27:12 -0700 Subject: std: Don't cache stdio handles on Windows This alters the stdio code on Windows to always call `GetStdHandle` whenever the stdio read/write functions are called as this allows us to track changes to the value over time (such as if a process calls `SetStdHandle` while it's running). Closes #40490 --- src/libstd/sys/windows/process.rs | 9 ++- src/libstd/sys/windows/stdio.rs | 92 ++++++++++++----------------- src/test/run-pass-fulldeps/switch-stdout.rs | 64 ++++++++++++++++++++ 3 files changed, 110 insertions(+), 55 deletions(-) create mode 100644 src/test/run-pass-fulldeps/switch-stdout.rs (limited to 'src/libstd') diff --git a/src/libstd/sys/windows/process.rs b/src/libstd/sys/windows/process.rs index 1afb3728c9d..dfbc1b581ee 100644 --- a/src/libstd/sys/windows/process.rs +++ b/src/libstd/sys/windows/process.rs @@ -257,8 +257,13 @@ impl Stdio { // INVALID_HANDLE_VALUE. Stdio::Inherit => { match stdio::get(stdio_id) { - Ok(io) => io.handle().duplicate(0, true, - c::DUPLICATE_SAME_ACCESS), + Ok(io) => { + let io = Handle::new(io.handle()); + let ret = io.duplicate(0, true, + c::DUPLICATE_SAME_ACCESS); + io.into_raw(); + return ret + } Err(..) => Ok(Handle::new(c::INVALID_HANDLE_VALUE)), } } diff --git a/src/libstd/sys/windows/stdio.rs b/src/libstd/sys/windows/stdio.rs index b1a57c349fb..d72e4b4438b 100644 --- a/src/libstd/sys/windows/stdio.rs +++ b/src/libstd/sys/windows/stdio.rs @@ -22,42 +22,43 @@ use sys::cvt; use sys::handle::Handle; use sys_common::io::read_to_end_uninitialized; -pub struct NoClose(Option); - pub enum Output { - Console(NoClose), - Pipe(NoClose), + Console(c::HANDLE), + Pipe(c::HANDLE), } pub struct Stdin { - handle: Output, utf8: Mutex>>, } -pub struct Stdout(Output); -pub struct Stderr(Output); +pub struct Stdout; +pub struct Stderr; pub fn get(handle: c::DWORD) -> io::Result { let handle = unsafe { c::GetStdHandle(handle) }; if handle == c::INVALID_HANDLE_VALUE { Err(io::Error::last_os_error()) } else if handle.is_null() { - Err(io::Error::new(io::ErrorKind::Other, - "no stdio handle available for this process")) + Err(io::Error::from_raw_os_error(c::ERROR_INVALID_HANDLE as i32)) } else { - let ret = NoClose::new(handle); let mut out = 0; match unsafe { c::GetConsoleMode(handle, &mut out) } { - 0 => Ok(Output::Pipe(ret)), - _ => Ok(Output::Console(ret)), + 0 => Ok(Output::Pipe(handle)), + _ => Ok(Output::Console(handle)), } } } -fn write(out: &Output, data: &[u8]) -> io::Result { - let handle = match *out { - Output::Console(ref c) => c.get().raw(), - Output::Pipe(ref p) => return p.get().write(data), +fn write(handle: c::DWORD, data: &[u8]) -> io::Result { + let handle = match try!(get(handle)) { + Output::Console(c) => c, + Output::Pipe(p) => { + let handle = Handle::new(p); + let ret = handle.write(data); + handle.into_raw(); + return ret + } }; + // As with stdin on windows, stdout often can't handle writes of large // sizes. For an example, see #14940. For this reason, don't try to // write the entire output buffer on windows. @@ -93,18 +94,20 @@ fn write(out: &Output, data: &[u8]) -> io::Result { impl Stdin { pub fn new() -> io::Result { - get(c::STD_INPUT_HANDLE).map(|handle| { - Stdin { - handle: handle, - utf8: Mutex::new(Cursor::new(Vec::new())), - } + Ok(Stdin { + utf8: Mutex::new(Cursor::new(Vec::new())), }) } pub fn read(&self, buf: &mut [u8]) -> io::Result { - let handle = match self.handle { - Output::Console(ref c) => c.get().raw(), - Output::Pipe(ref p) => return p.get().read(buf), + let handle = match try!(get(c::STD_INPUT_HANDLE)) { + Output::Console(c) => c, + Output::Pipe(p) => { + let handle = Handle::new(p); + let ret = handle.read(buf); + handle.into_raw(); + return ret + } }; let mut utf8 = self.utf8.lock().unwrap(); // Read more if the buffer is empty @@ -125,11 +128,9 @@ impl Stdin { Ok(utf8) => utf8.into_bytes(), Err(..) => return Err(invalid_encoding()), }; - if let Output::Console(_) = self.handle { - if let Some(&last_byte) = data.last() { - if last_byte == CTRL_Z { - data.pop(); - } + if let Some(&last_byte) = data.last() { + if last_byte == CTRL_Z { + data.pop(); } } *utf8 = Cursor::new(data); @@ -158,11 +159,11 @@ impl<'a> Read for &'a Stdin { impl Stdout { pub fn new() -> io::Result { - get(c::STD_OUTPUT_HANDLE).map(Stdout) + Ok(Stdout) } pub fn write(&self, data: &[u8]) -> io::Result { - write(&self.0, data) + write(c::STD_OUTPUT_HANDLE, data) } pub fn flush(&self) -> io::Result<()> { @@ -172,11 +173,11 @@ impl Stdout { impl Stderr { pub fn new() -> io::Result { - get(c::STD_ERROR_HANDLE).map(Stderr) + Ok(Stderr) } pub fn write(&self, data: &[u8]) -> io::Result { - write(&self.0, data) + write(c::STD_ERROR_HANDLE, data) } pub fn flush(&self) -> io::Result<()> { @@ -197,27 +198,12 @@ impl io::Write for Stderr { } } -impl NoClose { - fn new(handle: c::HANDLE) -> NoClose { - NoClose(Some(Handle::new(handle))) - } - - fn get(&self) -> &Handle { self.0.as_ref().unwrap() } -} - -impl Drop for NoClose { - fn drop(&mut self) { - self.0.take().unwrap().into_raw(); - } -} - impl Output { - pub fn handle(&self) -> &Handle { - let nc = match *self { - Output::Console(ref c) => c, - Output::Pipe(ref c) => c, - }; - nc.0.as_ref().unwrap() + pub fn handle(&self) -> c::HANDLE { + match *self { + Output::Console(c) => c, + Output::Pipe(c) => c, + } } } diff --git a/src/test/run-pass-fulldeps/switch-stdout.rs b/src/test/run-pass-fulldeps/switch-stdout.rs new file mode 100644 index 00000000000..4542e27545a --- /dev/null +++ b/src/test/run-pass-fulldeps/switch-stdout.rs @@ -0,0 +1,64 @@ +// Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +#![feature(rustc_private)] + +extern crate rustc_back; + +use std::fs::File; +use std::io::{Read, Write}; + +use rustc_back::tempdir::TempDir; + +#[cfg(unix)] +fn switch_stdout_to(file: File) { + use std::os::unix::prelude::*; + + extern { + fn dup2(old: i32, new: i32) -> i32; + } + + unsafe { + assert_eq!(dup2(file.as_raw_fd(), 1), 1); + } +} + +#[cfg(windows)] +fn switch_stdout_to(file: File) { + use std::os::windows::prelude::*; + + extern "system" { + fn SetStdHandle(nStdHandle: u32, handle: *mut u8) -> i32; + } + + const STD_OUTPUT_HANDLE: u32 = (-11i32) as u32; + + unsafe { + let rc = SetStdHandle(STD_OUTPUT_HANDLE, + file.into_raw_handle() as *mut _); + assert!(rc != 0); + } +} + +fn main() { + let td = TempDir::new("foo").unwrap(); + let path = td.path().join("bar"); + let f = File::create(&path).unwrap(); + + println!("foo"); + std::io::stdout().flush().unwrap(); + switch_stdout_to(f); + println!("bar"); + std::io::stdout().flush().unwrap(); + + let mut contents = String::new(); + File::open(&path).unwrap().read_to_string(&mut contents).unwrap(); + assert_eq!(contents, "bar\n"); +} -- cgit 1.4.1-3-g733a5 From 4dc122580714a5f8859e993bf56a7228b0bcd7c1 Mon Sep 17 00:00:00 2001 From: Nick Sweeting Date: Thu, 23 Mar 2017 13:17:21 -0400 Subject: Add helpful hint on io function for beginners --- src/libstd/io/mod.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 850885a8c0f..dda9d6bca79 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -144,6 +144,16 @@ //! # Ok(()) //! # } //! ``` +//! Note that you cannot use the `?` operator in functions that do not return a `Result` (e.g. `main()`). +//! Instead, you can `match` on the return value to catch any possible errors: +//! +//! ``` +//! let mut input = String::new(); +//! match io::stdin().read_line(&mut input) { +//! Err(why) => panic!("Failed to read input: {}", why.description()), +//! Ok(_) => println!("You typed: {}", input.trim()), +//! } +//! ``` //! //! And a very common source of output is standard output: //! -- cgit 1.4.1-3-g733a5 From 53d5082a2d08060ebca869cb8ee97c3ed3cf4ce9 Mon Sep 17 00:00:00 2001 From: Nick Sweeting Date: Thu, 23 Mar 2017 13:42:39 -0400 Subject: requested changes --- src/libstd/io/mod.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index dda9d6bca79..60b211a746f 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -144,7 +144,8 @@ //! # Ok(()) //! # } //! ``` -//! Note that you cannot use the `?` operator in functions that do not return a `Result` (e.g. `main()`). +//! +//! Note that you cannot use the `?` operator in functions that do not return a `Result` (e.g. `main`). //! Instead, you can `match` on the return value to catch any possible errors: //! //! ``` -- cgit 1.4.1-3-g733a5 From 04fbec1a0cb7467834bd264b80350b1cade8b4ca Mon Sep 17 00:00:00 2001 From: Nick Sweeting Date: Thu, 23 Mar 2017 13:43:09 -0400 Subject: newline for breathing room --- src/libstd/io/mod.rs | 1 + 1 file changed, 1 insertion(+) (limited to 'src/libstd') diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 60b211a746f..773b0964b42 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -150,6 +150,7 @@ //! //! ``` //! let mut input = String::new(); +//! //! match io::stdin().read_line(&mut input) { //! Err(why) => panic!("Failed to read input: {}", why.description()), //! Ok(_) => println!("You typed: {}", input.trim()), -- cgit 1.4.1-3-g733a5 From 8a91e4d1238b40200724826cc7ef3f7893c6152b Mon Sep 17 00:00:00 2001 From: Stepan Koltsov Date: Fri, 24 Mar 2017 05:05:34 +0300 Subject: Document Cursor::new position is 0 ... even if contained `Vec` is not empty. E. g. for ``` let v = vec![10u8, 20]; let mut c = io::Cursor::new(v); c.write_all(b"aaaa").unwrap(); println!("{:?}", c.into_inner()); ``` result is ``` [97, 97, 97, 97] ``` and not ``` [10, 20, 97, 97, 97, 97] ``` --- src/libstd/io/cursor.rs | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/io/cursor.rs b/src/libstd/io/cursor.rs index 60767ea4786..53347eb14db 100644 --- a/src/libstd/io/cursor.rs +++ b/src/libstd/io/cursor.rs @@ -89,6 +89,10 @@ pub struct Cursor { impl Cursor { /// 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 /// /// ``` -- cgit 1.4.1-3-g733a5 From 8fba638b08eb85cda1bd2a4e855f7f76727dfc52 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sat, 18 Mar 2017 10:37:52 -0400 Subject: Rewrite `io::BufRead` doc examples to better demonstrate behaviors. Prior to this commit, most of the `BufRead` examples used `StdinLock` to demonstrate how certain `BufRead` methods worked. Using `StdinLock` is not ideal since: * Relying on run-time data means we can't show concrete examples of how these methods work up-front. The user is required to run them in order to see how they behave. * If the user tries to run an example in the playpen, it won't work because the playpen doesn't support user input to stdin. --- src/libstd/io/mod.rs | 137 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 84 insertions(+), 53 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 850885a8c0f..5b628d51d15 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -1290,28 +1290,42 @@ pub trait BufRead: Read { /// If an I/O error is encountered then all bytes read so far will be /// present in `buf` and its length will have been adjusted appropriately. /// - /// # Examples - /// - /// A locked standard input implements `BufRead`. In this example, we'll - /// read from standard input until we see an `a` byte. - /// /// [`fill_buf`]: #tymethod.fill_buf /// [`ErrorKind::Interrupted`]: enum.ErrorKind.html#variant.Interrupted /// - /// ``` - /// use std::io; - /// use std::io::prelude::*; + /// # Examples /// - /// fn foo() -> io::Result<()> { - /// let stdin = io::stdin(); - /// let mut stdin = stdin.lock(); - /// let mut buffer = Vec::new(); + /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In + /// this example, we use [`Cursor`] to read all the bytes in a byte slice + /// in hyphen delimited segments: /// - /// stdin.read_until(b'a', &mut buffer)?; + /// [`Cursor`]: struct.Cursor.html /// - /// println!("{:?}", buffer); - /// # Ok(()) - /// # } + /// ``` + /// use std::io::{self, BufRead}; + /// + /// let mut cursor = io::Cursor::new(b"lorem-ipsum"); + /// let mut buf = vec![]; + /// + /// // cursor is at 'l' + /// let num_bytes = cursor.read_until(b'-', &mut buf) + /// .expect("reading from cursor won't fail"); + /// assert_eq!(num_bytes, 6); + /// assert_eq!(buf, b"lorem-"); + /// buf.clear(); + /// + /// // cursor is at 'i' + /// let num_bytes = cursor.read_until(b'-', &mut buf) + /// .expect("reading from cursor won't fail"); + /// assert_eq!(num_bytes, 5); + /// assert_eq!(buf, b"ipsum"); + /// buf.clear(); + /// + /// // cursor is at EOF + /// let num_bytes = cursor.read_until(b'-', &mut buf) + /// .expect("reading from cursor won't fail"); + /// assert_eq!(num_bytes, 0); + /// assert_eq!(buf, b""); /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn read_until(&mut self, byte: u8, buf: &mut Vec) -> Result { @@ -1337,28 +1351,36 @@ pub trait BufRead: Read { /// /// # Examples /// - /// A locked standard input implements `BufRead`. In this example, we'll - /// read all of the lines from standard input. If we were to do this in - /// an actual project, the [`lines`] method would be easier, of - /// course. + /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In + /// this example, we use [`Cursor`] to read all the lines in a byte slice: /// - /// [`lines`]: #method.lines - /// [`read_until`]: #method.read_until + /// [`Cursor`]: struct.Cursor.html /// /// ``` - /// use std::io; - /// use std::io::prelude::*; - /// - /// let stdin = io::stdin(); - /// let mut stdin = stdin.lock(); - /// let mut buffer = String::new(); - /// - /// while stdin.read_line(&mut buffer).unwrap() > 0 { - /// // work with buffer - /// println!("{:?}", buffer); - /// - /// buffer.clear(); - /// } + /// use std::io::{self, BufRead}; + /// + /// let mut cursor = io::Cursor::new(b"foo\nbar"); + /// let mut buf = String::new(); + /// + /// // cursor is at 'f' + /// let num_bytes = cursor.read_line(&mut buf) + /// .expect("reading from cursor won't fail"); + /// assert_eq!(num_bytes, 4); + /// assert_eq!(buf, "foo\n"); + /// buf.clear(); + /// + /// // cursor is at 'b' + /// let num_bytes = cursor.read_line(&mut buf) + /// .expect("reading from cursor won't fail"); + /// assert_eq!(num_bytes, 3); + /// assert_eq!(buf, "bar"); + /// buf.clear(); + /// + /// // cursor is at EOF + /// let num_bytes = cursor.read_line(&mut buf) + /// .expect("reading from cursor won't fail"); + /// assert_eq!(num_bytes, 0); + /// assert_eq!(buf, ""); /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn read_line(&mut self, buf: &mut String) -> Result { @@ -1378,24 +1400,28 @@ pub trait BufRead: Read { /// This function will yield errors whenever [`read_until`] would have /// also yielded an error. /// - /// # Examples - /// - /// A locked standard input implements `BufRead`. In this example, we'll - /// read some input from standard input, splitting on commas. - /// /// [`io::Result`]: type.Result.html /// [`Vec`]: ../vec/struct.Vec.html /// [`read_until`]: #method.read_until /// + /// # Examples + /// + /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In + /// this example, we use [`Cursor`] to iterate over all hyphen delimited + /// segments in a byte slice + /// + /// [`Cursor`]: struct.Cursor.html + /// /// ``` - /// use std::io; - /// use std::io::prelude::*; + /// use std::io::{self, BufRead}; /// - /// let stdin = io::stdin(); + /// let cursor = io::Cursor::new(b"lorem-ipsum-dolor"); /// - /// for content in stdin.lock().split(b',') { - /// println!("{:?}", content.unwrap()); - /// } + /// let mut split_iter = cursor.split(b'-').map(|l| l.unwrap()); + /// assert_eq!(split_iter.next(), Some(b"lorem".to_vec())); + /// assert_eq!(split_iter.next(), Some(b"ipsum".to_vec())); + /// assert_eq!(split_iter.next(), Some(b"dolor".to_vec())); + /// assert_eq!(split_iter.next(), None); /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn split(self, byte: u8) -> Split where Self: Sized { @@ -1413,17 +1439,22 @@ pub trait BufRead: Read { /// /// # Examples /// - /// A locked standard input implements `BufRead`: + /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In + /// this example, we use [`Cursor`] to iterate over all the lines in a byte + /// slice. + /// + /// [`Cursor`]: struct.Cursor.html /// /// ``` - /// use std::io; - /// use std::io::prelude::*; + /// use std::io::{self, BufRead}; /// - /// let stdin = io::stdin(); + /// let cursor = io::Cursor::new(b"lorem\nipsum\r\ndolor"); /// - /// for line in stdin.lock().lines() { - /// println!("{}", line.unwrap()); - /// } + /// let mut lines_iter = cursor.lines().map(|l| l.unwrap()); + /// assert_eq!(lines_iter.next(), Some(String::from("lorem"))); + /// assert_eq!(lines_iter.next(), Some(String::from("ipsum"))); + /// assert_eq!(lines_iter.next(), Some(String::from("dolor"))); + /// assert_eq!(lines_iter.next(), None); /// ``` /// /// # Errors -- cgit 1.4.1-3-g733a5 From 9b0a4a4e97c4977aae45934d2138d8db27b16843 Mon Sep 17 00:00:00 2001 From: Petr Zemek Date: Fri, 24 Mar 2017 09:42:21 +0100 Subject: Fix formatting in the docs for std::process::Command::envs(). An empty line between the "Basic usage:" text and the example is required to properly format the code. Without the empty line, the example is not formatted as code. --- src/libstd/process.rs | 1 + 1 file changed, 1 insertion(+) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 7a85e588662..b57a9883afe 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -437,6 +437,7 @@ impl Command { /// # Examples /// /// Basic usage: + /// /// ```no_run /// use std::process::{Command, Stdio}; /// use std::env; -- cgit 1.4.1-3-g733a5 From 432673a8ddbe5b62c8a15b7bc0141cf9a303866a Mon Sep 17 00:00:00 2001 From: Petr Zemek Date: Fri, 24 Mar 2017 15:47:45 +0100 Subject: Add a missing feature attribute to the example for std::process::Command::envs(). The person who originally wrote the example forgot to include this attribute. This caused Travis CI to fail on commit 9b0a4a4e97 (#40794), which just fixed formatting in the description of std::process::Command::envs(). --- src/libstd/process.rs | 2 ++ 1 file changed, 2 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index b57a9883afe..d46cf7a26da 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -439,6 +439,8 @@ impl Command { /// Basic usage: /// /// ```no_run + /// #![feature(command_envs)] + /// /// use std::process::{Command, Stdio}; /// use std::env; /// use std::collections::HashMap; -- cgit 1.4.1-3-g733a5 From a7add43389d435bda8769cb73ac6636237633836 Mon Sep 17 00:00:00 2001 From: Marco A L Barbosa Date: Thu, 16 Mar 2017 16:07:56 -0300 Subject: Fix c_char (u8 -> i8) definition for i686-linux-android --- src/libstd/os/raw.rs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/os/raw.rs b/src/libstd/os/raw.rs index 68d4ca90019..c34491941d6 100644 --- a/src/libstd/os/raw.rs +++ b/src/libstd/os/raw.rs @@ -14,22 +14,24 @@ use fmt; -#[cfg(any(target_os = "android", - target_os = "emscripten", +#[cfg(any(target_os = "emscripten", all(target_os = "linux", any(target_arch = "aarch64", target_arch = "arm", target_arch = "powerpc", target_arch = "powerpc64", target_arch = "s390x")), + all(target_os = "android", any(target_arch = "aarch64", + target_arch = "arm")), all(target_os = "fuchsia", target_arch = "aarch64")))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = u8; -#[cfg(not(any(target_os = "android", - target_os = "emscripten", +#[cfg(not(any(target_os = "emscripten", all(target_os = "linux", any(target_arch = "aarch64", target_arch = "arm", target_arch = "powerpc", target_arch = "powerpc64", target_arch = "s390x")), + all(target_os = "android", any(target_arch = "aarch64", + target_arch = "arm")), all(target_os = "fuchsia", target_arch = "aarch64"))))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = i8; #[stable(feature = "raw_os", since = "1.1.0")] pub type c_schar = i8; -- cgit 1.4.1-3-g733a5 From b45c631382a0bb831dc038973288e3f6d91cb07a Mon Sep 17 00:00:00 2001 From: Marco A L Barbosa Date: Fri, 17 Mar 2017 08:06:23 -0300 Subject: Fix libc::bind call on aarch64-linux-android --- src/libstd/sys/unix/ext/net.rs | 4 ++-- src/libstd/sys_common/net.rs | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/unix/ext/net.rs b/src/libstd/sys/unix/ext/net.rs index 55118829eee..d688f2fa504 100644 --- a/src/libstd/sys/unix/ext/net.rs +++ b/src/libstd/sys/unix/ext/net.rs @@ -641,7 +641,7 @@ impl UnixListener { let inner = Socket::new_raw(libc::AF_UNIX, libc::SOCK_STREAM)?; let (addr, len) = sockaddr_un(path)?; - cvt(libc::bind(*inner.as_inner(), &addr as *const _ as *const _, len))?; + cvt(libc::bind(*inner.as_inner(), &addr as *const _ as *const _, len as _))?; cvt(libc::listen(*inner.as_inner(), 128))?; Ok(UnixListener(inner)) @@ -920,7 +920,7 @@ impl UnixDatagram { let socket = UnixDatagram::unbound()?; let (addr, len) = sockaddr_un(path)?; - cvt(libc::bind(*socket.0.as_inner(), &addr as *const _ as *const _, len))?; + cvt(libc::bind(*socket.0.as_inner(), &addr as *const _ as *const _, len as _))?; Ok(socket) } diff --git a/src/libstd/sys_common/net.rs b/src/libstd/sys_common/net.rs index 3cdeb511945..9239c18e597 100644 --- a/src/libstd/sys_common/net.rs +++ b/src/libstd/sys_common/net.rs @@ -339,7 +339,7 @@ impl TcpListener { // Bind our new socket let (addrp, len) = addr.into_inner(); - cvt(unsafe { c::bind(*sock.as_inner(), addrp, len) })?; + cvt(unsafe { c::bind(*sock.as_inner(), addrp, len as _) })?; // Start listening cvt(unsafe { c::listen(*sock.as_inner(), 128) })?; @@ -430,7 +430,7 @@ impl UdpSocket { let sock = Socket::new(addr, c::SOCK_DGRAM)?; let (addrp, len) = addr.into_inner(); - cvt(unsafe { c::bind(*sock.as_inner(), addrp, len) })?; + cvt(unsafe { c::bind(*sock.as_inner(), addrp, len as _) })?; Ok(UdpSocket { inner: sock }) } -- cgit 1.4.1-3-g733a5 From 24be89980e2e89404075fe463edae0f5db369251 Mon Sep 17 00:00:00 2001 From: Marco A L Barbosa Date: Sat, 25 Mar 2017 17:15:26 -0300 Subject: Avoid using libc::sigemptyset on Android --- src/libstd/sys/unix/process/process_common.rs | 16 +++++++++++++++- src/libstd/sys/unix/process/process_unix.rs | 11 ++++++++++- 2 files changed, 25 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/sys/unix/process/process_common.rs b/src/libstd/sys/unix/process/process_common.rs index 5f1a6c2f746..e9f41009064 100644 --- a/src/libstd/sys/unix/process/process_common.rs +++ b/src/libstd/sys/unix/process/process_common.rs @@ -417,12 +417,26 @@ mod tests { } } + // Android with api less than 21 define sig* functions inline, so it is not + // available for dynamic link. Implementing sigemptyset and sigaddset allow us + // to support older Android version (independent of libc version). + // The following implementations are based on https://git.io/vSkNf + #[cfg(not(target_os = "android"))] extern { + #[cfg_attr(target_os = "netbsd", link_name = "__sigemptyset14")] + fn sigemptyset(set: *mut libc::sigset_t) -> libc::c_int; + #[cfg_attr(target_os = "netbsd", link_name = "__sigaddset14")] fn sigaddset(set: *mut libc::sigset_t, signum: libc::c_int) -> libc::c_int; } + #[cfg(target_os = "android")] + unsafe fn sigemptyset(set: *mut libc::sigset_t) -> libc::c_int { + libc::memset(set as *mut _, 0, mem::size_of::()); + return 0; + } + #[cfg(target_os = "android")] unsafe fn sigaddset(set: *mut libc::sigset_t, signum: libc::c_int) -> libc::c_int { use slice; @@ -450,7 +464,7 @@ mod tests { let mut set: libc::sigset_t = mem::uninitialized(); let mut old_set: libc::sigset_t = mem::uninitialized(); - t!(cvt(libc::sigemptyset(&mut set))); + t!(cvt(sigemptyset(&mut set))); t!(cvt(sigaddset(&mut set, libc::SIGINT))); t!(cvt(libc::pthread_sigmask(libc::SIG_SETMASK, &set, &mut old_set))); diff --git a/src/libstd/sys/unix/process/process_unix.rs b/src/libstd/sys/unix/process/process_unix.rs index a213273aac8..edd322ca6fa 100644 --- a/src/libstd/sys/unix/process/process_unix.rs +++ b/src/libstd/sys/unix/process/process_unix.rs @@ -193,7 +193,16 @@ impl Command { // need to clean things up now to avoid confusing the program // we're about to run. let mut set: libc::sigset_t = mem::uninitialized(); - t!(cvt(libc::sigemptyset(&mut set))); + if cfg!(target_os = "android") { + // Implementing sigemptyset allow us to support older Android + // versions. See the comment about Android and sig* functions in + // process_common.rs + libc::memset(&mut set as *mut _ as *mut _, + 0, + mem::size_of::()); + } else { + t!(cvt(libc::sigemptyset(&mut set))); + } t!(cvt(libc::pthread_sigmask(libc::SIG_SETMASK, &set, ptr::null_mut()))); let ret = sys::signal(libc::SIGPIPE, libc::SIG_DFL); -- cgit 1.4.1-3-g733a5 From 6e6dec0cab0731c4c32f6592f02c02cf4fd03a8d Mon Sep 17 00:00:00 2001 From: aStoate Date: Sun, 26 Mar 2017 21:47:22 +1030 Subject: change string references in asciiext r? @steveklabnik --- src/libstd/ascii.rs | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/ascii.rs b/src/libstd/ascii.rs index af21d6d906e..ba2b059f828 100644 --- a/src/libstd/ascii.rs +++ b/src/libstd/ascii.rs @@ -17,7 +17,7 @@ use mem; use ops::Range; use iter::FusedIterator; -/// Extension methods for ASCII-subset only operations on string slices. +/// Extension methods for ASCII-subset only operations. /// /// Be aware that operations on seemingly non-ASCII characters can sometimes /// have unexpected results. Consider this example: @@ -54,19 +54,21 @@ pub trait AsciiExt { /// /// let ascii = 'a'; /// let utf8 = '❤'; + /// let int_ascii = 97; /// /// assert!(ascii.is_ascii()); /// assert!(!utf8.is_ascii()); + /// assert!(int_ascii.is_ascii()); /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn is_ascii(&self) -> bool; - /// Makes a copy of the string in ASCII upper case. + /// Makes a copy of the value in it's ASCII upper case equivalent. /// /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', /// but non-ASCII letters are unchanged. /// - /// To uppercase the string in-place, use [`make_ascii_uppercase`]. + /// To uppercase the value in-place, use [`make_ascii_uppercase`]. /// /// To uppercase ASCII characters in addition to non-ASCII characters, use /// [`str::to_uppercase`]. @@ -78,9 +80,11 @@ pub trait AsciiExt { /// /// let ascii = 'a'; /// let utf8 = '❤'; + /// let int_ascii = 97; /// /// assert_eq!('A', ascii.to_ascii_uppercase()); /// assert_eq!('❤', utf8.to_ascii_uppercase()); + /// assert_eq!(65, int_ascii.to_ascii_uppercase()); /// ``` /// /// [`make_ascii_uppercase`]: #tymethod.make_ascii_uppercase @@ -88,12 +92,12 @@ pub trait AsciiExt { #[stable(feature = "rust1", since = "1.0.0")] fn to_ascii_uppercase(&self) -> Self::Owned; - /// Makes a copy of the string in ASCII lower case. + /// Makes a copy of the value in it's ASCII lower case equivalent. /// /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', /// but non-ASCII letters are unchanged. /// - /// To lowercase the string in-place, use [`make_ascii_lowercase`]. + /// To lowercase the value in-place, use [`make_ascii_lowercase`]. /// /// To lowercase ASCII characters in addition to non-ASCII characters, use /// [`str::to_lowercase`]. @@ -105,9 +109,11 @@ pub trait AsciiExt { /// /// let ascii = 'A'; /// let utf8 = '❤'; + /// let int_ascii = 65; /// /// assert_eq!('a', ascii.to_ascii_lowercase()); /// assert_eq!('❤', utf8.to_ascii_lowercase()); + /// assert_eq!(97, int_ascii.to_ascii_lowercase()); /// ``` /// /// [`make_ascii_lowercase`]: #tymethod.make_ascii_lowercase @@ -115,10 +121,10 @@ pub trait AsciiExt { #[stable(feature = "rust1", since = "1.0.0")] fn to_ascii_lowercase(&self) -> Self::Owned; - /// Checks that two strings are an ASCII case-insensitive match. + /// Checks that two values are an ASCII case-insensitive match. /// /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`, - /// but without allocating and copying temporary strings. + /// but without allocating and copying temporaries. /// /// # Examples /// @@ -142,7 +148,7 @@ pub trait AsciiExt { /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', /// but non-ASCII letters are unchanged. /// - /// To return a new uppercased string without modifying the existing one, use + /// To return a new uppercased value without modifying the existing one, use /// [`to_ascii_uppercase`]. /// /// # Examples @@ -166,7 +172,7 @@ pub trait AsciiExt { /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', /// but non-ASCII letters are unchanged. /// - /// To return a new lowercased string without modifying the existing one, use + /// To return a new lowercased value without modifying the existing one, use /// [`to_ascii_lowercase`]. /// /// # Examples -- cgit 1.4.1-3-g733a5 From 169facfc288586b7635652abace56d56da2a6f99 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sat, 25 Mar 2017 17:11:08 +0100 Subject: added missing links in std::net TCP docs part of #29363 --- src/libstd/net/tcp.rs | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index a07972468e6..8a21f17dc49 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -83,11 +83,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 +498,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 +536,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 +558,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 -- cgit 1.4.1-3-g733a5 From 76d08eda7d228ed475bf190253b8fd7ebfe667db Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sun, 26 Mar 2017 14:30:03 +0200 Subject: Update std::net:Incoming's docs to use standard iterator boilerplate Part of #29363 --- src/libstd/net/tcp.rs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index 8a21f17dc49..c6cf748d981 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -65,16 +65,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 } @@ -583,10 +581,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 /// -- cgit 1.4.1-3-g733a5 From 0df7398558cb7d8fbf5d191d7e07a601a4a30702 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sat, 25 Mar 2017 17:27:00 +0100 Subject: std::net docs: changed occurences of "RFC" to say "IETF RFC" part of #29363 --- src/libstd/net/ip.rs | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index 24e0e6f3fa6..44dc689a30f 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -296,9 +296,9 @@ impl Ipv4Addr { /// 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 /// /// # Examples /// @@ -315,13 +315,13 @@ impl Ipv4Addr { /// 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 /// /// # Examples /// @@ -348,9 +348,9 @@ impl Ipv4Addr { /// 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 /// /// # Examples /// @@ -403,9 +403,9 @@ impl Ipv4Addr { /// 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 /// /// # Examples /// @@ -423,9 +423,9 @@ 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]. + /// 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 /// /// # Examples /// @@ -443,13 +443,13 @@ impl Ipv4Addr { /// 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 /// /// # Examples /// @@ -719,9 +719,9 @@ impl Ipv6Addr { /// 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 /// /// # Examples /// @@ -738,9 +738,9 @@ impl Ipv6Addr { /// 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 /// /// # Examples /// @@ -786,9 +786,9 @@ impl Ipv6Addr { /// 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 /// /// # Examples /// @@ -809,9 +809,9 @@ impl Ipv6Addr { /// 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 /// /// # Examples /// @@ -853,9 +853,9 @@ impl Ipv6Addr { /// 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 /// /// # Examples /// @@ -939,9 +939,9 @@ impl Ipv6Addr { /// 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]. /// - /// [RFC 4291]: https://tools.ietf.org/html/rfc4291 + /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 /// # Examples /// /// ``` -- cgit 1.4.1-3-g733a5 From df5830a4ece5eae8451e7b3d4f77b8af92a9f9fc Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sat, 25 Mar 2017 18:28:12 +0100 Subject: Added links throughout std::net::ToSocketAddrs' documentation Part of #29363 In the section about the default implementations of ToSocketAddrs, I moved the bulletpoint of SocketAddrV4 & SocketAddrV6 to the one stating that SocketAddr is constructed trivially, as this is what's actually the case --- src/libstd/net/addr.rs | 52 +++++++++++++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 17 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index 84c4acb8d92..ea78843aa8c 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -559,37 +559,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 -/// `:` pair where `` 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 +/// `:` pair where `` 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}; @@ -622,7 +636,7 @@ pub trait ToSocketAddrs { #[stable(feature = "rust1", since = "1.0.0")] type Iter: Iterator; - /// Converts this object to an iterator of resolved `SocketAddr`s. + /// Converts this object to an iterator of resolved [`SocketAddr`]s. /// /// The returned iterator may not actually yield any values depending on the /// outcome of any resolution performed. @@ -630,9 +644,13 @@ pub trait ToSocketAddrs { /// Note that this function may block the current thread while resolution is /// performed. /// + /// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html + /// /// # Errors /// - /// Any errors encountered during resolution will be returned as an `Err`. + /// Any errors encountered during resolution will be returned as an [`Err`]. + /// + /// [`Err`]: ../../std/result/enum.Result.html#variant.Err #[stable(feature = "rust1", since = "1.0.0")] fn to_socket_addrs(&self) -> io::Result; } -- cgit 1.4.1-3-g733a5 From 0d5baba70d3adbb2a8ea436c6c89f21c1c6927b8 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sat, 25 Mar 2017 19:23:13 +0100 Subject: Added links to std::net::AddrParseError's documentation Additionally changed the summary sentence to be more consistent with most of the other FromStr implementations' error types. --- src/libstd/net/parser.rs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/net/parser.rs b/src/libstd/net/parser.rs index d86711c10ac..7d7c67ff3f9 100644 --- a/src/libstd/net/parser.rs +++ b/src/libstd/net/parser.rs @@ -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(()); -- cgit 1.4.1-3-g733a5 From 347b70901cdabcd78d2b0229c13c31b334b00617 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sun, 26 Mar 2017 14:25:31 +0200 Subject: Expanded and added links to std::net::{IpAddr,Ipv4Addr,Ipv6Addr} docs Part of #29363 Expanded top-level documentation & linked to relevant IETF RFCs. Added a bunch of links (to true/false/Ipv4Addr/etc.) throughout the docs. --- src/libstd/net/ip.rs | 202 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 160 insertions(+), 42 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index 44dc689a30f..3e58a335470 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -21,44 +21,99 @@ use net::{hton, ntoh}; use sys::net::netc as c; use sys_common::{AsInner, FromInner}; -/// An IP address, either an IPv4 or IPv6 address. +/// Either an IPv4 address or an IPv6 address. /// -/// # Examples +/// This enum can contain either an [`Ipv4Addr`] or an [`Ipv6Addr`], see their +/// respective documentation for more details. /// -/// Constructing an IPv4 address: +/// [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html +/// [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html /// -/// ``` -/// use std::net::{IpAddr, Ipv4Addr}; +/// # Examples /// -/// IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)); /// ``` +/// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; /// -/// Constructing an IPv6 address: +/// 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)); /// -/// ``` -/// use std::net::{IpAddr, Ipv6Addr}; +/// assert_eq!("127.0.0.1".parse(), Ok(localhost_v4)); +/// assert_eq!("::1".parse(), Ok(localhost_v6)); /// -/// 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 +133,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 +158,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 +183,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 +212,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 +237,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 +266,13 @@ 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`] if it's an + /// [IPv6 address]. + /// + /// [`true`]: ../../std/primitive.bool.html + /// [`false`]: ../../std/primitive.bool.html + /// [IPv4 address]: #variant.V4 + /// [IPv6 address]: #variant.V6 /// /// # Examples /// @@ -212,7 +293,13 @@ 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`] if it's an + /// [IPv4 address]. + /// + /// [`true`]: ../../std/primitive.bool.html + /// [`false`]: ../../std/primitive.bool.html + /// [IPv4 address]: #variant.V4 + /// [IPv6 address]: #variant.V6 /// /// # Examples /// @@ -274,12 +361,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 +382,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 [IETF RFC 1122]. /// /// [IETF RFC 1122]: https://tools.ietf.org/html/rfc1122 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -313,7 +402,7 @@ 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 [IETF RFC 1918] and include: /// @@ -322,6 +411,7 @@ impl Ipv4Addr { /// - 192.168.0.0/16 /// /// [IETF RFC 1918]: https://tools.ietf.org/html/rfc1918 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -346,11 +436,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 [IETF RFC 3927]. /// /// [IETF RFC 3927]: https://tools.ietf.org/html/rfc3927 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -366,7 +457,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 +470,7 @@ impl Ipv4Addr { /// - the unspecified address (0.0.0.0) /// /// [ipv4-sr]: http://goo.gl/RaZ7lg + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -400,12 +492,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 [IETF RFC 5771]. /// /// [IETF RFC 5771]: https://tools.ietf.org/html/rfc5771 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -421,11 +514,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 [IETF RFC 919]. /// /// [IETF RFC 919]: https://tools.ietf.org/html/rfc919 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -441,7 +535,7 @@ 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 [IETF RFC 5737]: /// @@ -450,6 +544,7 @@ impl Ipv4Addr { /// - 203.0.113.0/24 (TEST-NET-3) /// /// [IETF RFC 5737]: https://tools.ietf.org/html/rfc5737 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -471,10 +566,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 +587,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 +816,12 @@ impl Ipv6Addr { ] } - /// Returns true for the special 'unspecified' address (::). + /// Returns [`true`] for the special 'unspecified' address (::). /// /// This property is defined in [IETF RFC 4291]. /// /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -736,11 +836,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 [IETF RFC 4291]. /// /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -755,14 +856,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 +888,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 [IETF RFC 4193]. /// /// [IETF RFC 4193]: https://tools.ietf.org/html/rfc4193 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -807,11 +912,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 [IETF RFC 4291]. /// /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -830,9 +936,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 +958,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 [IETF RFC 3849]. /// /// [IETF RFC 3849]: https://tools.ietf.org/html/rfc3849 + /// [`true`]: ../../std/primitive.bool.html /// /// # Examples /// @@ -874,7 +983,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 +994,8 @@ impl Ipv6Addr { /// - the unspecified address /// - the address range reserved for documentation /// + /// [`true`]: ../../std/primitive.bool.html + /// /// # Examples /// /// ``` @@ -937,11 +1048,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 [IETF RFC 4291]. /// /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 + /// [`true`]: ../../std/primitive.bool.html + /// /// # Examples /// /// ``` @@ -955,11 +1068,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}; /// -- cgit 1.4.1-3-g733a5 From be713fa4bf12cf87a799dddfd29ab095a548fd01 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sun, 26 Mar 2017 01:01:32 +0100 Subject: Removed link in std::net::ToSocketAddr's summary sentence Relative links in trait methods don't resolve in e.g. std/primitive.tuple.html :( --- src/libstd/net/addr.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index ea78843aa8c..0b63a5a5c14 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -636,7 +636,7 @@ pub trait ToSocketAddrs { #[stable(feature = "rust1", since = "1.0.0")] type Iter: Iterator; - /// Converts this object to an iterator of resolved [`SocketAddr`]s. + /// Converts this object to an iterator of resolved `SocketAddr`s. /// /// The returned iterator may not actually yield any values depending on the /// outcome of any resolution performed. @@ -644,8 +644,6 @@ pub trait ToSocketAddrs { /// Note that this function may block the current thread while resolution is /// performed. /// - /// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html - /// /// # Errors /// /// Any errors encountered during resolution will be returned as an [`Err`]. -- cgit 1.4.1-3-g733a5 From 6f0c742b001e7861099e1048c4f0cd08f0528774 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sun, 26 Mar 2017 14:13:37 +0200 Subject: Expanded and added links to std::net::{SocketAddr,SocketAddrV4,SocketAddrV6} docs Part of #29363 Changed summary sentences of SocketAddr and IpAddr for consistency Linked to SocketAddrV4 and SocketAddrV6 from SocketAddr, moving explaination there Expanded top-level docs for SocketAddrV4 and SocketAddrV6, linking to some relevant IETF RFCs, and linking back to SocketAddr Changed some of the method summaries to third person as per RFC 1574; added links to IETF RFCs where appropriate --- src/libstd/net/addr.rs | 114 ++++++++++++++++++++++++++++++++++++++----------- src/libstd/net/ip.rs | 2 +- 2 files changed, 90 insertions(+), 26 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index 0b63a5a5c14..6584531a92a 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -20,15 +20,17 @@ 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. +/// This enum can contain either an [`SocketAddrV4`] or an [`SocketAddrV6`]. see their +/// respective documentation for more details. +/// +/// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html +/// [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html #[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 +38,39 @@ 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 #[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 #[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 +107,7 @@ impl SocketAddr { } } - /// Change the IP address associated with this socket address. + /// Changes the IP address associated with this socket address. /// /// # Examples /// @@ -123,7 +146,7 @@ impl SocketAddr { } } - /// Change the port number associated with this socket address. + /// Changes the port number associated with this socket address. /// /// # Examples /// @@ -142,8 +165,14 @@ 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`] if it's an [IPv6 address]. + /// + /// [`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 + /// [IPv6 address]: ../../std/net/enum.IpAddr.html#variant.V6 /// /// # Examples /// @@ -164,8 +193,14 @@ 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`] if it's an [IPv4 address]. + /// + /// [`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 + /// [IPv6 address]: ../../std/net/enum.IpAddr.html#variant.V6 /// /// # Examples /// @@ -189,7 +224,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 +264,7 @@ impl SocketAddrV4 { } } - /// Change the IP address associated with this socket address. + /// Changes the IP address associated with this socket address. /// /// # Examples /// @@ -258,7 +295,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 +313,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 +361,7 @@ impl SocketAddrV6 { } } - /// Change the IP address associated with this socket address. + /// Changes the IP address associated with this socket address. /// /// # Examples /// @@ -349,7 +392,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 +408,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, 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 +433,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 +453,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, 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 +475,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 /// /// ``` diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index 3e58a335470..85803ff0501 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -21,7 +21,7 @@ use net::{hton, ntoh}; use sys::net::netc as c; use sys_common::{AsInner, FromInner}; -/// Either an IPv4 address or an 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. -- cgit 1.4.1-3-g733a5 From 1a9c8baed55547593610eb935c9cceccec40fdb4 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sun, 26 Mar 2017 15:43:25 +0200 Subject: Added examples to std::net::{SocketAddr, SocketAddrV4, SocketAddrV6} docs --- src/libstd/net/addr.rs | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index 6584531a92a..ccfd2a1dfb1 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -27,6 +27,18 @@ use slice; /// /// [`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 { @@ -48,6 +60,18 @@ pub enum SocketAddr { /// [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 } @@ -63,6 +87,18 @@ pub struct SocketAddrV4 { inner: c::sockaddr_in } /// [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 } -- cgit 1.4.1-3-g733a5 From ad816f81748e6314b428a91352b0eb536f7fffc5 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sun, 26 Mar 2017 16:12:27 +0200 Subject: Added links to std::net::Shutdown docs and made them more consistent Part of #29363 --- src/libstd/net/mod.rs | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/mod.rs b/src/libstd/net/mod.rs index b0d2e3e4687..e4593cf3817 100644 --- a/src/libstd/net/mod.rs +++ b/src/libstd/net/mod.rs @@ -43,17 +43,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, } -- cgit 1.4.1-3-g733a5 From 597bcec379bec40641eb6a4637ebbec69e184582 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sun, 26 Mar 2017 17:06:39 +0200 Subject: Expanded top-level docs for std::net{TcpListener,TcpStream,UdpSocket} Part of #29363 --- src/libstd/net/tcp.rs | 37 +++++++++++++++++++++++++++++++++---- src/libstd/net/udp.rs | 30 +++++++++++++++++++++++++----- 2 files changed, 58 insertions(+), 9 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index c6cf748d981..cf119720e5a 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -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 /// diff --git a/src/libstd/net/udp.rs b/src/libstd/net/udp.rs index 1ebce939348..cdf04f7f1a4 100644 --- a/src/libstd/net/udp.rs +++ b/src/libstd/net/udp.rs @@ -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 -- cgit 1.4.1-3-g733a5 From 577677d55d7ca793b3845577939d99a97e112691 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sun, 26 Mar 2017 17:27:40 +0200 Subject: Expanded std::net module docs Part of #29363 --- src/libstd/net/mod.rs | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/net/mod.rs b/src/libstd/net/mod.rs index e4593cf3817..3b4808fee25 100644 --- a/src/libstd/net/mod.rs +++ b/src/libstd/net/mod.rs @@ -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 +//! * [`ToSocketAddr`] is a trait that used for generic address resolution 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 +//! [`ToSocketAddr`]: ../../std/net/trait.ToSocketAddr.html +//! [`UdpSocket`]: ../../std/net/struct.UdpSocket.html #![stable(feature = "rust1", since = "1.0.0")] -- cgit 1.4.1-3-g733a5 From c2601fd358769cbecae479e8d32521f6e5d5c633 Mon Sep 17 00:00:00 2001 From: lukaramu Date: Sun, 26 Mar 2017 18:06:22 +0200 Subject: fix trailing whitespace --- src/libstd/net/ip.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index 85803ff0501..2a1f959b35d 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -99,7 +99,7 @@ pub struct Ipv4Addr { /// # 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 +/// 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]. /// -- cgit 1.4.1-3-g733a5 From 2cf686f2cdd6446a3cd47df0305ead40fabe85df Mon Sep 17 00:00:00 2001 From: Jörg Thalheim Date: Sun, 26 Mar 2017 18:54:08 +0200 Subject: Implement AsRawFd/IntoRawFd for RawFd This is useful to build os abstraction like the nix crate does. It allows to define functions, which accepts generic arguments of data structures convertible to RawFd, including RawFd itself. For example: fn write(fd: FD, buf: &[u8]) -> Result instead of: fn write(fd: RawFd, buf: &[u8]) -> Result write(foo.as_raw_fd(), buf); --- src/libstd/sys/unix/ext/io.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/sys/unix/ext/io.rs b/src/libstd/sys/unix/ext/io.rs index 296235e173d..75aa72e3cff 100644 --- a/src/libstd/sys/unix/ext/io.rs +++ b/src/libstd/sys/unix/ext/io.rs @@ -72,6 +72,13 @@ pub trait IntoRawFd { fn into_raw_fd(self) -> RawFd; } +#[stable(feature = "rust1", since = "1.0.0")] +impl AsRawFd for RawFd { + fn as_raw_fd(&self) -> RawFd { + *self + } +} + #[stable(feature = "rust1", since = "1.0.0")] impl AsRawFd for fs::File { fn as_raw_fd(&self) -> RawFd { @@ -84,6 +91,14 @@ impl FromRawFd for fs::File { fs::File::from_inner(sys::fs::File::from_inner(fd)) } } + +#[stable(feature = "into_raw_os", since = "1.4.0")] +impl IntoRawFd for RawFd { + fn into_raw_fd(self) -> RawFd { + self + } +} + #[stable(feature = "into_raw_os", since = "1.4.0")] impl IntoRawFd for fs::File { fn into_raw_fd(self) -> RawFd { -- cgit 1.4.1-3-g733a5 From 1579fbd8ca8452d462f76e47a5367c1d51fb8d43 Mon Sep 17 00:00:00 2001 From: Alan Stoate Date: Mon, 27 Mar 2017 07:46:43 +1030 Subject: Fixed spelling mistakes --- src/libstd/ascii.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/ascii.rs b/src/libstd/ascii.rs index ba2b059f828..1cac11f668d 100644 --- a/src/libstd/ascii.rs +++ b/src/libstd/ascii.rs @@ -63,7 +63,7 @@ pub trait AsciiExt { #[stable(feature = "rust1", since = "1.0.0")] fn is_ascii(&self) -> bool; - /// Makes a copy of the value in it's ASCII upper case equivalent. + /// Makes a copy of the value in its ASCII upper case equivalent. /// /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', /// but non-ASCII letters are unchanged. @@ -92,7 +92,7 @@ pub trait AsciiExt { #[stable(feature = "rust1", since = "1.0.0")] fn to_ascii_uppercase(&self) -> Self::Owned; - /// Makes a copy of the value in it's ASCII lower case equivalent. + /// Makes a copy of the value in its ASCII lower case equivalent. /// /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', /// but non-ASCII letters are unchanged. -- cgit 1.4.1-3-g733a5 From b8cbc5d46af4b15bfeca324aa37d8c2ca054e58e Mon Sep 17 00:00:00 2001 From: lukaramu Date: Mon, 27 Mar 2017 16:38:17 +0200 Subject: Addressed requested changes for PR #40838 * Fixed spelling ToSocketAddr -> ToSocketAddrs in module docs (which also fixes a link) * Added missing "when" before "interacting" in module docs * Changed SocketAddr's top-level docs to explicitly state what socket addresses consist of, making them more consistent with SocketAddrV4's and SocketAddrV6's docs * Changed "in C" -> "in C's `netinet/in.h`" * Changed wording in is_ipv4/is_ipv6 methods to ", `false` otherwise" * Add missing closing ` ``` ` in Ipv6Addr's examples * Removed "Errors" section in ToSocketAddrs' to_socket_addrs method as it was rather redundant --- src/libstd/net/addr.rs | 30 ++++++++++++------------------ src/libstd/net/ip.rs | 9 +++------ src/libstd/net/mod.rs | 4 ++-- 3 files changed, 17 insertions(+), 26 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index ccfd2a1dfb1..36c06dc0b58 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -22,9 +22,11 @@ use slice; /// An internet socket address, either IPv4 or IPv6. /// -/// This enum can contain either an [`SocketAddrV4`] or an [`SocketAddrV6`]. see their -/// respective documentation for more details. +/// 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 /// @@ -202,13 +204,12 @@ impl SocketAddr { } /// Returns [`true`] if the [IP address] in this `SocketAddr` is an - /// [IPv4 address] and [`false`] if it's an [IPv6 address]. + /// [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 - /// [IPv6 address]: ../../std/net/enum.IpAddr.html#variant.V6 /// /// # Examples /// @@ -230,12 +231,11 @@ impl SocketAddr { } /// Returns [`true`] if the [IP address] in this `SocketAddr` is an - /// [IPv6 address] and [`false`] if it's an [IPv4 address]. + /// [IPv6 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 /// [IPv6 address]: ../../std/net/enum.IpAddr.html#variant.V6 /// /// # Examples @@ -446,10 +446,10 @@ impl SocketAddrV6 { /// Returns the flow information associated with this address. /// - /// This information corresponds to the `sin6_flowinfo` field in C, 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]. + /// 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 @@ -491,8 +491,8 @@ impl SocketAddrV6 { /// Returns the scope ID associated with this address. /// - /// This information corresponds to the `sin6_scope_id` field in C, as specified in - /// [IETF RFC 2553, Section 3.3]. + /// 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 /// @@ -743,12 +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`]. - /// - /// [`Err`]: ../../std/result/enum.Result.html#variant.Err #[stable(feature = "rust1", since = "1.0.0")] fn to_socket_addrs(&self) -> io::Result; } diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index 2a1f959b35d..c46fe4a58c7 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -114,6 +114,7 @@ pub struct Ipv4Addr { /// 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 { @@ -266,13 +267,11 @@ impl IpAddr { } } - /// Returns [`true`] if this address is an [IPv4 address] and [`false`] if it's an - /// [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 - /// [IPv6 address]: #variant.V6 /// /// # Examples /// @@ -293,12 +292,10 @@ impl IpAddr { } } - /// Returns [`true`] if this address is an [IPv6 address] and [`false`] if it's an - /// [IPv4 address]. + /// Returns [`true`] if this address is an [IPv6 address], and [`false`] otherwise. /// /// [`true`]: ../../std/primitive.bool.html /// [`false`]: ../../std/primitive.bool.html - /// [IPv4 address]: #variant.V4 /// [IPv6 address]: #variant.V6 /// /// # Examples diff --git a/src/libstd/net/mod.rs b/src/libstd/net/mod.rs index 3b4808fee25..9fcb93e2032 100644 --- a/src/libstd/net/mod.rs +++ b/src/libstd/net/mod.rs @@ -21,7 +21,7 @@ //! [`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 -//! * [`ToSocketAddr`] is a trait that used for generic address resolution interacting +//! * [`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 //! @@ -33,7 +33,7 @@ //! [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html //! [`TcpListener`]: ../../std/net/struct.TcpListener.html //! [`TcpStream`]: ../../std/net/struct.TcpStream.html -//! [`ToSocketAddr`]: ../../std/net/trait.ToSocketAddr.html +//! [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html //! [`UdpSocket`]: ../../std/net/struct.UdpSocket.html #![stable(feature = "rust1", since = "1.0.0")] -- cgit 1.4.1-3-g733a5 From 4806f01d7c1f35a1b6f675ff099b86ec6e6c1540 Mon Sep 17 00:00:00 2001 From: Nick Sweeting Date: Mon, 27 Mar 2017 16:34:13 -0400 Subject: Fix tidy errors and simplify example --- src/libstd/io/mod.rs | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 773b0964b42..1b0c992ba09 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -145,16 +145,14 @@ //! # } //! ``` //! -//! Note that you cannot use the `?` operator in functions that do not return a `Result` (e.g. `main`). -//! Instead, you can `match` on the return value to catch any possible errors: -//! +//! Note that you cannot use the `?` operator in functions that do not return +//! a `Result` (e.g. `main`). Instead, you can call `.unwrap()` or `match` +//! on the return value to catch any possible errors: +//! //! ``` //! let mut input = String::new(); -//! -//! match io::stdin().read_line(&mut input) { -//! Err(why) => panic!("Failed to read input: {}", why.description()), -//! Ok(_) => println!("You typed: {}", input.trim()), -//! } +//! +//! io::stdin().read_line(&mut input).unwrap(); //! ``` //! //! And a very common source of output is standard output: -- cgit 1.4.1-3-g733a5 From cd2ec7eded8d65b88b4c2fdb26efe1b3c505bd6f Mon Sep 17 00:00:00 2001 From: Nick Sweeting Date: Tue, 28 Mar 2017 13:27:46 -0400 Subject: add missing import --- src/libstd/io/mod.rs | 2 ++ 1 file changed, 2 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 1b0c992ba09..32ead78f6cd 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -150,6 +150,8 @@ //! on the return value to catch any possible errors: //! //! ``` +//! use std::io; +//! //! let mut input = String::new(); //! //! io::stdin().read_line(&mut input).unwrap(); -- cgit 1.4.1-3-g733a5 From 3207657d12951df71c30f6e5e26e2f70f7b07d2e Mon Sep 17 00:00:00 2001 From: projektir Date: Mon, 27 Mar 2017 16:10:44 -0400 Subject: Adding linking for Once docs #29377 --- src/libstd/sync/once.rs | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/sync/once.rs b/src/libstd/sync/once.rs index 1e7394c0b09..d9edf5d1254 100644 --- a/src/libstd/sync/once.rs +++ b/src/libstd/sync/once.rs @@ -72,9 +72,11 @@ use thread::{self, Thread}; /// A synchronization primitive which can be used to run a one-time global /// initialization. Useful for one-time initialization for FFI or related -/// functionality. This type can only be constructed with the `ONCE_INIT` +/// functionality. This type can only be constructed with the [`ONCE_INIT`] /// value. /// +/// [`ONCE_INIT`]: constant.ONCE_INIT.html +/// /// # Examples /// /// ``` @@ -101,15 +103,28 @@ unsafe impl Sync for Once {} #[stable(feature = "rust1", since = "1.0.0")] unsafe impl Send for Once {} -/// State yielded to the `call_once_force` method which can be used to query -/// whether the `Once` was previously poisoned or not. +/// State yielded to the [`call_once_force`] method which can be used to query +/// whether the [`Once`] was previously poisoned or not. +/// +/// [`call_once_force`]: struct.Once.html#method.call_once_force +/// [`Once`]: struct.Once.html #[unstable(feature = "once_poison", issue = "33577")] #[derive(Debug)] pub struct OnceState { poisoned: bool, } -/// Initialization value for static `Once` values. +/// Initialization value for static [`Once`] values. +/// +/// [`Once`]: struct.Once.html +/// +/// # Examples +/// +/// ``` +/// use std::sync::{Once, ONCE_INIT}; +/// +/// static START: Once = ONCE_INIT; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub const ONCE_INIT: Once = Once::new(); @@ -212,15 +227,19 @@ impl Once { self.call_inner(false, &mut |_| f.take().unwrap()()); } - /// Performs the same function as `call_once` except ignores poisoning. + /// Performs the same function as [`call_once`] except ignores poisoning. + /// + /// [`call_once`]: struct.Once.html#method.call_once /// /// If this `Once` has been poisoned (some initialization panicked) then /// this function will continue to attempt to call initialization functions /// until one of them doesn't panic. /// - /// The closure `f` is yielded a structure which can be used to query the + /// The closure `f` is yielded a [`OnceState`] structure which can be used to query the /// state of this `Once` (whether initialization has previously panicked or /// not). + /// + /// [`OnceState`]: struct.OnceState.html #[unstable(feature = "once_poison", issue = "33577")] pub fn call_once_force(&'static self, f: F) where F: FnOnce(&OnceState) { // same as above, just with a different parameter to `call_inner`. @@ -366,10 +385,12 @@ impl Drop for Finish { } impl OnceState { - /// Returns whether the associated `Once` has been poisoned. + /// Returns whether the associated [`Once`] has been poisoned. /// - /// Once an initalization routine for a `Once` has panicked it will forever + /// Once an initalization routine for a [`Once`] has panicked it will forever /// indicate to future forced initialization routines that it is poisoned. + /// + /// [`Once`]: struct.Once.html #[unstable(feature = "once_poison", issue = "33577")] pub fn poisoned(&self) -> bool { self.poisoned -- cgit 1.4.1-3-g733a5 From 022bae8a4a9254fbdb4217e86927809f0ad996d6 Mon Sep 17 00:00:00 2001 From: raph Date: Wed, 29 Mar 2017 15:59:22 +0200 Subject: Add example to std::process::abort --- src/libstd/process.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index d46cf7a26da..32b52d1f77a 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1056,6 +1056,19 @@ pub fn exit(code: i32) -> ! { /// will be run. If a clean shutdown is needed it is recommended to only call /// this function at a known point where there are no more destructors left /// to run. +/// +/// # Examples +/// ``` +/// use std::process; +/// +/// fn main() { +/// println!("aborting"); +/// +/// process::abort(); +/// +/// // execution never gets here +/// } +/// ``` #[stable(feature = "process_abort", since = "1.17.0")] pub fn abort() -> ! { unsafe { ::sys::abort_internal() }; -- cgit 1.4.1-3-g733a5 From 3ac27c3e54f3f5477ea907246c872523f14ef6df Mon Sep 17 00:00:00 2001 From: raph Date: Wed, 29 Mar 2017 16:19:23 +0200 Subject: adding /// --- src/libstd/process.rs | 1 + 1 file changed, 1 insertion(+) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 32b52d1f77a..83d34f71a70 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1058,6 +1058,7 @@ pub fn exit(code: i32) -> ! { /// to run. /// /// # Examples +/// /// ``` /// use std::process; /// -- cgit 1.4.1-3-g733a5 From 5a7e9ad64a160c9ebfb35969f2bdd1065bc154bb Mon Sep 17 00:00:00 2001 From: raph Date: Wed, 29 Mar 2017 16:30:39 +0200 Subject: Removing trailing spaces --- src/libstd/process.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 83d34f71a70..a86dba97f78 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1061,12 +1061,12 @@ pub fn exit(code: i32) -> ! { /// /// ``` /// use std::process; -/// +/// /// fn main() { /// println!("aborting"); -/// +/// /// process::abort(); -/// +/// /// // execution never gets here /// } /// ``` -- cgit 1.4.1-3-g733a5 From b36cff5c4f9dd65cc48e7cc2f833dd4d6b449749 Mon Sep 17 00:00:00 2001 From: Camille TJHOA Date: Mon, 27 Mar 2017 22:42:29 +0200 Subject: Improve os::linux documentation (#29367) --- src/libstd/os/linux/fs.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/os/linux/fs.rs b/src/libstd/os/linux/fs.rs index 11c41816cec..7ebda5ed744 100644 --- a/src/libstd/os/linux/fs.rs +++ b/src/libstd/os/linux/fs.rs @@ -34,36 +34,55 @@ pub trait MetadataExt { #[allow(deprecated)] fn as_raw_stat(&self) -> &raw::stat; + /// Returns the device ID on which this file resides. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_dev(&self) -> u64; + /// Returns the inode number. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_ino(&self) -> u64; + /// Returns the file type and mode. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_mode(&self) -> u32; + /// Returns the number of hard links to file. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_nlink(&self) -> u64; + /// Returns the user ID of the file owner. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_uid(&self) -> u32; + /// Returns the group ID of the file owner. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_gid(&self) -> u32; + /// Returns the device ID that this file represents. Only relevant for special file. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_rdev(&self) -> u64; + /// Returns the size of the file (if it is a regular file or a symbolic link) in bytes. + /// + /// The size of a symbolic link is the length of the pathname it contains, + /// without a terminating null byte. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_size(&self) -> u64; + /// Returns the last access time. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_atime(&self) -> i64; + /// Returns the last access time, nano seconds part. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_atime_nsec(&self) -> i64; + /// Returns the last modification time. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_mtime(&self) -> i64; + /// Returns the last modification time, nano seconds part. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_mtime_nsec(&self) -> i64; + /// Returns the last status change time. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_ctime(&self) -> i64; + /// Returns the last status change time, nano seconds part. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_ctime_nsec(&self) -> i64; + /// Returns the "preferred" blocksize for efficient filesystem I/O. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_blksize(&self) -> u64; + /// Returns the number of blocks allocated to the file, 512-byte units. #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_blocks(&self) -> u64; } -- cgit 1.4.1-3-g733a5 From 1be84cee75687856c0032ad0fd5ea96945c067b7 Mon Sep 17 00:00:00 2001 From: raph Date: Thu, 30 Mar 2017 09:55:44 +0200 Subject: Update process.rs --- src/libstd/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index a86dba97f78..7f1a00c707c 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -1059,7 +1059,7 @@ pub fn exit(code: i32) -> ! { /// /// # Examples /// -/// ``` +/// ```no_run /// use std::process; /// /// fn main() { -- cgit 1.4.1-3-g733a5 From b3763862280946cab09cbedc4ad5626ebd95a5b2 Mon Sep 17 00:00:00 2001 From: Thomas Jespersen Date: Fri, 17 Mar 2017 23:11:27 +0100 Subject: Replace hardcoded forward slash with path::MAIN_SEPARATOR Fixes #40149 --- src/libstd/sys_common/backtrace.rs | 4 +-- src/libsyntax/parse/parser.rs | 9 ++++--- src/test/parse-fail/mod_file_not_exist.rs | 2 ++ src/test/parse-fail/mod_file_not_exist_windows.rs | 32 +++++++++++++++++++++++ 4 files changed, 41 insertions(+), 6 deletions(-) create mode 100644 src/test/parse-fail/mod_file_not_exist_windows.rs (limited to 'src/libstd') diff --git a/src/libstd/sys_common/backtrace.rs b/src/libstd/sys_common/backtrace.rs index 99297b781e4..f5c188f7a75 100644 --- a/src/libstd/sys_common/backtrace.rs +++ b/src/libstd/sys_common/backtrace.rs @@ -19,7 +19,7 @@ use io; use libc; use str; use sync::atomic::{self, Ordering}; -use path::Path; +use path::{self, Path}; use sys::mutex::Mutex; use ptr; @@ -262,7 +262,7 @@ fn output_fileline(w: &mut Write, file: &[u8], line: libc::c_int, if let Ok(cwd) = env::current_dir() { if let Ok(stripped) = file_path.strip_prefix(&cwd) { if let Some(s) = stripped.to_str() { - write!(w, " at ./{}:{}", s, line)?; + write!(w, " at .{}{}:{}", path::MAIN_SEPARATOR, s, line)?; already_printed = true; } } diff --git a/src/libsyntax/parse/parser.rs b/src/libsyntax/parse/parser.rs index db2878c6b1e..c2c3e5a6855 100644 --- a/src/libsyntax/parse/parser.rs +++ b/src/libsyntax/parse/parser.rs @@ -59,7 +59,7 @@ use util::ThinVec; use std::collections::HashSet; use std::{cmp, mem, slice}; -use std::path::{Path, PathBuf}; +use std::path::{self, Path, PathBuf}; bitflags! { flags Restrictions: u8 { @@ -5146,7 +5146,7 @@ impl<'a> Parser<'a> { pub fn default_submod_path(id: ast::Ident, dir_path: &Path, codemap: &CodeMap) -> ModulePath { let mod_name = id.to_string(); let default_path_str = format!("{}.rs", mod_name); - let secondary_path_str = format!("{}/mod.rs", mod_name); + let secondary_path_str = format!("{}{}mod.rs", mod_name, path::MAIN_SEPARATOR); let default_path = dir_path.join(&default_path_str); let secondary_path = dir_path.join(&secondary_path_str); let default_exists = codemap.file_exists(&default_path); @@ -5224,8 +5224,9 @@ impl<'a> Parser<'a> { }; err.span_note(id_sp, &format!("maybe move this module `{0}` to its own directory \ - via `{0}/mod.rs`", - this_module)); + via `{0}{1}mod.rs`", + this_module, + path::MAIN_SEPARATOR)); if paths.path_exists { err.span_note(id_sp, &format!("... or maybe `use` the module `{}` instead \ diff --git a/src/test/parse-fail/mod_file_not_exist.rs b/src/test/parse-fail/mod_file_not_exist.rs index 7736394a6f5..4bc6e706d42 100644 --- a/src/test/parse-fail/mod_file_not_exist.rs +++ b/src/test/parse-fail/mod_file_not_exist.rs @@ -8,6 +8,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +// ignore-windows + // compile-flags: -Z parse-only mod not_a_real_file; //~ ERROR file not found for module `not_a_real_file` diff --git a/src/test/parse-fail/mod_file_not_exist_windows.rs b/src/test/parse-fail/mod_file_not_exist_windows.rs new file mode 100644 index 00000000000..c58603b4398 --- /dev/null +++ b/src/test/parse-fail/mod_file_not_exist_windows.rs @@ -0,0 +1,32 @@ +// Copyright 2012 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +// ignore-gnu +// ignore-android +// ignore-bitrig +// ignore-macos +// ignore-dragonfly +// ignore-freebsd +// ignore-haiku +// ignore-ios +// ignore-linux +// ignore-netbsd +// ignore-openbsd +// ignore-solaris +// ignore-emscripten + +// compile-flags: -Z parse-only + +mod not_a_real_file; //~ ERROR file not found for module `not_a_real_file` +//~^ HELP name the file either not_a_real_file.rs or not_a_real_file\mod.rs inside the directory + +fn main() { + assert_eq!(mod_file_aux::bar(), 10); +} -- cgit 1.4.1-3-g733a5