From a424e84a3e0157f3f0160ae366ba469457cb6295 Mon Sep 17 00:00:00 2001
From: Patrick Walton <pcwalton@mimiga.net>
Date: Sun, 16 Mar 2014 15:59:04 -0700
Subject: [PATCH 1/2] libstd: Document the following modules:
* native::io
* std::char
* std::fmt
* std::fmt::parse
* std::io
* std::io::extensions
* std::io::net::ip
* std::io::net::udp
* std::io::net::unix
* std::io::pipe
* std::num
* std::num::f32
* std::num::f64
* std::num::strconv
* std::os
---
src/libnative/io/mod.rs | 5 +-
src/libstd/char.rs | 140 +++++++++++++++++++++++++-
src/libstd/fmt/mod.rs | 103 +++++++++++++------
src/libstd/fmt/parse.rs | 61 +++++++++---
src/libstd/io/extensions.rs | 49 ++++++++-
src/libstd/io/mod.rs | 30 ++++++
src/libstd/io/net/ip.rs | 5 +
src/libstd/io/net/udp.rs | 52 ++++++++--
src/libstd/io/net/unix.rs | 4 +
src/libstd/io/pipe.rs | 2 +
src/libstd/num/f32.rs | 2 +-
src/libstd/num/f64.rs | 2 +-
src/libstd/num/mod.rs | 194 ++++++++++++++++++++++++++++--------
src/libstd/num/strconv.rs | 61 ++++++++----
src/libstd/os.rs | 126 ++++++++++++++++++++++-
15 files changed, 707 insertions(+), 129 deletions(-)
diff --git a/src/libnative/io/mod.rs b/src/libnative/io/mod.rs
index 615ed80a648..e802c8f0301 100644
--- a/src/libnative/io/mod.rs
+++ b/src/libnative/io/mod.rs
@@ -97,8 +97,9 @@ fn translate_error(errno: i32, detail: bool) -> IoError {
libc::WSAECONNREFUSED => (io::ConnectionRefused, "connection refused"),
libc::WSAECONNRESET => (io::ConnectionReset, "connection reset"),
libc::WSAEACCES => (io::PermissionDenied, "permission denied"),
- libc::WSAEWOULDBLOCK =>
- (io::ResourceUnavailable, "resource temporarily unavailable"),
+ libc::WSAEWOULDBLOCK => {
+ (io::ResourceUnavailable, "resource temporarily unavailable")
+ }
libc::WSAENOTCONN => (io::NotConnected, "not connected"),
libc::WSAECONNABORTED => (io::ConnectionAborted, "connection aborted"),
libc::WSAEADDRNOTAVAIL => (io::ConnectionRefused, "address not available"),
diff --git a/src/libstd/char.rs b/src/libstd/char.rs
index 52ca28c4ce8..46447e4a416 100644
--- a/src/libstd/char.rs
+++ b/src/libstd/char.rs
@@ -404,29 +404,163 @@ pub fn len_utf8_bytes(c: char) -> uint {
}
}
-#[allow(missing_doc)]
+/// Useful functions for Unicode characters.
pub trait Char {
+ /// Returns whether the specified character is considered a Unicode
+ /// alphabetic code point.
fn is_alphabetic(&self) -> bool;
+
+ /// Returns whether the specified character satisfies the 'XID_Start'
+ /// Unicode property.
+ ///
+ /// 'XID_Start' is a Unicode Derived Property specified in
+ /// [UAX #31](http://unicode.org/reports/tr31/#NFKC_Modifications),
+ /// mostly similar to ID_Start but modified for closure under NFKx.
fn is_XID_start(&self) -> bool;
+
+ /// Returns whether the specified `char` satisfies the 'XID_Continue'
+ /// Unicode property.
+ ///
+ /// 'XID_Continue' is a Unicode Derived Property specified in
+ /// [UAX #31](http://unicode.org/reports/tr31/#NFKC_Modifications),
+ /// mostly similar to 'ID_Continue' but modified for closure under NFKx.
fn is_XID_continue(&self) -> bool;
+
+
+ /// Indicates whether a character is in lowercase.
+ ///
+ /// This is defined according to the terms of the Unicode Derived Core
+ /// Property `Lowercase`.
fn is_lowercase(&self) -> bool;
+
+ /// Indicates whether a character is in uppercase.
+ ///
+ /// This is defined according to the terms of the Unicode Derived Core
+ /// Property `Uppercase`.
fn is_uppercase(&self) -> bool;
+
+ /// Indicates whether a character is whitespace.
+ ///
+ /// Whitespace is defined in terms of the Unicode Property `White_Space`.
fn is_whitespace(&self) -> bool;
+
+ /// Indicates whether a character is alphanumeric.
+ ///
+ /// Alphanumericness is defined in terms of the Unicode General Categories
+ /// 'Nd', 'Nl', 'No' and the Derived Core Property 'Alphabetic'.
fn is_alphanumeric(&self) -> bool;
+
+ /// Indicates whether a character is a control code point.
+ ///
+ /// Control code points are defined in terms of the Unicode General
+ /// Category `Cc`.
fn is_control(&self) -> bool;
+
+ /// Indicates whether the character is numeric (Nd, Nl, or No).
fn is_digit(&self) -> bool;
+
+ /// Checks if a `char` parses as a numeric digit in the given radix.
+ ///
+ /// Compared to `is_digit()`, this function only recognizes the characters
+ /// `0-9`, `a-z` and `A-Z`.
+ ///
+ /// # Return value
+ ///
+ /// Returns `true` if `c` is a valid digit under `radix`, and `false`
+ /// otherwise.
+ ///
+ /// # Failure
+ ///
+ /// Fails if given a radix > 36.
fn is_digit_radix(&self, radix: uint) -> bool;
+
+ /// Converts a character to the corresponding digit.
+ ///
+ /// # Return value
+ ///
+ /// If `c` is between '0' and '9', the corresponding value between 0 and
+ /// 9. If `c` is 'a' or 'A', 10. If `c` is 'b' or 'B', 11, etc. Returns
+ /// none if the character does not refer to a digit in the given radix.
+ ///
+ /// # Failure
+ ///
+ /// Fails if given a radix outside the range [0..36].
fn to_digit(&self, radix: uint) -> Option<uint>;
+
+ /// Converts a character to its lowercase equivalent.
+ ///
+ /// The case-folding performed is the common or simple mapping. See
+ /// `to_uppercase()` for references and more information.
+ ///
+ /// # Return value
+ ///
+ /// Returns the lowercase equivalent of the character, or the character
+ /// itself if no conversion is possible.
fn to_lowercase(&self) -> char;
+
+ /// Converts a character to its uppercase equivalent.
+ ///
+ /// The case-folding performed is the common or simple mapping: it maps
+ /// one unicode codepoint (one character in Rust) to its uppercase
+ /// equivalent according to the Unicode database [1]. The additional
+ /// `SpecialCasing.txt` is not considered here, as it expands to multiple
+ /// codepoints in some cases.
+ ///
+ /// A full reference can be found here [2].
+ ///
+ /// # Return value
+ ///
+ /// Returns the uppercase equivalent of the character, or the character
+ /// itself if no conversion was made.
+ ///
+ /// [1]: ftp://ftp.unicode.org/Public/UNIDATA/UnicodeData.txt
+ ///
+ /// [2]: http://www.unicode.org/versions/Unicode4.0.0/ch03.pdf#G33992
fn to_uppercase(&self) -> char;
+
+ /// Converts a number to the character representing it.
+ ///
+ /// # Return value
+ ///
+ /// Returns `Some(char)` if `num` represents one digit under `radix`,
+ /// using one character of `0-9` or `a-z`, or `None` if it doesn't.
+ ///
+ /// # Failure
+ ///
+ /// Fails if given a radix > 36.
fn from_digit(num: uint, radix: uint) -> Option<char>;
+
+ /// Returns the hexadecimal Unicode escape of a character.
+ ///
+ /// The rules are as follows:
+ ///
+ /// * Characters in [0,0xff] get 2-digit escapes: `\\xNN`
+ /// * Characters in [0x100,0xffff] get 4-digit escapes: `\\uNNNN`.
+ /// * Characters above 0x10000 get 8-digit escapes: `\\UNNNNNNNN`.
fn escape_unicode(&self, f: |char|);
+
+ /// Returns a 'default' ASCII and C++11-like literal escape of a
+ /// character.
+ ///
+ /// The default is chosen with a bias toward producing literals that are
+ /// legal in a variety of languages, including C++11 and similar C-family
+ /// languages. The exact rules are:
+ ///
+ /// * Tab, CR and LF are escaped as '\t', '\r' and '\n' respectively.
+ /// * Single-quote, double-quote and backslash chars are backslash-
+ /// escaped.
+ /// * Any other chars in the range [0x20,0x7e] are not escaped.
+ /// * Any other chars are given hex unicode escapes; see `escape_unicode`.
fn escape_default(&self, f: |char|);
+
+ /// Returns the amount of bytes this character would need if encoded in
+ /// UTF-8.
fn len_utf8_bytes(&self) -> uint;
- /// Encodes this `char` as utf-8 into the provided byte-buffer
+ /// Encodes this character as UTF-8 into the provided byte buffer.
///
- /// The buffer must be at least 4 bytes long or a runtime failure will occur.
+ /// The buffer must be at least 4 bytes long or a runtime failure will
+ /// occur.
///
/// This will then return the number of characters written to the slice.
fn encode_utf8(&self, dst: &mut [u8]) -> uint;
diff --git a/src/libstd/fmt/mod.rs b/src/libstd/fmt/mod.rs
index d3ceba025ea..c2a6510d656 100644
--- a/src/libstd/fmt/mod.rs
+++ b/src/libstd/fmt/mod.rs
@@ -562,51 +562,94 @@ pub struct Arguments<'a> {
/// When a format is not otherwise specified, types are formatted by ascribing
/// to this trait. There is not an explicit way of selecting this trait to be
/// used for formatting, it is only if no other format is specified.
-#[allow(missing_doc)]
-pub trait Show { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait Show {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
/// Format trait for the `b` character
-#[allow(missing_doc)]
-pub trait Bool { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait Bool {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `c` character
-#[allow(missing_doc)]
-pub trait Char { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait Char {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `i` and `d` characters
-#[allow(missing_doc)]
-pub trait Signed { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait Signed {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `u` character
-#[allow(missing_doc)]
-pub trait Unsigned { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait Unsigned {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `o` character
-#[allow(missing_doc)]
-pub trait Octal { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait Octal {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `t` character
-#[allow(missing_doc)]
-pub trait Binary { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait Binary {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `x` character
-#[allow(missing_doc)]
-pub trait LowerHex { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait LowerHex {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `X` character
-#[allow(missing_doc)]
-pub trait UpperHex { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait UpperHex {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `s` character
-#[allow(missing_doc)]
-pub trait String { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait String {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `?` character
-#[allow(missing_doc)]
-pub trait Poly { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait Poly {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `p` character
-#[allow(missing_doc)]
-pub trait Pointer { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait Pointer {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `f` character
-#[allow(missing_doc)]
-pub trait Float { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait Float {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `e` character
-#[allow(missing_doc)]
-pub trait LowerExp { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait LowerExp {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
+
/// Format trait for the `E` character
-#[allow(missing_doc)]
-pub trait UpperExp { fn fmt(&self, &mut Formatter) -> Result; }
+pub trait UpperExp {
+ /// Formats the value using the given formatter.
+ fn fmt(&self, &mut Formatter) -> Result;
+}
// FIXME #11938 - UFCS would make us able call the above methods
// directly Show::show(x, fmt).
diff --git a/src/libstd/fmt/parse.rs b/src/libstd/fmt/parse.rs
index 67088e6f4f8..384e2ff2380 100644
--- a/src/libstd/fmt/parse.rs
+++ b/src/libstd/fmt/parse.rs
@@ -11,16 +11,16 @@
//! Parsing of format strings
//!
//! These structures are used when parsing format strings for the compiler.
-//! Parsing does not currently happen at runtime (structures of std::fmt::rt are
-//! generated instead).
+//! Parsing does not happen at runtime: structures of `std::fmt::rt` are
+//! generated instead.
use prelude::*;
use char;
use str;
-/// A piece is a portion of the format string which represents the next part to
-/// emit. These are emitted as a stream by the `Parser` class.
+/// A piece is a portion of the format string which represents the next part
+/// to emit. These are emitted as a stream by the `Parser` class.
#[deriving(Eq)]
pub enum Piece<'a> {
/// A literal string which should directly be emitted
@@ -65,36 +65,55 @@ pub struct FormatSpec<'a> {
/// Enum describing where an argument for a format can be located.
#[deriving(Eq)]
-#[allow(missing_doc)]
pub enum Position<'a> {
- ArgumentNext, ArgumentIs(uint), ArgumentNamed(&'a str)
+ /// The argument will be in the next position. This is the default.
+ ArgumentNext,
+ /// The argument is located at a specific index.
+ ArgumentIs(uint),
+ /// The argument has a name.
+ ArgumentNamed(&'a str),
}
/// Enum of alignments which are supported.
#[deriving(Eq)]
-#[allow(missing_doc)]
-pub enum Alignment { AlignLeft, AlignRight, AlignUnknown }
+pub enum Alignment {
+ /// The value will be aligned to the left.
+ AlignLeft,
+ /// The value will be aligned to the right.
+ AlignRight,
+ /// The value will take on a default alignment.
+ AlignUnknown,
+}
-/// Various flags which can be applied to format strings, the meaning of these
+/// Various flags which can be applied to format strings. The meaning of these
/// flags is defined by the formatters themselves.
#[deriving(Eq)]
-#[allow(missing_doc)]
pub enum Flag {
+ /// A `+` will be used to denote positive numbers.
FlagSignPlus,
+ /// A `-` will be used to denote negative numbers. This is the default.
FlagSignMinus,
+ /// An alternate form will be used for the value. In the case of numbers,
+ /// this means that the number will be prefixed with the supplied string.
FlagAlternate,
+ /// For numbers, this means that the number will be padded with zeroes,
+ /// and the sign (`+` or `-`) will precede them.
FlagSignAwareZeroPad,
}
/// A count is used for the precision and width parameters of an integer, and
/// can reference either an argument or a literal integer.
#[deriving(Eq)]
-#[allow(missing_doc)]
pub enum Count<'a> {
+ /// The count is specified explicitly.
CountIs(uint),
+ /// The count is specified by the argument with the given name.
CountIsName(&'a str),
+ /// The count is specified by the argument at the given index.
CountIsParam(uint),
+ /// The count is specified by the next parameter.
CountIsNextParam,
+ /// The count is implied and cannot be explicitly specified.
CountImplied,
}
@@ -106,8 +125,9 @@ pub enum Method<'a> {
/// keyword-defined clauses. The meaning of the keywords is defined by the
/// current locale.
///
- /// An offset is optionally present at the beginning which is used to match
- /// against keywords, but it is not matched against the literal integers.
+ /// An offset is optionally present at the beginning which is used to
+ /// match against keywords, but it is not matched against the literal
+ /// integers.
///
/// The final element of this enum is the default "other" case which is
/// always required to be specified.
@@ -139,14 +159,23 @@ pub struct PluralArm<'a> {
result: ~[Piece<'a>],
}
-/// Enum of the 5 CLDR plural keywords. There is one more, "other", but that is
-/// specially placed in the `Plural` variant of `Method`
+/// Enum of the 5 CLDR plural keywords. There is one more, "other", but that
+/// is specially placed in the `Plural` variant of `Method`.
///
/// http://www.icu-project.org/apiref/icu4c/classicu_1_1PluralRules.html
#[deriving(Eq, TotalEq, Hash)]
#[allow(missing_doc)]
pub enum PluralKeyword {
- Zero, One, Two, Few, Many
+ /// The plural form for zero objects.
+ Zero,
+ /// The plural form for one object.
+ One,
+ /// The plural form for two objects.
+ Two,
+ /// The plural form for few objects.
+ Few,
+ /// The plural form for many objects.
+ Many,
}
/// Structure representing one "arm" of the `select` function.
diff --git a/src/libstd/io/extensions.rs b/src/libstd/io/extensions.rs
index e5938569ea3..b9e933d0b14 100644
--- a/src/libstd/io/extensions.rs
+++ b/src/libstd/io/extensions.rs
@@ -42,8 +42,11 @@ pub struct Bytes<'r, T> {
}
impl<'r, R: Reader> Bytes<'r, R> {
+ /// Constructs a new byte iterator from the given Reader instance.
pub fn new(r: &'r mut R) -> Bytes<'r, R> {
- Bytes { reader: r }
+ Bytes {
+ reader: r,
+ }
}
}
@@ -58,6 +61,20 @@ impl<'r, R: Reader> Iterator<IoResult<u8>> for Bytes<'r, R> {
}
}
+/// Converts an 8-bit to 64-bit unsigned value to a little-endian byte
+/// representation of the given size. If the size is not big enough to
+/// represent the value, then the high-order bytes are truncated.
+///
+/// Arguments:
+///
+/// * `n`: The value to convert.
+/// * `size`: The size of the value, in bytes. This must be 8 or less, or task
+/// failure occurs. If this is less than 8, then a value of that
+/// many bytes is produced. For example, if `size` is 4, then a
+/// 32-bit byte representation is produced.
+/// * `f`: A callback that receives the value.
+///
+/// This function returns the value returned by the callback, for convenience.
pub fn u64_to_le_bytes<T>(n: u64, size: uint, f: |v: &[u8]| -> T) -> T {
use mem::{to_le16, to_le32, to_le64};
use cast::transmute;
@@ -84,6 +101,20 @@ pub fn u64_to_le_bytes<T>(n: u64, size: uint, f: |v: &[u8]| -> T) -> T {
}
}
+/// Converts an 8-bit to 64-bit unsigned value to a big-endian byte
+/// representation of the given size. If the size is not big enough to
+/// represent the value, then the high-order bytes are truncated.
+///
+/// Arguments:
+///
+/// * `n`: The value to convert.
+/// * `size`: The size of the value, in bytes. This must be 8 or less, or task
+/// failure occurs. If this is less than 8, then a value of that
+/// many bytes is produced. For example, if `size` is 4, then a
+/// 32-bit byte representation is produced.
+/// * `f`: A callback that receives the value.
+///
+/// This function returns the value returned by the callback, for convenience.
pub fn u64_to_be_bytes<T>(n: u64, size: uint, f: |v: &[u8]| -> T) -> T {
use mem::{to_be16, to_be32, to_be64};
use cast::transmute;
@@ -108,10 +139,18 @@ pub fn u64_to_be_bytes<T>(n: u64, size: uint, f: |v: &[u8]| -> T) -> T {
}
}
-pub fn u64_from_be_bytes(data: &[u8],
- start: uint,
- size: uint)
- -> u64 {
+/// Extracts an 8-bit to 64-bit unsigned big-endian value from the given byte
+/// buffer and returns it as a 64-bit value.
+///
+/// Arguments:
+///
+/// * `data`: The buffer in which to extract the value.
+/// * `start`: The offset at which to extract the value.
+/// * `size`: The size of the value in bytes to extract. This must be 8 or
+/// less, or task failure occurs. If this is less than 8, then only
+/// that many bytes are parsed. For example, if `size` is 4, then a
+/// 32-bit value is parsed.
+pub fn u64_from_be_bytes(data: &[u8], start: uint, size: uint) -> u64 {
use ptr::{copy_nonoverlapping_memory};
use mem::from_be64;
use slice::MutableVector;
diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 6bd8f119ba2..3f959a8f780 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -300,25 +300,45 @@ impl fmt::Show for IoError {
}
}
+/// A list specifying general categories of I/O error.
#[deriving(Eq, Clone, Show)]
#[allow(missing_doc)]
pub enum IoErrorKind {
+ /// Any I/O error not part of this list.
OtherIoError,
+ /// The operation could not complete because end of file was reached.
EndOfFile,
+ /// The file was not found.
FileNotFound,
+ /// The file permissions disallowed access to this file.
PermissionDenied,
+ /// A network connection failed for some reason not specified in this list.
ConnectionFailed,
+ /// The network operation failed because the network connection was cloesd.
Closed,
+ /// The connection was refused by the remote server.
ConnectionRefused,
+ /// The connection was reset by the remote server.
ConnectionReset,
+ /// The connection was aborted (terminated) by the remote server.
ConnectionAborted,
+ /// The network operation failed because it was not connected yet.
NotConnected,
+ /// The operation failed because a pipe was closed.
BrokenPipe,
+ /// A file already existed with that name.
PathAlreadyExists,
+ /// No file exists at that location.
PathDoesntExist,
+ /// The path did not specify the type of file that this operation required. For example,
+ /// attempting to copy a directory with the `fs::copy()` operation will fail with this error.
MismatchedFileTypeForOperation,
+ /// The operation temporarily failed (for example, because a signal was received), and retrying
+ /// may succeed.
ResourceUnavailable,
+ /// No I/O functionality is available for this task.
IoUnavailable,
+ /// A parameter was incorrect in a way that caused an I/O error not part of this list.
InvalidInput,
}
@@ -1411,15 +1431,25 @@ pub struct FileStat {
#[allow(missing_doc)]
#[deriving(Hash)]
pub struct UnstableFileStat {
+ /// The ID of the device containing the file.
device: u64,
+ /// The file serial number.
inode: u64,
+ /// The device ID.
rdev: u64,
+ /// The number of hard links to this file.
nlink: u64,
+ /// The user ID of the file.
uid: u64,
+ /// The group ID of the file.
gid: u64,
+ /// The optimal block size for I/O.
blksize: u64,
+ /// The blocks allocated for this file.
blocks: u64,
+ /// User-defined flags for the file.
flags: u64,
+ /// The file generation number.
gen: u64,
}
diff --git a/src/libstd/io/net/ip.rs b/src/libstd/io/net/ip.rs
index dc24ead6258..fef4dd380e8 100644
--- a/src/libstd/io/net/ip.rs
+++ b/src/libstd/io/net/ip.rs
@@ -8,6 +8,11 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
+//! Internet Protocol (IP) addresses.
+//!
+//! This module contains functions useful for parsing, formatting, and
+//! manipulating IP addresses.
+
#[allow(missing_doc)];
use container::Container;
diff --git a/src/libstd/io/net/udp.rs b/src/libstd/io/net/udp.rs
index e2620556321..eabd00a6a2d 100644
--- a/src/libstd/io/net/udp.rs
+++ b/src/libstd/io/net/udp.rs
@@ -8,7 +8,14 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
-#[allow(missing_doc)];
+//! UDP (User Datagram Protocol) network connections.
+//!
+//! This module contains the ability to open a UDP stream to a socket address.
+//! The destination and binding addresses can either be an IPv4 or IPv6
+//! address. There is no corresponding notion of a server because UDP is a
+//! datagram protocol.
+//!
+//! A UDP connection implements the `Reader` and `Writer` traits.
use clone::Clone;
use result::{Ok, Err};
@@ -16,58 +23,85 @@ use io::net::ip::SocketAddr;
use io::{Reader, Writer, IoResult};
use rt::rtio::{RtioSocket, RtioUdpSocket, IoFactory, LocalIo};
+/// A User Datagram Protocol socket.
pub struct UdpSocket {
priv obj: ~RtioUdpSocket
}
impl UdpSocket {
+ /// Creates a UDP socket from the given socket address.
pub fn bind(addr: SocketAddr) -> IoResult<UdpSocket> {
LocalIo::maybe_raise(|io| {
io.udp_bind(addr).map(|s| UdpSocket { obj: s })
})
}
- pub fn recvfrom(&mut self, buf: &mut [u8]) -> IoResult<(uint, SocketAddr)> {
+ /// Receives data from the socket. On success, returns the number of bytes
+ /// read and the address from whence the data came.
+ pub fn recvfrom(&mut self, buf: &mut [u8])
+ -> IoResult<(uint, SocketAddr)> {
self.obj.recvfrom(buf)
}
+ /// Sends data on the socket to the given address. Returns nothing on
+ /// success.
pub fn sendto(&mut self, buf: &[u8], dst: SocketAddr) -> IoResult<()> {
self.obj.sendto(buf, dst)
}
+ /// Creates a `UdpStream`, which allows use of the `Reader` and `Writer`
+ /// traits to receive and send data from the same address. This transfers
+ /// ownership of the socket to the stream.
+ ///
+ /// Note that this call does not perform any actual network communication,
+ /// because UDP is a datagram protocol.
pub fn connect(self, other: SocketAddr) -> UdpStream {
- UdpStream { socket: self, connected_to: other }
+ UdpStream {
+ socket: self,
+ connected_to: other,
+ }
}
+ /// Returns the socket address that this socket was created from.
pub fn socket_name(&mut self) -> IoResult<SocketAddr> {
self.obj.socket_name()
}
}
impl Clone for UdpSocket {
- /// Creates a new handle to this UDP socket, allowing for simultaneous reads
- /// and writes of the socket.
+ /// Creates a new handle to this UDP socket, allowing for simultaneous
+ /// reads and writes of the socket.
///
/// The underlying UDP socket will not be closed until all handles to the
- /// socket have been deallocated. Two concurrent reads will not receive the
- /// same data. Instead, the first read will receive the first packet
+ /// socket have been deallocated. Two concurrent reads will not receive
+ /// the same data. Instead, the first read will receive the first packet
/// received, and the second read will receive the second packet.
fn clone(&self) -> UdpSocket {
- UdpSocket { obj: self.obj.clone() }
+ UdpSocket {
+ obj: self.obj.clone(),
+ }
}
}
+/// A type that allows convenient usage of a UDP stream connected to one
+/// address via the `Reader` and `Writer` traits.
pub struct UdpStream {
priv socket: UdpSocket,
priv connected_to: SocketAddr
}
impl UdpStream {
+ /// Allows access to the underlying UDP socket owned by this stream. This
+ /// is useful to, for example, use the socket to send data to hosts other
+ /// than the one that this stream is connected to.
pub fn as_socket<T>(&mut self, f: |&mut UdpSocket| -> T) -> T {
f(&mut self.socket)
}
- pub fn disconnect(self) -> UdpSocket { self.socket }
+ /// Consumes this UDP stream and returns out the underlying socket.
+ pub fn disconnect(self) -> UdpSocket {
+ self.socket
+ }
}
impl Reader for UdpStream {
diff --git a/src/libstd/io/net/unix.rs b/src/libstd/io/net/unix.rs
index bd715858a01..9f04317a5c8 100644
--- a/src/libstd/io/net/unix.rs
+++ b/src/libstd/io/net/unix.rs
@@ -79,7 +79,9 @@ impl Writer for UnixStream {
fn write(&mut self, buf: &[u8]) -> IoResult<()> { self.obj.write(buf) }
}
+/// A value that can listen for incoming named pipe connection requests.
pub struct UnixListener {
+ /// The internal, opaque runtime Unix listener.
priv obj: ~RtioUnixListener,
}
@@ -119,7 +121,9 @@ impl Listener<UnixStream, UnixAcceptor> for UnixListener {
}
}
+/// A value that can accept named pipe connections, returned from `listen()`.
pub struct UnixAcceptor {
+ /// The internal, opaque runtime Unix acceptor.
priv obj: ~RtioUnixAcceptor,
}
diff --git a/src/libstd/io/pipe.rs b/src/libstd/io/pipe.rs
index 02dfaeb7164..9984a3e5cdf 100644
--- a/src/libstd/io/pipe.rs
+++ b/src/libstd/io/pipe.rs
@@ -20,7 +20,9 @@ use io::IoResult;
use libc;
use rt::rtio::{RtioPipe, LocalIo};
+/// A synchronous, in-memory pipe.
pub struct PipeStream {
+ /// The internal, opaque runtime pipe object.
priv obj: ~RtioPipe,
}
diff --git a/src/libstd/num/f32.rs b/src/libstd/num/f32.rs
index 3ba3a9a134f..323f24a52c3 100644
--- a/src/libstd/num/f32.rs
+++ b/src/libstd/num/f32.rs
@@ -116,7 +116,7 @@ pub static NAN: f32 = 0.0_f32/0.0_f32;
pub static INFINITY: f32 = 1.0_f32/0.0_f32;
pub static NEG_INFINITY: f32 = -1.0_f32/0.0_f32;
-/* Module: consts */
+/// Various useful constants.
pub mod consts {
// FIXME (requires Issue #1433 to fix): replace with mathematical
// staticants from cmath.
diff --git a/src/libstd/num/f64.rs b/src/libstd/num/f64.rs
index b95188b0765..fc8c5f47073 100644
--- a/src/libstd/num/f64.rs
+++ b/src/libstd/num/f64.rs
@@ -120,7 +120,7 @@ pub static NEG_INFINITY: f64 = -1.0_f64/0.0_f64;
// FIXME (#1999): add is_normal, is_subnormal, and fpclassify
-/* Module: consts */
+/// Various useful constants.
pub mod consts {
// FIXME (requires Issue #1433 to fix): replace with mathematical
// constants from cmath.
diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs
index 98379b5e5fb..31124db49b9 100644
--- a/src/libstd/num/mod.rs
+++ b/src/libstd/num/mod.rs
@@ -96,25 +96,56 @@ pub trait One: Mul<Self, Self> {
/// Returns the multiplicative identity, `1`.
#[inline(always)] pub fn one<T: One>() -> T { One::one() }
-pub trait Signed: Num
- + Neg<Self> {
+/// Useful functions for signed numbers (i.e. numbers that can be negative).
+pub trait Signed: Num + Neg<Self> {
+ /// Computes the absolute value.
+ ///
+ /// For float, f32, and f64, `NaN` will be returned if the number is `NaN`.
fn abs(&self) -> Self;
+
+ /// The positive difference of two numbers.
+ ///
+ /// Returns `zero` if the number is less than or equal to `other`, otherwise the difference
+ /// between `self` and `other` is returned.
fn abs_sub(&self, other: &Self) -> Self;
+
+ /// Returns the sign of the number.
+ ///
+ /// For `float`, `f32`, `f64`:
+ /// * `1.0` if the number is positive, `+0.0` or `INFINITY`
+ /// * `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY`
+ /// * `NaN` if the number is `NaN`
+ ///
+ /// For `int`:
+ /// * `0` if the number is zero
+ /// * `1` if the number is positive
+ /// * `-1` if the number is negative
fn signum(&self) -> Self;
+ /// Returns true if the number is positive and false if the number is zero or negative.
fn is_positive(&self) -> bool;
+
+ /// Returns true if the number is negative and false if the number is zero or positive.
fn is_negative(&self) -> bool;
}
/// Computes the absolute value.
///
/// For float, f32, and f64, `NaN` will be returned if the number is `NaN`
-#[inline(always)] pub fn abs<T: Signed>(value: T) -> T { value.abs() }
+#[inline(always)]
+pub fn abs<T: Signed>(value: T) -> T {
+ value.abs()
+}
+
/// The positive difference of two numbers.
///
/// Returns `zero` if the number is less than or equal to `other`,
/// otherwise the difference between `self` and `other` is returned.
-#[inline(always)] pub fn abs_sub<T: Signed>(x: T, y: T) -> T { x.abs_sub(&y) }
+#[inline(always)]
+pub fn abs_sub<T: Signed>(x: T, y: T) -> T {
+ x.abs_sub(&y)
+}
+
/// Returns the sign of the number.
///
/// For float, f32, f64:
@@ -308,70 +339,150 @@ pub enum FPCategory {
FPNormal,
}
-/// Primitive floating point numbers
-pub trait Float: Signed
- + Round
- + Primitive {
+/// Operations on primitive floating point numbers.
+///
+/// TODO(#5527): In a future version of Rust, many of these functions will become constants.
+///
+/// FIXME(#8888): Several of these functions have a parameter named `unused_self`. Removing it
+/// requires #8888 to be fixed.
+pub trait Float: Signed + Round + Primitive {
+ /// Returns the maximum of the two numbers.
fn max(self, other: Self) -> Self;
+ /// Returns the minimum of the two numbers.
fn min(self, other: Self) -> Self;
- // FIXME (#5527): These should be associated constants
+ /// Returns the NaN value.
fn nan() -> Self;
+
+ /// Returns the infinite value.
fn infinity() -> Self;
+
+ /// Returns the negative infinite value.
fn neg_infinity() -> Self;
+
+ /// Returns -0.0.
fn neg_zero() -> Self;
+ /// Returns true if this value is NaN and false otherwise.
fn is_nan(&self) -> bool;
+
+ /// Returns true if this value is positive infinity or negative infinity and false otherwise.
fn is_infinite(&self) -> bool;
+
+ /// Returns true if this number is neither infinite nor NaN.
fn is_finite(&self) -> bool;
+
+ /// Returns true if this number is neither zero, infinite, denormal, or NaN.
fn is_normal(&self) -> bool;
+
+ /// Returns the category that this number falls into.
fn classify(&self) -> FPCategory;
- // FIXME (#8888): Removing `unused_self` requires #8888 to be fixed.
+ /// Returns the number of binary digits of mantissa that this type supports.
fn mantissa_digits(unused_self: Option<Self>) -> uint;
+
+ /// Returns the number of binary digits of exponent that this type supports.
fn digits(unused_self: Option<Self>) -> uint;
+
+ /// Returns the smallest positive number that this type can represent.
fn epsilon() -> Self;
+
+ /// Returns the minimum binary exponent that this type can represent.
fn min_exp(unused_self: Option<Self>) -> int;
+
+ /// Returns the maximum binary exponent that this type can represent.
fn max_exp(unused_self: Option<Self>) -> int;
+
+ /// Returns the minimum base-10 exponent that this type can represent.
fn min_10_exp(unused_self: Option<Self>) -> int;
+
+ /// Returns the maximum base-10 exponent that this type can represent.
fn max_10_exp(unused_self: Option<Self>) -> int;
+ /// Constructs a floating point number created by multiplying `x` by 2 raised to the power of
+ /// `exp`.
fn ldexp(x: Self, exp: int) -> Self;
+
+ /// Breaks the number into a normalized fraction and a base-2 exponent, satisfying:
+ ///
+ /// * `self = x * pow(2, exp)`
+ ///
+ /// * `0.5 <= abs(x) < 1.0`
fn frexp(&self) -> (Self, int);
+ /// Returns the exponential of the number, minus 1, in a way that is accurate even if the
+ /// number is close to zero.
fn exp_m1(&self) -> Self;
+
+ /// Returns the natural logarithm of the number plus 1 (`ln(1+n)`) more accurately than if the
+ /// operations were performed separately.
fn ln_1p(&self) -> Self;
+
+ /// Fused multiply-add. Computes `(self * a) + b` with only one rounding error. This produces a
+ /// more accurate result with better performance than a separate multiplication operation
+ /// followed by an add.
fn mul_add(&self, a: Self, b: Self) -> Self;
+
+ /// Returns the next representable floating-point value in the direction of `other`.
fn next_after(&self, other: Self) -> Self;
+ /// Returns the mantissa, exponent and sign as integers, respectively.
fn integer_decode(&self) -> (u64, i16, i8);
- // Common Mathematical Constants
- // FIXME (#5527): These should be associated constants
+ /// Archimedes' constant.
fn pi() -> Self;
- fn two_pi() -> Self;
- fn frac_pi_2() -> Self;
- fn frac_pi_3() -> Self;
- fn frac_pi_4() -> Self;
- fn frac_pi_6() -> Self;
- fn frac_pi_8() -> Self;
- fn frac_1_pi() -> Self;
- fn frac_2_pi() -> Self;
- fn frac_2_sqrtpi() -> Self;
- fn sqrt2() -> Self;
- fn frac_1_sqrt2() -> Self;
- fn e() -> Self;
- fn log2_e() -> Self;
- fn log10_e() -> Self;
- fn ln_2() -> Self;
- fn ln_10() -> Self;
- // Fractional functions
+ /// 2.0 * pi.
+ fn two_pi() -> Self;
+
+ /// pi / 2.0.
+ fn frac_pi_2() -> Self;
+
+ /// pi / 3.0.
+ fn frac_pi_3() -> Self;
+
+ /// pi / 4.0.
+ fn frac_pi_4() -> Self;
+
+ /// pi / 6.0.
+ fn frac_pi_6() -> Self;
+
+ /// pi / 8.0.
+ fn frac_pi_8() -> Self;
+
+ /// 1.0 / pi.
+ fn frac_1_pi() -> Self;
+
+ /// 2.0 / pi.
+ fn frac_2_pi() -> Self;
+
+ /// 2.0 / sqrt(pi).
+ fn frac_2_sqrtpi() -> Self;
+
+ /// sqrt(2.0).
+ fn sqrt2() -> Self;
+
+ /// 1.0 / sqrt(2.0).
+ fn frac_1_sqrt2() -> Self;
+
+ /// Euler's number.
+ fn e() -> Self;
+
+ /// log2(e).
+ fn log2_e() -> Self;
+
+ /// log10(e).
+ fn log10_e() -> Self;
+
+ /// ln(2.0).
+ fn ln_2() -> Self;
+
+ /// ln(10.0).
+ fn ln_10() -> Self;
/// Take the reciprocal (inverse) of a number, `1/x`.
fn recip(&self) -> Self;
- // Algebraic functions
/// Raise a number to a power.
fn powf(&self, n: &Self) -> Self;
@@ -385,8 +496,6 @@ pub trait Float: Signed
/// legs of length `x` and `y`.
fn hypot(&self, other: &Self) -> Self;
- // Trigonometric functions
-
/// Computes the sine of a number (in radians).
fn sin(&self) -> Self;
/// Computes the cosine of a number (in radians).
@@ -412,8 +521,6 @@ pub trait Float: Signed
/// `(sin(x), cos(x))`.
fn sin_cos(&self) -> (Self, Self);
- // Exponential functions
-
/// Returns `e^(self)`, (the exponential function).
fn exp(&self) -> Self;
/// Returns 2 raised to the power of the number, `2^(self)`.
@@ -427,8 +534,6 @@ pub trait Float: Signed
/// Returns the base 10 logarithm of the number.
fn log10(&self) -> Self;
- // Hyperbolic functions
-
/// Hyperbolic sine function.
fn sinh(&self) -> Self;
/// Hyperbolic cosine function.
@@ -442,8 +547,6 @@ pub trait Float: Signed
/// Inverse hyperbolic tangent function.
fn atanh(&self) -> Self;
- // Angular conversions
-
/// Convert radians to degrees.
fn to_degrees(&self) -> Self;
/// Convert degrees to radians.
@@ -978,8 +1081,10 @@ pub fn cast<T: NumCast,U: NumCast>(n: T) -> Option<U> {
NumCast::from(n)
}
-/// An interface for casting between machine scalars
+/// An interface for casting between machine scalars.
pub trait NumCast: ToPrimitive {
+ /// Creates a number from another value that can be converted into a primitive via the
+ /// `ToPrimitive` trait.
fn from<T: ToPrimitive>(n: T) -> Option<Self>;
}
@@ -1059,19 +1164,30 @@ impl<T: CheckedAdd + CheckedSub + Zero + Ord + Bounded> Saturating for T {
}
}
+/// Performs addition that returns `None` instead of wrapping around on overflow.
pub trait CheckedAdd: Add<Self, Self> {
+ /// Adds two numbers, checking for overflow. If overflow happens, `None` is returned.
fn checked_add(&self, v: &Self) -> Option<Self>;
}
+/// Performs subtraction that returns `None` instead of wrapping around on underflow.
pub trait CheckedSub: Sub<Self, Self> {
+ /// Subtracts two numbers, checking for underflow. If underflow happens, `None` is returned.
fn checked_sub(&self, v: &Self) -> Option<Self>;
}
+/// Performs multiplication that returns `None` instead of wrapping around on underflow or
+/// overflow.
pub trait CheckedMul: Mul<Self, Self> {
+ /// Multiplies two numbers, checking for underflow or overflow. If underflow or overflow
+ /// happens, `None` is returned.
fn checked_mul(&self, v: &Self) -> Option<Self>;
}
+/// Performs division that returns `None` instead of wrapping around on underflow or overflow.
pub trait CheckedDiv: Div<Self, Self> {
+ /// Divides two numbers, checking for underflow or overflow. If underflow or overflow happens,
+ /// `None` is returned.
fn checked_div(&self, v: &Self) -> Option<Self>;
}
diff --git a/src/libstd/num/strconv.rs b/src/libstd/num/strconv.rs
index 9d3d012bae7..9f9a9ec8e2e 100644
--- a/src/libstd/num/strconv.rs
+++ b/src/libstd/num/strconv.rs
@@ -24,31 +24,66 @@ use num;
use num::{NumCast, Zero, One, cast, Int};
use num::{Round, Float, FPNaN, FPInfinite, ToPrimitive};
+/// A flag that specifies whether to use exponential (scientific) notation.
pub enum ExponentFormat {
+ /// Do not use exponential notation.
ExpNone,
+ /// Use exponential notation with the exponent having a base of 10 and the
+ /// exponent sign being `e` or `E`. For example, 1000 would be printed
+ /// 1e3.
ExpDec,
- ExpBin
+ /// Use exponential notation with the exponent having a base of 2 and the
+ /// exponent sign being `p` or `P`. For example, 8 would be printed 1p3.
+ ExpBin,
}
+/// The number of digits used for emitting the fractional part of a number, if
+/// any.
pub enum SignificantDigits {
+ /// All calculable digits will be printed.
+ ///
+ /// Note that bignums or fractions may cause a surprisingly large number
+ /// of digits to be printed.
DigAll,
+
+ /// At most the given number of digits will be printed, truncating any
+ /// trailing zeroes.
DigMax(uint),
+
+ /// Precisely the given number of digits will be printed.
DigExact(uint)
}
+/// How to emit the sign of a number.
pub enum SignFormat {
+ /// No sign will be printed. The exponent sign will also be emitted.
SignNone,
+ /// `-` will be printed for negative values, but no sign will be emitted
+ /// for positive numbers.
SignNeg,
- SignAll
+ /// `+` will be printed for positive values, and `-` will be printed for
+ /// negative values.
+ SignAll,
}
+/// Encompasses functions used by the string converter.
pub trait NumStrConv {
+ /// Returns the NaN value.
fn nan() -> Option<Self>;
+
+ /// Returns the infinite value.
fn inf() -> Option<Self>;
+
+ /// Returns the negative infinite value.
fn neg_inf() -> Option<Self>;
+
+ /// Returns -0.0.
fn neg_zero() -> Option<Self>;
+ /// Rounds the number toward zero.
fn round_to_zero(&self) -> Self;
+
+ /// Returns the fractional part of the number.
fn fractional_part(&self) -> Self;
}
@@ -200,25 +235,11 @@ pub fn int_to_str_bytes_common<T: Int>(num: T, radix: uint, sign: SignFormat, f:
* itself always printed using a base of 10.
* - `negative_zero` - Whether to treat the special value `-0` as
* `-0` or as `+0`.
- * - `sign` - How to emit the sign. Options are:
- * - `SignNone`: No sign at all. The exponent sign is also omitted.
- * - `SignNeg`: Only `-` on negative values.
- * - `SignAll`: Both `+` on positive, and `-` on negative numbers.
- * - `digits` - The amount of digits to use for emitting the
- * fractional part, if any. Options are:
- * - `DigAll`: All calculatable digits. Beware of bignums or
- * fractions!
- * - `DigMax(uint)`: Maximum N digits, truncating any trailing zeros.
- * - `DigExact(uint)`: Exactly N digits.
+ * - `sign` - How to emit the sign. See `SignFormat`.
+ * - `digits` - The amount of digits to use for emitting the fractional
+ * part, if any. See `SignificantDigits`.
* - `exp_format` - Whether or not to use the exponential (scientific) notation.
- * Options are:
- * - `ExpNone`: Do not use the exponential notation.
- * - `ExpDec`: Use the exponential notation with the exponent having a base of 10,
- * and exponent sign being `'e'` or `'E'` depending on the value of
- * the `exp_upper` argument. E.g. the number 1000 would be printed as 1e3.
- * - `ExpBin`: Use the exponential notation with the exponent having a base of 2,
- * and exponent sign being `'p'` or `'P'` depending on the value of
- * the `exp_upper` argument. E.g. the number 8 would be printed as 1p3.
+ * See `ExponentFormat`.
* - `exp_capital` - Whether or not to use a capital letter for the exponent sign, if
* exponential notation is desired.
*
diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index f270c7e7a74..3d05414c625 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -65,6 +65,7 @@ pub fn close(fd: int) -> int {
pub static TMPBUF_SZ : uint = 1000u;
static BUF_BYTES : uint = 2048u;
+/// Returns the current working directory.
#[cfg(unix)]
pub fn getcwd() -> Path {
use c_str::CString;
@@ -78,6 +79,7 @@ pub fn getcwd() -> Path {
}
}
+/// Returns the current working directory.
#[cfg(windows)]
pub fn getcwd() -> Path {
use libc::DWORD;
@@ -364,11 +366,19 @@ pub fn unsetenv(n: &str) {
_unsetenv(n);
}
+/// A low-level OS in-memory pipe.
+///
+/// This type is deprecated in favor of the types in `std::io::pipe`.
pub struct Pipe {
+ /// A file descriptor representing the input end of the pipe.
input: c_int,
- out: c_int
+ /// A file descriptor representing the output end of the pipe.
+ out: c_int,
}
+/// Creates a new low-level OS in-memory pipe.
+///
+/// This function is deprecated in favor of the types in `std::io::pipe`.
#[cfg(unix)]
pub fn pipe() -> Pipe {
unsafe {
@@ -379,6 +389,9 @@ pub fn pipe() -> Pipe {
}
}
+/// Creates a new low-level OS in-memory pipe.
+///
+/// This function is deprecated in favor of the types in `std::io::pipe`.
#[cfg(windows)]
pub fn pipe() -> Pipe {
unsafe {
@@ -908,6 +921,7 @@ fn round_up(from: uint, to: uint) -> uint {
}
}
+/// Returns the page size of the current architecture in bytes.
#[cfg(unix)]
pub fn page_size() -> uint {
unsafe {
@@ -915,6 +929,7 @@ pub fn page_size() -> uint {
}
}
+/// Returns the page size of the current architecture in bytes.
#[cfg(windows)]
pub fn page_size() -> uint {
unsafe {
@@ -1274,8 +1289,8 @@ impl Drop for MemoryMap {
}
}
+/// Various useful system-specific constants.
pub mod consts {
-
#[cfg(unix)]
pub use os::consts::unix::*;
@@ -1309,70 +1324,175 @@ pub mod consts {
#[cfg(target_arch = "mips")]
pub use os::consts::mips::*;
+ /// Constants for Unix systems.
pub mod unix {
+ /// A string describing the family that this operating system belongs
+ /// to: in this case, `unix`.
pub static FAMILY: &'static str = "unix";
}
+ /// Constants for Windows systems.
pub mod windows {
+ /// A string describing the family that this operating system belongs
+ /// to: in this case, `windows`.
pub static FAMILY: &'static str = "windows";
}
+ /// Constants for Mac OS systems.
pub mod macos {
+ /// A string describing the specific operating system in use: in this
+ /// case, `macos`.
pub static SYSNAME: &'static str = "macos";
+
+ /// Specifies the filename prefix used for shared libraries on this
+ /// platform: in this case, `lib`.
pub static DLL_PREFIX: &'static str = "lib";
+
+ /// Specifies the filename suffix used for shared libraries on this
+ /// platform: in this case, `.dylib`.
pub static DLL_SUFFIX: &'static str = ".dylib";
+
+ /// Specifies the file extension used for shared libraries on this
+ /// platform that goes after the dot: in this case, `dylib`.
pub static DLL_EXTENSION: &'static str = "dylib";
+
+ /// Specifies the filename suffix used for executable binaries on this
+ /// platform: in this case, the empty string.
pub static EXE_SUFFIX: &'static str = "";
+
+ /// Specifies the file extension, if any, used for executable binaries
+ /// on this platform: in this case, the empty string.
pub static EXE_EXTENSION: &'static str = "";
}
+ /// Constants for FreeBSD systems.
pub mod freebsd {
+ /// A string describing the specific operating system in use: in this
+ /// case, `freebsd`.
pub static SYSNAME: &'static str = "freebsd";
+
+ /// Specifies the filename prefix used for shared libraries on this
+ /// platform: in this case, `lib`.
pub static DLL_PREFIX: &'static str = "lib";
+
+ /// Specifies the filename suffix used for shared libraries on this
+ /// platform: in this case, `.so`.
pub static DLL_SUFFIX: &'static str = ".so";
+
+ /// Specifies the file extension used for shared libraries on this
+ /// platform that goes after the dot: in this case, `so`.
pub static DLL_EXTENSION: &'static str = "so";
+
+ /// Specifies the filename suffix used for executable binaries on this
+ /// platform: in this case, the empty string.
pub static EXE_SUFFIX: &'static str = "";
+
+ /// Specifies the file extension, if any, used for executable binaries
+ /// on this platform: in this case, the empty string.
pub static EXE_EXTENSION: &'static str = "";
}
+ /// Constants for GNU/Linux systems.
pub mod linux {
+ /// A string describing the specific operating system in use: in this
+ /// case, `linux`.
pub static SYSNAME: &'static str = "linux";
+
+ /// Specifies the filename prefix used for shared libraries on this
+ /// platform: in this case, `lib`.
pub static DLL_PREFIX: &'static str = "lib";
+
+ /// Specifies the filename suffix used for shared libraries on this
+ /// platform: in this case, `.so`.
pub static DLL_SUFFIX: &'static str = ".so";
+
+ /// Specifies the file extension used for shared libraries on this
+ /// platform that goes after the dot: in this case, `so`.
pub static DLL_EXTENSION: &'static str = "so";
+
+ /// Specifies the filename suffix used for executable binaries on this
+ /// platform: in this case, the empty string.
pub static EXE_SUFFIX: &'static str = "";
+
+ /// Specifies the file extension, if any, used for executable binaries
+ /// on this platform: in this case, the empty string.
pub static EXE_EXTENSION: &'static str = "";
}
+ /// Constants for Android systems.
pub mod android {
+ /// A string describing the specific operating system in use: in this
+ /// case, `android`.
pub static SYSNAME: &'static str = "android";
+
+ /// Specifies the filename prefix used for shared libraries on this
+ /// platform: in this case, `lib`.
pub static DLL_PREFIX: &'static str = "lib";
+
+ /// Specifies the filename suffix used for shared libraries on this
+ /// platform: in this case, `.so`.
pub static DLL_SUFFIX: &'static str = ".so";
+
+ /// Specifies the file extension used for shared libraries on this
+ /// platform that goes after the dot: in this case, `so`.
pub static DLL_EXTENSION: &'static str = "so";
+
+ /// Specifies the filename suffix used for executable binaries on this
+ /// platform: in this case, the empty string.
pub static EXE_SUFFIX: &'static str = "";
+
+ /// Specifies the file extension, if any, used for executable binaries
+ /// on this platform: in this case, the empty string.
pub static EXE_EXTENSION: &'static str = "";
}
+ /// Constants for 32-bit or 64-bit Windows systems.
pub mod win32 {
+ /// A string describing the specific operating system in use: in this
+ /// case, `win32`.
pub static SYSNAME: &'static str = "win32";
+
+ /// Specifies the filename prefix used for shared libraries on this
+ /// platform: in this case, the empty string.
pub static DLL_PREFIX: &'static str = "";
+
+ /// Specifies the filename suffix used for shared libraries on this
+ /// platform: in this case, `.dll`.
pub static DLL_SUFFIX: &'static str = ".dll";
+
+ /// Specifies the file extension used for shared libraries on this
+ /// platform that goes after the dot: in this case, `dll`.
pub static DLL_EXTENSION: &'static str = "dll";
+
+ /// Specifies the filename suffix used for executable binaries on this
+ /// platform: in this case, `.exe`.
pub static EXE_SUFFIX: &'static str = ".exe";
+
+ /// Specifies the file extension, if any, used for executable binaries
+ /// on this platform: in this case, `exe`.
pub static EXE_EXTENSION: &'static str = "exe";
}
-
+ /// Constants for Intel Architecture-32 (x86) architectures.
pub mod x86 {
+ /// A string describing the architecture in use: in this case, `x86`.
pub static ARCH: &'static str = "x86";
}
+ /// Constants for Intel 64/AMD64 (x86-64) architectures.
pub mod x86_64 {
+ /// A string describing the architecture in use: in this case,
+ /// `x86_64`.
pub static ARCH: &'static str = "x86_64";
}
+ /// Constants for Advanced RISC Machine (ARM) architectures.
pub mod arm {
+ /// A string describing the architecture in use: in this case, `ARM`.
pub static ARCH: &'static str = "arm";
}
+ /// Constants for Microprocessor without Interlocked Pipeline Stages
+ /// (MIPS) architectures.
pub mod mips {
+ /// A string describing the architecture in use: in this case, `MIPS`.
pub static ARCH: &'static str = "mips";
}
}
From fad77175e1811bdd0991ed00dc1a10ade8721a0b Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Tue, 25 Mar 2014 10:23:51 -0700
Subject: [PATCH 2/2] std: Touch various I/O documentation blocks
These are mostly touchups from the previous commit.
---
src/libstd/io/mod.rs | 2 --
src/libstd/io/net/udp.rs | 32 ++++++++++++++++++++++++++++++--
src/libstd/num/mod.rs | 10 +++++-----
src/libstd/os.rs | 12 ++++--------
4 files changed, 39 insertions(+), 17 deletions(-)
diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 3f959a8f780..3e193f246a8 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -302,7 +302,6 @@ impl fmt::Show for IoError {
/// A list specifying general categories of I/O error.
#[deriving(Eq, Clone, Show)]
-#[allow(missing_doc)]
pub enum IoErrorKind {
/// Any I/O error not part of this list.
OtherIoError,
@@ -1428,7 +1427,6 @@ pub struct FileStat {
/// structure. This information is not necessarily platform independent, and may
/// have different meanings or no meaning at all on some platforms.
#[unstable]
-#[allow(missing_doc)]
#[deriving(Hash)]
pub struct UnstableFileStat {
/// The ID of the device containing the file.
diff --git a/src/libstd/io/net/udp.rs b/src/libstd/io/net/udp.rs
index eabd00a6a2d..95241813257 100644
--- a/src/libstd/io/net/udp.rs
+++ b/src/libstd/io/net/udp.rs
@@ -14,8 +14,6 @@
//! The destination and binding addresses can either be an IPv4 or IPv6
//! address. There is no corresponding notion of a server because UDP is a
//! datagram protocol.
-//!
-//! A UDP connection implements the `Reader` and `Writer` traits.
use clone::Clone;
use result::{Ok, Err};
@@ -24,6 +22,36 @@ use io::{Reader, Writer, IoResult};
use rt::rtio::{RtioSocket, RtioUdpSocket, IoFactory, LocalIo};
/// A User Datagram Protocol 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.
+///
+/// # Example
+///
+/// ```rust,no_run
+/// # #[allow(unused_must_use)];
+/// use std::io::net::udp::UdpSocket;
+/// use std::io::net::ip::{Ipv4Addr, SocketAddr};
+///
+/// let addr = SocketAddr { ip: Ipv4Addr(127, 0, 0, 1), port: 34254 };
+/// let mut socket = match UdpSocket::bind(addr) {
+/// Ok(s) => s,
+/// Err(e) => fail!("couldn't bind socket: {}", e),
+/// };
+///
+/// let mut buf = [0, ..10];
+/// match socket.recvfrom(buf) {
+/// Ok((amt, src)) => {
+/// // Send a reply to the socket we received data from
+/// let buf = buf.mut_slice_to(amt);
+/// buf.reverse();
+/// socket.sendto(buf, src);
+/// }
+/// Err(e) => println!("couldn't receive a datagram: {}", e)
+/// }
+/// drop(socket); // close the socket
+/// ```
pub struct UdpSocket {
priv obj: ~RtioUdpSocket
}
diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs
index 31124db49b9..202e26e2c93 100644
--- a/src/libstd/num/mod.rs
+++ b/src/libstd/num/mod.rs
@@ -340,11 +340,11 @@ pub enum FPCategory {
}
/// Operations on primitive floating point numbers.
-///
-/// TODO(#5527): In a future version of Rust, many of these functions will become constants.
-///
-/// FIXME(#8888): Several of these functions have a parameter named `unused_self`. Removing it
-/// requires #8888 to be fixed.
+// FIXME(#5527): In a future version of Rust, many of these functions will
+// become constants.
+//
+// FIXME(#8888): Several of these functions have a parameter named
+// `unused_self`. Removing it requires #8888 to be fixed.
pub trait Float: Signed + Round + Primitive {
/// Returns the maximum of the two numbers.
fn max(self, other: Self) -> Self;
diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index 3d05414c625..eeebede6c58 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -367,18 +367,16 @@ pub fn unsetenv(n: &str) {
}
/// A low-level OS in-memory pipe.
-///
-/// This type is deprecated in favor of the types in `std::io::pipe`.
pub struct Pipe {
- /// A file descriptor representing the input end of the pipe.
+ /// A file descriptor representing the reading end of the pipe. Data written
+ /// on the `out` file descriptor can be read from this file descriptor.
input: c_int,
- /// A file descriptor representing the output end of the pipe.
+ /// A file descriptor representing the write end of the pipe. Data written
+ /// to this file descriptor can be read from the `input` file descriptor.
out: c_int,
}
/// Creates a new low-level OS in-memory pipe.
-///
-/// This function is deprecated in favor of the types in `std::io::pipe`.
#[cfg(unix)]
pub fn pipe() -> Pipe {
unsafe {
@@ -390,8 +388,6 @@ pub fn pipe() -> Pipe {
}
/// Creates a new low-level OS in-memory pipe.
-///
-/// This function is deprecated in favor of the types in `std::io::pipe`.
#[cfg(windows)]
pub fn pipe() -> Pipe {
unsafe {