diff options
Diffstat (limited to 'src/libstd')
28 files changed, 1058 insertions, 1062 deletions
diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index 9c7967d17bb..50a00714ea0 100644 --- a/src/libstd/collections/hash/map.rs +++ b/src/libstd/collections/hash/map.rs @@ -1376,7 +1376,7 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> { /// Takes the value out of the entry, and returns it pub fn take(self) -> V { - let (_, _, v) = self.elem.take(); + let (_, v) = pop_internal(self.elem); v } } @@ -1433,6 +1433,7 @@ mod test_map { use hash; use iter::{Iterator,range_inclusive,range_step_inclusive}; use cell::RefCell; + use rand::{weak_rng, Rng}; struct KindaIntLike(int); @@ -2073,4 +2074,37 @@ mod test_map { assert_eq!(map.get(&10).unwrap(), &1000); assert_eq!(map.len(), 6); } + + #[test] + fn test_entry_take_doesnt_corrupt() { + // Test for #19292 + fn check(m: &HashMap<int, ()>) { + for k in m.keys() { + assert!(m.contains_key(k), + "{} is in keys() but not in the map?", k); + } + } + + let mut m = HashMap::new(); + let mut rng = weak_rng(); + + // Populate the map with some items. + for _ in range(0u, 50) { + let x = rng.gen_range(-10, 10); + m.insert(x, ()); + } + + for i in range(0u, 1000) { + let x = rng.gen_range(-10, 10); + match m.entry(x) { + Vacant(_) => {}, + Occupied(e) => { + println!("{}: remove {}", i, x); + e.take(); + }, + } + + check(&m); + } + } } diff --git a/src/libstd/comm/select.rs b/src/libstd/comm/select.rs index 621556f75ce..3191519815a 100644 --- a/src/libstd/comm/select.rs +++ b/src/libstd/comm/select.rs @@ -84,7 +84,7 @@ pub struct Handle<'rx, T:'rx> { next: *mut Handle<'static, ()>, prev: *mut Handle<'static, ()>, added: bool, - packet: &'rx Packet+'rx, + packet: &'rx (Packet+'rx), // due to our fun transmutes, we be sure to place this at the end. (nothing // previous relies on T) diff --git a/src/libstd/dynamic_lib.rs b/src/libstd/dynamic_lib.rs index 4b868f6a95b..3cd0c0eeaf2 100644 --- a/src/libstd/dynamic_lib.rs +++ b/src/libstd/dynamic_lib.rs @@ -8,13 +8,9 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! - -Dynamic library facilities. - -A simple wrapper over the platform's dynamic library facilities - -*/ +//! Dynamic library facilities. +//! +//! A simple wrapper over the platform's dynamic library facilities #![experimental] #![allow(missing_docs)] diff --git a/src/libstd/failure.rs b/src/libstd/failure.rs index 32a8be22902..d839c1484e5 100644 --- a/src/libstd/failure.rs +++ b/src/libstd/failure.rs @@ -40,7 +40,7 @@ impl Writer for Stdio { } } -pub fn on_fail(obj: &Any + Send, file: &'static str, line: uint) { +pub fn on_fail(obj: &(Any+Send), file: &'static str, line: uint) { let msg = match obj.downcast_ref::<&'static str>() { Some(s) => *s, None => match obj.downcast_ref::<String>() { diff --git a/src/libstd/fmt.rs b/src/libstd/fmt.rs index c817e6a806b..7e1bfd704a9 100644 --- a/src/libstd/fmt.rs +++ b/src/libstd/fmt.rs @@ -10,392 +10,397 @@ // // ignore-lexer-test FIXME #15679 -/*! - -Utilities for formatting and printing strings - -This module contains the runtime support for the `format!` syntax extension. -This macro is implemented in the compiler to emit calls to this module in order -to format arguments at runtime into strings and streams. - -The functions contained in this module should not normally be used in everyday -use cases of `format!`. The assumptions made by these functions are unsafe for -all inputs, and the compiler performs a large amount of validation on the -arguments to `format!` in order to ensure safety at runtime. While it is -possible to call these functions directly, it is not recommended to do so in the -general case. - -## Usage - -The `format!` macro is intended to be familiar to those coming from C's -printf/fprintf functions or Python's `str.format` function. In its current -revision, the `format!` macro returns a `String` type which is the result of -the formatting. In the future it will also be able to pass in a stream to -format arguments directly while performing minimal allocations. - -Some examples of the `format!` extension are: - -```rust -# fn main() { -format!("Hello"); // => "Hello" -format!("Hello, {}!", "world"); // => "Hello, world!" -format!("The number is {}", 1i); // => "The number is 1" -format!("{}", (3i, 4i)); // => "(3, 4)" -format!("{value}", value=4i); // => "4" -format!("{} {}", 1i, 2u); // => "1 2" -# } -``` - -From these, you can see that the first argument is a format string. It is -required by the compiler for this to be a string literal; it cannot be a -variable passed in (in order to perform validity checking). The compiler will -then parse the format string and determine if the list of arguments provided is -suitable to pass to this format string. - -### Positional parameters - -Each formatting argument is allowed to specify which value argument it's -referencing, and if omitted it is assumed to be "the next argument". For -example, the format string `{} {} {}` would take three parameters, and they -would be formatted in the same order as they're given. The format string -`{2} {1} {0}`, however, would format arguments in reverse order. - -Things can get a little tricky once you start intermingling the two types of -positional specifiers. The "next argument" specifier can be thought of as an -iterator over the argument. Each time a "next argument" specifier is seen, the -iterator advances. This leads to behavior like this: - -```rust -format!("{1} {} {0} {}", 1i, 2i); // => "2 1 1 2" -``` - -The internal iterator over the argument has not been advanced by the time the -first `{}` is seen, so it prints the first argument. Then upon reaching the -second `{}`, the iterator has advanced forward to the second argument. -Essentially, parameters which explicitly name their argument do not affect -parameters which do not name an argument in terms of positional specifiers. - -A format string is required to use all of its arguments, otherwise it is a -compile-time error. You may refer to the same argument more than once in the -format string, although it must always be referred to with the same type. - -### Named parameters - -Rust itself does not have a Python-like equivalent of named parameters to a -function, but the `format!` macro is a syntax extension which allows it to -leverage named parameters. Named parameters are listed at the end of the -argument list and have the syntax: - -```text -identifier '=' expression -``` - -For example, the following `format!` expressions all use named argument: - -```rust -# fn main() { -format!("{argument}", argument = "test"); // => "test" -format!("{name} {}", 1i, name = 2i); // => "2 1" -format!("{a} {c} {b}", a="a", b=(), c=3i); // => "a 3 ()" -# } -``` - -It is illegal to put positional parameters (those without names) after arguments -which have names. Like with positional parameters, it is illegal to provide -named parameters that are unused by the format string. - -### Argument types - -Each argument's type is dictated by the format string. It is a requirement that every argument is -only ever referred to by one type. For example, this is an invalid format string: - -```text -{0:x} {0:o} -``` - -This is invalid because the first argument is both referred to as a hexidecimal as well as an -octal. - -There are various parameters which do require a particular type, however. Namely if the syntax -`{:.*}` is used, then the number of characters to print precedes the actual object being formatted, -and the number of characters must have the type `uint`. Although a `uint` can be printed with -`{}`, it is illegal to reference an argument as such. For example this is another invalid -format string: - -```text -{:.*} {0} -``` - -### Formatting traits - -When requesting that an argument be formatted with a particular type, you are -actually requesting that an argument ascribes to a particular trait. This allows -multiple actual types to be formatted via `{:x}` (like `i8` as well as `int`). -The current mapping of types to traits is: - -* *nothing* ⇒ `Show` -* `o` ⇒ `Octal` -* `x` ⇒ `LowerHex` -* `X` ⇒ `UpperHex` -* `p` ⇒ `Pointer` -* `b` ⇒ `Binary` -* `e` ⇒ `LowerExp` -* `E` ⇒ `UpperExp` - -What this means is that any type of argument which implements the -`std::fmt::Binary` trait can then be formatted with `{:b}`. Implementations are -provided for these traits for a number of primitive types by the standard -library as well. If no format is specified (as in `{}` or `{:6}`), then the -format trait used is the `Show` trait. This is one of the more commonly -implemented traits when formatting a custom type. - -When implementing a format trait for your own type, you will have to implement a -method of the signature: - -```rust -# use std::fmt; -# struct Foo; // our custom type -# impl fmt::Show for Foo { -fn fmt(&self, f: &mut std::fmt::Formatter) -> fmt::Result { -# write!(f, "testing, testing") -# } } -``` - -Your type will be passed as `self` by-reference, and then the function should -emit output into the `f.buf` stream. It is up to each format trait -implementation to correctly adhere to the requested formatting parameters. The -values of these parameters will be listed in the fields of the `Formatter` -struct. In order to help with this, the `Formatter` struct also provides some -helper methods. - -Additionally, the return value of this function is `fmt::Result` which is a -typedef to `Result<(), IoError>` (also known as `IoResult<()>`). Formatting -implementations should ensure that they return errors from `write!` correctly -(propagating errors upward). - -An example of implementing the formatting traits would look -like: - -```rust -use std::fmt; -use std::f64; -use std::num::Float; - -struct Vector2D { - x: int, - y: int, -} - -impl fmt::Show for Vector2D { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - // The `f` value implements the `Writer` trait, which is what the - // write! macro is expecting. Note that this formatting ignores the - // various flags provided to format strings. - write!(f, "({}, {})", self.x, self.y) - } -} - -// Different traits allow different forms of output of a type. The meaning of -// this format is to print the magnitude of a vector. -impl fmt::Binary for Vector2D { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - let magnitude = (self.x * self.x + self.y * self.y) as f64; - let magnitude = magnitude.sqrt(); - - // Respect the formatting flags by using the helper method - // `pad_integral` on the Formatter object. See the method documentation - // for details, and the function `pad` can be used to pad strings. - let decimals = f.precision().unwrap_or(3); - let string = f64::to_str_exact(magnitude, decimals); - f.pad_integral(true, "", string.as_bytes()) - } -} - -fn main() { - let myvector = Vector2D { x: 3, y: 4 }; - - println!("{}", myvector); // => "(3, 4)" - println!("{:10.3b}", myvector); // => " 5.000" -} -``` - -### Related macros - -There are a number of related macros in the `format!` family. The ones that are -currently implemented are: - -```ignore -format! // described above -write! // first argument is a &mut io::Writer, the destination -writeln! // same as write but appends a newline -print! // the format string is printed to the standard output -println! // same as print but appends a newline -format_args! // described below. -``` - -#### `write!` - -This and `writeln` are two macros which are used to emit the format string to a -specified stream. This is used to prevent intermediate allocations of format -strings and instead directly write the output. Under the hood, this function is -actually invoking the `write` function defined in this module. Example usage is: - -```rust -# #![allow(unused_must_use)] -use std::io; - -let mut w = Vec::new(); -write!(&mut w as &mut io::Writer, "Hello {}!", "world"); -``` - -#### `print!` - -This and `println` emit their output to stdout. Similarly to the `write!` macro, -the goal of these macros is to avoid intermediate allocations when printing -output. Example usage is: - -```rust -print!("Hello {}!", "world"); -println!("I have a newline {}", "character at the end"); -``` - -#### `format_args!` -This is a curious macro which is used to safely pass around -an opaque object describing the format string. This object -does not require any heap allocations to create, and it only -references information on the stack. Under the hood, all of -the related macros are implemented in terms of this. First -off, some example usage is: - -``` -use std::fmt; -use std::io; - -# #[allow(unused_must_use)] -# fn main() { -format_args!(fmt::format, "this returns {}", "String"); - -let some_writer: &mut io::Writer = &mut io::stdout(); -format_args!(|args| { write!(some_writer, "{}", args) }, "print with a {}", "closure"); - -fn my_fmt_fn(args: &fmt::Arguments) { - write!(&mut io::stdout(), "{}", args); -} -format_args!(my_fmt_fn, "or a {} too", "function"); -# } -``` - -The first argument of the `format_args!` macro is a function (or closure) which -takes one argument of type `&fmt::Arguments`. This structure can then be -passed to the `write` and `format` functions inside this module in order to -process the format string. The goal of this macro is to even further prevent -intermediate allocations when dealing formatting strings. - -For example, a logging library could use the standard formatting syntax, but it -would internally pass around this structure until it has been determined where -output should go to. - -It is unsafe to programmatically create an instance of `fmt::Arguments` because -the operations performed when executing a format string require the compile-time -checks provided by the compiler. The `format_args!` macro is the only method of -safely creating these structures, but they can be unsafely created with the -constructor provided. - -## Syntax - -The syntax for the formatting language used is drawn from other languages, so it -should not be too alien. Arguments are formatted with python-like syntax, -meaning that arguments are surrounded by `{}` instead of the C-like `%`. The -actual grammar for the formatting syntax is: - -```text -format_string := <text> [ format <text> ] * -format := '{' [ argument ] [ ':' format_spec ] '}' -argument := integer | identifier - -format_spec := [[fill]align][sign]['#'][0][width]['.' precision][type] -fill := character -align := '<' | '^' | '>' -sign := '+' | '-' -width := count -precision := count | '*' -type := identifier | '' -count := parameter | integer -parameter := integer '$' -``` - -## Formatting Parameters - -Each argument being formatted can be transformed by a number of formatting -parameters (corresponding to `format_spec` in the syntax above). These -parameters affect the string representation of what's being formatted. This -syntax draws heavily from Python's, so it may seem a bit familiar. - -### Fill/Alignment - -The fill character is provided normally in conjunction with the `width` -parameter. This indicates that if the value being formatted is smaller than -`width` some extra characters will be printed around it. The extra characters -are specified by `fill`, and the alignment can be one of two options: - -* `<` - the argument is left-aligned in `width` columns -* `^` - the argument is center-aligned in `width` columns -* `>` - the argument is right-aligned in `width` columns - -### Sign/#/0 - -These can all be interpreted as flags for a particular formatter. - -* '+' - This is intended for numeric types and indicates that the sign should - always be printed. Positive signs are never printed by default, and the - negative sign is only printed by default for the `Signed` trait. This - flag indicates that the correct sign (+ or -) should always be printed. -* '-' - Currently not used -* '#' - This flag is indicates that the "alternate" form of printing should be - used. By default, this only applies to the integer formatting traits and - performs like: - * `x` - precedes the argument with a "0x" - * `X` - precedes the argument with a "0x" - * `t` - precedes the argument with a "0b" - * `o` - precedes the argument with a "0o" -* '0' - This is used to indicate for integer formats that the padding should - both be done with a `0` character as well as be sign-aware. A format - like `{:08d}` would yield `00000001` for the integer `1`, while the same - format would yield `-0000001` for the integer `-1`. Notice that the - negative version has one fewer zero than the positive version. - -### Width - -This is a parameter for the "minimum width" that the format should take up. If -the value's string does not fill up this many characters, then the padding -specified by fill/alignment will be used to take up the required space. - -The default fill/alignment for non-numerics is a space and left-aligned. The -defaults for numeric formatters is also a space but with right-alignment. If the -'0' flag is specified for numerics, then the implicit fill character is '0'. - -The value for the width can also be provided as a `uint` in the list of -parameters by using the `2$` syntax indicating that the second argument is a -`uint` specifying the width. - -### Precision - -For non-numeric types, this can be considered a "maximum width". If the -resulting string is longer than this width, then it is truncated down to this -many characters and only those are emitted. - -For integral types, this has no meaning currently. - -For floating-point types, this indicates how many digits after the decimal point -should be printed. - -## Escaping - -The literal characters `{` and `}` may be included in a string by preceding them -with the same character. For example, the `{` character is escaped with `{{` and -the `}` character is escaped with `}}`. - -*/ +//! Utilities for formatting and printing strings +//! +//! This module contains the runtime support for the `format!` syntax extension. +//! This macro is implemented in the compiler to emit calls to this module in +//! order to format arguments at runtime into strings and streams. +//! +//! The functions contained in this module should not normally be used in +//! everyday use cases of `format!`. The assumptions made by these functions are +//! unsafe for all inputs, and the compiler performs a large amount of +//! validation on the arguments to `format!` in order to ensure safety at +//! runtime. While it is possible to call these functions directly, it is not +//! recommended to do so in the general case. +//! +//! ## Usage +//! +//! The `format!` macro is intended to be familiar to those coming from C's +//! printf/fprintf functions or Python's `str.format` function. In its current +//! revision, the `format!` macro returns a `String` type which is the result of +//! the formatting. In the future it will also be able to pass in a stream to +//! format arguments directly while performing minimal allocations. +//! +//! Some examples of the `format!` extension are: +//! +//! ```rust +//! # fn main() { +//! format!("Hello"); // => "Hello" +//! format!("Hello, {}!", "world"); // => "Hello, world!" +//! format!("The number is {}", 1i); // => "The number is 1" +//! format!("{}", (3i, 4i)); // => "(3, 4)" +//! format!("{value}", value=4i); // => "4" +//! format!("{} {}", 1i, 2u); // => "1 2" +//! # } +//! ``` +//! +//! From these, you can see that the first argument is a format string. It is +//! required by the compiler for this to be a string literal; it cannot be a +//! variable passed in (in order to perform validity checking). The compiler +//! will then parse the format string and determine if the list of arguments +//! provided is suitable to pass to this format string. +//! +//! ### Positional parameters +//! +//! Each formatting argument is allowed to specify which value argument it's +//! referencing, and if omitted it is assumed to be "the next argument". For +//! example, the format string `{} {} {}` would take three parameters, and they +//! would be formatted in the same order as they're given. The format string +//! `{2} {1} {0}`, however, would format arguments in reverse order. +//! +//! Things can get a little tricky once you start intermingling the two types of +//! positional specifiers. The "next argument" specifier can be thought of as an +//! iterator over the argument. Each time a "next argument" specifier is seen, +//! the iterator advances. This leads to behavior like this: +//! +//! ```rust +//! format!("{1} {} {0} {}", 1i, 2i); // => "2 1 1 2" +//! ``` +//! +//! The internal iterator over the argument has not been advanced by the time +//! the first `{}` is seen, so it prints the first argument. Then upon reaching +//! the second `{}`, the iterator has advanced forward to the second argument. +//! Essentially, parameters which explicitly name their argument do not affect +//! parameters which do not name an argument in terms of positional specifiers. +//! +//! A format string is required to use all of its arguments, otherwise it is a +//! compile-time error. You may refer to the same argument more than once in the +//! format string, although it must always be referred to with the same type. +//! +//! ### Named parameters +//! +//! Rust itself does not have a Python-like equivalent of named parameters to a +//! function, but the `format!` macro is a syntax extension which allows it to +//! leverage named parameters. Named parameters are listed at the end of the +//! argument list and have the syntax: +//! +//! ```text +//! identifier '=' expression +//! ``` +//! +//! For example, the following `format!` expressions all use named argument: +//! +//! ```rust +//! # fn main() { +//! format!("{argument}", argument = "test"); // => "test" +//! format!("{name} {}", 1i, name = 2i); // => "2 1" +//! format!("{a} {c} {b}", a="a", b=(), c=3i); // => "a 3 ()" +//! # } +//! ``` +//! +//! It is illegal to put positional parameters (those without names) after +//! arguments which have names. Like with positional parameters, it is illegal +//! to provide named parameters that are unused by the format string. +//! +//! ### Argument types +//! +//! Each argument's type is dictated by the format string. It is a requirement +//! that every argument is only ever referred to by one type. For example, this +//! is an invalid format string: +//! +//! ```text +//! {0:x} {0:o} +//! ``` +//! +//! This is invalid because the first argument is both referred to as a +//! hexidecimal as well as an +//! octal. +//! +//! There are various parameters which do require a particular type, however. +//! Namely if the syntax `{:.*}` is used, then the number of characters to print +//! precedes the actual object being formatted, and the number of characters +//! must have the type `uint`. Although a `uint` can be printed with `{}`, it is +//! illegal to reference an argument as such. For example this is another +//! invalid format string: +//! +//! ```text +//! {:.*} {0} +//! ``` +//! +//! ### Formatting traits +//! +//! When requesting that an argument be formatted with a particular type, you +//! are actually requesting that an argument ascribes to a particular trait. +//! This allows multiple actual types to be formatted via `{:x}` (like `i8` as +//! well as `int`). The current mapping of types to traits is: +//! +//! * *nothing* ⇒ `Show` +//! * `o` ⇒ `Octal` +//! * `x` ⇒ `LowerHex` +//! * `X` ⇒ `UpperHex` +//! * `p` ⇒ `Pointer` +//! * `b` ⇒ `Binary` +//! * `e` ⇒ `LowerExp` +//! * `E` ⇒ `UpperExp` +//! +//! What this means is that any type of argument which implements the +//! `std::fmt::Binary` trait can then be formatted with `{:b}`. Implementations +//! are provided for these traits for a number of primitive types by the +//! standard library as well. If no format is specified (as in `{}` or `{:6}`), +//! then the format trait used is the `Show` trait. This is one of the more +//! commonly implemented traits when formatting a custom type. +//! +//! When implementing a format trait for your own type, you will have to +//! implement a method of the signature: +//! +//! ```rust +//! # use std::fmt; +//! # struct Foo; // our custom type +//! # impl fmt::Show for Foo { +//! fn fmt(&self, f: &mut std::fmt::Formatter) -> fmt::Result { +//! # write!(f, "testing, testing") +//! # } } +//! ``` +//! +//! Your type will be passed as `self` by-reference, and then the function +//! should emit output into the `f.buf` stream. It is up to each format trait +//! implementation to correctly adhere to the requested formatting parameters. +//! The values of these parameters will be listed in the fields of the +//! `Formatter` struct. In order to help with this, the `Formatter` struct also +//! provides some helper methods. +//! +//! Additionally, the return value of this function is `fmt::Result` which is a +//! typedef to `Result<(), IoError>` (also known as `IoResult<()>`). Formatting +//! implementations should ensure that they return errors from `write!` +//! correctly (propagating errors upward). +//! +//! An example of implementing the formatting traits would look +//! like: +//! +//! ```rust +//! use std::fmt; +//! use std::f64; +//! use std::num::Float; +//! +//! struct Vector2D { +//! x: int, +//! y: int, +//! } +//! +//! impl fmt::Show for Vector2D { +//! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { +//! // The `f` value implements the `Writer` trait, which is what the +//! // write! macro is expecting. Note that this formatting ignores the +//! // various flags provided to format strings. +//! write!(f, "({}, {})", self.x, self.y) +//! } +//! } +//! +//! // Different traits allow different forms of output of a type. The meaning +//! // of this format is to print the magnitude of a vector. +//! impl fmt::Binary for Vector2D { +//! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { +//! let magnitude = (self.x * self.x + self.y * self.y) as f64; +//! let magnitude = magnitude.sqrt(); +//! +//! // Respect the formatting flags by using the helper method +//! // `pad_integral` on the Formatter object. See the method documentation +//! // for details, and the function `pad` can be used to pad strings. +//! let decimals = f.precision().unwrap_or(3); +//! let string = f64::to_str_exact(magnitude, decimals); +//! f.pad_integral(true, "", string.as_bytes()) +//! } +//! } +//! +//! fn main() { +//! let myvector = Vector2D { x: 3, y: 4 }; +//! +//! println!("{}", myvector); // => "(3, 4)" +//! println!("{:10.3b}", myvector); // => " 5.000" +//! } +//! ``` +//! +//! ### Related macros +//! +//! There are a number of related macros in the `format!` family. The ones that +//! are currently implemented are: +//! +//! ```ignore +//! format! // described above +//! write! // first argument is a &mut io::Writer, the destination +//! writeln! // same as write but appends a newline +//! print! // the format string is printed to the standard output +//! println! // same as print but appends a newline +//! format_args! // described below. +//! ``` +//! +//! #### `write!` +//! +//! This and `writeln` are two macros which are used to emit the format string +//! to a specified stream. This is used to prevent intermediate allocations of +//! format strings and instead directly write the output. Under the hood, this +//! function is actually invoking the `write` function defined in this module. +//! Example usage is: +//! +//! ```rust +//! # #![allow(unused_must_use)] +//! use std::io; +//! +//! let mut w = Vec::new(); +//! write!(&mut w as &mut io::Writer, "Hello {}!", "world"); +//! ``` +//! +//! #### `print!` +//! +//! This and `println` emit their output to stdout. Similarly to the `write!` +//! macro, the goal of these macros is to avoid intermediate allocations when +//! printing output. Example usage is: +//! +//! ```rust +//! print!("Hello {}!", "world"); +//! println!("I have a newline {}", "character at the end"); +//! ``` +//! +//! #### `format_args!` +//! This is a curious macro which is used to safely pass around +//! an opaque object describing the format string. This object +//! does not require any heap allocations to create, and it only +//! references information on the stack. Under the hood, all of +//! the related macros are implemented in terms of this. First +//! off, some example usage is: +//! +//! ``` +//! use std::fmt; +//! use std::io; +//! +//! # #[allow(unused_must_use)] +//! # fn main() { +//! format_args!(fmt::format, "this returns {}", "String"); +//! +//! let some_writer: &mut io::Writer = &mut io::stdout(); +//! format_args!(|args| { write!(some_writer, "{}", args) }, +//! "print with a {}", "closure"); +//! +//! fn my_fmt_fn(args: &fmt::Arguments) { +//! write!(&mut io::stdout(), "{}", args); +//! } +//! format_args!(my_fmt_fn, "or a {} too", "function"); +//! # } +//! ``` +//! +//! The first argument of the `format_args!` macro is a function (or closure) +//! which takes one argument of type `&fmt::Arguments`. This structure can then +//! be passed to the `write` and `format` functions inside this module in order +//! to process the format string. The goal of this macro is to even further +//! prevent intermediate allocations when dealing formatting strings. +//! +//! For example, a logging library could use the standard formatting syntax, but +//! it would internally pass around this structure until it has been determined +//! where output should go to. +//! +//! It is unsafe to programmatically create an instance of `fmt::Arguments` +//! because the operations performed when executing a format string require the +//! compile-time checks provided by the compiler. The `format_args!` macro is +//! the only method of safely creating these structures, but they can be +//! unsafely created with the constructor provided. +//! +//! ## Syntax +//! +//! The syntax for the formatting language used is drawn from other languages, +//! so it should not be too alien. Arguments are formatted with python-like +//! syntax, meaning that arguments are surrounded by `{}` instead of the C-like +//! `%`. The actual grammar for the formatting syntax is: +//! +//! ```text +//! format_string := <text> [ format <text> ] * +//! format := '{' [ argument ] [ ':' format_spec ] '}' +//! argument := integer | identifier +//! +//! format_spec := [[fill]align][sign]['#'][0][width]['.' precision][type] +//! fill := character +//! align := '<' | '^' | '>' +//! sign := '+' | '-' +//! width := count +//! precision := count | '*' +//! type := identifier | '' +//! count := parameter | integer +//! parameter := integer '$' +//! ``` +//! +//! ## Formatting Parameters +//! +//! Each argument being formatted can be transformed by a number of formatting +//! parameters (corresponding to `format_spec` in the syntax above). These +//! parameters affect the string representation of what's being formatted. This +//! syntax draws heavily from Python's, so it may seem a bit familiar. +//! +//! ### Fill/Alignment +//! +//! The fill character is provided normally in conjunction with the `width` +//! parameter. This indicates that if the value being formatted is smaller than +//! `width` some extra characters will be printed around it. The extra +//! characters are specified by `fill`, and the alignment can be one of two +//! options: +//! +//! * `<` - the argument is left-aligned in `width` columns +//! * `^` - the argument is center-aligned in `width` columns +//! * `>` - the argument is right-aligned in `width` columns +//! +//! ### Sign/#/0 +//! +//! These can all be interpreted as flags for a particular formatter. +//! +//! * '+' - This is intended for numeric types and indicates that the sign +//! should always be printed. Positive signs are never printed by +//! default, and the negative sign is only printed by default for the +//! `Signed` trait. This flag indicates that the correct sign (+ or -) +//! should always be printed. +//! * '-' - Currently not used +//! * '#' - This flag is indicates that the "alternate" form of printing should +//! be used. By default, this only applies to the integer formatting +//! traits and performs like: +//! * `x` - precedes the argument with a "0x" +//! * `X` - precedes the argument with a "0x" +//! * `t` - precedes the argument with a "0b" +//! * `o` - precedes the argument with a "0o" +//! * '0' - This is used to indicate for integer formats that the padding should +//! both be done with a `0` character as well as be sign-aware. A format +//! like `{:08d}` would yield `00000001` for the integer `1`, while the +//! same format would yield `-0000001` for the integer `-1`. Notice that +//! the negative version has one fewer zero than the positive version. +//! +//! ### Width +//! +//! This is a parameter for the "minimum width" that the format should take up. +//! If the value's string does not fill up this many characters, then the +//! padding specified by fill/alignment will be used to take up the required +//! space. +//! +//! The default fill/alignment for non-numerics is a space and left-aligned. The +//! defaults for numeric formatters is also a space but with right-alignment. If +//! the '0' flag is specified for numerics, then the implicit fill character is +//! '0'. +//! +//! The value for the width can also be provided as a `uint` in the list of +//! parameters by using the `2$` syntax indicating that the second argument is a +//! `uint` specifying the width. +//! +//! ### Precision +//! +//! For non-numeric types, this can be considered a "maximum width". If the +//! resulting string is longer than this width, then it is truncated down to +//! this many characters and only those are emitted. +//! +//! For integral types, this has no meaning currently. +//! +//! For floating-point types, this indicates how many digits after the decimal +//! point should be printed. +//! +//! ## Escaping +//! +//! The literal characters `{` and `}` may be included in a string by preceding +//! them with the same character. For example, the `{` character is escaped with +//! `{{` and the `}` character is escaped with `}}`. #![experimental] diff --git a/src/libstd/hash.rs b/src/libstd/hash.rs index e4017ea5a47..ac68e1ef121 100644 --- a/src/libstd/hash.rs +++ b/src/libstd/hash.rs @@ -8,58 +8,56 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! - * Generic hashing support. - * - * This module provides a generic way to compute the hash of a value. The - * simplest way to make a type hashable is to use `#[deriving(Hash)]`: - * - * # Example - * - * ```rust - * use std::hash; - * use std::hash::Hash; - * - * #[deriving(Hash)] - * struct Person { - * id: uint, - * name: String, - * phone: u64, - * } - * - * let person1 = Person { id: 5, name: "Janet".to_string(), phone: 555_666_7777 }; - * let person2 = Person { id: 5, name: "Bob".to_string(), phone: 555_666_7777 }; - * - * assert!(hash::hash(&person1) != hash::hash(&person2)); - * ``` - * - * If you need more control over how a value is hashed, you need to implement - * the trait `Hash`: - * - * ```rust - * use std::hash; - * use std::hash::Hash; - * use std::hash::sip::SipState; - * - * struct Person { - * id: uint, - * name: String, - * phone: u64, - * } - * - * impl Hash for Person { - * fn hash(&self, state: &mut SipState) { - * self.id.hash(state); - * self.phone.hash(state); - * } - * } - * - * let person1 = Person { id: 5, name: "Janet".to_string(), phone: 555_666_7777 }; - * let person2 = Person { id: 5, name: "Bob".to_string(), phone: 555_666_7777 }; - * - * assert!(hash::hash(&person1) == hash::hash(&person2)); - * ``` - */ +//! Generic hashing support. +//! +//! This module provides a generic way to compute the hash of a value. The +//! simplest way to make a type hashable is to use `#[deriving(Hash)]`: +//! +//! # Example +//! +//! ```rust +//! use std::hash; +//! use std::hash::Hash; +//! +//! #[deriving(Hash)] +//! struct Person { +//! id: uint, +//! name: String, +//! phone: u64, +//! } +//! +//! let person1 = Person { id: 5, name: "Janet".to_string(), phone: 555_666_7777 }; +//! let person2 = Person { id: 5, name: "Bob".to_string(), phone: 555_666_7777 }; +//! +//! assert!(hash::hash(&person1) != hash::hash(&person2)); +//! ``` +//! +//! If you need more control over how a value is hashed, you need to implement +//! the trait `Hash`: +//! +//! ```rust +//! use std::hash; +//! use std::hash::Hash; +//! use std::hash::sip::SipState; +//! +//! struct Person { +//! id: uint, +//! name: String, +//! phone: u64, +//! } +//! +//! impl Hash for Person { +//! fn hash(&self, state: &mut SipState) { +//! self.id.hash(state); +//! self.phone.hash(state); +//! } +//! } +//! +//! let person1 = Person { id: 5, name: "Janet".to_string(), phone: 555_666_7777 }; +//! let person2 = Person { id: 5, name: "Bob".to_string(), phone: 555_666_7777 }; +//! +//! assert!(hash::hash(&person1) == hash::hash(&person2)); +//! ``` #![experimental] diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs index 025033a112c..e92bad592d1 100644 --- a/src/libstd/io/buffered.rs +++ b/src/libstd/io/buffered.rs @@ -75,10 +75,14 @@ impl<R: Reader> BufferedReader<R> { } /// Gets a reference to the underlying reader. + pub fn get_ref<'a>(&self) -> &R { &self.inner } + + /// Gets a mutable reference to the underlying reader. /// - /// This type does not expose the ability to get a mutable reference to the - /// underlying reader because that could possibly corrupt the buffer. - pub fn get_ref<'a>(&'a self) -> &'a R { &self.inner } + /// ## Warning + /// + /// It is inadvisable to directly read from the underlying reader. + pub fn get_mut(&mut self) -> &mut R { &mut self.inner } /// Unwraps this `BufferedReader`, returning the underlying reader. /// @@ -176,10 +180,14 @@ impl<W: Writer> BufferedWriter<W> { } /// Gets a reference to the underlying writer. + pub fn get_ref(&self) -> &W { self.inner.as_ref().unwrap() } + + /// Gets a mutable reference to the underlying write. /// - /// This type does not expose the ability to get a mutable reference to the - /// underlying reader because that could possibly corrupt the buffer. - pub fn get_ref<'a>(&'a self) -> &'a W { self.inner.as_ref().unwrap() } + /// ## Warning + /// + /// It is inadvisable to directly read from the underlying writer. + pub fn get_mut(&mut self) -> &mut W { self.inner.as_mut().unwrap() } /// Unwraps this `BufferedWriter`, returning the underlying writer. /// @@ -341,14 +349,22 @@ impl<S: Stream> BufferedStream<S> { } /// Gets a reference to the underlying stream. - /// - /// This type does not expose the ability to get a mutable reference to the - /// underlying reader because that could possibly corrupt the buffer. - pub fn get_ref<'a>(&'a self) -> &'a S { + pub fn get_ref(&self) -> &S { let InternalBufferedWriter(ref w) = self.inner.inner; w.get_ref() } + /// Gets a mutable reference to the underlying stream. + /// + /// ## Warning + /// + /// It is inadvisable to read directly from or write directly to the + /// underlying stream. + pub fn get_mut(&mut self) -> &mut S { + let InternalBufferedWriter(ref mut w) = self.inner.inner; + w.get_mut() + } + /// Unwraps this `BufferedStream`, returning the underlying stream. /// /// The internal buffer is flushed before returning the stream. Any leftover diff --git a/src/libstd/io/fs.rs b/src/libstd/io/fs.rs index 6d29f3d2538..bd334f52628 100644 --- a/src/libstd/io/fs.rs +++ b/src/libstd/io/fs.rs @@ -10,51 +10,49 @@ // // ignore-lexer-test FIXME #15679 -/*! Synchronous File I/O - -This module provides a set of functions and traits for working -with regular files & directories on a filesystem. - -At the top-level of the module are a set of freestanding functions, associated -with various filesystem operations. They all operate on `Path` objects. - -All operations in this module, including those as part of `File` et al -block the task during execution. In the event of failure, all functions/methods -will return an `IoResult` type with an `Err` value. - -Also included in this module is an implementation block on the `Path` object -defined in `std::path::Path`. The impl adds useful methods about inspecting the -metadata of a file. This includes getting the `stat` information, reading off -particular bits of it, etc. - -# Example - -```rust -# #![allow(unused_must_use)] -use std::io::fs::PathExtensions; -use std::io::{File, fs}; - -let path = Path::new("foo.txt"); - -// create the file, whether it exists or not -let mut file = File::create(&path); -file.write(b"foobar"); -# drop(file); - -// open the file in read-only mode -let mut file = File::open(&path); -file.read_to_end(); - -println!("{}", path.stat().unwrap().size); -# drop(file); -fs::unlink(&path); -``` - -*/ +//! Synchronous File I/O +//! +//! This module provides a set of functions and traits for working +//! with regular files & directories on a filesystem. +//! +//! At the top-level of the module are a set of freestanding functions, associated +//! with various filesystem operations. They all operate on `Path` objects. +//! +//! All operations in this module, including those as part of `File` et al +//! block the task during execution. In the event of failure, all functions/methods +//! will return an `IoResult` type with an `Err` value. +//! +//! Also included in this module is an implementation block on the `Path` object +//! defined in `std::path::Path`. The impl adds useful methods about inspecting the +//! metadata of a file. This includes getting the `stat` information, reading off +//! particular bits of it, etc. +//! +//! # Example +//! +//! ```rust +//! # #![allow(unused_must_use)] +//! use std::io::fs::PathExtensions; +//! use std::io::{File, fs}; +//! +//! let path = Path::new("foo.txt"); +//! +//! // create the file, whether it exists or not +//! let mut file = File::create(&path); +//! file.write(b"foobar"); +//! # drop(file); +//! +//! // open the file in read-only mode +//! let mut file = File::open(&path); +//! file.read_to_end(); +//! +//! println!("{}", path.stat().unwrap().size); +//! # drop(file); +//! fs::unlink(&path); +//! ``` use clone::Clone; use io::standard_error; -use io::{FilePermission, Write, Open, FileAccess, FileMode}; +use io::{FilePermission, Write, Open, FileAccess, FileMode, FileType}; use io::{IoResult, IoError, FileStat, SeekStyle, Seek, Writer, Reader}; use io::{Read, Truncate, ReadWrite, Append}; use io::UpdateIoError; @@ -592,7 +590,7 @@ pub fn mkdir_recursive(path: &Path, mode: FilePermission) -> IoResult<()> { match result { Err(mkdir_err) => { // already exists ? - if try!(stat(&curpath)).kind != io::TypeDirectory { + if try!(stat(&curpath)).kind != FileType::Directory { return Err(mkdir_err); } } @@ -638,7 +636,7 @@ pub fn rmdir_recursive(path: &Path) -> IoResult<()> { false => try!(update_err(lstat(&child), path)) }; - if child_type.kind == io::TypeDirectory { + if child_type.kind == FileType::Directory { rm_stack.push(child); has_child_dir = true; } else { @@ -772,13 +770,13 @@ impl PathExtensions for path::Path { } fn is_file(&self) -> bool { match self.stat() { - Ok(s) => s.kind == io::TypeFile, + Ok(s) => s.kind == FileType::RegularFile, Err(..) => false } } fn is_dir(&self) -> bool { match self.stat() { - Ok(s) => s.kind == io::TypeDirectory, + Ok(s) => s.kind == FileType::Directory, Err(..) => false } } @@ -806,7 +804,7 @@ fn access_string(access: FileAccess) -> &'static str { #[allow(unused_mut)] mod test { use prelude::*; - use io::{SeekSet, SeekCur, SeekEnd, Read, Open, ReadWrite}; + use io::{SeekSet, SeekCur, SeekEnd, Read, Open, ReadWrite, FileType}; use io; use str; use io::fs::*; @@ -1028,12 +1026,12 @@ mod test { fs.write(msg.as_bytes()).unwrap(); let fstat_res = check!(fs.stat()); - assert_eq!(fstat_res.kind, io::TypeFile); + assert_eq!(fstat_res.kind, FileType::RegularFile); } let stat_res_fn = check!(stat(filename)); - assert_eq!(stat_res_fn.kind, io::TypeFile); + assert_eq!(stat_res_fn.kind, FileType::RegularFile); let stat_res_meth = check!(filename.stat()); - assert_eq!(stat_res_meth.kind, io::TypeFile); + assert_eq!(stat_res_meth.kind, FileType::RegularFile); check!(unlink(filename)); } @@ -1043,9 +1041,9 @@ mod test { let filename = &tmpdir.join("file_stat_correct_on_is_dir"); check!(mkdir(filename, io::USER_RWX)); let stat_res_fn = check!(stat(filename)); - assert!(stat_res_fn.kind == io::TypeDirectory); + assert!(stat_res_fn.kind == FileType::Directory); let stat_res_meth = check!(filename.stat()); - assert!(stat_res_meth.kind == io::TypeDirectory); + assert!(stat_res_meth.kind == FileType::Directory); check!(rmdir(filename)); } @@ -1315,8 +1313,8 @@ mod test { check!(File::create(&input).write("foobar".as_bytes())); check!(symlink(&input, &out)); if cfg!(not(windows)) { - assert_eq!(check!(lstat(&out)).kind, io::TypeSymlink); - assert_eq!(check!(out.lstat()).kind, io::TypeSymlink); + assert_eq!(check!(lstat(&out)).kind, FileType::Symlink); + assert_eq!(check!(out.lstat()).kind, FileType::Symlink); } assert_eq!(check!(stat(&out)).size, check!(stat(&input)).size); assert_eq!(check!(File::open(&out).read_to_end()), @@ -1350,8 +1348,8 @@ mod test { check!(File::create(&input).write("foobar".as_bytes())); check!(link(&input, &out)); if cfg!(not(windows)) { - assert_eq!(check!(lstat(&out)).kind, io::TypeFile); - assert_eq!(check!(out.lstat()).kind, io::TypeFile); + assert_eq!(check!(lstat(&out)).kind, FileType::RegularFile); + assert_eq!(check!(out.lstat()).kind, FileType::RegularFile); assert_eq!(check!(stat(&out)).unstable.nlink, 2); assert_eq!(check!(out.stat()).unstable.nlink, 2); } diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index a25674030ae..5ed10eab15b 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -16,207 +16,205 @@ // error handling -/*! I/O, including files, networking, timers, and processes - -`std::io` provides Rust's basic I/O types, -for reading and writing to files, TCP, UDP, -and other types of sockets and pipes, -manipulating the file system, spawning processes. - -# Examples - -Some examples of obvious things you might want to do - -* Read lines from stdin - - ```rust - use std::io; - - for line in io::stdin().lines() { - print!("{}", line.unwrap()); - } - ``` - -* Read a complete file - - ```rust - use std::io::File; - - let contents = File::open(&Path::new("message.txt")).read_to_end(); - ``` - -* Write a line to a file - - ```rust - # #![allow(unused_must_use)] - use std::io::File; - - let mut file = File::create(&Path::new("message.txt")); - file.write(b"hello, file!\n"); - # drop(file); - # ::std::io::fs::unlink(&Path::new("message.txt")); - ``` - -* Iterate over the lines of a file - - ```rust,no_run - use std::io::BufferedReader; - use std::io::File; - - let path = Path::new("message.txt"); - let mut file = BufferedReader::new(File::open(&path)); - for line in file.lines() { - print!("{}", line.unwrap()); - } - ``` - -* Pull the lines of a file into a vector of strings - - ```rust,no_run - use std::io::BufferedReader; - use std::io::File; - - let path = Path::new("message.txt"); - let mut file = BufferedReader::new(File::open(&path)); - let lines: Vec<String> = file.lines().map(|x| x.unwrap()).collect(); - ``` - -* Make a simple TCP client connection and request - - ```rust - # #![allow(unused_must_use)] - use std::io::TcpStream; - - # // connection doesn't fail if a server is running on 8080 - # // locally, we still want to be type checking this code, so lets - # // just stop it running (#11576) - # if false { - let mut socket = TcpStream::connect("127.0.0.1:8080").unwrap(); - socket.write(b"GET / HTTP/1.0\n\n"); - let response = socket.read_to_end(); - # } - ``` - -* Make a simple TCP server - - ```rust - # fn main() { } - # fn foo() { - # #![allow(dead_code)] - use std::io::{TcpListener, TcpStream}; - use std::io::{Acceptor, Listener}; - - let listener = TcpListener::bind("127.0.0.1:80"); - - // bind the listener to the specified address - let mut acceptor = listener.listen(); - - fn handle_client(mut stream: TcpStream) { - // ... - # &mut stream; // silence unused mutability/variable warning - } - // accept connections and process them, spawning a new tasks for each one - for stream in acceptor.incoming() { - match stream { - Err(e) => { /* connection failed */ } - Ok(stream) => spawn(proc() { - // connection succeeded - handle_client(stream) - }) - } - } - - // close the socket server - drop(acceptor); - # } - ``` - - -# Error Handling - -I/O is an area where nearly every operation can result in unexpected -errors. Errors should be painfully visible when they happen, and handling them -should be easy to work with. It should be convenient to handle specific I/O -errors, and it should also be convenient to not deal with I/O errors. - -Rust's I/O employs a combination of techniques to reduce boilerplate -while still providing feedback about errors. The basic strategy: - -* All I/O operations return `IoResult<T>` which is equivalent to - `Result<T, IoError>`. The `Result` type is defined in the `std::result` - module. -* If the `Result` type goes unused, then the compiler will by default emit a - warning about the unused result. This is because `Result` has the - `#[must_use]` attribute. -* Common traits are implemented for `IoResult`, e.g. - `impl<R: Reader> Reader for IoResult<R>`, so that error values do not have - to be 'unwrapped' before use. - -These features combine in the API to allow for expressions like -`File::create(&Path::new("diary.txt")).write(b"Met a girl.\n")` -without having to worry about whether "diary.txt" exists or whether -the write succeeds. As written, if either `new` or `write_line` -encounters an error then the result of the entire expression will -be an error. - -If you wanted to handle the error though you might write: - -```rust -# #![allow(unused_must_use)] -use std::io::File; - -match File::create(&Path::new("diary.txt")).write(b"Met a girl.\n") { - Ok(()) => (), // succeeded - Err(e) => println!("failed to write to my diary: {}", e), -} - -# ::std::io::fs::unlink(&Path::new("diary.txt")); -``` - -So what actually happens if `create` encounters an error? -It's important to know that what `new` returns is not a `File` -but an `IoResult<File>`. If the file does not open, then `new` will simply -return `Err(..)`. Because there is an implementation of `Writer` (the trait -required ultimately required for types to implement `write_line`) there is no -need to inspect or unwrap the `IoResult<File>` and we simply call `write_line` -on it. If `new` returned an `Err(..)` then the followup call to `write_line` -will also return an error. - -## `try!` - -Explicit pattern matching on `IoResult`s can get quite verbose, especially -when performing many I/O operations. Some examples (like those above) are -alleviated with extra methods implemented on `IoResult`, but others have more -complex interdependencies among each I/O operation. - -The `try!` macro from `std::macros` is provided as a method of early-return -inside `Result`-returning functions. It expands to an early-return on `Err` -and otherwise unwraps the contained `Ok` value. - -If you wanted to read several `u32`s from a file and return their product: - -```rust -use std::io::{File, IoResult}; - -fn file_product(p: &Path) -> IoResult<u32> { - let mut f = File::open(p); - let x1 = try!(f.read_le_u32()); - let x2 = try!(f.read_le_u32()); - - Ok(x1 * x2) -} - -match file_product(&Path::new("numbers.bin")) { - Ok(x) => println!("{}", x), - Err(e) => println!("Failed to read numbers!") -} -``` - -With `try!` in `file_product`, each `read_le_u32` need not be directly -concerned with error handling; instead its caller is responsible for -responding to errors that may occur while attempting to read the numbers. - -*/ +//! I/O, including files, networking, timers, and processes +//! +//! `std::io` provides Rust's basic I/O types, +//! for reading and writing to files, TCP, UDP, +//! and other types of sockets and pipes, +//! manipulating the file system, spawning processes. +//! +//! # Examples +//! +//! Some examples of obvious things you might want to do +//! +//! * Read lines from stdin +//! +//! ```rust +//! use std::io; +//! +//! for line in io::stdin().lines() { +//! print!("{}", line.unwrap()); +//! } +//! ``` +//! +//! * Read a complete file +//! +//! ```rust +//! use std::io::File; +//! +//! let contents = File::open(&Path::new("message.txt")).read_to_end(); +//! ``` +//! +//! * Write a line to a file +//! +//! ```rust +//! # #![allow(unused_must_use)] +//! use std::io::File; +//! +//! let mut file = File::create(&Path::new("message.txt")); +//! file.write(b"hello, file!\n"); +//! # drop(file); +//! # ::std::io::fs::unlink(&Path::new("message.txt")); +//! ``` +//! +//! * Iterate over the lines of a file +//! +//! ```rust,no_run +//! use std::io::BufferedReader; +//! use std::io::File; +//! +//! let path = Path::new("message.txt"); +//! let mut file = BufferedReader::new(File::open(&path)); +//! for line in file.lines() { +//! print!("{}", line.unwrap()); +//! } +//! ``` +//! +//! * Pull the lines of a file into a vector of strings +//! +//! ```rust,no_run +//! use std::io::BufferedReader; +//! use std::io::File; +//! +//! let path = Path::new("message.txt"); +//! let mut file = BufferedReader::new(File::open(&path)); +//! let lines: Vec<String> = file.lines().map(|x| x.unwrap()).collect(); +//! ``` +//! +//! * Make a simple TCP client connection and request +//! +//! ```rust +//! # #![allow(unused_must_use)] +//! use std::io::TcpStream; +//! +//! # // connection doesn't fail if a server is running on 8080 +//! # // locally, we still want to be type checking this code, so lets +//! # // just stop it running (#11576) +//! # if false { +//! let mut socket = TcpStream::connect("127.0.0.1:8080").unwrap(); +//! socket.write(b"GET / HTTP/1.0\n\n"); +//! let response = socket.read_to_end(); +//! # } +//! ``` +//! +//! * Make a simple TCP server +//! +//! ```rust +//! # fn main() { } +//! # fn foo() { +//! # #![allow(dead_code)] +//! use std::io::{TcpListener, TcpStream}; +//! use std::io::{Acceptor, Listener}; +//! +//! let listener = TcpListener::bind("127.0.0.1:80"); +//! +//! // bind the listener to the specified address +//! let mut acceptor = listener.listen(); +//! +//! fn handle_client(mut stream: TcpStream) { +//! // ... +//! # &mut stream; // silence unused mutability/variable warning +//! } +//! // accept connections and process them, spawning a new tasks for each one +//! for stream in acceptor.incoming() { +//! match stream { +//! Err(e) => { /* connection failed */ } +//! Ok(stream) => spawn(proc() { +//! // connection succeeded +//! handle_client(stream) +//! }) +//! } +//! } +//! +//! // close the socket server +//! drop(acceptor); +//! # } +//! ``` +//! +//! +//! # Error Handling +//! +//! I/O is an area where nearly every operation can result in unexpected +//! errors. Errors should be painfully visible when they happen, and handling them +//! should be easy to work with. It should be convenient to handle specific I/O +//! errors, and it should also be convenient to not deal with I/O errors. +//! +//! Rust's I/O employs a combination of techniques to reduce boilerplate +//! while still providing feedback about errors. The basic strategy: +//! +//! * All I/O operations return `IoResult<T>` which is equivalent to +//! `Result<T, IoError>`. The `Result` type is defined in the `std::result` +//! module. +//! * If the `Result` type goes unused, then the compiler will by default emit a +//! warning about the unused result. This is because `Result` has the +//! `#[must_use]` attribute. +//! * Common traits are implemented for `IoResult`, e.g. +//! `impl<R: Reader> Reader for IoResult<R>`, so that error values do not have +//! to be 'unwrapped' before use. +//! +//! These features combine in the API to allow for expressions like +//! `File::create(&Path::new("diary.txt")).write(b"Met a girl.\n")` +//! without having to worry about whether "diary.txt" exists or whether +//! the write succeeds. As written, if either `new` or `write_line` +//! encounters an error then the result of the entire expression will +//! be an error. +//! +//! If you wanted to handle the error though you might write: +//! +//! ```rust +//! # #![allow(unused_must_use)] +//! use std::io::File; +//! +//! match File::create(&Path::new("diary.txt")).write(b"Met a girl.\n") { +//! Ok(()) => (), // succeeded +//! Err(e) => println!("failed to write to my diary: {}", e), +//! } +//! +//! # ::std::io::fs::unlink(&Path::new("diary.txt")); +//! ``` +//! +//! So what actually happens if `create` encounters an error? +//! It's important to know that what `new` returns is not a `File` +//! but an `IoResult<File>`. If the file does not open, then `new` will simply +//! return `Err(..)`. Because there is an implementation of `Writer` (the trait +//! required ultimately required for types to implement `write_line`) there is no +//! need to inspect or unwrap the `IoResult<File>` and we simply call `write_line` +//! on it. If `new` returned an `Err(..)` then the followup call to `write_line` +//! will also return an error. +//! +//! ## `try!` +//! +//! Explicit pattern matching on `IoResult`s can get quite verbose, especially +//! when performing many I/O operations. Some examples (like those above) are +//! alleviated with extra methods implemented on `IoResult`, but others have more +//! complex interdependencies among each I/O operation. +//! +//! The `try!` macro from `std::macros` is provided as a method of early-return +//! inside `Result`-returning functions. It expands to an early-return on `Err` +//! and otherwise unwraps the contained `Ok` value. +//! +//! If you wanted to read several `u32`s from a file and return their product: +//! +//! ```rust +//! use std::io::{File, IoResult}; +//! +//! fn file_product(p: &Path) -> IoResult<u32> { +//! let mut f = File::open(p); +//! let x1 = try!(f.read_le_u32()); +//! let x2 = try!(f.read_le_u32()); +//! +//! Ok(x1 * x2) +//! } +//! +//! match file_product(&Path::new("numbers.bin")) { +//! Ok(x) => println!("{}", x), +//! Err(e) => println!("Failed to read numbers!") +//! } +//! ``` +//! +//! With `try!` in `file_product`, each `read_le_u32` need not be directly +//! concerned with error handling; instead its caller is responsible for +//! responding to errors that may occur while attempting to read the numbers. #![experimental] #![deny(unused_must_use)] @@ -224,7 +222,6 @@ responding to errors that may occur while attempting to read the numbers. pub use self::SeekStyle::*; pub use self::FileMode::*; pub use self::FileAccess::*; -pub use self::FileType::*; pub use self::IoErrorKind::*; use char::Char; @@ -911,7 +908,7 @@ impl<'a> Reader for Box<Reader+'a> { } } -impl<'a> Reader for &'a mut Reader+'a { +impl<'a> Reader for &'a mut (Reader+'a) { fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> { (*self).read(buf) } } @@ -1279,7 +1276,7 @@ impl<'a> Writer for Box<Writer+'a> { } } -impl<'a> Writer for &'a mut Writer+'a { +impl<'a> Writer for &'a mut (Writer+'a) { #[inline] fn write(&mut self, buf: &[u8]) -> IoResult<()> { (**self).write(buf) } @@ -1698,22 +1695,22 @@ pub enum FileAccess { #[deriving(PartialEq, Show, Hash, Clone)] pub enum FileType { /// This is a normal file, corresponding to `S_IFREG` - TypeFile, + RegularFile, /// This file is a directory, corresponding to `S_IFDIR` - TypeDirectory, + Directory, /// This file is a named pipe, corresponding to `S_IFIFO` - TypeNamedPipe, + NamedPipe, /// This file is a block device, corresponding to `S_IFBLK` - TypeBlockSpecial, + BlockSpecial, /// This file is a symbolic link to another file, corresponding to `S_IFLNK` - TypeSymlink, + Symlink, /// The type of this file is not recognized as one of the other categories - TypeUnknown, + Unknown, } /// A structure used to describe metadata information about a file. This diff --git a/src/libstd/io/net/addrinfo.rs b/src/libstd/io/net/addrinfo.rs index d6a48fd39e6..7de78692130 100644 --- a/src/libstd/io/net/addrinfo.rs +++ b/src/libstd/io/net/addrinfo.rs @@ -8,14 +8,10 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! - -Synchronous DNS Resolution - -Contains the functionality to perform DNS resolution in a style related to -getaddrinfo() - -*/ +//! Synchronous DNS Resolution +//! +//! Contains the functionality to perform DNS resolution in a style related to +//! `getaddrinfo()` #![allow(missing_docs)] diff --git a/src/libstd/io/net/pipe.rs b/src/libstd/io/net/pipe.rs index 2984fa59631..ec997b71986 100644 --- a/src/libstd/io/net/pipe.rs +++ b/src/libstd/io/net/pipe.rs @@ -8,19 +8,15 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! - -Named pipes - -This module contains the ability to communicate over named pipes with -synchronous I/O. On windows, this corresponds to talking over a Named Pipe, -while on Unix it corresponds to UNIX domain sockets. - -These pipes are similar to TCP in the sense that you can have both a stream to a -server and a server itself. The server provided accepts other `UnixStream` -instances as clients. - -*/ +//! Named pipes +//! +//! This module contains the ability to communicate over named pipes with +//! synchronous I/O. On windows, this corresponds to talking over a Named Pipe, +//! while on Unix it corresponds to UNIX domain sockets. +//! +//! These pipes are similar to TCP in the sense that you can have both a stream to a +//! server and a server itself. The server provided accepts other `UnixStream` +//! instances as clients. #![allow(missing_docs)] diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs index e6dd20f63fb..665000eae88 100644 --- a/src/libstd/io/stdio.rs +++ b/src/libstd/io/stdio.rs @@ -8,24 +8,22 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! Non-blocking access to stdin, stdout, and stderr. - -This module provides bindings to the local event loop's TTY interface, using it -to offer synchronous but non-blocking versions of stdio. These handles can be -inspected for information about terminal dimensions or for related information -about the stream or terminal to which it is attached. - -# Example - -```rust -# #![allow(unused_must_use)] -use std::io; - -let mut out = io::stdout(); -out.write(b"Hello, world!"); -``` - -*/ +//! Non-blocking access to stdin, stdout, and stderr. +//! +//! This module provides bindings to the local event loop's TTY interface, using it +//! to offer synchronous but non-blocking versions of stdio. These handles can be +//! inspected for information about terminal dimensions or for related information +//! about the stream or terminal to which it is attached. +//! +//! # Example +//! +//! ```rust +//! # #![allow(unused_must_use)] +//! use std::io; +//! +//! let mut out = io::stdout(); +//! out.write(b"Hello, world!"); +//! ``` use self::StdSource::*; diff --git a/src/libstd/io/test.rs b/src/libstd/io/test.rs index a153ead2a38..af56735021e 100644 --- a/src/libstd/io/test.rs +++ b/src/libstd/io/test.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! Various utility functions useful for writing I/O tests */ +//! Various utility functions useful for writing I/O tests #![macro_escape] @@ -95,17 +95,14 @@ pub fn raise_fd_limit() { unsafe { darwin_fd_limit::raise_fd_limit() } } +/// darwin_fd_limit exists to work around an issue where launchctl on Mac OS X defaults the rlimit +/// maxfiles to 256/unlimited. The default soft limit of 256 ends up being far too low for our +/// multithreaded scheduler testing, depending on the number of cores available. +/// +/// This fixes issue #7772. #[cfg(target_os="macos")] #[allow(non_camel_case_types)] mod darwin_fd_limit { - /*! - * darwin_fd_limit exists to work around an issue where launchctl on Mac OS X defaults the - * rlimit maxfiles to 256/unlimited. The default soft limit of 256 ends up being far too low - * for our multithreaded scheduler testing, depending on the number of cores available. - * - * This fixes issue #7772. - */ - use libc; type rlim_t = libc::uint64_t; #[repr(C)] diff --git a/src/libstd/io/timer.rs b/src/libstd/io/timer.rs index ec588f13478..ad02b534d04 100644 --- a/src/libstd/io/timer.rs +++ b/src/libstd/io/timer.rs @@ -8,14 +8,10 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! - -Synchronous Timers - -This module exposes the functionality to create timers, block the current task, -and create receivers which will receive notifications after a period of time. - -*/ +//! Synchronous Timers +//! +//! This module exposes the functionality to create timers, block the current task, +//! and create receivers which will receive notifications after a period of time. // FIXME: These functions take Durations but only pass ms to the backend impls. diff --git a/src/libstd/io/util.rs b/src/libstd/io/util.rs index 8e0cd660816..393283ff64c 100644 --- a/src/libstd/io/util.rs +++ b/src/libstd/io/util.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! Utility implementations of Reader and Writer */ +//! Utility implementations of Reader and Writer use prelude::*; use cmp; diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index c3260225d0a..12ca80bfaab 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -186,26 +186,43 @@ macro_rules! debug_assert_eq( ($($arg:tt)*) => (if cfg!(not(ndebug)) { assert_eq!($($arg)*); }) ) -/// A utility macro for indicating unreachable code. It will panic if -/// executed. This is occasionally useful to put after loops that never -/// terminate normally, but instead directly return from a function. +/// A utility macro for indicating unreachable code. /// -/// # Example +/// This is useful any time that the compiler can't determine that some code is unreachable. For +/// example: +/// +/// * Match arms with guard conditions. +/// * Loops that dynamically terminate. +/// * Iterators that dynamically terminate. +/// +/// # Panics +/// +/// This will always panic. +/// +/// # Examples +/// +/// Match arms: /// -/// ```{.rust} -/// struct Item { weight: uint } -/// -/// fn choose_weighted_item(v: &[Item]) -> Item { -/// assert!(!v.is_empty()); -/// let mut so_far = 0u; -/// for item in v.iter() { -/// so_far += item.weight; -/// if so_far > 100 { -/// return *item; -/// } +/// ```rust +/// fn foo(x: Option<int>) { +/// match x { +/// Some(n) if n >= 0 => println!("Some(Non-negative)"), +/// Some(n) if n < 0 => println!("Some(Negative)"), +/// Some(_) => unreachable!(), // compile error if commented out +/// None => println!("None") /// } -/// // The above loop always returns, so we must hint to the -/// // type checker that it isn't possible to get down here +/// } +/// ``` +/// +/// Iterators: +/// +/// ```rust +/// fn divide_by_three(x: i32) -> i32 { // one of the poorest implementations of x/3 +/// for i in std::iter::count(0_i32, 1) { +/// if i < 0 { panic!("i32 overflow"); } +/// if x < 3*i { return i; } +/// } +/// /// unreachable!(); /// } /// ``` diff --git a/src/libstd/num/strconv.rs b/src/libstd/num/strconv.rs index 649298d9c08..be6e387ad83 100644 --- a/src/libstd/num/strconv.rs +++ b/src/libstd/num/strconv.rs @@ -67,31 +67,32 @@ pub enum SignFormat { SignAll, } -/** - * Converts an integral number to its string representation as a byte vector. - * This is meant to be a common base implementation for all integral string - * conversion functions like `to_string()` or `to_str_radix()`. - * - * # Arguments - * - `num` - The number to convert. Accepts any number that - * implements the numeric traits. - * - `radix` - Base to use. Accepts only the values 2-36. - * - `sign` - How to emit the sign. Options are: - * - `SignNone`: No sign at all. Basically emits `abs(num)`. - * - `SignNeg`: Only `-` on negative values. - * - `SignAll`: Both `+` on positive, and `-` on negative numbers. - * - `f` - a callback which will be invoked for each ascii character - * which composes the string representation of this integer - * - * # Return value - * A tuple containing the byte vector, and a boolean flag indicating - * whether it represents a special value like `inf`, `-inf`, `NaN` or not. - * It returns a tuple because there can be ambiguity between a special value - * and a number representation at higher bases. - * - * # Panics - * - Panics if `radix` < 2 or `radix` > 36. - */ +/// Converts an integral number to its string representation as a byte vector. +/// This is meant to be a common base implementation for all integral string +/// conversion functions like `to_string()` or `to_str_radix()`. +/// +/// # Arguments +/// +/// - `num` - The number to convert. Accepts any number that +/// implements the numeric traits. +/// - `radix` - Base to use. Accepts only the values 2-36. +/// - `sign` - How to emit the sign. Options are: +/// - `SignNone`: No sign at all. Basically emits `abs(num)`. +/// - `SignNeg`: Only `-` on negative values. +/// - `SignAll`: Both `+` on positive, and `-` on negative numbers. +/// - `f` - a callback which will be invoked for each ascii character +/// which composes the string representation of this integer +/// +/// # Return value +/// +/// A tuple containing the byte vector, and a boolean flag indicating +/// whether it represents a special value like `inf`, `-inf`, `NaN` or not. +/// It returns a tuple because there can be ambiguity between a special value +/// and a number representation at higher bases. +/// +/// # Panics +/// +/// - Panics if `radix` < 2 or `radix` > 36. fn int_to_str_bytes_common<T: Int>(num: T, radix: uint, sign: SignFormat, f: |u8|) { assert!(2 <= radix && radix <= 36); diff --git a/src/libstd/os.rs b/src/libstd/os.rs index 6b5ec983a80..90203709627 100644 --- a/src/libstd/os.rs +++ b/src/libstd/os.rs @@ -8,23 +8,19 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! - * Higher-level interfaces to libc::* functions and operating system services. - * - * In general these take and return rust types, use rust idioms (enums, - * closures, vectors) rather than C idioms, and do more extensive safety - * checks. - * - * This module is not meant to only contain 1:1 mappings to libc entries; any - * os-interface code that is reasonably useful and broadly applicable can go - * here. Including utility routines that merely build on other os code. - * - * We assume the general case is that users do not care, and do not want to - * be made to care, which operating system they are on. While they may want - * to special case various special cases -- and so we will not _hide_ the - * facts of which OS the user is on -- they should be given the opportunity - * to write OS-ignorant code by default. - */ +//! Higher-level interfaces to libc::* functions and operating system services. +//! +//! In general these take and return rust types, use rust idioms (enums, closures, vectors) rather +//! than C idioms, and do more extensive safety checks. +//! +//! This module is not meant to only contain 1:1 mappings to libc entries; any os-interface code +//! that is reasonably useful and broadly applicable can go here. Including utility routines that +//! merely build on other os code. +//! +//! We assume the general case is that users do not care, and do not want to be made to care, which +//! operating system they are on. While they may want to special case various special cases -- and +//! so we will not _hide_ the facts of which OS the user is on -- they should be given the +//! opportunity to write OS-ignorant code by default. #![experimental] @@ -793,18 +789,16 @@ pub fn homedir() -> Option<Path> { _homedir() } -/** - * Returns the path to a temporary directory. - * - * On Unix, returns the value of the 'TMPDIR' environment variable if it is - * set, otherwise for non-Android it returns '/tmp'. If Android, since there - * is no global temporary folder (it is usually allocated per-app), we return - * '/data/local/tmp'. - * - * On Windows, returns the value of, in order, the 'TMP', 'TEMP', - * 'USERPROFILE' environment variable if any are set and not the empty - * string. Otherwise, tmpdir returns the path to the Windows directory. - */ +/// Returns the path to a temporary directory. +/// +/// On Unix, returns the value of the 'TMPDIR' environment variable if it is +/// set, otherwise for non-Android it returns '/tmp'. If Android, since there +/// is no global temporary folder (it is usually allocated per-app), we return +/// '/data/local/tmp'. +/// +/// On Windows, returns the value of, in order, the 'TMP', 'TEMP', +/// 'USERPROFILE' environment variable if any are set and not the empty +/// string. Otherwise, tmpdir returns the path to the Windows directory. pub fn tmpdir() -> Path { return lookup(); @@ -938,16 +932,14 @@ pub fn last_os_error() -> String { static EXIT_STATUS: AtomicInt = INIT_ATOMIC_INT; -/** - * Sets the process exit code - * - * Sets the exit code returned by the process if all supervised tasks - * terminate successfully (without panicking). If the current root task panics - * and is supervised by the scheduler then any user-specified exit status is - * ignored and the process exits with the default panic status. - * - * Note that this is not synchronized against modifications of other threads. - */ +/// Sets the process exit code +/// +/// Sets the exit code returned by the process if all supervised tasks +/// terminate successfully (without panicking). If the current root task panics +/// and is supervised by the scheduler then any user-specified exit status is +/// ignored and the process exits with the default panic status. +/// +/// Note that this is not synchronized against modifications of other threads. pub fn set_exit_status(code: int) { EXIT_STATUS.store(code, SeqCst) } @@ -968,11 +960,9 @@ unsafe fn load_argc_and_argv(argc: int, }) } -/** - * Returns the command line arguments - * - * Returns a list of the command line arguments. - */ +/// Returns the command line arguments +/// +/// Returns a list of the command line arguments. #[cfg(target_os = "macos")] fn real_args_as_bytes() -> Vec<Vec<u8>> { unsafe { diff --git a/src/libstd/path/mod.rs b/src/libstd/path/mod.rs index 047fa51b92f..b17106e811f 100644 --- a/src/libstd/path/mod.rs +++ b/src/libstd/path/mod.rs @@ -8,62 +8,56 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! - -Cross-platform path support - -This module implements support for two flavors of paths. `PosixPath` represents -a path on any unix-like system, whereas `WindowsPath` represents a path on -Windows. This module also exposes a typedef `Path` which is equal to the -appropriate platform-specific path variant. - -Both `PosixPath` and `WindowsPath` implement a trait `GenericPath`, which -contains the set of methods that behave the same for both paths. They each also -implement some methods that could not be expressed in `GenericPath`, yet behave -identically for both path flavors, such as `.components()`. - -The three main design goals of this module are 1) to avoid unnecessary -allocation, 2) to behave the same regardless of which flavor of path is being -used, and 3) to support paths that cannot be represented in UTF-8 (as Linux has -no restriction on paths beyond disallowing NUL). - -## Usage - -Usage of this module is fairly straightforward. Unless writing platform-specific -code, `Path` should be used to refer to the platform-native path. - -Creation of a path is typically done with either `Path::new(some_str)` or -`Path::new(some_vec)`. This path can be modified with `.push()` and -`.pop()` (and other setters). The resulting Path can either be passed to another -API that expects a path, or can be turned into a `&[u8]` with `.as_vec()` or a -`Option<&str>` with `.as_str()`. Similarly, attributes of the path can be queried -with methods such as `.filename()`. There are also methods that return a new -path instead of modifying the receiver, such as `.join()` or `.dir_path()`. - -Paths are always kept in normalized form. This means that creating the path -`Path::new("a/b/../c")` will return the path `a/c`. Similarly any attempt -to mutate the path will always leave it in normalized form. - -When rendering a path to some form of output, there is a method `.display()` -which is compatible with the `format!()` parameter `{}`. This will render the -path as a string, replacing all non-utf8 sequences with the Replacement -Character (U+FFFD). As such it is not suitable for passing to any API that -actually operates on the path; it is only intended for display. - -## Example - -```rust -use std::io::fs::PathExtensions; - -let mut path = Path::new("/tmp/path"); -println!("path: {}", path.display()); -path.set_filename("foo"); -path.push("bar"); -println!("new path: {}", path.display()); -println!("path exists: {}", path.exists()); -``` - -*/ +//! Cross-platform path support +//! +//! This module implements support for two flavors of paths. `PosixPath` represents a path on any +//! unix-like system, whereas `WindowsPath` represents a path on Windows. This module also exposes +//! a typedef `Path` which is equal to the appropriate platform-specific path variant. +//! +//! Both `PosixPath` and `WindowsPath` implement a trait `GenericPath`, which contains the set of +//! methods that behave the same for both paths. They each also implement some methods that could +//! not be expressed in `GenericPath`, yet behave identically for both path flavors, such as +//! `.components()`. +//! +//! The three main design goals of this module are 1) to avoid unnecessary allocation, 2) to behave +//! the same regardless of which flavor of path is being used, and 3) to support paths that cannot +//! be represented in UTF-8 (as Linux has no restriction on paths beyond disallowing NUL). +//! +//! ## Usage +//! +//! Usage of this module is fairly straightforward. Unless writing platform-specific code, `Path` +//! should be used to refer to the platform-native path. +//! +//! Creation of a path is typically done with either `Path::new(some_str)` or +//! `Path::new(some_vec)`. This path can be modified with `.push()` and `.pop()` (and other +//! setters). The resulting Path can either be passed to another API that expects a path, or can be +//! turned into a `&[u8]` with `.as_vec()` or a `Option<&str>` with `.as_str()`. Similarly, +//! attributes of the path can be queried with methods such as `.filename()`. There are also +//! methods that return a new path instead of modifying the receiver, such as `.join()` or +//! `.dir_path()`. +//! +//! Paths are always kept in normalized form. This means that creating the path +//! `Path::new("a/b/../c")` will return the path `a/c`. Similarly any attempt to mutate the path +//! will always leave it in normalized form. +//! +//! When rendering a path to some form of output, there is a method `.display()` which is +//! compatible with the `format!()` parameter `{}`. This will render the path as a string, +//! replacing all non-utf8 sequences with the Replacement Character (U+FFFD). As such it is not +//! suitable for passing to any API that actually operates on the path; it is only intended for +//! display. +//! +//! ## Example +//! +//! ```rust +//! use std::io::fs::PathExtensions; +//! +//! let mut path = Path::new("/tmp/path"); +//! println!("path: {}", path.display()); +//! path.set_filename("foo"); +//! path.push("bar"); +//! println!("new path: {}", path.display()); +//! println!("path exists: {}", path.exists()); +//! ``` #![experimental] diff --git a/src/libstd/prelude.rs b/src/libstd/prelude.rs index 590a7894fa7..ec1cff73e96 100644 --- a/src/libstd/prelude.rs +++ b/src/libstd/prelude.rs @@ -87,6 +87,7 @@ #[doc(no_inline)] pub use slice::{SlicePrelude, AsSlice, CloneSlicePrelude}; #[doc(no_inline)] pub use slice::{VectorVector, PartialEqSlicePrelude, OrdSlicePrelude}; #[doc(no_inline)] pub use slice::{CloneSliceAllocPrelude, OrdSliceAllocPrelude, SliceAllocPrelude}; +#[doc(no_inline)] pub use slice::{BoxedSlicePrelude}; #[doc(no_inline)] pub use string::{IntoString, String, ToString}; #[doc(no_inline)] pub use vec::Vec; diff --git a/src/libstd/rt/backtrace.rs b/src/libstd/rt/backtrace.rs index 4f6c1f8a2c6..d375ddcc94b 100644 --- a/src/libstd/rt/backtrace.rs +++ b/src/libstd/rt/backtrace.rs @@ -288,7 +288,7 @@ mod imp { struct Context<'a> { idx: int, - writer: &'a mut Writer+'a, + writer: &'a mut (Writer+'a), last_error: Option<IoError>, } diff --git a/src/libstd/rt/mod.rs b/src/libstd/rt/mod.rs index 872a5452241..5ecd3ff04f1 100644 --- a/src/libstd/rt/mod.rs +++ b/src/libstd/rt/mod.rs @@ -8,46 +8,38 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! Runtime services, including the task scheduler and I/O dispatcher - -The `rt` module provides the private runtime infrastructure necessary -to support core language features like the exchange and local heap, -logging, local data and unwinding. It also implements the default task -scheduler and task model. Initialization routines are provided for setting -up runtime resources in common configurations, including that used by -`rustc` when generating executables. - -It is intended that the features provided by `rt` can be factored in a -way such that the core library can be built with different 'profiles' -for different use cases, e.g. excluding the task scheduler. A number -of runtime features though are critical to the functioning of the -language and an implementation must be provided regardless of the -execution environment. - -Of foremost importance is the global exchange heap, in the module -`heap`. Very little practical Rust code can be written without -access to the global heap. Unlike most of `rt` the global heap is -truly a global resource and generally operates independently of the -rest of the runtime. - -All other runtime features are task-local, including the local heap, -local storage, logging and the stack unwinder. - -The relationship between `rt` and the rest of the core library is -not entirely clear yet and some modules will be moving into or -out of `rt` as development proceeds. - -Several modules in `core` are clients of `rt`: - -* `std::task` - The user-facing interface to the Rust task model. -* `std::local_data` - The interface to local data. -* `std::unstable::lang` - Miscellaneous lang items, some of which rely on `std::rt`. -* `std::cleanup` - Local heap destruction. -* `std::io` - In the future `std::io` will use an `rt` implementation. -* `std::logging` -* `std::comm` - -*/ +//! Runtime services, including the task scheduler and I/O dispatcher +//! +//! The `rt` module provides the private runtime infrastructure necessary to support core language +//! features like the exchange and local heap, logging, local data and unwinding. It also +//! implements the default task scheduler and task model. Initialization routines are provided for +//! setting up runtime resources in common configurations, including that used by `rustc` when +//! generating executables. +//! +//! It is intended that the features provided by `rt` can be factored in a way such that the core +//! library can be built with different 'profiles' for different use cases, e.g. excluding the task +//! scheduler. A number of runtime features though are critical to the functioning of the language +//! and an implementation must be provided regardless of the execution environment. +//! +//! Of foremost importance is the global exchange heap, in the module `heap`. Very little practical +//! Rust code can be written without access to the global heap. Unlike most of `rt` the global heap +//! is truly a global resource and generally operates independently of the rest of the runtime. +//! +//! All other runtime features are task-local, including the local heap, local storage, logging and +//! the stack unwinder. +//! +//! The relationship between `rt` and the rest of the core library is not entirely clear yet and +//! some modules will be moving into or out of `rt` as development proceeds. +//! +//! Several modules in `core` are clients of `rt`: +//! +//! * `std::task` - The user-facing interface to the Rust task model. +//! * `std::local_data` - The interface to local data. +//! * `std::unstable::lang` - Miscellaneous lang items, some of which rely on `std::rt`. +//! * `std::cleanup` - Local heap destruction. +//! * `std::io` - In the future `std::io` will use an `rt` implementation. +//! * `std::logging` +//! * `std::comm` #![experimental] diff --git a/src/libstd/sync/future.rs b/src/libstd/sync/future.rs index d6f413a0828..f2f9351fd0d 100644 --- a/src/libstd/sync/future.rs +++ b/src/libstd/sync/future.rs @@ -8,21 +8,19 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! - * A type representing values that may be computed concurrently and - * operations for working with them. - * - * # Example - * - * ```rust - * use std::sync::Future; - * # fn fib(n: uint) -> uint {42}; - * # fn make_a_sandwich() {}; - * let mut delayed_fib = Future::spawn(proc() { fib(5000) }); - * make_a_sandwich(); - * println!("fib(5000) = {}", delayed_fib.get()) - * ``` - */ +//! A type representing values that may be computed concurrently and operations for working with +//! them. +//! +//! # Example +//! +//! ```rust +//! use std::sync::Future; +//! # fn fib(n: uint) -> uint {42}; +//! # fn make_a_sandwich() {}; +//! let mut delayed_fib = Future::spawn(proc() { fib(5000) }); +//! make_a_sandwich(); +//! println!("fib(5000) = {}", delayed_fib.get()) +//! ``` #![allow(missing_docs)] diff --git a/src/libstd/sync/lock.rs b/src/libstd/sync/lock.rs index 6b63f7ae618..77f5b013519 100644 --- a/src/libstd/sync/lock.rs +++ b/src/libstd/sync/lock.rs @@ -29,9 +29,7 @@ use rustrt::task::Task; use super::raw; -/**************************************************************************** - * Poisoning helpers - ****************************************************************************/ +// Poisoning helpers struct PoisonOnFail<'a> { flag: &'a mut bool, @@ -67,9 +65,7 @@ impl<'a> Drop for PoisonOnFail<'a> { } } -/**************************************************************************** - * Condvar - ****************************************************************************/ +// Condvar enum Inner<'a> { InnerMutex(raw::MutexGuard<'a>), @@ -147,10 +143,6 @@ impl<'a> Condvar<'a> { } } -/**************************************************************************** - * Mutex - ****************************************************************************/ - /// A wrapper type which provides synchronized access to the underlying data, of /// type `T`. A mutex always provides exclusive access, and concurrent requests /// will block while the mutex is already locked. @@ -249,10 +241,6 @@ impl<'a, T: Send> DerefMut<T> for MutexGuard<'a, T> { fn deref_mut<'a>(&'a mut self) -> &'a mut T { &mut *self._data } } -/**************************************************************************** - * R/W lock protected lock - ****************************************************************************/ - /// A dual-mode reader-writer lock. The data can be accessed mutably or /// immutably, and immutably-accessing tasks may run concurrently. /// @@ -387,10 +375,6 @@ impl<'a, T: Send + Sync> DerefMut<T> for RWLockWriteGuard<'a, T> { fn deref_mut<'a>(&'a mut self) -> &'a mut T { &mut *self._data } } -/**************************************************************************** - * Barrier - ****************************************************************************/ - /// A barrier enables multiple tasks to synchronize the beginning /// of some computation. /// @@ -452,10 +436,6 @@ impl Barrier { } } -/**************************************************************************** - * Tests - ****************************************************************************/ - #[cfg(test)] mod tests { use prelude::*; @@ -795,9 +775,6 @@ mod tests { } } - /************************************************************************ - * Barrier tests - ************************************************************************/ #[test] fn test_barrier() { let barrier = Arc::new(Barrier::new(10)); diff --git a/src/libstd/sync/raw.rs b/src/libstd/sync/raw.rs index ff3f2c9462c..47580a11513 100644 --- a/src/libstd/sync/raw.rs +++ b/src/libstd/sync/raw.rs @@ -32,10 +32,6 @@ use vec::Vec; use super::mutex; use comm::{Receiver, Sender, channel}; -/**************************************************************************** - * Internals - ****************************************************************************/ - // Each waiting task receives on one of these. type WaitEnd = Receiver<()>; type SignalEnd = Sender<()>; @@ -353,10 +349,6 @@ struct SemCondGuard<'a> { cvar: Condvar<'a>, } -/**************************************************************************** - * Semaphores - ****************************************************************************/ - /// A counting, blocking, bounded-waiting semaphore. pub struct Semaphore { sem: Sem<()>, @@ -394,10 +386,6 @@ impl Semaphore { } } -/**************************************************************************** - * Mutexes - ****************************************************************************/ - /// A blocking, bounded-waiting, mutual exclusion lock with an associated /// FIFO condition variable. /// @@ -441,10 +429,6 @@ impl Mutex { } } -/**************************************************************************** - * Reader-writer locks - ****************************************************************************/ - // NB: Wikipedia - Readers-writers_problem#The_third_readers-writers_problem /// A blocking, no-starvation, reader-writer lock with an associated condvar. @@ -618,10 +602,6 @@ impl<'a> Drop for RWLockReadGuard<'a> { } } -/**************************************************************************** - * Tests - ****************************************************************************/ - #[cfg(test)] mod tests { pub use self::RWLockMode::*; @@ -634,9 +614,6 @@ mod tests { use result; use task; - /************************************************************************ - * Semaphore tests - ************************************************************************/ #[test] fn test_sem_acquire_release() { let s = Semaphore::new(1); @@ -644,16 +621,19 @@ mod tests { s.release(); s.acquire(); } + #[test] fn test_sem_basic() { let s = Semaphore::new(1); let _g = s.access(); } + #[test] #[should_fail] fn test_sem_basic2() { Semaphore::new(-1); } + #[test] fn test_sem_as_mutex() { let s = Arc::new(Semaphore::new(1)); @@ -665,6 +645,7 @@ mod tests { let _g = s.access(); for _ in range(0u, 5) { task::deschedule(); } } + #[test] fn test_sem_as_cvar() { /* Child waits and parent signals */ @@ -691,6 +672,7 @@ mod tests { s.acquire(); tx.send(()); } + #[test] fn test_sem_multi_resource() { // Parent and child both get in the critical section at the same @@ -708,6 +690,7 @@ mod tests { tx2.send(()); let _ = rx1.recv(); } + #[test] fn test_sem_runtime_friendly_blocking() { // Force the runtime to schedule two threads on the same sched_loop. @@ -727,9 +710,7 @@ mod tests { } rx.recv(); // wait for child to be done } - /************************************************************************ - * Mutex tests - ************************************************************************/ + #[test] fn test_mutex_lock() { // Unsafely achieve shared state, and do the textbook @@ -761,6 +742,7 @@ mod tests { } } } + #[test] fn test_mutex_cond_wait() { let m = Arc::new(Mutex::new()); @@ -820,14 +802,17 @@ mod tests { // wait until all children wake up for rx in rxs.iter_mut() { rx.recv(); } } + #[test] fn test_mutex_cond_broadcast() { test_mutex_cond_broadcast_helper(12); } + #[test] fn test_mutex_cond_broadcast_none() { test_mutex_cond_broadcast_helper(0); } + #[test] fn test_mutex_cond_no_waiter() { let m = Arc::new(Mutex::new()); @@ -838,6 +823,7 @@ mod tests { let lock = m2.lock(); assert!(!lock.cond.signal()); } + #[test] fn test_mutex_killed_simple() { use any::Any; @@ -854,6 +840,7 @@ mod tests { // child task must have finished by the time try returns drop(m.lock()); } + #[test] fn test_mutex_cond_signal_on_0() { // Tests that signal_on(0) is equivalent to signal(). @@ -866,6 +853,7 @@ mod tests { }); lock.cond.wait(); } + #[test] fn test_mutex_no_condvars() { let result = task::try(proc() { @@ -884,11 +872,10 @@ mod tests { }); assert!(result.is_err()); } - /************************************************************************ - * Reader/writer lock tests - ************************************************************************/ + #[cfg(test)] pub enum RWLockMode { Read, Write, Downgrade, DowngradeRead } + #[cfg(test)] fn lock_rwlock_in_mode(x: &Arc<RWLock>, mode: RWLockMode, blk: ||) { match mode { @@ -898,6 +885,7 @@ mod tests { DowngradeRead => { let _g = x.write().downgrade(); blk() } } } + #[cfg(test)] fn test_rwlock_exclusion(x: Arc<RWLock>, mode1: RWLockMode, @@ -934,6 +922,7 @@ mod tests { } } } + #[test] fn test_rwlock_readers_wont_modify_the_data() { test_rwlock_exclusion(Arc::new(RWLock::new()), Read, Write); @@ -943,6 +932,7 @@ mod tests { test_rwlock_exclusion(Arc::new(RWLock::new()), Write, DowngradeRead); test_rwlock_exclusion(Arc::new(RWLock::new()), DowngradeRead, Write); } + #[test] fn test_rwlock_writers_and_writers() { test_rwlock_exclusion(Arc::new(RWLock::new()), Write, Write); @@ -950,6 +940,7 @@ mod tests { test_rwlock_exclusion(Arc::new(RWLock::new()), Downgrade, Write); test_rwlock_exclusion(Arc::new(RWLock::new()), Downgrade, Downgrade); } + #[cfg(test)] fn test_rwlock_handshake(x: Arc<RWLock>, mode1: RWLockMode, @@ -982,6 +973,7 @@ mod tests { rx1.recv(); }) } + #[test] fn test_rwlock_readers_and_readers() { test_rwlock_handshake(Arc::new(RWLock::new()), Read, Read, false); @@ -991,6 +983,7 @@ mod tests { test_rwlock_handshake(Arc::new(RWLock::new()), Read, DowngradeRead, true); // Two downgrade_reads can never both end up reading at the same time. } + #[test] fn test_rwlock_downgrade_unlock() { // Tests that downgrade can unlock the lock in both modes @@ -1001,12 +994,14 @@ mod tests { lock_rwlock_in_mode(&y, DowngradeRead, || { }); test_rwlock_exclusion(y, Write, Write); } + #[test] fn test_rwlock_read_recursive() { let x = RWLock::new(); let _g1 = x.read(); let _g2 = x.read(); } + #[test] fn test_rwlock_cond_wait() { // As test_mutex_cond_wait above. @@ -1040,6 +1035,7 @@ mod tests { rx.recv(); // Wait until child wakes up drop(x.read()); // Just for good measure } + #[cfg(test)] fn test_rwlock_cond_broadcast_helper(num_waiters: uint) { // Much like the mutex broadcast test. Downgrade-enabled. @@ -1073,11 +1069,13 @@ mod tests { // wait until all children wake up for rx in rxs.iter_mut() { let _ = rx.recv(); } } + #[test] fn test_rwlock_cond_broadcast() { test_rwlock_cond_broadcast_helper(0); test_rwlock_cond_broadcast_helper(12); } + #[cfg(test)] fn rwlock_kill_helper(mode1: RWLockMode, mode2: RWLockMode) { use any::Any; @@ -1095,22 +1093,27 @@ mod tests { // child task must have finished by the time try returns lock_rwlock_in_mode(&x, mode2, || { }) } + #[test] fn test_rwlock_reader_killed_writer() { rwlock_kill_helper(Read, Write); } + #[test] fn test_rwlock_writer_killed_reader() { rwlock_kill_helper(Write, Read); } + #[test] fn test_rwlock_reader_killed_reader() { rwlock_kill_helper(Read, Read); } + #[test] fn test_rwlock_writer_killed_writer() { rwlock_kill_helper(Write, Write); } + #[test] fn test_rwlock_kill_downgrader() { rwlock_kill_helper(Downgrade, Read); diff --git a/src/libstd/sys/unix/fs.rs b/src/libstd/sys/unix/fs.rs index 816876b5e4a..4b47b768d60 100644 --- a/src/libstd/sys/unix/fs.rs +++ b/src/libstd/sys/unix/fs.rs @@ -305,12 +305,12 @@ fn mkstat(stat: &libc::stat) -> FileStat { FileStat { size: stat.st_size as u64, kind: match (stat.st_mode as libc::mode_t) & libc::S_IFMT { - libc::S_IFREG => io::TypeFile, - libc::S_IFDIR => io::TypeDirectory, - libc::S_IFIFO => io::TypeNamedPipe, - libc::S_IFBLK => io::TypeBlockSpecial, - libc::S_IFLNK => io::TypeSymlink, - _ => io::TypeUnknown, + libc::S_IFREG => io::FileType::RegularFile, + libc::S_IFDIR => io::FileType::Directory, + libc::S_IFIFO => io::FileType::NamedPipe, + libc::S_IFBLK => io::FileType::BlockSpecial, + libc::S_IFLNK => io::FileType::Symlink, + _ => io::FileType::Unknown, }, perm: FilePermission::from_bits_truncate(stat.st_mode as u32), created: mktime(stat.st_ctime as u64, stat.st_ctime_nsec as u64), diff --git a/src/libstd/sys/windows/fs.rs b/src/libstd/sys/windows/fs.rs index b881eb2d495..9c4ffb926b5 100644 --- a/src/libstd/sys/windows/fs.rs +++ b/src/libstd/sys/windows/fs.rs @@ -407,12 +407,12 @@ fn mkstat(stat: &libc::stat) -> FileStat { FileStat { size: stat.st_size as u64, kind: match (stat.st_mode as libc::c_int) & libc::S_IFMT { - libc::S_IFREG => io::TypeFile, - libc::S_IFDIR => io::TypeDirectory, - libc::S_IFIFO => io::TypeNamedPipe, - libc::S_IFBLK => io::TypeBlockSpecial, - libc::S_IFLNK => io::TypeSymlink, - _ => io::TypeUnknown, + libc::S_IFREG => io::FileType::RegularFile, + libc::S_IFDIR => io::FileType::Directory, + libc::S_IFIFO => io::FileType::NamedPipe, + libc::S_IFBLK => io::FileType::BlockSpecial, + libc::S_IFLNK => io::FileType::Symlink, + _ => io::FileType::Unknown, }, perm: FilePermission::from_bits_truncate(stat.st_mode as u32), created: stat.st_ctime as u64, diff --git a/src/libstd/sys/windows/process.rs b/src/libstd/sys/windows/process.rs index 7d0151a7b6b..78a8e09dac1 100644 --- a/src/libstd/sys/windows/process.rs +++ b/src/libstd/sys/windows/process.rs @@ -33,13 +33,11 @@ use string::String; pub use sys_common::ProcessConfig; -/** - * A value representing a child process. - * - * The lifetime of this value is linked to the lifetime of the actual - * process - the Process destructor calls self.finish() which waits - * for the process to terminate. - */ +/// A value representing a child process. +/// +/// The lifetime of this value is linked to the lifetime of the actual +/// process - the Process destructor calls self.finish() which waits +/// for the process to terminate. pub struct Process { /// The unique id of the process (this should never be negative). pid: pid_t, @@ -263,16 +261,14 @@ impl Process { } } - /** - * Waits for a process to exit and returns the exit code, failing - * if there is no process with the specified id. - * - * Note that this is private to avoid race conditions on unix where if - * a user calls waitpid(some_process.get_id()) then some_process.finish() - * and some_process.destroy() and some_process.finalize() will then either - * operate on a none-existent process or, even worse, on a newer process - * with the same id. - */ + /// Waits for a process to exit and returns the exit code, failing + /// if there is no process with the specified id. + /// + /// Note that this is private to avoid race conditions on unix where if + /// a user calls waitpid(some_process.get_id()) then some_process.finish() + /// and some_process.destroy() and some_process.finalize() will then either + /// operate on a none-existent process or, even worse, on a newer process + /// with the same id. pub fn wait(&self, deadline: u64) -> IoResult<ProcessExit> { use libc::types::os::arch::extra::DWORD; use libc::consts::os::extra::{ |