diff --git a/src/libnative/io/mod.rs b/src/libnative/io/mod.rs index 615ed80a64866..e802c8f030126 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 52ca28c4ce890..46447e4a41638 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; + + /// 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; + + /// 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 d3ceba025ea90..c2a6510d6563a 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 67088e6f4f8c8..384e2ff2380ef 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 e5938569ea3aa..b9e933d0b14dd 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> 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(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(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(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(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 6bd8f119ba29b..3f959a8f7802e 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 dc24ead625898..fef4dd380e8c1 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 e262055632158..eabd00a6a2d07 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 { 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 { 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(&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 bd715858a01f0..9f04317a5c867 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 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 02dfaeb71645b..9984a3e5cdf3f 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 3ba3a9a134f68..323f24a52c31e 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 b95188b07650d..fc8c5f47073af 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 98379b5e5fb30..31124db49b90f 100644 --- a/src/libstd/num/mod.rs +++ b/src/libstd/num/mod.rs @@ -96,25 +96,56 @@ pub trait One: Mul { /// Returns the multiplicative identity, `1`. #[inline(always)] pub fn one() -> T { One::one() } -pub trait Signed: Num - + Neg { +/// Useful functions for signed numbers (i.e. numbers that can be negative). +pub trait Signed: Num + Neg { + /// 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(value: T) -> T { value.abs() } +#[inline(always)] +pub fn abs(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(x: T, y: T) -> T { x.abs_sub(&y) } +#[inline(always)] +pub fn abs_sub(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) -> uint; + + /// Returns the number of binary digits of exponent that this type supports. fn digits(unused_self: Option) -> 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) -> int; + + /// Returns the maximum binary exponent that this type can represent. fn max_exp(unused_self: Option) -> int; + + /// Returns the minimum base-10 exponent that this type can represent. fn min_10_exp(unused_self: Option) -> int; + + /// Returns the maximum base-10 exponent that this type can represent. fn max_10_exp(unused_self: Option) -> 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; + + /// 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; - fn ln_10() -> Self; - // Fractional functions + /// 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(n: T) -> Option { 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(n: T) -> Option; } @@ -1059,19 +1164,30 @@ impl Saturating for T { } } +/// Performs addition that returns `None` instead of wrapping around on overflow. pub trait CheckedAdd: Add { + /// Adds two numbers, checking for overflow. If overflow happens, `None` is returned. fn checked_add(&self, v: &Self) -> Option; } +/// Performs subtraction that returns `None` instead of wrapping around on underflow. pub trait CheckedSub: Sub { + /// Subtracts two numbers, checking for underflow. If underflow happens, `None` is returned. fn checked_sub(&self, v: &Self) -> Option; } +/// Performs multiplication that returns `None` instead of wrapping around on underflow or +/// overflow. pub trait CheckedMul: Mul { + /// Multiplies two numbers, checking for underflow or overflow. If underflow or overflow + /// happens, `None` is returned. fn checked_mul(&self, v: &Self) -> Option; } +/// Performs division that returns `None` instead of wrapping around on underflow or overflow. pub trait CheckedDiv: Div { + /// Divides two numbers, checking for underflow or overflow. If underflow or overflow happens, + /// `None` is returned. fn checked_div(&self, v: &Self) -> Option; } diff --git a/src/libstd/num/strconv.rs b/src/libstd/num/strconv.rs index 9d3d012bae7b5..9f9a9ec8e2e3b 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; + + /// Returns the infinite value. fn inf() -> Option; + + /// Returns the negative infinite value. fn neg_inf() -> Option; + + /// Returns -0.0. fn neg_zero() -> Option; + /// 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(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 f270c7e7a743c..3d05414c62590 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"; } }