-#[doc = "An atomically reference counted wrapper that can be used to
-share immutable data between tasks."]
+/**
+ * An atomically reference counted wrapper that can be used to
+ * share immutable data between tasks.
+ */
import comm::{port, chan, methods};
import sys::methods;
type arc<T: const> = arc_destruct<T>;
-#[doc="Create an atomically reference counted wrapper."]
+/// Create an atomically reference counted wrapper.
fn arc<T: const>(-data: T) -> arc<T> {
let data = ~{mut count: 1, data: data};
unsafe {
}
}
-#[doc="Access the underlying data in an atomically reference counted
- wrapper."]
+/**
+ * Access the underlying data in an atomically reference counted
+ * wrapper.
+ */
fn get<T: const>(rc: &a.arc<T>) -> &a.T {
unsafe {
let ptr: ~arc_data<T> = unsafe::reinterpret_cast((*rc).data);
}
}
-#[doc="Duplicate an atomically reference counted wrapper.
-
-The resulting two `arc` objects will point to the same underlying data
-object. However, one of the `arc` objects can be sent to another task,
-allowing them to share the underlying data."]
+/**
+ * Duplicate an atomically reference counted wrapper.
+ *
+ * The resulting two `arc` objects will point to the same underlying data
+ * object. However, one of the `arc` objects can be sent to another task,
+ * allowing them to share the underlying data.
+ */
fn clone<T: const>(rc: &arc<T>) -> arc<T> {
unsafe {
let ptr: ~arc_data<T> = unsafe::reinterpret_cast((*rc).data);
// -*- rust -*-
-#[doc = "Boolean logic"];
+//! Boolean logic
export not, and, or, xor, implies;
export eq, ne, is_true, is_false;
export from_str, to_str, all_values, to_bit;
-#[doc = "Negation / inverse"]
+/// Negation / inverse
pure fn not(v: bool) -> bool { !v }
-#[doc = "Conjunction"]
+/// Conjunction
pure fn and(a: bool, b: bool) -> bool { a && b }
-#[doc = "Disjunction"]
+/// Disjunction
pure fn or(a: bool, b: bool) -> bool { a || b }
-#[doc = "
-Exclusive or
-
-Identical to `or(and(a, not(b)), and(not(a), b))`
-"]
+/**
+ * Exclusive or
+ *
+ * Identical to `or(and(a, not(b)), and(not(a), b))`
+ */
pure fn xor(a: bool, b: bool) -> bool { (a && !b) || (!a && b) }
-#[doc = "Implication in the logic, i.e. from `a` follows `b`"]
+/// Implication in the logic, i.e. from `a` follows `b`
pure fn implies(a: bool, b: bool) -> bool { !a || b }
-#[doc = "
-true if truth values `a` and `b` are indistinguishable in the logic
-"]
+/// true if truth values `a` and `b` are indistinguishable in the logic
pure fn eq(a: bool, b: bool) -> bool { a == b }
-#[doc = "true if truth values `a` and `b` are distinguishable in the logic"]
+/// true if truth values `a` and `b` are distinguishable in the logic
pure fn ne(a: bool, b: bool) -> bool { a != b }
-#[doc = "true if `v` represents truth in the logic"]
+/// true if `v` represents truth in the logic
pure fn is_true(v: bool) -> bool { v }
-#[doc = "true if `v` represents falsehood in the logic"]
+/// true if `v` represents falsehood in the logic
pure fn is_false(v: bool) -> bool { !v }
-#[doc = "Parse logic value from `s`"]
+/// Parse logic value from `s`
pure fn from_str(s: str) -> option<bool> {
alt check s {
"true" { some(true) }
}
}
-#[doc = "Convert `v` into a string"]
+/// Convert `v` into a string
pure fn to_str(v: bool) -> str { if v { "true" } else { "false" } }
-#[doc = "
-Iterates over all truth values by passing them to `blk` in an unspecified
-order
-"]
+/**
+ * Iterates over all truth values by passing them to `blk` in an unspecified
+ * order
+ */
fn all_values(blk: fn(v: bool)) {
blk(true);
blk(false);
}
-#[doc = "converts truth value to an 8 bit byte"]
+/// converts truth value to an 8 bit byte
pure fn to_bit(v: bool) -> u8 { if v { 1u8 } else { 0u8 } }
#[test]
-#[doc = "Operations on shared box types"];
+//! Operations on shared box types
export ptr_eq;
pure fn ptr_eq<T>(a: @T, b: @T) -> bool {
- #[doc = "Determine if two shared boxes point to the same object"];
+ //! Determine if two shared boxes point to the same object
unsafe { ptr::addr_of(*a) == ptr::addr_of(*b) }
}
-#[doc = "Utilities for manipulating the char type"];
+//! Utilities for manipulating the char type
/*
Lu Uppercase_Letter an uppercase letter
import is_XID_continue = unicode::derived_property::XID_Continue;
-#[doc = "
-Indicates whether a character is in lower case, defined
-in terms of the Unicode General Category 'Ll'
-"]
+/**
+ * Indicates whether a character is in lower case, defined
+ * in terms of the Unicode General Category 'Ll'
+ */
pure fn is_lowercase(c: char) -> bool {
ret unicode::general_category::Ll(c);
}
-#[doc = "
-Indicates whether a character is in upper case, defined
-in terms of the Unicode General Category 'Lu'.
-"]
+/**
+ * Indicates whether a character is in upper case, defined
+ * in terms of the Unicode General Category 'Lu'.
+ */
pure fn is_uppercase(c: char) -> bool {
ret unicode::general_category::Lu(c);
}
-#[doc = "
-Indicates whether a character is whitespace, defined in
-terms of the Unicode General Categories 'Zs', 'Zl', 'Zp'
-additional 'Cc'-category control codes in the range [0x09, 0x0d]/~
-"]
+/**
+ * Indicates whether a character is whitespace, defined in
+ * terms of the Unicode General Categories 'Zs', 'Zl', 'Zp'
+ * additional 'Cc'-category control codes in the range [0x09, 0x0d]
+ */
pure fn is_whitespace(c: char) -> bool {
ret ('\x09' <= c && c <= '\x0d')
|| unicode::general_category::Zs(c)
|| unicode::general_category::Zp(c);
}
-#[doc = "
-Indicates whether a character is alphanumeric, defined
-in terms of the Unicode General Categories 'Nd',
-'Nl', 'No' and the Derived Core Property 'Alphabetic'.
-"]
+/**
+ * Indicates whether a character is alphanumeric, defined
+ * in terms of the Unicode General Categories 'Nd',
+ * 'Nl', 'No' and the Derived Core Property 'Alphabetic'.
+ */
pure fn is_alphanumeric(c: char) -> bool {
ret unicode::derived_property::Alphabetic(c) ||
unicode::general_category::Nd(c) ||
unicode::general_category::No(c);
}
-#[doc = "Indicates whether the character is an ASCII character"]
+/// Indicates whether the character is an ASCII character
pure fn is_ascii(c: char) -> bool {
c - ('\x7F' & c) == '\x00'
}
-#[doc = "Indicates whether the character is numeric (Nd, Nl, or No)"]
+/// Indicates whether the character is numeric (Nd, Nl, or No)
pure fn is_digit(c: char) -> bool {
ret unicode::general_category::Nd(c) ||
unicode::general_category::Nl(c) ||
unicode::general_category::No(c);
}
-#[doc = "
-Convert a char to the corresponding digit.
-
-# Safety note
-
-This function fails if `c` is not a valid char
-
-# Return value
-
-If `c` is between '0' and '9', the corresponding value
-between 0 and 9. If `c` is 'a' or 'A', 10. If `c` is
-'b' or 'B', 11, etc. Returns none if the char does not
-refer to a digit in the given radix.
-"]
+/**
+ * Convert a char to the corresponding digit.
+ *
+ * # Safety note
+ *
+ * This function fails if `c` is not a valid char
+ *
+ * # Return value
+ *
+ * If `c` is between '0' and '9', the corresponding value
+ * between 0 and 9. If `c` is 'a' or 'A', 10. If `c` is
+ * 'b' or 'B', 11, etc. Returns none if the char does not
+ * refer to a digit in the given radix.
+ */
pure fn to_digit(c: char, radix: uint) -> option<uint> {
let val = alt c {
'0' to '9' { c as uint - ('0' as uint) }
else { none }
}
-#[doc = "
-Return the hexadecimal unicode escape of a char.
-
-The rules are as follows:
-
- - chars in [0,0xff]/~ get 2-digit escapes: `\\xNN`
- - chars in [0x100,0xffff]/~ get 4-digit escapes: `\\uNNNN`
- - chars above 0x10000 get 8-digit escapes: `\\UNNNNNNNN`
-"]
+/**
+ * Return the hexadecimal unicode escape of a char.
+ *
+ * The rules are as follows:
+ *
+ * - chars in [0,0xff] get 2-digit escapes: `\\xNN`
+ * - chars in [0x100,0xffff] get 4-digit escapes: `\\uNNNN`
+ * - chars above 0x10000 get 8-digit escapes: `\\UNNNNNNNN`
+ */
fn escape_unicode(c: char) -> str {
let s = u32::to_str(c as u32, 16u);
let (c, pad) = (if c <= '\xff' { ('x', 2u) }
ret out;
}
-#[doc = "
-Return a 'default' ASCII and C++11-like char-literal escape of a char.
-
-The default is chosen with a bias toward producing literals that are
-legal in a variety of languages, including C++11 and similar C-family
-languages. The exact rules are:
-
- - Tab, CR and LF are escaped as '\t', '\r' and '\n' respectively.
- - Single-quote, double-quote and backslash chars are backslash-escaped.
- - Any other chars in the range [0x20,0x7e]/~ are not escaped.
- - Any other chars are given hex unicode escapes; see `escape_unicode`.
-"]
+/**
+ * Return a 'default' ASCII and C++11-like char-literal escape of a char.
+ *
+ * The default is chosen with a bias toward producing literals that are
+ * legal in a variety of languages, including C++11 and similar C-family
+ * languages. The exact rules are:
+ *
+ * - Tab, CR and LF are escaped as '\t', '\r' and '\n' respectively.
+ * - Single-quote, double-quote and backslash chars are backslash-escaped.
+ * - Any other chars in the range [0x20,0x7e] are not escaped.
+ * - Any other chars are given hex unicode escapes; see `escape_unicode`.
+ */
fn escape_default(c: char) -> str {
alt c {
'\t' { "\\t" }
}
}
-#[doc = "
-Compare two chars
-
-# Return value
-
--1 if a < b, 0 if a == b, +1 if a > b
-"]
+/**
+ * Compare two chars
+ *
+ * # Return value
+ *
+ * -1 if a < b, 0 if a == b, +1 if a > b
+ */
pure fn cmp(a: char, b: char) -> int {
ret if b > a { -1 }
else if b < a { 1 }
-#[doc="Interfaces used for comparison."]
+/// Interfaces used for comparison.
iface ord {
fn lt(&&other: self) -> bool;
-#[doc = "
-Communication between tasks
-
-Communication between tasks is facilitated by ports (in the receiving
-task), and channels (in the sending task). Any number of channels may
-feed into a single port. Ports and channels may only transmit values
-of unique types; that is, values that are statically guaranteed to be
-accessed by a single 'owner' at a time. Unique types include scalars,
-vectors, strings, and records, tags, tuples and unique boxes (`~T`)
-thereof. Most notably, shared boxes (`@T`) may not be transmitted
-across channels.
-
-# Example
-
-~~~
-let po = comm::port();
-let ch = comm::chan(po);
-
-task::spawn {||
- comm::send(ch, \"Hello, World\");
-});
-
-io::println(comm::recv(p));
-~~~
-"];
+/*!
+ * Communication between tasks
+ *
+ * Communication between tasks is facilitated by ports (in the receiving
+ * task), and channels (in the sending task). Any number of channels may
+ * feed into a single port. Ports and channels may only transmit values
+ * of unique types; that is, values that are statically guaranteed to be
+ * accessed by a single 'owner' at a time. Unique types include scalars,
+ * vectors, strings, and records, tags, tuples and unique boxes (`~T`)
+ * thereof. Most notably, shared boxes (`@T`) may not be transmitted
+ * across channels.
+ *
+ * # Example
+ *
+ * ~~~
+ * let po = comm::port();
+ * let ch = comm::chan(po);
+ *
+ * task::spawn {||
+ * comm::send(ch, "Hello, World");
+ * });
+ *
+ * io::println(comm::recv(p));
+ * ~~~
+ */
import either::either;
import libc::size_t;
export listen;
-#[doc = "
-A communication endpoint that can receive messages
-
-Each port has a unique per-task identity and may not be replicated or
-transmitted. If a port value is copied, both copies refer to the same
-port. Ports may be associated with multiple `chan`s.
-"]
+/**
+ * A communication endpoint that can receive messages
+ *
+ * Each port has a unique per-task identity and may not be replicated or
+ * transmitted. If a port value is copied, both copies refer to the same
+ * port. Ports may be associated with multiple `chan`s.
+ */
enum port<T: send> {
port_t(@port_ptr<T>)
}
// It's critical that this only have one variant, so it has a record
// layout, and will work in the rust_task structure in task.rs.
-#[doc = "
-A communication endpoint that can send messages
-
-Each channel is bound to a port when the channel is constructed, so
-the destination port for a channel must exist before the channel
-itself. Channels are weak: a channel does not keep the port it is
-bound to alive. If a channel attempts to send data to a dead port that
-data will be silently dropped. Channels may be duplicated and
-themselves transmitted over other channels.
-"]
+/**
+ * A communication endpoint that can send messages
+ *
+ * Each channel is bound to a port when the channel is constructed, so
+ * the destination port for a channel must exist before the channel
+ * itself. Channels are weak: a channel does not keep the port it is
+ * bound to alive. If a channel attempts to send data to a dead port that
+ * data will be silently dropped. Channels may be duplicated and
+ * themselves transmitted over other channels.
+ */
enum chan<T: send> {
chan_t(port_id)
}
-#[doc = "Constructs a port"]
+/// Constructs a port
fn port<T: send>() -> port<T> {
port_t(@port_ptr(rustrt::new_port(sys::size_of::<T>() as size_t)))
}
}
-#[doc = "Open a new receiving channel for the duration of a function"]
+/// Open a new receiving channel for the duration of a function
fn listen<T: send, U>(f: fn(chan<T>) -> U) -> U {
let po = port();
f(po.chan())
}
}
-#[doc = "
-Internal function for converting from a channel to a port
-
-# Failure
-
-Fails if the port is detached or dead. Fails if the port
-is owned by a different task.
-"]
+/**
+ * Internal function for converting from a channel to a port
+ *
+ * # Failure
+ *
+ * Fails if the port is detached or dead. Fails if the port
+ * is owned by a different task.
+ */
fn as_raw_port<T: send, U>(ch: comm::chan<T>, f: fn(*rust_port) -> U) -> U {
class portref {
f(p.p)
}
-#[doc = "
-Constructs a channel. The channel is bound to the port used to
-construct it.
-"]
+/**
+ * Constructs a channel. The channel is bound to the port used to
+ * construct it.
+ */
fn chan<T: send>(p: port<T>) -> chan<T> {
chan_t(rustrt::get_port_id((**p).po))
}
-#[doc = "
-Sends data over a channel. The sent data is moved into the channel,
-whereupon the caller loses access to it.
-"]
+/**
+ * Sends data over a channel. The sent data is moved into the channel,
+ * whereupon the caller loses access to it.
+ */
fn send<T: send>(ch: chan<T>, -data: T) {
let chan_t(p) = ch;
let data_ptr = ptr::addr_of(data) as *();
task::yield();
}
-#[doc = "
-Receive from a port. If no data is available on the port then the
-task will block until data becomes available.
-"]
+/**
+ * Receive from a port. If no data is available on the port then the
+ * task will block until data becomes available.
+ */
fn recv<T: send>(p: port<T>) -> T { recv_((**p).po) }
-#[doc = "Returns true if there are messages available"]
+/// Returns true if there are messages available
fn peek<T: send>(p: port<T>) -> bool { peek_((**p).po) }
#[doc(hidden)]
as_raw_port(ch, |x|peek_(x))
}
-#[doc = "Receive on a raw port pointer"]
+/// Receive on a raw port pointer
fn recv_<T: send>(p: *rust_port) -> T {
let yield = 0u;
let yieldp = ptr::addr_of(yield);
rustrt::rust_port_size(p) != 0u as libc::size_t
}
-#[doc = "Receive on one of two ports"]
+/// Receive on one of two ports
fn select2<A: send, B: send>(p_a: port<A>, p_b: port<B>)
-> either<A, B> {
let ports = ~[(**p_a).po, (**p_b).po];
#[license = "MIT"];
#[crate_type = "lib"];
-#[doc = "
-The Rust core library provides functionality that is closely tied to the Rust
-built-in types and runtime services, or that is used in nearly every
-non-trivial program.
-
-`core` includes modules corresponding to each of the integer types, each of
-the floating point types, the `bool` type, tuples, characters, strings,
-vectors (`vec`), shared boxes (`box`), and unsafe pointers (`ptr`).
-Additionally, `core` provides very commonly used built-in types and
-operations, concurrency primitives, platform abstractions, I/O, and complete
-bindings to the C standard library.
-
-`core` is linked by default to all crates and the contents imported.
-Implicitly, all crates behave as if they included the following prologue:
-
- use core;
- import core::*;
-
-This behavior can be disabled with the `#[no_core]` crate attribute.
-"];
+/*!
+ * The Rust core library provides functionality that is closely tied to the
+ * Rust built-in types and runtime services, or that is used in nearly every
+ * non-trivial program.
+ *
+ * `core` includes modules corresponding to each of the integer types, each of
+ * the floating point types, the `bool` type, tuples, characters, strings,
+ * vectors (`vec`), shared boxes (`box`), and unsafe pointers (`ptr`).
+ * Additionally, `core` provides very commonly used built-in types and
+ * operations, concurrency primitives, platform abstractions, I/O, and
+ * complete bindings to the C standard library.
+ *
+ * `core` is linked by default to all crates and the contents imported.
+ * Implicitly, all crates behave as if they included the following prologue:
+ *
+ * use core;
+ * import core::*;
+ *
+ * This behavior can be disabled with the `#[no_core]` crate attribute.
+ */
// Don't link to core. We are core.
#[no_core];
// Built-in-type support modules
-#[doc = "Operations and constants for `int`"]
+/// Operations and constants for `int`
#[path = "int-template"]
mod int {
import inst::{ hash, pow };
mod inst;
}
-#[doc = "Operations and constants for `i8`"]
+/// Operations and constants for `i8`
#[path = "int-template"]
mod i8 {
#[path = "i8.rs"]
mod inst;
}
-#[doc = "Operations and constants for `i16`"]
+/// Operations and constants for `i16`
#[path = "int-template"]
mod i16 {
#[path = "i16.rs"]
mod inst;
}
-#[doc = "Operations and constants for `i32`"]
+/// Operations and constants for `i32`
#[path = "int-template"]
mod i32 {
#[path = "i32.rs"]
mod inst;
}
-#[doc = "Operations and constants for `i64`"]
+/// Operations and constants for `i64`
#[path = "int-template"]
mod i64 {
#[path = "i64.rs"]
mod inst;
}
-#[doc = "Operations and constants for `uint`"]
+/// Operations and constants for `uint`
#[path = "uint-template"]
mod uint {
import inst::{
mod inst;
}
-#[doc = "Operations and constants for `u8`"]
+/// Operations and constants for `u8`
#[path = "uint-template"]
mod u8 {
import inst::is_ascii;
mod inst;
}
-#[doc = "Operations and constants for `u16`"]
+/// Operations and constants for `u16`
#[path = "uint-template"]
mod u16 {
#[path = "u16.rs"]
mod inst;
}
-#[doc = "Operations and constants for `u32`"]
+/// Operations and constants for `u32`
#[path = "uint-template"]
mod u32 {
#[path = "u32.rs"]
mod inst;
}
-#[doc = "Operations and constants for `u64`"]
+/// Operations and constants for `u64`
#[path = "uint-template"]
mod u64 {
#[path = "u64.rs"]
export error, warn, info, debug;
-#[doc = "The error log level"]
+/// The error log level
const error : u32 = 0_u32;
-#[doc = "The warning log level"]
+/// The warning log level
const warn : u32 = 1_u32;
-#[doc = "The info log level"]
+/// The info log level
const info : u32 = 2_u32;
-#[doc = "The debug log level"]
+/// The debug log level
const debug : u32 = 3_u32;
// A curious inner-module that's not exported that contains the binding
import std::test;
}
-#[doc = "
-A standard function to use to indicate unreachable code. Because the
-function is guaranteed to fail typestate will correctly identify
-any code paths following the appearance of this function as unreachable.
-"]
+/**
+ * A standard function to use to indicate unreachable code. Because the
+ * function is guaranteed to fail typestate will correctly identify
+ * any code paths following the appearance of this function as unreachable.
+ */
fn unreachable() -> ! {
fail "Internal error: entered unreachable code";
}
-#[doc = "
-A doubly-linked list. Supports O(1) head, tail, count, push, pop, etc.
-
-Do not use ==, !=, <, etc on doubly-linked lists -- it may not terminate.
-"]
+/**
+ * A doubly-linked list. Supports O(1) head, tail, count, push, pop, etc.
+ *
+ * Do not use ==, !=, <, etc on doubly-linked lists -- it may not terminate.
+ */
import dlist_iter::extensions;
}
impl extensions<T> for dlist_node<T> {
- #[doc = "Get the next node in the list, if there is one."]
+ /// Get the next node in the list, if there is one.
pure fn next_link() -> option<dlist_node<T>> {
self.assert_links();
self.next
}
- #[doc = "Get the next node in the list, failing if there isn't one."]
+ /// Get the next node in the list, failing if there isn't one.
pure fn next_node() -> dlist_node<T> {
alt self.next_link() {
some(nobe) { nobe }
none { fail "This dlist node has no next neighbour." }
}
}
- #[doc = "Get the previous node in the list, if there is one."]
+ /// Get the previous node in the list, if there is one.
pure fn prev_link() -> option<dlist_node<T>> {
self.assert_links();
self.prev
}
- #[doc = "Get the previous node in the list, failing if there isn't one."]
+ /// Get the previous node in the list, failing if there isn't one.
pure fn prev_node() -> dlist_node<T> {
alt self.prev_link() {
some(nobe) { nobe }
}
}
- #[doc = "Remove a node from whatever dlist it's on (failing if none)."]
+ /// Remove a node from whatever dlist it's on (failing if none).
fn remove() {
if option::is_some(self.root) {
option::get(self.root).remove(self);
}
}
-#[doc = "Creates a new dlist node with the given data."]
+/// Creates a new dlist node with the given data.
pure fn create_node<T>(+data: T) -> dlist_node<T> {
dlist_node(@{data: data, mut root: none, mut prev: none, mut next: none})
}
-#[doc = "Creates a new, empty dlist."]
+/// Creates a new, empty dlist.
pure fn create<T>() -> dlist<T> {
dlist(@{mut size: 0, mut hd: none, mut tl: none})
}
-#[doc = "Creates a new dlist with a single element"]
+/// Creates a new dlist with a single element
fn from_elt<T>(+data: T) -> dlist<T> {
let list = create();
list.push(data);
}
impl extensions<T> for dlist<T> {
- #[doc = "Get the size of the list. O(1)."]
+ /// Get the size of the list. O(1).
pure fn len() -> uint { self.size }
- #[doc = "Returns true if the list is empty. O(1)."]
+ /// Returns true if the list is empty. O(1).
pure fn is_empty() -> bool { self.len() == 0 }
- #[doc = "Returns true if the list is not empty. O(1)."]
+ /// Returns true if the list is not empty. O(1).
pure fn is_not_empty() -> bool { self.len() != 0 }
- #[doc = "Add data to the head of the list. O(1)."]
+ /// Add data to the head of the list. O(1).
fn push_head(+data: T) {
self.add_head(self.new_link(data));
}
- #[doc = "Add data to the head of the list, and get the new containing
- node. O(1)."]
+ /**
+ * Add data to the head of the list, and get the new containing
+ * node. O(1).
+ */
fn push_head_n(+data: T) -> dlist_node<T> {
let mut nobe = self.new_link(data);
self.add_head(nobe);
option::get(nobe)
}
- #[doc = "Add data to the tail of the list. O(1)."]
+ /// Add data to the tail of the list. O(1).
fn push(+data: T) {
self.add_tail(self.new_link(data));
}
- #[doc = "Add data to the tail of the list, and get the new containing
- node. O(1)."]
+ /**
+ * Add data to the tail of the list, and get the new containing
+ * node. O(1).
+ */
fn push_n(+data: T) -> dlist_node<T> {
let mut nobe = self.new_link(data);
self.add_tail(nobe);
option::get(nobe)
}
- #[doc = "Insert data into the middle of the list, left of the given node.
- O(1)."]
+ /**
+ * Insert data into the middle of the list, left of the given node.
+ * O(1).
+ */
fn insert_before(+data: T, neighbour: dlist_node<T>) {
self.insert_left(self.new_link(data), neighbour);
}
- #[doc = "Insert an existing node in the middle of the list, left of the
- given node. O(1)."]
+ /**
+ * Insert an existing node in the middle of the list, left of the
+ * given node. O(1).
+ */
fn insert_n_before(nobe: dlist_node<T>, neighbour: dlist_node<T>) {
self.make_mine(nobe);
self.insert_left(some(nobe), neighbour);
}
- #[doc = "Insert data in the middle of the list, left of the given node,
- and get its containing node. O(1)."]
+ /**
+ * Insert data in the middle of the list, left of the given node,
+ * and get its containing node. O(1).
+ */
fn insert_before_n(+data: T, neighbour: dlist_node<T>) -> dlist_node<T> {
let mut nobe = self.new_link(data);
self.insert_left(nobe, neighbour);
option::get(nobe)
}
- #[doc = "Insert data into the middle of the list, right of the given node.
- O(1)."]
+ /**
+ * Insert data into the middle of the list, right of the given node.
+ * O(1).
+ */
fn insert_after(+data: T, neighbour: dlist_node<T>) {
self.insert_right(neighbour, self.new_link(data));
}
- #[doc = "Insert an existing node in the middle of the list, right of the
- given node. O(1)."]
+ /**
+ * Insert an existing node in the middle of the list, right of the
+ * given node. O(1).
+ */
fn insert_n_after(nobe: dlist_node<T>, neighbour: dlist_node<T>) {
self.make_mine(nobe);
self.insert_right(neighbour, some(nobe));
}
- #[doc = "Insert data in the middle of the list, right of the given node,
- and get its containing node. O(1)."]
+ /**
+ * Insert data in the middle of the list, right of the given node,
+ * and get its containing node. O(1).
+ */
fn insert_after_n(+data: T, neighbour: dlist_node<T>) -> dlist_node<T> {
let mut nobe = self.new_link(data);
self.insert_right(neighbour, nobe);
option::get(nobe)
}
- #[doc = "Remove a node from the head of the list. O(1)."]
+ /// Remove a node from the head of the list. O(1).
fn pop_n() -> option<dlist_node<T>> {
let hd = self.peek_n();
hd.map(|nobe| self.unlink(nobe));
hd
}
- #[doc = "Remove a node from the tail of the list. O(1)."]
+ /// Remove a node from the tail of the list. O(1).
fn pop_tail_n() -> option<dlist_node<T>> {
let tl = self.peek_tail_n();
tl.map(|nobe| self.unlink(nobe));
tl
}
- #[doc = "Get the node at the list's head. O(1)."]
+ /// Get the node at the list's head. O(1).
pure fn peek_n() -> option<dlist_node<T>> { self.hd }
- #[doc = "Get the node at the list's tail. O(1)."]
+ /// Get the node at the list's tail. O(1).
pure fn peek_tail_n() -> option<dlist_node<T>> { self.tl }
- #[doc = "Get the node at the list's head, failing if empty. O(1)."]
+ /// Get the node at the list's head, failing if empty. O(1).
pure fn head_n() -> dlist_node<T> {
alt self.hd {
some(nobe) { nobe }
none { fail "Attempted to get the head of an empty dlist." }
}
}
- #[doc = "Get the node at the list's tail, failing if empty. O(1)."]
+ /// Get the node at the list's tail, failing if empty. O(1).
pure fn tail_n() -> dlist_node<T> {
alt self.tl {
some(nobe) { nobe }
}
}
- #[doc = "Remove a node from anywhere in the list. O(1)."]
+ /// Remove a node from anywhere in the list. O(1).
fn remove(nobe: dlist_node<T>) { self.unlink(nobe); }
- #[doc = "Check data structure integrity. O(n)."]
+ /// Check data structure integrity. O(n).
fn assert_consistent() {
if option::is_none(self.hd) || option::is_none(self.tl) {
assert option::is_none(self.hd) && option::is_none(self.tl);
}
impl extensions<T: copy> for dlist<T> {
- #[doc = "Remove data from the head of the list. O(1)."]
+ /// Remove data from the head of the list. O(1).
fn pop() -> option<T> { self.pop_n().map (|nobe| nobe.data) }
- #[doc = "Remove data from the tail of the list. O(1)."]
+ /// Remove data from the tail of the list. O(1).
fn pop_tail() -> option<T> { self.pop_tail_n().map (|nobe| nobe.data) }
- #[doc = "Get data at the list's head. O(1)."]
+ /// Get data at the list's head. O(1).
fn peek() -> option<T> { self.peek_n().map (|nobe| nobe.data) }
- #[doc = "Get data at the list's tail. O(1)."]
+ /// Get data at the list's tail. O(1).
fn peek_tail() -> option<T> { self.peek_tail_n().map (|nobe| nobe.data) }
- #[doc = "Get data at the list's head, failing if empty. O(1)."]
+ /// Get data at the list's head, failing if empty. O(1).
pure fn head() -> T { self.head_n().data }
- #[doc = "Get data at the list's tail, failing if empty. O(1)."]
+ /// Get data at the list's tail, failing if empty. O(1).
pure fn tail() -> T { self.tail_n().data }
}
export extensions;
export unwrap;
-#[doc = "
-
-A growable, modifiable vector type that accumulates elements into a
-unique vector.
-
-# Limitations on recursive use
-
-This class works by swapping the unique vector out of the data
-structure whenever it is to be used. Therefore, recursive use is not
-permitted. That is, while iterating through a vector, you cannot
-access the vector in any other way or else the program will fail. If
-you wish, you can use the `swap()` method to gain access to the raw
-vector and transform it or use it any way you like. Eventually, we
-may permit read-only access during iteration or other use.
-
-# WARNING
-
-For maximum performance, this type is implemented using some rather
-unsafe code. In particular, this innocent looking `[mut A]/~` pointer
-*may be null!* Therefore, it is important you not reach into the
-data structure manually but instead use the provided extensions.
-
-The reason that I did not use an unsafe pointer in the structure
-itself is that I wanted to ensure that the vector would be freed when
-the dvec is dropped. The reason that I did not use an `option<T>`
-instead of a nullable pointer is that I found experimentally that it
-becomes approximately 50% slower. This can probably be improved
-through optimization. You can run your own experiments using
-`src/test/bench/vec-append.rs`. My own tests found that using null
-pointers achieved about 103 million pushes/second. Using an option
-type could only produce 47 million pushes/second.
-
-"]
+/**
+ * A growable, modifiable vector type that accumulates elements into a
+ * unique vector.
+ *
+ * # Limitations on recursive use
+ *
+ * This class works by swapping the unique vector out of the data
+ * structure whenever it is to be used. Therefore, recursive use is not
+ * permitted. That is, while iterating through a vector, you cannot
+ * access the vector in any other way or else the program will fail. If
+ * you wish, you can use the `swap()` method to gain access to the raw
+ * vector and transform it or use it any way you like. Eventually, we
+ * may permit read-only access during iteration or other use.
+ *
+ * # WARNING
+ *
+ * For maximum performance, this type is implemented using some rather
+ * unsafe code. In particular, this innocent looking `[mut A]/~` pointer
+ * *may be null!* Therefore, it is important you not reach into the
+ * data structure manually but instead use the provided extensions.
+ *
+ * The reason that I did not use an unsafe pointer in the structure
+ * itself is that I wanted to ensure that the vector would be freed when
+ * the dvec is dropped. The reason that I did not use an `option<T>`
+ * instead of a nullable pointer is that I found experimentally that it
+ * becomes approximately 50% slower. This can probably be improved
+ * through optimization. You can run your own experiments using
+ * `src/test/bench/vec-append.rs`. My own tests found that using null
+ * pointers achieved about 103 million pushes/second. Using an option
+ * type could only produce 47 million pushes/second.
+ */
type dvec<A> = {
mut data: ~[mut A]
};
-#[doc = "Creates a new, empty dvec"]
+/// Creates a new, empty dvec
fn dvec<A>() -> dvec<A> {
{mut data: ~[mut]}
}
-#[doc = "Creates a new dvec with a single element"]
+/// Creates a new dvec with a single element
fn from_elt<A>(+e: A) -> dvec<A> {
{mut data: ~[mut e]}
}
-#[doc = "Creates a new dvec with the contents of a vector"]
+/// Creates a new dvec with the contents of a vector
fn from_vec<A>(+v: ~[mut A]) -> dvec<A> {
{mut data: v}
}
-#[doc = "Consumes the vector and returns its contents"]
+/// Consumes the vector and returns its contents
fn unwrap<A>(-d: dvec<A>) -> ~[mut A] {
let {data: v} <- d;
ret v;
// almost nothing works without the copy bound due to limitations
// around closures.
impl extensions<A> for dvec<A> {
- #[doc = "
-
- Swaps out the current vector and hands it off to a user-provided
- function `f`. The function should transform it however is desired
- and return a new vector to replace it with.
-
- "]
+ /**
+ * Swaps out the current vector and hands it off to a user-provided
+ * function `f`. The function should transform it however is desired
+ * and return a new vector to replace it with.
+ */
#[inline(always)]
fn swap(f: fn(-~[mut A]) -> ~[mut A]) {
self.borrow(|v| self.return(f(v)))
}
- #[doc = "Returns the number of elements currently in the dvec"]
+ /// Returns the number of elements currently in the dvec
fn len() -> uint {
do self.borrow |v| {
let l = v.len();
}
}
- #[doc = "Overwrite the current contents"]
+ /// Overwrite the current contents
fn set(+w: ~[mut A]) {
self.check_not_borrowed();
self.data <- w;
}
- #[doc = "Remove and return the last element"]
+ /// Remove and return the last element
fn pop() -> A {
do self.borrow |v| {
let mut v <- v;
}
}
- #[doc = "Insert a single item at the front of the list"]
+ /// Insert a single item at the front of the list
fn unshift(-t: A) {
unsafe {
let mut data = unsafe::reinterpret_cast(null::<()>());
}
}
- #[doc = "Append a single item to the end of the list"]
+ /// Append a single item to the end of the list
fn push(+t: A) {
self.check_not_borrowed();
vec::push(self.data, t);
}
- #[doc = "Remove and return the first element"]
+ /// Remove and return the first element
fn shift() -> A {
do self.borrow |v| {
let mut v = vec::from_mut(v);
}
impl extensions<A:copy> for dvec<A> {
- #[doc = "
- Append all elements of a vector to the end of the list
-
- Equivalent to `append_iter()` but potentially more efficient.
- "]
+ /**
+ * Append all elements of a vector to the end of the list
+ *
+ * Equivalent to `append_iter()` but potentially more efficient.
+ */
fn push_all(ts: &[const A]) {
self.push_slice(ts, 0u, vec::len(ts));
}
- #[doc = "
- Appends elements from `from_idx` to `to_idx` (exclusive)
- "]
+ /// Appends elements from `from_idx` to `to_idx` (exclusive)
fn push_slice(ts: &[const A], from_idx: uint, to_idx: uint) {
do self.swap |v| {
let mut v <- v;
}
/*
- #[doc = "
- Append all elements of an iterable.
-
- Failure will occur if the iterable's `each()` method
- attempts to access this vector.
- "]
+ /**
+ * Append all elements of an iterable.
+ *
+ * Failure will occur if the iterable's `each()` method
+ * attempts to access this vector.
+ */
fn append_iter<A, I:iter::base_iter<A>>(ts: I) {
do self.swap |v| {
let mut v = alt ts.size_hint() {
}
*/
- #[doc = "
- Gets a copy of the current contents.
-
- See `unwrap()` if you do not wish to copy the contents.
- "]
+ /**
+ * Gets a copy of the current contents.
+ *
+ * See `unwrap()` if you do not wish to copy the contents.
+ */
fn get() -> ~[A] {
do self.borrow |v| {
let w = vec::from_mut(copy v);
}
}
- #[doc = "Copy out an individual element"]
+ /// Copy out an individual element
#[inline(always)]
fn [](idx: uint) -> A {
self.get_elt(idx)
}
- #[doc = "Copy out an individual element"]
+ /// Copy out an individual element
#[inline(always)]
fn get_elt(idx: uint) -> A {
self.check_not_borrowed();
ret self.data[idx];
}
- #[doc = "Overwrites the contents of the element at `idx` with `a`"]
+ /// Overwrites the contents of the element at `idx` with `a`
fn set_elt(idx: uint, a: A) {
self.check_not_borrowed();
self.data[idx] = a;
}
- #[doc = "Overwrites the contents of the element at `idx` with `a`,
- growing the vector if necessary. New elements will be initialized
- with `initval`"]
+ /**
+ * Overwrites the contents of the element at `idx` with `a`,
+ * growing the vector if necessary. New elements will be initialized
+ * with `initval`
+ */
fn grow_set_elt(idx: uint, initval: A, val: A) {
do self.swap |v| {
let mut v <- v;
}
}
- #[doc = "Returns the last element, failing if the vector is empty"]
+ /// Returns the last element, failing if the vector is empty
#[inline(always)]
fn last() -> A {
self.check_not_borrowed();
ret self.data[length - 1u];
}
- #[doc="Iterates over the elements in reverse order"]
+ /// Iterates over the elements in reverse order
#[inline(always)]
fn reach(f: fn(A) -> bool) {
let length = self.len();
-#[doc = "A type that represents one of two alternatives"];
+//! A type that represents one of two alternatives
import result::result;
-#[doc = "The either type"]
+/// The either type
enum either<T, U> {
left(T),
right(U)
fn either<T, U, V>(f_left: fn(T) -> V,
f_right: fn(U) -> V, value: either<T, U>) -> V {
- #[doc = "
- Applies a function based on the given either value
-
- If `value` is left(T) then `f_left` is applied to its contents, if `value`
- is right(U) then `f_right` is applied to its contents, and the result is
- returned.
- "];
+ /*!
+ * Applies a function based on the given either value
+ *
+ * If `value` is left(T) then `f_left` is applied to its contents, if
+ * `value` is right(U) then `f_right` is applied to its contents, and the
+ * result is returned.
+ */
alt value { left(l) { f_left(l) } right(r) { f_right(r) } }
}
fn lefts<T: copy, U>(eithers: ~[either<T, U>]) -> ~[T] {
- #[doc = "Extracts from a vector of either all the left values"];
+ //! Extracts from a vector of either all the left values
let mut result: ~[T] = ~[];
for vec::each(eithers) |elt| {
}
fn rights<T, U: copy>(eithers: ~[either<T, U>]) -> ~[U] {
- #[doc = "Extracts from a vector of either all the right values"];
+ //! Extracts from a vector of either all the right values
let mut result: ~[U] = ~[];
for vec::each(eithers) |elt| {
fn partition<T: copy, U: copy>(eithers: ~[either<T, U>])
-> {lefts: ~[T], rights: ~[U]} {
- #[doc = "
- Extracts from a vector of either all the left values and right values
-
- Returns a structure containing a vector of left values and a vector of
- right values.
- "];
+ /*!
+ * Extracts from a vector of either all the left values and right values
+ *
+ * Returns a structure containing a vector of left values and a vector of
+ * right values.
+ */
let mut lefts: ~[T] = ~[];
let mut rights: ~[U] = ~[];
}
pure fn flip<T: copy, U: copy>(eith: either<T, U>) -> either<U, T> {
- #[doc = "Flips between left and right of a given either"];
+ //! Flips between left and right of a given either
alt eith {
right(r) { left(r) }
pure fn to_result<T: copy, U: copy>(
eith: either<T, U>) -> result<U, T> {
- #[doc = "
- Converts either::t to a result::t
-
- Converts an `either` type to a `result` type, making the \"right\" choice
- an ok result, and the \"left\" choice a fail
- "];
+ /*!
+ * Converts either::t to a result::t
+ *
+ * Converts an `either` type to a `result` type, making the "right" choice
+ * an ok result, and the "left" choice a fail
+ */
alt eith {
right(r) { result::ok(r) }
}
pure fn is_left<T, U>(eith: either<T, U>) -> bool {
- #[doc = "Checks whether the given value is a left"];
+ //! Checks whether the given value is a left
alt eith { left(_) { true } _ { false } }
}
pure fn is_right<T, U>(eith: either<T, U>) -> bool {
- #[doc = "Checks whether the given value is a right"];
+ //! Checks whether the given value is a right
alt eith { right(_) { true } _ { false } }
}
-#[doc = "Operations and constants for `f32`"];
+//! Operations and constants for `f32`
// PORT
// FIXME (#1999): replace the predicates below with llvm intrinsics or
// calls to the libmath macros in the rust runtime for performance.
-#[doc = "
-Returns true if `x` is a positive number, including +0.0f320 and +Infinity
-"]
+/// Returns true if `x` is a positive number, including +0.0f320 and +Infinity
pure fn is_positive(x: f32) -> bool
{ ret x > 0.0f32 || (1.0f32/x) == infinity; }
-#[doc = "
-Returns true if `x` is a negative number, including -0.0f320 and -Infinity
-"]
+/// Returns true if `x` is a negative number, including -0.0f320 and -Infinity
pure fn is_negative(x: f32) -> bool
{ ret x < 0.0f32 || (1.0f32/x) == neg_infinity; }
-#[doc = "
-Returns true if `x` is a negative number, including -0.0f320 and -Infinity
-
-This is the same as `f32::is_negative`.
-"]
+/**
+ * Returns true if `x` is a negative number, including -0.0f320 and -Infinity
+ *
+ * This is the same as `f32::is_negative`.
+ */
pure fn is_nonpositive(x: f32) -> bool {
ret x < 0.0f32 || (1.0f32/x) == neg_infinity;
}
-#[doc = "
-Returns true if `x` is a positive number, including +0.0f320 and +Infinity
-
-This is the same as `f32::is_positive`.)
-"]
+/**
+ * Returns true if `x` is a positive number, including +0.0f320 and +Infinity
+ *
+ * This is the same as `f32::is_positive`.)
+ */
pure fn is_nonnegative(x: f32) -> bool {
ret x > 0.0f32 || (1.0f32/x) == infinity;
}
-#[doc = "
-Returns true if `x` is a zero number (positive or negative zero)
-"]
+/// Returns true if `x` is a zero number (positive or negative zero)
pure fn is_zero(x: f32) -> bool {
ret x == 0.0f32 || x == -0.0f32;
}
-#[doc = "Returns true if `x`is an infinite number"]
+/// Returns true if `x`is an infinite number
pure fn is_infinite(x: f32) -> bool {
ret x == infinity || x == neg_infinity;
}
-#[doc = "Returns true if `x`is a finite number"]
+/// Returns true if `x`is a finite number
pure fn is_finite(x: f32) -> bool {
ret !(is_NaN(x) || is_infinite(x));
}
// FIXME (requires Issue #1433 to fix): replace with mathematical
// constants from cmath.
- #[doc = "Archimedes' constant"]
+ /// Archimedes' constant
const pi: f32 = 3.14159265358979323846264338327950288_f32;
- #[doc = "pi/2.0"]
+ /// pi/2.0
const frac_pi_2: f32 = 1.57079632679489661923132169163975144_f32;
- #[doc = "pi/4.0"]
+ /// pi/4.0
const frac_pi_4: f32 = 0.785398163397448309615660845819875721_f32;
- #[doc = "1.0/pi"]
+ /// 1.0/pi
const frac_1_pi: f32 = 0.318309886183790671537767526745028724_f32;
- #[doc = "2.0/pi"]
+ /// 2.0/pi
const frac_2_pi: f32 = 0.636619772367581343075535053490057448_f32;
- #[doc = "2.0/sqrt(pi)"]
+ /// 2.0/sqrt(pi)
const frac_2_sqrtpi: f32 = 1.12837916709551257389615890312154517_f32;
- #[doc = "sqrt(2.0)"]
+ /// sqrt(2.0)
const sqrt2: f32 = 1.41421356237309504880168872420969808_f32;
- #[doc = "1.0/sqrt(2.0)"]
+ /// 1.0/sqrt(2.0)
const frac_1_sqrt2: f32 = 0.707106781186547524400844362104849039_f32;
- #[doc = "Euler's number"]
+ /// Euler's number
const e: f32 = 2.71828182845904523536028747135266250_f32;
- #[doc = "log2(e)"]
+ /// log2(e)
const log2_e: f32 = 1.44269504088896340735992468100189214_f32;
- #[doc = "log10(e)"]
+ /// log10(e)
const log10_e: f32 = 0.434294481903251827651128918916605082_f32;
- #[doc = "ln(2.0)"]
+ /// ln(2.0)
const ln_2: f32 = 0.693147180559945309417232121458176568_f32;
- #[doc = "ln(10.0)"]
+ /// ln(10.0)
const ln_10: f32 = 2.30258509299404568401799145468436421_f32;
}
-#[doc = "Operations and constants for `f64`"];
+//! Operations and constants for `f64`
// PORT
cmath::c_double::sqrt(x as libc::c_double) as f64
}
-#[doc = "
-Returns true if `x` is a positive number, including +0.0f640 and +Infinity.
-"]
+/// Returns true if `x` is a positive number, including +0.0f640 and +Infinity
pure fn is_positive(x: f64) -> bool
{ ret x > 0.0f64 || (1.0f64/x) == infinity; }
-#[doc = "
-Returns true if `x` is a negative number, including -0.0f640 and -Infinity
-"]
+/// Returns true if `x` is a negative number, including -0.0f640 and -Infinity
pure fn is_negative(x: f64) -> bool
{ ret x < 0.0f64 || (1.0f64/x) == neg_infinity; }
-#[doc = "
-Returns true if `x` is a negative number, including -0.0f640 and -Infinity
-
-This is the same as `f64::is_negative`.
-"]
+/**
+ * Returns true if `x` is a negative number, including -0.0f640 and -Infinity
+ *
+ * This is the same as `f64::is_negative`.
+ */
pure fn is_nonpositive(x: f64) -> bool {
ret x < 0.0f64 || (1.0f64/x) == neg_infinity;
}
-#[doc = "
-Returns true if `x` is a positive number, including +0.0f640 and +Infinity
-
-This is the same as `f64::positive`.
-"]
+/**
+ * Returns true if `x` is a positive number, including +0.0f640 and +Infinity
+ *
+ * This is the same as `f64::positive`.
+ */
pure fn is_nonnegative(x: f64) -> bool {
ret x > 0.0f64 || (1.0f64/x) == infinity;
}
-#[doc = "Returns true if `x` is a zero number (positive or negative zero)"]
+/// Returns true if `x` is a zero number (positive or negative zero)
pure fn is_zero(x: f64) -> bool {
ret x == 0.0f64 || x == -0.0f64;
}
-#[doc = "Returns true if `x`is an infinite number"]
+/// Returns true if `x`is an infinite number
pure fn is_infinite(x: f64) -> bool {
ret x == infinity || x == neg_infinity;
}
-#[doc = "Returns true if `x`is a finite number"]
+/// Returns true if `x`is a finite number
pure fn is_finite(x: f64) -> bool {
ret !(is_NaN(x) || is_infinite(x));
}
// FIXME (requires Issue #1433 to fix): replace with mathematical
// constants from cmath.
- #[doc = "Archimedes' constant"]
+ /// Archimedes' constant
const pi: f64 = 3.14159265358979323846264338327950288_f64;
- #[doc = "pi/2.0"]
+ /// pi/2.0
const frac_pi_2: f64 = 1.57079632679489661923132169163975144_f64;
- #[doc = "pi/4.0"]
+ /// pi/4.0
const frac_pi_4: f64 = 0.785398163397448309615660845819875721_f64;
- #[doc = "1.0/pi"]
+ /// 1.0/pi
const frac_1_pi: f64 = 0.318309886183790671537767526745028724_f64;
- #[doc = "2.0/pi"]
+ /// 2.0/pi
const frac_2_pi: f64 = 0.636619772367581343075535053490057448_f64;
- #[doc = "2.0/sqrt(pi)"]
+ /// 2.0/sqrt(pi)
const frac_2_sqrtpi: f64 = 1.12837916709551257389615890312154517_f64;
- #[doc = "sqrt(2.0)"]
+ /// sqrt(2.0)
const sqrt2: f64 = 1.41421356237309504880168872420969808_f64;
- #[doc = "1.0/sqrt(2.0)"]
+ /// 1.0/sqrt(2.0)
const frac_1_sqrt2: f64 = 0.707106781186547524400844362104849039_f64;
- #[doc = "Euler's number"]
+ /// Euler's number
const e: f64 = 2.71828182845904523536028747135266250_f64;
- #[doc = "log2(e)"]
+ /// log2(e)
const log2_e: f64 = 1.44269504088896340735992468100189214_f64;
- #[doc = "log10(e)"]
+ /// log10(e)
const log10_e: f64 = 0.434294481903251827651128918916605082_f64;
- #[doc = "ln(2.0)"]
+ /// ln(2.0)
const ln_2: f64 = 0.693147180559945309417232121458176568_f64;
- #[doc = "ln(10.0)"]
+ /// ln(10.0)
const ln_10: f64 = 2.30258509299404568401799145468436421_f64;
}
-#[doc = "Operations and constants for `float`"];
+//! Operations and constants for `float`
// Even though this module exports everything defined in it,
// because it contains re-exports, we also have to explicitly
// FIXME (requires Issue #1433 to fix): replace with mathematical
// constants from cmath.
- #[doc = "Archimedes' constant"]
+ /// Archimedes' constant
const pi: float = 3.14159265358979323846264338327950288;
- #[doc = "pi/2.0"]
+ /// pi/2.0
const frac_pi_2: float = 1.57079632679489661923132169163975144;
- #[doc = "pi/4.0"]
+ /// pi/4.0
const frac_pi_4: float = 0.785398163397448309615660845819875721;
- #[doc = "1.0/pi"]
+ /// 1.0/pi
const frac_1_pi: float = 0.318309886183790671537767526745028724;
- #[doc = "2.0/pi"]
+ /// 2.0/pi
const frac_2_pi: float = 0.636619772367581343075535053490057448;
- #[doc = "2.0/sqrt(pi)"]
+ /// 2.0/sqrt(pi)
const frac_2_sqrtpi: float = 1.12837916709551257389615890312154517;
- #[doc = "sqrt(2.0)"]
+ /// sqrt(2.0)
const sqrt2: float = 1.41421356237309504880168872420969808;
- #[doc = "1.0/sqrt(2.0)"]
+ /// 1.0/sqrt(2.0)
const frac_1_sqrt2: float = 0.707106781186547524400844362104849039;
- #[doc = "Euler's number"]
+ /// Euler's number
const e: float = 2.71828182845904523536028747135266250;
- #[doc = "log2(e)"]
+ /// log2(e)
const log2_e: float = 1.44269504088896340735992468100189214;
- #[doc = "log10(e)"]
+ /// log10(e)
const log10_e: float = 0.434294481903251827651128918916605082;
- #[doc = "ln(2.0)"]
+ /// ln(2.0)
const ln_2: float = 0.693147180559945309417232121458176568;
- #[doc = "ln(10.0)"]
+ /// ln(10.0)
const ln_10: float = 2.30258509299404568401799145468436421;
}
* Section: String Conversions
*/
-#[doc = "
-Converts a float to a string
-
-# Arguments
-
-* num - The float value
-* digits - The number of significant digits
-* exact - Whether to enforce the exact number of significant digits
-"]
+/**
+ * Converts a float to a string
+ *
+ * # Arguments
+ *
+ * * num - The float value
+ * * digits - The number of significant digits
+ * * exact - Whether to enforce the exact number of significant digits
+ */
fn to_str_common(num: float, digits: uint, exact: bool) -> str {
if is_NaN(num) { ret "NaN"; }
if num == infinity { ret "inf"; }
ret acc;
}
-#[doc = "
-Converts a float to a string with exactly the number of
-provided significant digits
-
-# Arguments
-
-* num - The float value
-* digits - The number of significant digits
-"]
+/**
+ * Converts a float to a string with exactly the number of
+ * provided significant digits
+ *
+ * # Arguments
+ *
+ * * num - The float value
+ * * digits - The number of significant digits
+ */
fn to_str_exact(num: float, digits: uint) -> str {
to_str_common(num, digits, true)
}
}
-#[doc = "
-Converts a float to a string with a maximum number of
-significant digits
-
-# Arguments
-
-* num - The float value
-* digits - The number of significant digits
-"]
+/**
+ * Converts a float to a string with a maximum number of
+ * significant digits
+ *
+ * # Arguments
+ *
+ * * num - The float value
+ * * digits - The number of significant digits
+ */
fn to_str(num: float, digits: uint) -> str {
to_str_common(num, digits, false)
}
-#[doc = "
-Convert a string to a float
-
-This function accepts strings such as
-
-* '3.14'
-* '+3.14', equivalent to '3.14'
-* '-3.14'
-* '2.5E10', or equivalently, '2.5e10'
-* '2.5E-10'
-* '', or, equivalently, '.' (understood as 0)
-* '5.'
-* '.5', or, equivalently, '0.5'
-* 'inf', '-inf', 'NaN'
-
-Leading and trailing whitespace are ignored.
-
-# Arguments
-
-* num - A string
-
-# Return value
-
-`none` if the string did not represent a valid number. Otherwise, `some(n)`
-where `n` is the floating-point number represented by `[num]/~`.
-"]
+/**
+ * Convert a string to a float
+ *
+ * This function accepts strings such as
+ *
+ * * '3.14'
+ * * '+3.14', equivalent to '3.14'
+ * * '-3.14'
+ * * '2.5E10', or equivalently, '2.5e10'
+ * * '2.5E-10'
+ * * '', or, equivalently, '.' (understood as 0)
+ * * '5.'
+ * * '.5', or, equivalently, '0.5'
+ * * 'inf', '-inf', 'NaN'
+ *
+ * Leading and trailing whitespace are ignored.
+ *
+ * # Arguments
+ *
+ * * num - A string
+ *
+ * # Return value
+ *
+ * `none` if the string did not represent a valid number. Otherwise,
+ * `some(n)` where `n` is the floating-point number represented by `[num]/~`.
+ */
fn from_str(num: str) -> option<float> {
if num == "inf" {
ret some(infinity as float);
* Section: Arithmetics
*/
-#[doc = "
-Compute the exponentiation of an integer by another integer as a float
-
-# Arguments
-
-* x - The base
-* pow - The exponent
-
-# Return value
-
-`NaN` if both `x` and `pow` are `0u`, otherwise `x^pow`
-"]
+/**
+ * Compute the exponentiation of an integer by another integer as a float
+ *
+ * # Arguments
+ *
+ * * x - The base
+ * * pow - The exponent
+ *
+ * # Return value
+ *
+ * `NaN` if both `x` and `pow` are `0u`, otherwise `x^pow`
+ */
fn pow_with_uint(base: uint, pow: uint) -> float {
if base == 0u {
if pow == 0u {
-#[doc = "
-A type representing values that may be computed concurrently and
-operations for working with them.
-
-# Example
-
-~~~
-let delayed_fib = future::spawn {|| fib(5000) };
-make_a_sandwich();
-io::println(#fmt(\"fib(5000) = %?\", delayed_fib.get()))
-~~~
-"];
+/*!
+ * A type representing values that may be computed concurrently and
+ * operations for working with them.
+ *
+ * # Example
+ *
+ * ~~~
+ * let delayed_fib = future::spawn {|| fib(5000) };
+ * make_a_sandwich();
+ * io::println(#fmt("fib(5000) = %?", delayed_fib.get()))
+ * ~~~
+ */
import either::either;
export with;
export spawn;
-#[doc = "The future type"]
+/// The future type
enum future<A> = {
mut v: either<@A, fn@() -> A>
};
-#[doc = "Methods on the `future` type"]
+/// Methods on the `future` type
impl extensions<A:copy send> for future<A> {
fn get() -> A {
- #[doc = "Get the value of the future"];
+ //! Get the value of the future
get(self)
}
fn with<B>(blk: fn(A) -> B) -> B {
- #[doc = "Work with the value without copying it"];
+ //! Work with the value without copying it
with(self, blk)
}
}
fn from_value<A>(+val: A) -> future<A> {
- #[doc = "
- Create a future from a value
-
- The value is immediately available and calling `get` later will
- not block.
- "];
+ /*!
+ * Create a future from a value
+ *
+ * The value is immediately available and calling `get` later will
+ * not block.
+ */
future({
mut v: either::left(@val)
}
fn from_port<A:send>(-port: comm::port<A>) -> future<A> {
- #[doc = "
- Create a future from a port
-
- The first time that the value is requested the task will block
- waiting for the result to be received on the port.
- "];
+ /*!
+ * Create a future from a port
+ *
+ * The first time that the value is requested the task will block
+ * waiting for the result to be received on the port.
+ */
do from_fn {
comm::recv(port)
}
fn from_fn<A>(f: fn@() -> A) -> future<A> {
- #[doc = "
- Create a future from a function.
-
- The first time that the value is requested it will be retreived by
- calling the function. Note that this function is a local
- function. It is not spawned into another task.
- "];
+ /*!
+ * Create a future from a function.
+ *
+ * The first time that the value is requested it will be retreived by
+ * calling the function. Note that this function is a local
+ * function. It is not spawned into another task.
+ */
future({
mut v: either::right(f)
}
fn spawn<A:send>(+blk: fn~() -> A) -> future<A> {
- #[doc = "
- Create a future from a unique closure.
-
- The closure will be run in a new task and its result used as the
- value of the future.
- "];
+ /*!
+ * Create a future from a unique closure.
+ *
+ * The closure will be run in a new task and its result used as the
+ * value of the future.
+ */
let mut po = comm::port();
let ch = comm::chan(po);
}
fn get<A:copy>(future: future<A>) -> A {
- #[doc = "Get the value of the future"];
+ //! Get the value of the future
do with(future) |v| { v }
}
fn with<A,B>(future: future<A>, blk: fn(A) -> B) -> B {
- #[doc = "Work with the value without copying it"];
+ //! Work with the value without copying it
let v = alt copy future.v {
either::left(v) { v }
pure fn is_nonnegative(x: T) -> bool { x >= 0 as T }
#[inline(always)]
-#[doc = "Iterate over the range [`lo`..`hi`)"]
+/// Iterate over the range [`lo`..`hi`)
fn range(lo: T, hi: T, it: fn(T) -> bool) {
let mut i = lo;
while i < hi {
}
}
-#[doc = "Computes the bitwise complement"]
+/// Computes the bitwise complement
pure fn compl(i: T) -> T {
-1 as T ^ i
}
-#[doc = "Computes the absolute value"]
+/// Computes the absolute value
// FIXME: abs should return an unsigned int (#2353)
pure fn abs(i: T) -> T {
if is_negative(i) { -i } else { i }
}
-#[doc = "
-Parse a buffer of bytes
-
-# Arguments
-
-* buf - A byte buffer
-* radix - The base of the number
-"]
+/**
+ * Parse a buffer of bytes
+ *
+ * # Arguments
+ *
+ * * buf - A byte buffer
+ * * radix - The base of the number
+ */
fn parse_buf(buf: ~[u8], radix: uint) -> option<T> {
if vec::len(buf) == 0u { ret none; }
let mut i = vec::len(buf) - 1u;
};
}
-#[doc = "Parse a string to an int"]
+/// Parse a string to an int
fn from_str(s: str) -> option<T> { parse_buf(str::bytes(s), 10u) }
-#[doc = "Convert to a string in a given base"]
+/// Convert to a string in a given base
fn to_str(n: T, radix: uint) -> str {
do to_str_bytes(n, radix) |slice| {
do vec::unpack_slice(slice) |p, len| {
}
}
-#[doc = "Convert to a string"]
+/// Convert to a string
fn str(i: T) -> str { ret to_str(i, 10u); }
impl ord of ord for T {
#[cfg(target_arch = "x86_64")]
const bits: T = 64 as T;
-#[doc = "Produce a uint suitable for use in a hash table"]
+/// Produce a uint suitable for use in a hash table
pure fn hash(&&x: int) -> uint { ret x as uint; }
-#[doc = "Returns `base` raised to the power of `exponent`"]
+/// Returns `base` raised to the power of `exponent`
fn pow(base: int, exponent: uint) -> int {
if exponent == 0u { ret 1; } //Not mathemtically true if ~[base == 0]
if base == 0 { ret 0; }
type IMPL_T<A> = dlist::dlist<A>;
-#[doc = "
-Iterates through the current contents.
-
-Attempts to access this dlist during iteration are allowed (to allow for e.g.
-breadth-first search with in-place enqueues), but removing the current node
-is forbidden.
-"]
+/**
+ * Iterates through the current contents.
+ *
+ * Attempts to access this dlist during iteration are allowed (to allow for
+ * e.g. breadth-first search with in-place enqueues), but removing the current
+ * node is forbidden.
+ */
fn EACH<A>(self: IMPL_T<A>, f: fn(A) -> bool) {
import dlist::extensions;
type IMPL_T<A> = dvec::dvec<A>;
-#[doc = "
-Iterates through the current contents.
-
-Attempts to access this dvec during iteration will fail.
-"]
+/**
+ * Iterates through the current contents.
+ *
+ * Attempts to access this dvec during iteration will fail.
+ */
fn EACH<A>(self: IMPL_T<A>, f: fn(A) -> bool) {
import dvec::extensions;
self.swap(|v| { vec::each(v, f); v })
-#[doc = "
-Bindings for libc.
-
-We consider the following specs reasonably normative with respect
-to interoperating with the C standard library (libc/msvcrt):
-
-* ISO 9899:1990 ('C95', 'ANSI C', 'Standard C'), NA1, 1995.
-* ISO 9899:1999 ('C99' or 'C9x').
-* ISO 9945:1988 / IEEE 1003.1-1988 ('POSIX.1').
-* ISO 9945:2001 / IEEE 1003.1-2001 ('POSIX:2001', 'SUSv3').
-* ISO 9945:2008 / IEEE 1003.1-2008 ('POSIX:2008', 'SUSv4').
-
-Despite having several names each, these are *reasonably* coherent
-point-in-time, list-of-definition sorts of specs. You can get each under a
-variety of names but will wind up with the same definition in each case.
-
-Our interface to these libraries is complicated by the non-universality of
-conformance to any of them. About the only thing universally supported is
-the first (C95), beyond that definitions quickly become absent on various
-platforms.
-
-We therefore wind up dividing our module-space up (mostly for the sake of
-sanity while editing, filling-in-details and eliminating duplication) into
-definitions common-to-all (held in modules named c95, c99, posix88, posix01
-and posix08) and definitions that appear only on *some* platforms (named
-'extra'). This would be things like significant OSX foundation kit, or
-win32 library kernel32.dll, or various fancy glibc, linux or BSD
-extensions.
-
-In addition to the per-platform 'extra' modules, we define a module of
-'common BSD' libc routines that never quite made it into POSIX but show up
-in multiple derived systems. This is the 4.4BSD r2 / 1995 release, the
-final one from Berkeley after the lawsuits died down and the CSRG
-dissolved.
-"];
+/*!
+ * Bindings for libc.
+ *
+ * We consider the following specs reasonably normative with respect
+ * to interoperating with the C standard library (libc/msvcrt):
+ *
+ * * ISO 9899:1990 ('C95', 'ANSI C', 'Standard C'), NA1, 1995.
+ * * ISO 9899:1999 ('C99' or 'C9x').
+ * * ISO 9945:1988 / IEEE 1003.1-1988 ('POSIX.1').
+ * * ISO 9945:2001 / IEEE 1003.1-2001 ('POSIX:2001', 'SUSv3').
+ * * ISO 9945:2008 / IEEE 1003.1-2008 ('POSIX:2008', 'SUSv4').
+ *
+ * Despite having several names each, these are *reasonably* coherent
+ * point-in-time, list-of-definition sorts of specs. You can get each under a
+ * variety of names but will wind up with the same definition in each case.
+ *
+ * Our interface to these libraries is complicated by the non-universality of
+ * conformance to any of them. About the only thing universally supported is
+ * the first (C95), beyond that definitions quickly become absent on various
+ * platforms.
+ *
+ * We therefore wind up dividing our module-space up (mostly for the sake of
+ * sanity while editing, filling-in-details and eliminating duplication) into
+ * definitions common-to-all (held in modules named c95, c99, posix88, posix01
+ * and posix08) and definitions that appear only on *some* platforms (named
+ * 'extra'). This would be things like significant OSX foundation kit, or
+ * win32 library kernel32.dll, or various fancy glibc, linux or BSD
+ * extensions.
+ *
+ * In addition to the per-platform 'extra' modules, we define a module of
+ * 'common BSD' libc routines that never quite made it into POSIX but show up
+ * in multiple derived systems. This is the 4.4BSD r2 / 1995 release, the
+ * final one from Berkeley after the lawsuits died down and the CSRG
+ * dissolved.
+ */
// Initial glob-exports mean that all the contents of all the modules
// wind up exported, if you're interested in writing platform-specific code.
-#[doc = "Logging"];
+//! Logging
export console_on, console_off;
fn rust_log_console_off();
}
-#[doc = "Turns on logging to stdout globally"]
+/// Turns on logging to stdout globally
fn console_on() {
rustrt::rust_log_console_on();
}
-#[doc = "
-Turns off logging to stdout globally
-
-Turns off the console unless the user has overridden the
-runtime environment's logging spec, e.g. by setting
-the RUST_LOG environment variable
-"]
+/**
+ * Turns off logging to stdout globally
+ *
+ * Turns off the console unless the user has overridden the
+ * runtime environment's logging spec, e.g. by setting
+ * the RUST_LOG environment variable
+ */
fn console_off() {
rustrt::rust_log_console_off();
}
\ No newline at end of file
-#[doc="A new implementation of communication.
-
-This should be implementing almost entirely in Rust, and hopefully
-avoid needing a single global lock."]
+/**
+ * A new implementation of communication.
+ *
+ * This should be implementing almost entirely in Rust, and hopefully
+ * avoid needing a single global lock.
+ */
import arc::methods;
import dvec::dvec;
-#[doc="An interface for numbers."]
+/// An interface for numbers.
iface num {
// FIXME: Cross-crate overloading doesn't work yet. (#2615)
-#[doc = "
-Operations on the ubiquitous `option` type.
-
-Type `option` represents an optional value.
-
-Every `option<T>` value can either be `some(T)` or `none`. Where in other
-languages you might use a nullable type, in Rust you would use an option type.
-"];
-
-#[doc = "The option type"]
+/*!
+ * Operations on the ubiquitous `option` type.
+ *
+ * Type `option` represents an optional value.
+ *
+ * Every `option<T>` value can either be `some(T)` or `none`. Where in other
+ * languages you might use a nullable type, in Rust you would use an option
+ * type.
+ */
+
+/// The option type
enum option<T> {
none,
some(T),
}
pure fn get<T: copy>(opt: option<T>) -> T {
- #[doc = "
- Gets the value out of an option
-
- # Failure
-
- Fails if the value equals `none`
- "];
+ /*!
+ * Gets the value out of an option
+ *
+ * # Failure
+ *
+ * Fails if the value equals `none`
+ */
alt opt { some(x) { ret x; } none { fail "option none"; } }
}
}
pure fn map<T, U: copy>(opt: option<T>, f: fn(T) -> U) -> option<U> {
- #[doc = "Maps a `some` value from one type to another"];
+ //! Maps a `some` value from one type to another
alt opt { some(x) { some(f(x)) } none { none } }
}
pure fn chain<T, U>(opt: option<T>, f: fn(T) -> option<U>) -> option<U> {
- #[doc = "
- Update an optional value by optionally running its content through a
- function that returns an option.
- "];
+ /*!
+ * Update an optional value by optionally running its content through a
+ * function that returns an option.
+ */
alt opt { some(x) { f(x) } none { none } }
}
pure fn is_none<T>(opt: option<T>) -> bool {
- #[doc = "Returns true if the option equals `none`"];
+ //! Returns true if the option equals `none`
alt opt { none { true } some(_) { false } }
}
pure fn is_some<T>(opt: option<T>) -> bool {
- #[doc = "Returns true if the option contains some value"];
+ //! Returns true if the option contains some value
!is_none(opt)
}
pure fn get_default<T: copy>(opt: option<T>, def: T) -> T {
- #[doc = "Returns the contained value or a default"];
+ //! Returns the contained value or a default
alt opt { some(x) { x } none { def } }
}
pure fn map_default<T, U: copy>(opt: option<T>, def: U, f: fn(T) -> U) -> U {
- #[doc = "Applies a function to the contained value or returns a default"];
+ //! Applies a function to the contained value or returns a default
alt opt { none { def } some(t) { f(t) } }
}
pure fn iter<T>(opt: option<T>, f: fn(T)) {
- #[doc = "Performs an operation on the contained value or does nothing"];
+ //! Performs an operation on the contained value or does nothing
alt opt { none { } some(t) { f(t); } }
}
pure fn unwrap<T>(-opt: option<T>) -> T {
- #[doc = "
- Moves a value out of an option type and returns it.
-
- Useful primarily for getting strings, vectors and unique pointers out of
- option types without copying them.
- "];
+ /*!
+ * Moves a value out of an option type and returns it.
+ *
+ * Useful primarily for getting strings, vectors and unique pointers out
+ * of option types without copying them.
+ */
unsafe {
let addr = alt opt {
}
impl extensions<T> for option<T> {
- #[doc = "
- Update an optional value by optionally running its content through a
- function that returns an option.
- "]
- pure fn chain<U>(f: fn(T) -> option<U>) -> option<U> { chain(self, f) }
- #[doc = "Applies a function to the contained value or returns a default"]
- pure fn map_default<U: copy>(def: U, f: fn(T) -> U) -> U
+ /**
+ * Update an optional value by optionally running its content through a
+ * function that returns an option.
+ */
+ fn chain<U>(f: fn(T) -> option<U>) -> option<U> { chain(self, f) }
+ /// Applies a function to the contained value or returns a default
+ fn map_default<U: copy>(def: U, f: fn(T) -> U) -> U
{ map_default(self, def, f) }
- #[doc = "Performs an operation on the contained value or does nothing"]
- pure fn iter(f: fn(T)) { iter(self, f) }
- #[doc = "Returns true if the option equals `none`"]
- pure fn is_none() -> bool { is_none(self) }
- #[doc = "Returns true if the option contains some value"]
- pure fn is_some() -> bool { is_some(self) }
- #[doc = "Maps a `some` value from one type to another"]
- pure fn map<U:copy>(f: fn(T) -> U) -> option<U> { map(self, f) }
+ /// Performs an operation on the contained value or does nothing
+ fn iter(f: fn(T)) { iter(self, f) }
+ /// Returns true if the option equals `none`
+ fn is_none() -> bool { is_none(self) }
+ /// Returns true if the option contains some value
+ fn is_some() -> bool { is_some(self) }
+ /// Maps a `some` value from one type to another
+ fn map<U:copy>(f: fn(T) -> U) -> option<U> { map(self, f) }
}
impl extensions<T: copy> for option<T> {
- #[doc = "
- Gets the value out of an option
-
- # Failure
-
- Fails if the value equals `none`
- "]
- pure fn get() -> T { get(self) }
- pure fn get_default(def: T) -> T { get_default(self, def) }
- #[doc = "
- Gets the value out of an option, printing a specified message on failure
-
- # Failure
-
- Fails if the value equals `none`
- "]
+ /**
+ * Gets the value out of an option
+ *
+ * # Failure
+ *
+ * Fails if the value equals `none`
+ */
+ fn get() -> T { get(self) }
+ fn get_default(def: T) -> T { get_default(self, def) }
+ /**
+ * Gets the value out of an option, printing a specified message on
+ * failure
+ *
+ * # Failure
+ *
+ * Fails if the value equals `none`
+ */
pure fn expect(reason: str) -> T { expect(self, reason) }
}
-#[doc = "
-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.
+ */
import libc::{c_char, c_void, c_int, c_uint, size_t, ssize_t,
mode_t, pid_t, FILE};
}
mod global_env {
- #[doc = "Internal module for serializing access to getenv/setenv"];
+ //! Internal module for serializing access to getenv/setenv
export getenv;
export setenv;
}
-#[doc = "
-Returns the path to the user's home directory, if known.
-
-On Unix, returns the value of the 'HOME' environment variable if it is set and
-not equal to the empty string.
-
-On Windows, returns the value of the 'HOME' environment variable if it is set
-and not equal to the empty string. Otherwise, returns the value of the
-'USERPROFILE' environment variable if it is set and not equal to the empty
-string.
-
-Otherwise, homedir returns option::none.
-"]
+/**
+ * Returns the path to the user's home directory, if known.
+ *
+ * On Unix, returns the value of the 'HOME' environment variable if it is set
+ * and not equal to the empty string.
+ *
+ * On Windows, returns the value of the 'HOME' environment variable if it is
+ * set and not equal to the empty string. Otherwise, returns the value of the
+ * 'USERPROFILE' environment variable if it is set and not equal to the empty
+ * string.
+ *
+ * Otherwise, homedir returns option::none.
+ */
fn homedir() -> option<path> {
ret alt getenv("HOME") {
some(p) {
}
}
-#[doc = "Recursively walk a directory structure"]
+/// Recursively walk a directory structure
fn walk_dir(p: path, f: fn(path) -> bool) {
walk_dir_(p, f);
}
}
-#[doc = "Indicates whether a path represents a directory"]
+/// Indicates whether a path represents a directory
fn path_is_dir(p: path) -> bool {
do str::as_c_str(p) |buf| {
rustrt::rust_path_is_dir(buf) != 0 as c_int
}
}
-#[doc = "Indicates whether a path exists"]
+/// Indicates whether a path exists
fn path_exists(p: path) -> bool {
do str::as_c_str(p) |buf| {
rustrt::rust_path_exists(buf) != 0 as c_int
// FIXME (#2622): under Windows, we should prepend the current drive letter
// to paths that start with a slash.
-#[doc = "
-Convert a relative path to an absolute path
-
-If the given path is relative, return it prepended with the current working
-directory. If the given path is already an absolute path, return it
-as is.
-"]
+/**
+ * Convert a relative path to an absolute path
+ *
+ * If the given path is relative, return it prepended with the current working
+ * directory. If the given path is already an absolute path, return it
+ * as is.
+ */
// NB: this is here rather than in path because it is a form of environment
// querying; what it does depends on the process working directory, not just
// the input paths.
}
-#[doc = "Creates a directory at the specified path"]
+/// Creates a directory at the specified path
fn make_dir(p: path, mode: c_int) -> bool {
ret mkdir(p, mode);
}
}
-#[doc = "Lists the contents of a directory"]
+/// Lists the contents of a directory
fn list_dir(p: path) -> ~[str] {
#[cfg(unix)]
}
}
-#[doc = "
-Lists the contents of a directory
-
-This version prepends each entry with the directory.
-"]
+/**
+ * Lists the contents of a directory
+ *
+ * This version prepends each entry with the directory.
+ */
fn list_dir_path(p: path) -> ~[str] {
let mut p = p;
let pl = str::len(p);
os::list_dir(p).map(|f| p + f)
}
-#[doc = "Removes a directory at the specified path"]
+/// Removes a directory at the specified path
fn remove_dir(p: path) -> bool {
ret rmdir(p);
}
}
-#[doc = "Copies a file from one location to another"]
+/// Copies a file from one location to another
fn copy_file(from: path, to: path) -> bool {
ret do_copy_file(from, to);
}
}
-#[doc = "Deletes an existing file"]
+/// Deletes an existing file
fn remove_file(p: path) -> bool {
ret unlink(p);
}
}
-#[doc = "Get a string representing the platform-dependent last error"]
+/// Get a string representing the platform-dependent last error
fn last_os_error() -> str {
rustrt::last_os_error()
}
-#[doc = "
-Sets the process exit code
-
-Sets the exit code returned by the process if all supervised tasks terminate
-successfully (without failing). If the current root task fails and is
-supervised by the scheduler then any user-specified exit status is ignored and
-the process exits with the default failure status
-"]
+/**
+ * Sets the process exit code
+ *
+ * Sets the exit code returned by the process if all supervised tasks
+ * terminate successfully (without failing). If the current root task fails
+ * and is supervised by the scheduler then any user-specified exit status is
+ * ignored and the process exits with the default failure status
+ */
fn set_exit_status(code: int) {
rustrt::rust_set_exit_status(code as libc::intptr_t);
}
-#[doc = "Path data type and helper functions"];
+//! Path data type and helper functions
export path;
export consts;
export normalize;
// FIXME: This type should probably be constrained (#2624)
-#[doc = "A path or fragment of a filesystem path"]
+/// A path or fragment of a filesystem path
type path = str;
#[cfg(unix)]
mod consts {
- #[doc = "
- The primary path separator character for the platform
-
- On all platforms it is '/'
- "]
+ /**
+ * The primary path separator character for the platform
+ *
+ * On all platforms it is '/'
+ */
const path_sep: char = '/';
- #[doc = "
- The secondary path separator character for the platform
-
- On Unixes it is '/'. On Windows it is '\\'.
- "]
+ /**
+ * The secondary path separator character for the platform
+ *
+ * On Unixes it is '/'. On Windows it is '\'.
+ */
const alt_path_sep: char = '/';
}
const alt_path_sep: char = '\\';
}
-#[doc = "
-Indicates whether a path is absolute.
-
-A path is considered absolute if it begins at the filesystem root (\"/\") or,
-on Windows, begins with a drive letter.
-"]
+/**
+ * Indicates whether a path is absolute.
+ *
+ * A path is considered absolute if it begins at the filesystem root ("/") or,
+ * on Windows, begins with a drive letter.
+ */
#[cfg(unix)]
fn path_is_absolute(p: path) -> bool {
str::char_at(p, 0u) == '/'
|| str::char_at(p, 2u) == consts::alt_path_sep);
}
-#[doc = "Get the default path separator for the host platform"]
+/// Get the default path separator for the host platform
fn path_sep() -> str { ret str::from_char(consts::path_sep); }
fn split_dirname_basename (pp: path) -> {dirname: str, basename: str} {
}
}
-#[doc = "
-Get the directory portion of a path
-
-Returns all of the path up to, but excluding, the final path separator.
-The dirname of \"/usr/share\" will be \"/usr\", but the dirname of
-\"/usr/share/\" is \"/usr/share\".
-
-If the path is not prefixed with a directory, then \".\" is returned.
-"]
+/**
+ * Get the directory portion of a path
+ *
+ * Returns all of the path up to, but excluding, the final path separator.
+ * The dirname of "/usr/share" will be "/usr", but the dirname of
+ * "/usr/share/" is "/usr/share".
+ *
+ * If the path is not prefixed with a directory, then "." is returned.
+ */
fn dirname(pp: path) -> path {
ret split_dirname_basename(pp).dirname;
}
-#[doc = "
-Get the file name portion of a path
-
-Returns the portion of the path after the final path separator.
-The basename of \"/usr/share\" will be \"share\". If there are no
-path separators in the path then the returned path is identical to
-the provided path. If an empty path is provided or the path ends
-with a path separator then an empty path is returned.
-"]
+/**
+ * Get the file name portion of a path
+ *
+ * Returns the portion of the path after the final path separator.
+ * The basename of "/usr/share" will be "share". If there are no
+ * path separators in the path then the returned path is identical to
+ * the provided path. If an empty path is provided or the path ends
+ * with a path separator then an empty path is returned.
+ */
fn basename(pp: path) -> path {
ret split_dirname_basename(pp).basename;
}
-#[doc = "
-Connects to path segments
-
-Given paths `pre` and `post, removes any trailing path separator on `pre` and
-any leading path separator on `post`, and returns the concatenation of the two
-with a single path separator between them.
-"]
+/**
+ * Connects to path segments
+ *
+ * Given paths `pre` and `post, removes any trailing path separator on `pre`
+ * and any leading path separator on `post`, and returns the concatenation of
+ * the two with a single path separator between them.
+ */
fn connect(pre: path, post: path) -> path {
let mut pre_ = pre;
let mut post_ = post;
ret pre_ + path_sep() + post_;
}
-#[doc = "
-Connects a vector of path segments into a single path.
-
-Inserts path separators as needed.
-"]
+/**
+ * Connects a vector of path segments into a single path.
+ *
+ * Inserts path separators as needed.
+ */
fn connect_many(paths: ~[path]) -> path {
ret if vec::len(paths) == 1u {
paths[0]
}
}
-#[doc = "
-Split a path into its individual components
-
-Splits a given path by path separators and returns a vector containing
-each piece of the path. On Windows, if the path is absolute then
-the first element of the returned vector will be the drive letter
-followed by a colon.
-"]
+/**
+ * Split a path into its individual components
+ *
+ * Splits a given path by path separators and returns a vector containing
+ * each piece of the path. On Windows, if the path is absolute then
+ * the first element of the returned vector will be the drive letter
+ * followed by a colon.
+ */
fn split(p: path) -> ~[path] {
str::split_nonempty(p, |c| {
c == consts::path_sep || c == consts::alt_path_sep
})
}
-#[doc = "
-Split a path into the part before the extension and the extension
-
-Split a path into a pair of strings with the first element being the filename
-without the extension and the second being either empty or the file extension
-including the period. Leading periods in the basename are ignored. If the
-path includes directory components then they are included in the filename part
-of the result pair.
-"]
+/**
+ * Split a path into the part before the extension and the extension
+ *
+ * Split a path into a pair of strings with the first element being the
+ * filename without the extension and the second being either empty or the
+ * file extension including the period. Leading periods in the basename are
+ * ignored. If the path includes directory components then they are included
+ * in the filename part of the result pair.
+ */
fn splitext(p: path) -> (str, str) {
if str::is_empty(p) { ("", "") }
else {
}
}
-#[doc = "
-Collapses redundant path separators.
-
-Does not follow symbolic links.
-
-# Examples
-
-* '/a/../b' becomes '/b'
-* 'a/./b/' becomes 'a/b/'
-* 'a/b/../../../' becomes '..'
-* '/a/b/c/../d/./../../e/' becomes '/a/e/'
-
-"]
+/**
+ * Collapses redundant path separators.
+ *
+ * Does not follow symbolic links.
+ *
+ * # Examples
+ *
+ * * '/a/../b' becomes '/b'
+ * * 'a/./b/' becomes 'a/b/'
+ * * 'a/b/../../../' becomes '..'
+ * * '/a/b/c/../d/./../../e/' becomes '/a/e/'
+ */
fn normalize(p: path) -> path {
let s = split(p);
let s = strip_dots(s);
type global_ptr = *libc::uintptr_t;
-#[doc = "
-Atomically gets a channel from a pointer to a pointer-sized memory location
-or, if no channel exists creates and installs a new channel and sets up a new
-task to receive from it.
-"]
+/**
+ * Atomically gets a channel from a pointer to a pointer-sized memory location
+ * or, if no channel exists creates and installs a new channel and sets up a
+ * new task to receive from it.
+ */
unsafe fn chan_from_global_ptr<T: send>(
global: global_ptr,
builder: fn() -> task::builder,
}
}
-#[doc = "
-Convert the current task to a 'weak' task temporarily
-
-As a weak task it will not be counted towards the runtime's set
-of live tasks. When there are no more outstanding live (non-weak) tasks
-the runtime will send an exit message on the provided channel.
-
-This function is super-unsafe. Do not use.
-
-# Safety notes
-
-* Weak tasks must either die on their own or exit upon receipt of
- the exit message. Failure to do so will cause the runtime to never
- exit
-* Tasks must not call `weaken_task` multiple times. This will
- break the kernel's accounting of live tasks.
-* Weak tasks must not be supervised. A supervised task keeps
- a reference to its parent, so the parent will not die.
-"]
+/**
+ * Convert the current task to a 'weak' task temporarily
+ *
+ * As a weak task it will not be counted towards the runtime's set
+ * of live tasks. When there are no more outstanding live (non-weak) tasks
+ * the runtime will send an exit message on the provided channel.
+ *
+ * This function is super-unsafe. Do not use.
+ *
+ * # Safety notes
+ *
+ * * Weak tasks must either die on their own or exit upon receipt of
+ * the exit message. Failure to do so will cause the runtime to never
+ * exit
+ * * Tasks must not call `weaken_task` multiple times. This will
+ * break the kernel's accounting of live tasks.
+ * * Weak tasks must not be supervised. A supervised task keeps
+ * a reference to its parent, so the parent will not die.
+ */
unsafe fn weaken_task(f: fn(comm::port<()>)) {
let po = comm::port();
let ch = comm::chan(po);
-#[doc = "Unsafe pointer utility functions"];
+//! Unsafe pointer utility functions
export addr_of;
export mut_addr_of;
fn addr_of<T>(val: T) -> *T;
}
-#[doc = "Get an unsafe pointer to a value"]
+/// Get an unsafe pointer to a value
#[inline(always)]
pure fn addr_of<T>(val: T) -> *T { unchecked { rusti::addr_of(val) } }
-#[doc = "Get an unsafe mut pointer to a value"]
+/// Get an unsafe mut pointer to a value
#[inline(always)]
pure fn mut_addr_of<T>(val: T) -> *mut T {
unsafe {
}
}
-#[doc = "Calculate the offset from a pointer"]
+/// Calculate the offset from a pointer
#[inline(always)]
fn offset<T>(ptr: *T, count: uint) -> *T {
unsafe {
}
}
-#[doc = "Calculate the offset from a const pointer"]
+/// Calculate the offset from a const pointer
#[inline(always)]
fn const_offset<T>(ptr: *const T, count: uint) -> *const T {
unsafe {
}
}
-#[doc = "Calculate the offset from a mut pointer"]
+/// Calculate the offset from a mut pointer
#[inline(always)]
fn mut_offset<T>(ptr: *mut T, count: uint) -> *mut T {
(ptr as uint + count * sys::size_of::<T>()) as *mut T
}
-#[doc = "Return the offset of the first null pointer in `buf`."]
+/// Return the offset of the first null pointer in `buf`.
#[inline(always)]
unsafe fn buf_len<T>(buf: **T) -> uint {
position(buf, |i| i == null())
}
-#[doc = "Return the first offset `i` such that `f(buf[i]) == true`."]
+/// Return the first offset `i` such that `f(buf[i]) == true`.
#[inline(always)]
unsafe fn position<T>(buf: *T, f: fn(T) -> bool) -> uint {
let mut i = 0u;
}
}
-#[doc = "Create an unsafe null pointer"]
+/// Create an unsafe null pointer
#[inline(always)]
pure fn null<T>() -> *T { unsafe { unsafe::reinterpret_cast(0u) } }
-#[doc = "Returns true if the pointer is equal to the null pointer."]
+/// Returns true if the pointer is equal to the null pointer.
pure fn is_null<T>(ptr: *const T) -> bool { ptr == null() }
-#[doc = "Returns true if the pointer is not equal to the null pointer."]
+/// Returns true if the pointer is not equal to the null pointer.
pure fn is_not_null<T>(ptr: *const T) -> bool { !is_null(ptr) }
-#[doc = "
-Copies data from one location to another
-
-Copies `count` elements (not bytes) from `src` to `dst`. The source
-and destination may not overlap.
-"]
+/**
+ * Copies data from one location to another
+ *
+ * Copies `count` elements (not bytes) from `src` to `dst`. The source
+ * and destination may not overlap.
+ */
#[inline(always)]
unsafe fn memcpy<T>(dst: *T, src: *T, count: uint) {
let n = count * sys::size_of::<T>();
libc_::memcpy(dst as *c_void, src as *c_void, n as size_t);
}
-#[doc = "
-Copies data from one location to another
-
-Copies `count` elements (not bytes) from `src` to `dst`. The source
-and destination may overlap.
-"]
+/**
+ * Copies data from one location to another
+ *
+ * Copies `count` elements (not bytes) from `src` to `dst`. The source
+ * and destination may overlap.
+ */
#[inline(always)]
unsafe fn memmove<T>(dst: *T, src: *T, count: uint) {
let n = count * sys::size_of::<T>();
libc_::memset(dst as *c_void, c as libc::c_int, n as size_t);
}
-#[doc = "Extension methods for pointers"]
+/// Extension methods for pointers
impl extensions<T> for *T {
- #[doc = "Returns true if the pointer is equal to the null pointer."]
+ /// Returns true if the pointer is equal to the null pointer.
pure fn is_null() -> bool { is_null(self) }
- #[doc = "Returns true if the pointer is not equal to the null pointer."]
+ /// Returns true if the pointer is not equal to the null pointer.
pure fn is_not_null() -> bool { is_not_null(self) }
}
-#[doc = "Random number generation"];
+//! Random number generation
export rng, seed, seeded_rng, weighted, extensions;
export xorshift, seeded_xorshift;
fn rand_free(c: *rctx);
}
-#[doc = "A random number generator"]
+/// A random number generator
iface rng {
- #[doc = "Return the next random integer"]
+ /// Return the next random integer
fn next() -> u32;
}
-#[doc = "A value with a particular weight compared to other values"]
+/// A value with a particular weight compared to other values
type weighted<T> = { weight: uint, item: T };
-#[doc = "Extension methods for random number generators"]
+/// Extension methods for random number generators
impl extensions for rng {
- #[doc = "Return a random int"]
+ /// Return a random int
fn gen_int() -> int {
self.gen_i64() as int
}
- #[doc = "Return an int randomly chosen from the range [start, end), \
- failing if start >= end"]
+ /**
+ * Return an int randomly chosen from the range [start, end),
+ * failing if start >= end
+ */
fn gen_int_range(start: int, end: int) -> int {
assert start < end;
start + int::abs(self.gen_int() % (end - start))
}
- #[doc = "Return a random i8"]
+ /// Return a random i8
fn gen_i8() -> i8 {
self.next() as i8
}
- #[doc = "Return a random i16"]
+ /// Return a random i16
fn gen_i16() -> i16 {
self.next() as i16
}
- #[doc = "Return a random i32"]
+ /// Return a random i32
fn gen_i32() -> i32 {
self.next() as i32
}
- #[doc = "Return a random i64"]
+ /// Return a random i64
fn gen_i64() -> i64 {
(self.next() as i64 << 32) | self.next() as i64
}
- #[doc = "Return a random uint"]
+ /// Return a random uint
fn gen_uint() -> uint {
self.gen_u64() as uint
}
- #[doc = "Return a uint randomly chosen from the range [start, end), \
- failing if start >= end"]
+ /**
+ * Return a uint randomly chosen from the range [start, end),
+ * failing if start >= end
+ */
fn gen_uint_range(start: uint, end: uint) -> uint {
assert start < end;
start + (self.gen_uint() % (end - start))
}
- #[doc = "Return a random u8"]
+ /// Return a random u8
fn gen_u8() -> u8 {
self.next() as u8
}
- #[doc = "Return a random u16"]
+ /// Return a random u16
fn gen_u16() -> u16 {
self.next() as u16
}
- #[doc = "Return a random u32"]
+ /// Return a random u32
fn gen_u32() -> u32 {
self.next()
}
- #[doc = "Return a random u64"]
+ /// Return a random u64
fn gen_u64() -> u64 {
(self.next() as u64 << 32) | self.next() as u64
}
- #[doc = "Return a random float"]
+ /// Return a random float
fn gen_float() -> float {
self.gen_f64() as float
}
- #[doc = "Return a random f32"]
+ /// Return a random f32
fn gen_f32() -> f32 {
self.gen_f64() as f32
}
- #[doc = "Return a random f64"]
+ /// Return a random f64
fn gen_f64() -> f64 {
let u1 = self.next() as f64;
let u2 = self.next() as f64;
ret ((u1 / scale + u2) / scale + u3) / scale;
}
- #[doc = "Return a random char"]
+ /// Return a random char
fn gen_char() -> char {
self.next() as char
}
- #[doc = "Return a char randomly chosen from chars, failing if chars is \
- empty"]
+ /**
+ * Return a char randomly chosen from chars, failing if chars is empty
+ */
fn gen_char_from(chars: str) -> char {
assert !chars.is_empty();
self.choose(str::chars(chars))
}
- #[doc = "Return a random bool"]
+ /// Return a random bool
fn gen_bool() -> bool {
self.next() & 1u32 == 1u32
}
- #[doc = "Return a bool with a 1 in n chance of true"]
+ /// Return a bool with a 1 in n chance of true
fn gen_weighted_bool(n: uint) -> bool {
if n == 0u {
true
}
}
- #[doc = "Return a random string of the specified length composed of A-Z, \
- a-z, 0-9"]
+ /**
+ * Return a random string of the specified length composed of A-Z,a-z,0-9
+ */
fn gen_str(len: uint) -> str {
let charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" +
"abcdefghijklmnopqrstuvwxyz" +
s
}
- #[doc = "Return a random byte string of the specified length"]
+ /// Return a random byte string of the specified length
fn gen_bytes(len: uint) -> ~[u8] {
do vec::from_fn(len) |_i| {
self.gen_u8()
}
}
- #[doc = "Choose an item randomly, failing if values is empty"]
+ /// Choose an item randomly, failing if values is empty
fn choose<T:copy>(values: ~[T]) -> T {
self.choose_option(values).get()
}
- #[doc = "Choose some(item) randomly, returning none if values is empty"]
+ /// Choose some(item) randomly, returning none if values is empty
fn choose_option<T:copy>(values: ~[T]) -> option<T> {
if values.is_empty() {
none
}
}
- #[doc = "Choose an item respecting the relative weights, failing if \
- the sum of the weights is 0"]
+ /**
+ * Choose an item respecting the relative weights, failing if the sum of
+ * the weights is 0
+ */
fn choose_weighted<T: copy>(v : ~[weighted<T>]) -> T {
self.choose_weighted_option(v).get()
}
- #[doc = "Choose some(item) respecting the relative weights, returning \
- none if the sum of the weights is 0"]
+ /**
+ * Choose some(item) respecting the relative weights, returning none if
+ * the sum of the weights is 0
+ */
fn choose_weighted_option<T:copy>(v: ~[weighted<T>]) -> option<T> {
let mut total = 0u;
for v.each |item| {
unreachable();
}
- #[doc = "Return a vec containing copies of the items, in order, where \
- the weight of the item determines how many copies there are"]
+ /**
+ * Return a vec containing copies of the items, in order, where
+ * the weight of the item determines how many copies there are
+ */
fn weighted_vec<T:copy>(v: ~[weighted<T>]) -> ~[T] {
let mut r = ~[];
for v.each |item| {
r
}
- #[doc = "Shuffle a vec"]
+ /// Shuffle a vec
fn shuffle<T:copy>(values: ~[T]) -> ~[T] {
let mut m = vec::to_mut(values);
self.shuffle_mut(m);
ret vec::from_mut(m);
}
- #[doc = "Shuffle a mutable vec in place"]
+ /// Shuffle a mutable vec in place
fn shuffle_mut<T>(&&values: ~[mut T]) {
let mut i = values.len();
while i >= 2u {
fn next() -> u32 { ret rustrt::rand_next((*self).c); }
}
-#[doc = "Create a new random seed for seeded_rng"]
+/// Create a new random seed for seeded_rng
fn seed() -> ~[u8] {
rustrt::rand_seed()
}
-#[doc = "Create a random number generator with a system specified seed"]
+/// Create a random number generator with a system specified seed
fn rng() -> rng {
@rand_res(rustrt::rand_new()) as rng
}
-#[doc = "Create a random number generator using the specified seed. A \
- generator constructed with a given seed will generate the same \
- sequence of values as all other generators constructed with the \
- same seed. The seed may be any length."]
+/**
+ * Create a random number generator using the specified seed. A generator
+ * constructed with a given seed will generate the same sequence of values as
+ * all other generators constructed with the same seed. The seed may be any
+ * length.
+ */
fn seeded_rng(seed: ~[u8]) -> rng {
@rand_res(rustrt::rand_new_seeded(seed)) as rng
}
-#[doc = "A type representing either success or failure"];
+//! A type representing either success or failure
import either::either;
-#[doc = "The result type"]
+/// The result type
enum result<T, U> {
- #[doc = "Contains the successful result value"]
+ /// Contains the successful result value
ok(T),
- #[doc = "Contains the error value"]
+ /// Contains the error value
err(U)
}
-#[doc = "
-Get the value out of a successful result
-
-# Failure
-
-If the result is an error
-"]
+/**
+ * Get the value out of a successful result
+ *
+ * # Failure
+ *
+ * If the result is an error
+ */
pure fn get<T: copy, U>(res: result<T, U>) -> T {
alt res {
ok(t) { t }
}
}
-#[doc = "
-Get the value out of an error result
-
-# Failure
-
-If the result is not an error
-"]
+/**
+ * Get the value out of an error result
+ *
+ * # Failure
+ *
+ * If the result is not an error
+ */
pure fn get_err<T, U: copy>(res: result<T, U>) -> U {
alt res {
err(u) { u }
}
}
-#[doc = "Returns true if the result is `ok`"]
+/// Returns true if the result is `ok`
pure fn is_ok<T, U>(res: result<T, U>) -> bool {
alt res {
ok(_) { true }
}
}
-#[doc = "Returns true if the result is `err`"]
+/// Returns true if the result is `err`
pure fn is_err<T, U>(res: result<T, U>) -> bool {
!is_ok(res)
}
-#[doc = "
-Convert to the `either` type
-
-`ok` result variants are converted to `either::right` variants, `err`
-result variants are converted to `either::left`.
-"]
+/**
+ * Convert to the `either` type
+ *
+ * `ok` result variants are converted to `either::right` variants, `err`
+ * result variants are converted to `either::left`.
+ */
pure fn to_either<T: copy, U: copy>(res: result<U, T>) -> either<T, U> {
alt res {
ok(res) { either::right(res) }
}
}
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `ok` then the value is extracted and passed to `op` whereupon
-`op`s result is returned. if `res` is `err` then it is immediately returned.
-This function can be used to compose the results of two functions.
-
-Example:
-
- let res = chain(read_file(file)) { |buf|
- ok(parse_buf(buf))
- }
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `ok` then the value is extracted and passed to `op` whereupon
+ * `op`s result is returned. if `res` is `err` then it is immediately
+ * returned. This function can be used to compose the results of two
+ * functions.
+ *
+ * Example:
+ *
+ * let res = chain(read_file(file)) { |buf|
+ * ok(parse_buf(buf))
+ * }
+ */
fn chain<T, U: copy, V: copy>(res: result<T, V>, op: fn(T) -> result<U, V>)
-> result<U, V> {
alt res {
}
}
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `err` then the value is extracted and passed to `op`
-whereupon `op`s result is returned. if `res` is `ok` then it is
-immediately returned. This function can be used to pass through a
-successful result while handling an error.
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `err` then the value is extracted and passed to `op`
+ * whereupon `op`s result is returned. if `res` is `ok` then it is
+ * immediately returned. This function can be used to pass through a
+ * successful result while handling an error.
+ */
fn chain_err<T: copy, U: copy, V: copy>(
res: result<T, V>,
op: fn(V) -> result<T, U>)
}
}
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `ok` then the value is extracted and passed to `op` whereupon
-`op`s result is returned. if `res` is `err` then it is immediately returned.
-This function can be used to compose the results of two functions.
-
-Example:
-
- iter(read_file(file)) { |buf|
- print_buf(buf)
- }
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `ok` then the value is extracted and passed to `op` whereupon
+ * `op`s result is returned. if `res` is `err` then it is immediately
+ * returned. This function can be used to compose the results of two
+ * functions.
+ *
+ * Example:
+ *
+ * iter(read_file(file)) { |buf|
+ * print_buf(buf)
+ * }
+ */
fn iter<T, E>(res: result<T, E>, f: fn(T)) {
alt res {
ok(t) { f(t) }
}
}
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `err` then the value is extracted and passed to `op` whereupon
-`op`s result is returned. if `res` is `ok` then it is immediately returned.
-This function can be used to pass through a successful result while handling
-an error.
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `err` then the value is extracted and passed to `op` whereupon
+ * `op`s result is returned. if `res` is `ok` then it is immediately returned.
+ * This function can be used to pass through a successful result while
+ * handling an error.
+ */
fn iter_err<T, E>(res: result<T, E>, f: fn(E)) {
alt res {
ok(_) { }
}
}
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `ok` then the value is extracted and passed to `op` whereupon
-`op`s result is wrapped in `ok` and returned. if `res` is `err` then it is
-immediately returned. This function can be used to compose the results of two
-functions.
-
-Example:
-
- let res = map(read_file(file)) { |buf|
- parse_buf(buf)
- }
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `ok` then the value is extracted and passed to `op` whereupon
+ * `op`s result is wrapped in `ok` and returned. if `res` is `err` then it is
+ * immediately returned. This function can be used to compose the results of
+ * two functions.
+ *
+ * Example:
+ *
+ * let res = map(read_file(file)) { |buf|
+ * parse_buf(buf)
+ * }
+ */
fn map<T, E: copy, U: copy>(res: result<T, E>, op: fn(T) -> U)
-> result<U, E> {
alt res {
}
}
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `err` then the value is extracted and passed to `op` whereupon
-`op`s result is wrapped in an `err` and returned. if `res` is `ok` then it is
-immediately returned. This function can be used to pass through a successful
-result while handling an error.
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `err` then the value is extracted and passed to `op` whereupon
+ * `op`s result is wrapped in an `err` and returned. if `res` is `ok` then it
+ * is immediately returned. This function can be used to pass through a
+ * successful result while handling an error.
+ */
fn map_err<T: copy, E, F: copy>(res: result<T, E>, op: fn(E) -> F)
-> result<T, F> {
alt res {
}
}
-#[doc = "
-Maps each element in the vector `ts` using the operation `op`. Should an
-error occur, no further mappings are performed and the error is returned.
-Should no error occur, a vector containing the result of each map is
-returned.
-
-Here is an example which increments every integer in a vector,
-checking for overflow:
-
- fn inc_conditionally(x: uint) -> result<uint,str> {
- if x == uint::max_value { ret err(\"overflow\"); }
- else { ret ok(x+1u); }
- }
- map([1u, 2u, 3u]/~, inc_conditionally).chain {|incd|
- assert incd == [2u, 3u, 4u]/~;
- }
-"]
+/**
+ * Maps each element in the vector `ts` using the operation `op`. Should an
+ * error occur, no further mappings are performed and the error is returned.
+ * Should no error occur, a vector containing the result of each map is
+ * returned.
+ *
+ * Here is an example which increments every integer in a vector,
+ * checking for overflow:
+ *
+ * fn inc_conditionally(x: uint) -> result<uint,str> {
+ * if x == uint::max_value { ret err("overflow"); }
+ * else { ret ok(x+1u); }
+ * }
+ * map([1u, 2u, 3u]/~, inc_conditionally).chain {|incd|
+ * assert incd == [2u, 3u, 4u]/~;
+ * }
+ */
fn map_vec<T,U:copy,V:copy>(
ts: ~[T], op: fn(T) -> result<V,U>) -> result<~[V],U> {
}
}
-#[doc = "Same as map, but it operates over two parallel vectors.
-
-A precondition is used here to ensure that the vectors are the same
-length. While we do not often use preconditions in the standard
-library, a precondition is used here because result::t is generally
-used in 'careful' code contexts where it is both appropriate and easy
-to accommodate an error like the vectors being of different lengths."]
+/**
+ * Same as map, but it operates over two parallel vectors.
+ *
+ * A precondition is used here to ensure that the vectors are the same
+ * length. While we do not often use preconditions in the standard
+ * library, a precondition is used here because result::t is generally
+ * used in 'careful' code contexts where it is both appropriate and easy
+ * to accommodate an error like the vectors being of different lengths.
+ */
fn map_vec2<S,T,U:copy,V:copy>(ss: ~[S], ts: ~[T],
op: fn(S,T) -> result<V,U>)
: vec::same_length(ss, ts) -> result<~[V],U> {
ret ok(vs);
}
-#[doc = "
-Applies op to the pairwise elements from `ss` and `ts`, aborting on
-error. This could be implemented using `map2()` but it is more efficient
-on its own as no result vector is built.
-"]
+/**
+ * Applies op to the pairwise elements from `ss` and `ts`, aborting on
+ * error. This could be implemented using `map2()` but it is more efficient
+ * on its own as no result vector is built.
+ */
fn iter_vec2<S,T,U:copy>(ss: ~[S], ts: ~[T],
op: fn(S,T) -> result<(),U>)
: vec::same_length(ss, ts)
ret ok(());
}
-#[doc="
-Unwraps a result, assuming it is an `ok(T)`
-"]
+/// Unwraps a result, assuming it is an `ok(T)`
fn unwrap<T, U>(-res: result<T, U>) -> T {
unsafe {
let addr = alt res {
-#[doc ="Process spawning"];
+//! Process spawning
import option::{some, none};
import libc::{pid_t, c_void, c_int};
-> pid_t;
}
-#[doc ="A value representing a child process"]
+/// A value representing a child process
iface program {
- #[doc ="Returns the process id of the program"]
+ /// Returns the process id of the program
fn get_id() -> pid_t;
- #[doc ="Returns an io::writer that can be used to write to stdin"]
+ /// Returns an io::writer that can be used to write to stdin
fn input() -> io::writer;
- #[doc ="Returns an io::reader that can be used to read from stdout"]
+ /// Returns an io::reader that can be used to read from stdout
fn output() -> io::reader;
- #[doc ="Returns an io::reader that can be used to read from stderr"]
+ /// Returns an io::reader that can be used to read from stderr
fn err() -> io::reader;
- #[doc = "Closes the handle to the child processes standard input"]
+ /// Closes the handle to the child processes standard input
fn close_input();
- #[doc = "
- Waits for the child process to terminate. Closes the handle
- to stdin if necessary.
- "]
+ /**
+ * Waits for the child process to terminate. Closes the handle
+ * to stdin if necessary.
+ */
fn finish() -> int;
- #[doc ="Closes open handles"]
+ /// Closes open handles
fn destroy();
}
-#[doc = "
-Run a program, providing stdin, stdout and stderr handles
-
-# Arguments
-
-* prog - The path to an executable
-* args - Vector of arguments to pass to the child process
-* env - optional env-modification for child
-* dir - optional dir to run child in (default current dir)
-* in_fd - A file descriptor for the child to use as std input
-* out_fd - A file descriptor for the child to use as std output
-* err_fd - A file descriptor for the child to use as std error
-
-# Return value
-
-The process id of the spawned process
-"]
+/**
+ * Run a program, providing stdin, stdout and stderr handles
+ *
+ * # Arguments
+ *
+ * * prog - The path to an executable
+ * * args - Vector of arguments to pass to the child process
+ * * env - optional env-modification for child
+ * * dir - optional dir to run child in (default current dir)
+ * * in_fd - A file descriptor for the child to use as std input
+ * * out_fd - A file descriptor for the child to use as std output
+ * * err_fd - A file descriptor for the child to use as std error
+ *
+ * # Return value
+ *
+ * The process id of the spawned process
+ */
fn spawn_process(prog: str, args: ~[str],
env: option<~[(str,str)]>,
dir: option<str>,
}
}
-#[doc ="
-Spawns a process and waits for it to terminate
-
-# Arguments
-
-* prog - The path to an executable
-* args - Vector of arguments to pass to the child process
-
-# Return value
-
-The process id
-"]
+/**
+ * Spawns a process and waits for it to terminate
+ *
+ * # Arguments
+ *
+ * * prog - The path to an executable
+ * * args - Vector of arguments to pass to the child process
+ *
+ * # Return value
+ *
+ * The process id
+ */
fn run_program(prog: str, args: ~[str]) -> int {
let pid = spawn_process(prog, args, none, none,
0i32, 0i32, 0i32);
ret waitpid(pid);
}
-#[doc ="
-Spawns a process and returns a program
-
-The returned value is a boxed class containing a <program> object that can
-be used for sending and receiving data over the standard file descriptors.
-The class will ensure that file descriptors are closed properly.
-
-# Arguments
-
-* prog - The path to an executable
-* args - Vector of arguments to pass to the child process
-
-# Return value
-
-A class with a <program> field
-"]
+/**
+ * Spawns a process and returns a program
+ *
+
* The returned value is a boxed class containing a <program> object that can
+ * be used for sending and receiving data over the standard file descriptors.
+ * The class will ensure that file descriptors are closed properly.
+ *
+ * # Arguments
+ *
+ * * prog - The path to an executable
+ * * args - Vector of arguments to pass to the child process
+ *
+ * # Return value
+ *
+
* A class with a <program> field
+ */
fn start_program(prog: str, args: ~[str]) -> program {
let pipe_input = os::pipe();
let pipe_output = os::pipe();
ret buf;
}
-#[doc ="
-Spawns a process, waits for it to exit, and returns the exit code, and
-contents of stdout and stderr.
-
-# Arguments
-
-* prog - The path to an executable
-* args - Vector of arguments to pass to the child process
-
-# Return value
-
-A record, {status: int, out: str, err: str} containing the exit code,
-the contents of stdout and the contents of stderr.
-"]
+/**
+ * Spawns a process, waits for it to exit, and returns the exit code, and
+ * contents of stdout and stderr.
+ *
+ * # Arguments
+ *
+ * * prog - The path to an executable
+ * * args - Vector of arguments to pass to the child process
+ *
+ * # Return value
+ *
+ * A record, {status: int, out: str, err: str} containing the exit code,
+ * the contents of stdout and the contents of stderr.
+ */
fn program_output(prog: str, args: ~[str]) ->
{status: int, out: str, err: str} {
ret buf;
}
-#[doc ="Waits for a process to exit and returns the exit code"]
+/// Waits for a process to exit and returns the exit code
fn waitpid(pid: pid_t) -> int {
ret waitpid_os(pid);
-#[doc = "
-String manipulation
-
-Strings are a packed UTF-8 representation of text, stored as null
-terminated buffers of u8 bytes. Strings should be indexed in bytes,
-for efficiency, but UTF-8 unsafe operations should be avoided. For
-some heavy-duty uses, try std::rope.
-"];
+/*!
+ * String manipulation
+ *
+ * Strings are a packed UTF-8 representation of text, stored as null
+ * terminated buffers of u8 bytes. Strings should be indexed in bytes,
+ * for efficiency, but UTF-8 unsafe operations should be avoided. For
+ * some heavy-duty uses, try std::rope.
+ */
import libc::size_t;
Section: Creating a string
*/
-#[doc = "
-Convert a vector of bytes to a UTF-8 string
-
-# Failure
-
-Fails if invalid UTF-8
-"]
+/**
+ * Convert a vector of bytes to a UTF-8 string
+ *
+ * # Failure
+ *
+ * Fails if invalid UTF-8
+ */
pure fn from_bytes(+vv: ~[u8]) -> str {
assert is_utf8(vv);
ret unsafe { unsafe::from_bytes(vv) };
}
-#[doc = "
-Convert a byte to a UTF-8 string
-
-# Failure
-
-Fails if invalid UTF-8
-"]
+/**
+ * Convert a byte to a UTF-8 string
+ *
+ * # Failure
+ *
+ * Fails if invalid UTF-8
+ */
pure fn from_byte(b: u8) -> str {
assert b < 128u8;
let mut v = ~[b, 0u8];
unsafe { ::unsafe::transmute(v) }
}
-#[doc = "Appends a character at the end of a string"]
+/// Appends a character at the end of a string
fn push_char(&s: str, ch: char) {
unsafe {
let code = ch as uint;
}
}
-#[doc = "Convert a char to a string"]
+/// Convert a char to a string
pure fn from_char(ch: char) -> str {
let mut buf = "";
unchecked { push_char(buf, ch); }
ret buf;
}
-#[doc = "Convert a vector of chars to a string"]
+/// Convert a vector of chars to a string
pure fn from_chars(chs: &[const char]) -> str {
let mut buf = "";
unchecked {
ret buf;
}
-#[doc = "Concatenate a vector of strings"]
+/// Concatenate a vector of strings
pure fn concat(v: &[const str]) -> str {
let mut s: str = "";
for vec::each(v) |ss| { s += ss; }
ret s;
}
-#[doc = "
-Concatenate a vector of strings, placing a given separator between each
-"]
+/// Concatenate a vector of strings, placing a given separator between each
pure fn connect(v: &[const str], sep: str) -> str {
let mut s = "", first = true;
for vec::each(v) |ss| {
Section: Adding to and removing from a string
*/
-#[doc = "
-Remove the final character from a string and return it
-
-# Failure
-
-If the string does not contain any characters
-"]
+/**
+ * Remove the final character from a string and return it
+ *
+ * # Failure
+ *
+ * If the string does not contain any characters
+ */
fn pop_char(&s: str) -> char {
let end = len(s);
assert end > 0u;
ret ch;
}
-#[doc = "
-Remove the first character from a string and return it
-
-# Failure
-
-If the string does not contain any characters
-"]
+/**
+ * Remove the first character from a string and return it
+ *
+ * # Failure
+ *
+ * If the string does not contain any characters
+ */
fn shift_char(&s: str) -> char {
let {ch, next} = char_range_at(s, 0u);
s = unsafe { unsafe::slice_bytes(s, next, len(s)) };
ret ch;
}
-#[doc = "Prepend a char to a string"]
+/// Prepend a char to a string
fn unshift_char(&s: str, ch: char) { s = from_char(ch) + s; }
-#[doc = "Returns a string with leading whitespace removed"]
+/// Returns a string with leading whitespace removed
pure fn trim_left(+s: str) -> str {
alt find(s, |c| !char::is_whitespace(c)) {
none { "" }
}
}
-#[doc = "Returns a string with trailing whitespace removed"]
+/// Returns a string with trailing whitespace removed
pure fn trim_right(+s: str) -> str {
alt rfind(s, |c| !char::is_whitespace(c)) {
none { "" }
}
}
-#[doc = "Returns a string with leading and trailing whitespace removed"]
+/// Returns a string with leading and trailing whitespace removed
pure fn trim(+s: str) -> str { trim_left(trim_right(s)) }
/*
Section: Transforming strings
*/
-#[doc = "
-Converts a string to a vector of bytes
-
-The result vector is not null-terminated.
-"]
+/**
+ * Converts a string to a vector of bytes
+ *
+ * The result vector is not null-terminated.
+ */
pure fn bytes(s: str) -> ~[u8] {
unsafe {
let mut s_copy = s;
}
}
-#[doc = "
-Work with the string as a byte slice, not including trailing null.
-"]
+/// Work with the string as a byte slice, not including trailing null.
#[inline(always)]
pure fn byte_slice<T>(s: str/&, f: fn(v: &[u8]) -> T) -> T {
do unpack_slice(s) |p,n| {
}
}
-#[doc = "Convert a string to a vector of characters"]
+/// Convert a string to a vector of characters
pure fn chars(s: str/&) -> ~[char] {
let mut buf = ~[], i = 0u;
let len = len(s);
ret buf;
}
-#[doc = "
-Take a substring of another.
-
-Returns a string containing `n` characters starting at byte offset
-`begin`.
-"]
+/**
+ * Take a substring of another.
+ *
+ * Returns a string containing `n` characters starting at byte offset
+ * `begin`.
+ */
pure fn substr(s: str/&, begin: uint, n: uint) -> str {
slice(s, begin, begin + count_bytes(s, begin, n))
}
-#[doc = "
-Returns a slice of the given string from the byte range [`begin`..`end`)
-
-Fails when `begin` and `end` do not point to valid characters or
-beyond the last character of the string
-"]
+/**
+ * Returns a slice of the given string from the byte range [`begin`..`end`)
+ *
+ * Fails when `begin` and `end` do not point to valid characters or
+ * beyond the last character of the string
+ */
pure fn slice(s: str/&, begin: uint, end: uint) -> str {
assert is_char_boundary(s, begin);
assert is_char_boundary(s, end);
unsafe { unsafe::slice_bytes(s, begin, end) }
}
-#[doc = "
-Splits a string into substrings at each occurrence of a given character
-"]
+/// Splits a string into substrings at each occurrence of a given character
pure fn split_char(s: str/&, sep: char) -> ~[str] {
split_char_inner(s, sep, len(s), true)
}
-#[doc = "
-Splits a string into substrings at each occurrence of a given
-character up to 'count' times
-
-The byte must be a valid UTF-8/ASCII byte
-"]
+/**
+ * Splits a string into substrings at each occurrence of a given
+ * character up to 'count' times
+ *
+ * The byte must be a valid UTF-8/ASCII byte
+ */
pure fn splitn_char(s: str/&, sep: char, count: uint) -> ~[str] {
split_char_inner(s, sep, count, true)
}
-#[doc = "
-Like `split_char`, but omits empty strings from the returned vector
-"]
+/// Like `split_char`, but omits empty strings from the returned vector
pure fn split_char_nonempty(s: str/&, sep: char) -> ~[str] {
split_char_inner(s, sep, len(s), false)
}
}
-#[doc = "Splits a string into substrings using a character function"]
+/// Splits a string into substrings using a character function
pure fn split(s: str/&, sepfn: fn(char) -> bool) -> ~[str] {
split_inner(s, sepfn, len(s), true)
}
-#[doc = "
-Splits a string into substrings using a character function, cutting at
-most `count` times.
-"]
+/**
+ * Splits a string into substrings using a character function, cutting at
+ * most `count` times.
+ */
pure fn splitn(s: str/&, sepfn: fn(char) -> bool, count: uint) -> ~[str] {
split_inner(s, sepfn, count, true)
}
-#[doc = "Like `split`, but omits empty strings from the returned vector"]
+/// Like `split`, but omits empty strings from the returned vector
pure fn split_nonempty(s: str/&, sepfn: fn(char) -> bool) -> ~[str] {
split_inner(s, sepfn, len(s), false)
}
f(last_end, len(s));
}
-#[doc = "
-Splits a string into a vector of the substrings separated by a given string
-
-# Example
-
-~~~
-assert [\"\", \"XXX\", \"YYY\", \"\"] == split_str(\".XXX.YYY.\", \".\")
-~~~
-"]
+/**
+ * Splits a string into a vector of the substrings separated by a given string
+ *
+ * # Example
+ *
+ * ~~~
+ * assert ["", "XXX", "YYY", ""] == split_str(".XXX.YYY.", ".")
+ * ~~~
+ */
pure fn split_str(s: str/&a, sep: str/&b) -> ~[str] {
let mut result = ~[];
do iter_between_matches(s, sep) |from, to| {
result
}
-#[doc = "
-Splits a string into a vector of the substrings separated by LF ('\\n')
-"]
+/**
+ * Splits a string into a vector of the substrings separated by LF ('\n')
+ */
pure fn lines(s: str/&) -> ~[str] { split_char(s, '\n') }
-#[doc = "
-Splits a string into a vector of the substrings separated by LF ('\\n')
-and/or CR LF ('\\r\\n')
-"]
+/**
+ * Splits a string into a vector of the substrings separated by LF ('\n')
+ * and/or CR LF ("\r\n")
+ */
pure fn lines_any(s: str/&) -> ~[str] {
vec::map(lines(s), |s| {
let l = len(s);
})
}
-#[doc = "
-Splits a string into a vector of the substrings separated by whitespace
-"]
+/// Splits a string into a vector of the substrings separated by whitespace
pure fn words(s: str/&) -> ~[str] {
split_nonempty(s, |c| char::is_whitespace(c))
}
-#[doc = "Convert a string to lowercase. ASCII only"]
+/// Convert a string to lowercase. ASCII only
pure fn to_lower(s: str/&) -> str {
map(s,
|c| unchecked{(libc::tolower(c as libc::c_char)) as char}
)
}
-#[doc = "Convert a string to uppercase. ASCII only"]
+/// Convert a string to uppercase. ASCII only
pure fn to_upper(s: str/&) -> str {
map(s,
|c| unchecked{(libc::toupper(c as libc::c_char)) as char}
)
}
-#[doc = "
-Replace all occurrences of one string with another
-
-# Arguments
-
-* s - The string containing substrings to replace
-* from - The string to replace
-* to - The replacement string
-
-# Return value
-
-The original string with all occurances of `from` replaced with `to`
-"]
+/**
+ * Replace all occurrences of one string with another
+ *
+ * # Arguments
+ *
+ * * s - The string containing substrings to replace
+ * * from - The string to replace
+ * * to - The replacement string
+ *
+ * # Return value
+ *
+ * The original string with all occurances of `from` replaced with `to`
+ */
pure fn replace(s: str, from: str, to: str) -> str {
let mut result = "", first = true;
do iter_between_matches(s, from) |start, end| {
Section: Comparing strings
*/
-#[doc = "Bytewise string equality"]
+/// Bytewise string equality
pure fn eq(&&a: str, &&b: str) -> bool {
// FIXME (#2627): This should just be "a == b" but that calls into the
// shape code.
ret true;
}
-#[doc = "Bytewise less than or equal"]
+/// Bytewise less than or equal
pure fn le(&&a: str, &&b: str) -> bool { a <= b }
-#[doc = "String hash function"]
+/// String hash function
pure fn hash(&&s: str) -> uint {
// djb hash.
// FIXME: replace with murmur. (see #859 and #1616)
Section: Iterating through strings
*/
-#[doc = "
-Return true if a predicate matches all characters or if the string
-contains no characters
-"]
+/**
+ * Return true if a predicate matches all characters or if the string
+ * contains no characters
+ */
pure fn all(s: str/&, it: fn(char) -> bool) -> bool {
all_between(s, 0u, len(s), it)
}
-#[doc = "
-Return true if a predicate matches any character (and false if it
-matches none or there are no characters)
-"]
+/**
+ * Return true if a predicate matches any character (and false if it
+ * matches none or there are no characters)
+ */
pure fn any(ss: str/&, pred: fn(char) -> bool) -> bool {
!all(ss, |cc| !pred(cc))
}
-#[doc = "Apply a function to each character"]
+/// Apply a function to each character
pure fn map(ss: str/&, ff: fn(char) -> char) -> str {
let mut result = "";
unchecked {
result
}
-#[doc = "Iterate over the bytes in a string"]
+/// Iterate over the bytes in a string
pure fn bytes_iter(ss: str/&, it: fn(u8)) {
let mut pos = 0u;
let len = len(ss);
}
}
-#[doc = "Iterate over the bytes in a string"]
+/// Iterate over the bytes in a string
#[inline(always)]
pure fn each(s: str/&, it: fn(u8) -> bool) {
eachi(s, |_i, b| it(b) )
}
-#[doc = "Iterate over the bytes in a string, with indices"]
+/// Iterate over the bytes in a string, with indices
#[inline(always)]
pure fn eachi(s: str/&, it: fn(uint, u8) -> bool) {
let mut i = 0u, l = len(s);
}
}
-#[doc = "Iterates over the chars in a string"]
+/// Iterates over the chars in a string
#[inline(always)]
pure fn each_char(s: str/&, it: fn(char) -> bool) {
each_chari(s, |_i, c| it(c))
}
-#[doc = "Iterates over the chars in a string, with indices"]
+/// Iterates over the chars in a string, with indices
#[inline(always)]
pure fn each_chari(s: str/&, it: fn(uint, char) -> bool) {
let mut pos = 0u, ch_pos = 0u;
}
}
-#[doc = "Iterate over the characters in a string"]
+/// Iterate over the characters in a string
pure fn chars_iter(s: str/&, it: fn(char)) {
let mut pos = 0u;
let len = len(s);
}
}
-#[doc = "
-Apply a function to each substring after splitting by character
-"]
+/// Apply a function to each substring after splitting by character
pure fn split_char_iter(ss: str/&, cc: char, ff: fn(&&str)) {
vec::iter(split_char(ss, cc), ff)
}
-#[doc = "
-Apply a function to each substring after splitting by character, up to
-`count` times
-"]
+/**
+ * Apply a function to each substring after splitting by character, up to
+ * `count` times
+ */
pure fn splitn_char_iter(ss: str/&, sep: char, count: uint,
ff: fn(&&str)) {
vec::iter(splitn_char(ss, sep, count), ff)
}
-#[doc = "Apply a function to each word"]
+/// Apply a function to each word
pure fn words_iter(ss: str/&, ff: fn(&&str)) {
vec::iter(words(ss), ff)
}
-#[doc = "Apply a function to each line (by '\\n')"]
+/**
+ * Apply a function to each line (by '\n')
+ */
pure fn lines_iter(ss: str/&, ff: fn(&&str)) {
vec::iter(lines(ss), ff)
}
Section: Searching
*/
-#[doc = "
-Returns the byte index of the first matching character
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-"]
+/**
+ * Returns the byte index of the first matching character
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ */
pure fn find_char(s: str/&, c: char) -> option<uint> {
find_char_between(s, c, 0u, len(s))
}
-#[doc = "
-Returns the byte index of the first matching character beginning
-from a given byte offset
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-* `start` - The byte index to begin searching at, inclusive
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `len(s)`. `start` must be the
-index of a character boundary, as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the first matching character beginning
+ * from a given byte offset
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ * * `start` - The byte index to begin searching at, inclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `len(s)`. `start` must be the
+ * index of a character boundary, as defined by `is_char_boundary`.
+ */
pure fn find_char_from(s: str/&, c: char, start: uint) -> option<uint> {
find_char_between(s, c, start, len(s))
}
-#[doc = "
-Returns the byte index of the first matching character within a given range
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-* `start` - The byte index to begin searching at, inclusive
-* `end` - The byte index to end searching at, exclusive
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `end` and `end` must be less than
-or equal to `len(s)`. `start` must be the index of a character boundary,
-as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the first matching character within a given range
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ * * `start` - The byte index to begin searching at, inclusive
+ * * `end` - The byte index to end searching at, exclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `end` and `end` must be less than
+ * or equal to `len(s)`. `start` must be the index of a character boundary,
+ * as defined by `is_char_boundary`.
+ */
pure fn find_char_between(s: str/&, c: char, start: uint, end: uint)
-> option<uint> {
if c < 128u as char {
}
}
-#[doc = "
-Returns the byte index of the last matching character
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-"]
+/**
+ * Returns the byte index of the last matching character
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ */
pure fn rfind_char(s: str/&, c: char) -> option<uint> {
rfind_char_between(s, c, len(s), 0u)
}
-#[doc = "
-Returns the byte index of the last matching character beginning
-from a given byte offset
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-* `start` - The byte index to begin searching at, exclusive
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `len(s)`. `start` must be
-the index of a character boundary, as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the last matching character beginning
+ * from a given byte offset
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ * * `start` - The byte index to begin searching at, exclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `len(s)`. `start` must be
+ * the index of a character boundary, as defined by `is_char_boundary`.
+ */
pure fn rfind_char_from(s: str/&, c: char, start: uint) -> option<uint> {
rfind_char_between(s, c, start, 0u)
}
-#[doc = "
-Returns the byte index of the last matching character within a given range
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-* `start` - The byte index to begin searching at, exclusive
-* `end` - The byte index to end searching at, inclusive
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-
-# Failure
-
-`end` must be less than or equal to `start` and `start` must be less than
-or equal to `len(s)`. `start` must be the index of a character boundary,
-as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the last matching character within a given range
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ * * `start` - The byte index to begin searching at, exclusive
+ * * `end` - The byte index to end searching at, inclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `end` must be less than or equal to `start` and `start` must be less than
+ * or equal to `len(s)`. `start` must be the index of a character boundary,
+ * as defined by `is_char_boundary`.
+ */
pure fn rfind_char_between(s: str/&, c: char, start: uint, end: uint)
-> option<uint> {
if c < 128u as char {
}
}
-#[doc = "
-Returns the byte index of the first character that satisfies
-the given predicate
-
-# Arguments
-
-* `s` - The string to search
-* `f` - The predicate to satisfy
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-"]
+/**
+ * Returns the byte index of the first character that satisfies
+ * the given predicate
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ */
pure fn find(s: str/&, f: fn(char) -> bool) -> option<uint> {
find_between(s, 0u, len(s), f)
}
-#[doc = "
-Returns the byte index of the first character that satisfies
-the given predicate, beginning from a given byte offset
-
-# Arguments
-
-* `s` - The string to search
-* `start` - The byte index to begin searching at, inclusive
-* `f` - The predicate to satisfy
-
-# Return value
-
-An `option` containing the byte index of the first matching charactor
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `len(s)`. `start` must be the
-index of a character boundary, as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the first character that satisfies
+ * the given predicate, beginning from a given byte offset
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `start` - The byte index to begin searching at, inclusive
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching charactor
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `len(s)`. `start` must be the
+ * index of a character boundary, as defined by `is_char_boundary`.
+ */
pure fn find_from(s: str/&, start: uint, f: fn(char)
-> bool) -> option<uint> {
find_between(s, start, len(s), f)
}
-#[doc = "
-Returns the byte index of the first character that satisfies
-the given predicate, within a given range
-
-# Arguments
-
-* `s` - The string to search
-* `start` - The byte index to begin searching at, inclusive
-* `end` - The byte index to end searching at, exclusive
-* `f` - The predicate to satisfy
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `end` and `end` must be less than
-or equal to `len(s)`. `start` must be the index of a character
-boundary, as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the first character that satisfies
+ * the given predicate, within a given range
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `start` - The byte index to begin searching at, inclusive
+ * * `end` - The byte index to end searching at, exclusive
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `end` and `end` must be less than
+ * or equal to `len(s)`. `start` must be the index of a character
+ * boundary, as defined by `is_char_boundary`.
+ */
pure fn find_between(s: str/&, start: uint, end: uint, f: fn(char) -> bool)
-> option<uint> {
assert start <= end;
ret none;
}
-#[doc = "
-Returns the byte index of the last character that satisfies
-the given predicate
-
-# Arguments
-
-* `s` - The string to search
-* `f` - The predicate to satisfy
-
-# Return value
-
-An option containing the byte index of the last matching character
-or `none` if there is no match
-"]
+/**
+ * Returns the byte index of the last character that satisfies
+ * the given predicate
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An option containing the byte index of the last matching character
+ * or `none` if there is no match
+ */
pure fn rfind(s: str/&, f: fn(char) -> bool) -> option<uint> {
rfind_between(s, len(s), 0u, f)
}
-#[doc = "
-Returns the byte index of the last character that satisfies
-the given predicate, beginning from a given byte offset
-
-# Arguments
-
-* `s` - The string to search
-* `start` - The byte index to begin searching at, exclusive
-* `f` - The predicate to satisfy
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `len(s)', `start` must be the
-index of a character boundary, as defined by `is_char_boundary`
-"]
+/**
+ * Returns the byte index of the last character that satisfies
+ * the given predicate, beginning from a given byte offset
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `start` - The byte index to begin searching at, exclusive
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `len(s)', `start` must be the
+ * index of a character boundary, as defined by `is_char_boundary`
+ */
pure fn rfind_from(s: str/&, start: uint, f: fn(char) -> bool)
-> option<uint> {
rfind_between(s, start, 0u, f)
}
-#[doc = "
-Returns the byte index of the last character that satisfies
-the given predicate, within a given range
-
-# Arguments
-
-* `s` - The string to search
-* `start` - The byte index to begin searching at, exclusive
-* `end` - The byte index to end searching at, inclusive
-* `f` - The predicate to satisfy
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-
-# Failure
-
-`end` must be less than or equal to `start` and `start` must be less
-than or equal to `len(s)`. `start` must be the index of a character
-boundary, as defined by `is_char_boundary`
-"]
+/**
+ * Returns the byte index of the last character that satisfies
+ * the given predicate, within a given range
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `start` - The byte index to begin searching at, exclusive
+ * * `end` - The byte index to end searching at, inclusive
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `end` must be less than or equal to `start` and `start` must be less
+ * than or equal to `len(s)`. `start` must be the index of a character
+ * boundary, as defined by `is_char_boundary`
+ */
pure fn rfind_between(s: str/&, start: uint, end: uint, f: fn(char) -> bool)
-> option<uint> {
assert start >= end;
ret true;
}
-#[doc = "
-Returns the byte index of the first matching substring
-
-# Arguments
-
-* `haystack` - The string to search
-* `needle` - The string to search for
-
-# Return value
-
-An `option` containing the byte index of the first matching substring
-or `none` if there is no match
-"]
+/**
+ * Returns the byte index of the first matching substring
+ *
+ * # Arguments
+ *
+ * * `haystack` - The string to search
+ * * `needle` - The string to search for
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching substring
+ * or `none` if there is no match
+ */
pure fn find_str(haystack: str/&a, needle: str/&b) -> option<uint> {
find_str_between(haystack, needle, 0u, len(haystack))
}
-#[doc = "
-Returns the byte index of the first matching substring beginning
-from a given byte offset
-
-# Arguments
-
-* `haystack` - The string to search
-* `needle` - The string to search for
-* `start` - The byte index to begin searching at, inclusive
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `len(s)`
-"]
+/**
+ * Returns the byte index of the first matching substring beginning
+ * from a given byte offset
+ *
+ * # Arguments
+ *
+ * * `haystack` - The string to search
+ * * `needle` - The string to search for
+ * * `start` - The byte index to begin searching at, inclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `len(s)`
+ */
pure fn find_str_from(haystack: str/&a, needle: str/&b, start: uint)
-> option<uint> {
find_str_between(haystack, needle, start, len(haystack))
}
-#[doc = "
-Returns the byte index of the first matching substring within a given range
-
-# Arguments
-
-* `haystack` - The string to search
-* `needle` - The string to search for
-* `start` - The byte index to begin searching at, inclusive
-* `end` - The byte index to end searching at, exclusive
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `end` and `end` must be less than
-or equal to `len(s)`.
-"]
+/**
+ * Returns the byte index of the first matching substring within a given range
+ *
+ * # Arguments
+ *
+ * * `haystack` - The string to search
+ * * `needle` - The string to search for
+ * * `start` - The byte index to begin searching at, inclusive
+ * * `end` - The byte index to end searching at, exclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `end` and `end` must be less than
+ * or equal to `len(s)`.
+ */
pure fn find_str_between(haystack: str/&a, needle: str/&b, start: uint,
end:uint)
-> option<uint> {
ret none;
}
-#[doc = "
-Returns true if one string contains another
-
-# Arguments
-
-* haystack - The string to look in
-* needle - The string to look for
-"]
+/**
+ * Returns true if one string contains another
+ *
+ * # Arguments
+ *
+ * * haystack - The string to look in
+ * * needle - The string to look for
+ */
pure fn contains(haystack: str/&a, needle: str/&b) -> bool {
option::is_some(find_str(haystack, needle))
}
-#[doc = "
-Returns true if a string contains a char.
-
-# Arguments
-
-* haystack - The string to look in
-* needle - The char to look for
-"]
+/**
+ * Returns true if a string contains a char.
+ *
+ * # Arguments
+ *
+ * * haystack - The string to look in
+ * * needle - The char to look for
+ */
pure fn contains_char(haystack: str/&, needle: char) -> bool {
option::is_some(find_char(haystack, needle))
}
-#[doc = "
-Returns true if one string starts with another
-
-# Arguments
-
-* haystack - The string to look in
-* needle - The string to look for
-"]
+/**
+ * Returns true if one string starts with another
+ *
+ * # Arguments
+ *
+ * * haystack - The string to look in
+ * * needle - The string to look for
+ */
pure fn starts_with(haystack: str/&a, needle: str/&b) -> bool {
let haystack_len = len(haystack), needle_len = len(needle);
if needle_len == 0u { true }
else { match_at(haystack, needle, 0u) }
}
-#[doc = "
-Returns true if one string ends with another
-
-# Arguments
-
-* haystack - The string to look in
-* needle - The string to look for
-"]
+/**
+ * Returns true if one string ends with another
+ *
+ * # Arguments
+ *
+ * * haystack - The string to look in
+ * * needle - The string to look for
+ */
pure fn ends_with(haystack: str/&a, needle: str/&b) -> bool {
let haystack_len = len(haystack), needle_len = len(needle);
if needle_len == 0u { true }
Section: String properties
*/
-#[doc = "Determines if a string contains only ASCII characters"]
+/// Determines if a string contains only ASCII characters
pure fn is_ascii(s: str/&) -> bool {
let mut i: uint = len(s);
while i > 0u { i -= 1u; if !u8::is_ascii(s[i]) { ret false; } }
ret true;
}
-#[doc = "Returns true if the string has length 0"]
+/// Returns true if the string has length 0
pure fn is_empty(s: str/&) -> bool { len(s) == 0u }
-#[doc = "Returns true if the string has length greater than 0"]
+/// Returns true if the string has length greater than 0
pure fn is_not_empty(s: str/&) -> bool { !is_empty(s) }
-#[doc = "
-Returns true if the string contains only whitespace
-
-Whitespace characters are determined by `char::is_whitespace`
-"]
+/**
+ * Returns true if the string contains only whitespace
+ *
+ * Whitespace characters are determined by `char::is_whitespace`
+ */
pure fn is_whitespace(s: str/&) -> bool {
ret all(s, char::is_whitespace);
}
-#[doc = "
-Returns true if the string contains only alphanumerics
-
-Alphanumeric characters are determined by `char::is_alphanumeric`
-"]
+/**
+ * Returns true if the string contains only alphanumerics
+ *
+ * Alphanumeric characters are determined by `char::is_alphanumeric`
+ */
fn is_alphanumeric(s: str/&) -> bool {
ret all(s, char::is_alphanumeric);
}
-#[doc = "
-Returns the string length/size in bytes not counting the null terminator
-"]
+/// Returns the string length/size in bytes not counting the null terminator
pure fn len(s: str/&) -> uint {
do unpack_slice(s) |_p, n| { n - 1u }
}
-#[doc = "Returns the number of characters that a string holds"]
+/// Returns the number of characters that a string holds
pure fn char_len(s: str/&) -> uint { count_chars(s, 0u, len(s)) }
/*
Section: Misc
*/
-#[doc = "Determines if a vector of bytes contains valid UTF-8"]
+/// Determines if a vector of bytes contains valid UTF-8
pure fn is_utf8(v: &[const u8]) -> bool {
let mut i = 0u;
let total = vec::len::<u8>(v);
ret true;
}
-#[doc = "Determines if a vector of `u16` contains valid UTF-16"]
+/// Determines if a vector of `u16` contains valid UTF-16
pure fn is_utf16(v: &[const u16]) -> bool {
let len = vec::len(v);
let mut i = 0u;
ret true;
}
-#[doc = "Converts to a vector of `u16` encoded as UTF-16"]
+/// Converts to a vector of `u16` encoded as UTF-16
pure fn to_utf16(s: str/&) -> ~[u16] {
let mut u = ~[];
do chars_iter(s) |cch| {
}
-#[doc = "
-As char_len but for a slice of a string
-
-# Arguments
-
-* s - A valid string
-* start - The position inside `s` where to start counting in bytes
-* end - The position where to stop counting
-
-# Return value
-
-The number of Unicode characters in `s` between the given indices.
-"]
+/**
+ * As char_len but for a slice of a string
+ *
+ * # Arguments
+ *
+ * * s - A valid string
+ * * start - The position inside `s` where to start counting in bytes
+ * * end - The position where to stop counting
+ *
+ * # Return value
+ *
+ * The number of Unicode characters in `s` between the given indices.
+ */
pure fn count_chars(s: str/&, start: uint, end: uint) -> uint {
assert is_char_boundary(s, start);
assert is_char_boundary(s, end);
ret len;
}
-#[doc = "
-Counts the number of bytes taken by the `n` in `s` starting from `start`.
-"]
+/// Counts the number of bytes taken by the `n` in `s` starting from `start`.
pure fn count_bytes(s: str/&b, start: uint, n: uint) -> uint {
assert is_char_boundary(s, start);
let mut end = start, cnt = n;
end - start
}
-#[doc = "
-Given a first byte, determine how many bytes are in this UTF-8 character
-"]
+/// Given a first byte, determine how many bytes are in this UTF-8 character
pure fn utf8_char_width(b: u8) -> uint {
let byte: uint = b as uint;
if byte < 128u { ret 1u; }
ret 6u;
}
-#[doc = "
-Returns false if the index points into the middle of a multi-byte
-character sequence.
-"]
+/**
+ * Returns false if the index points into the middle of a multi-byte
+ * character sequence.
+ */
pure fn is_char_boundary(s: str/&, index: uint) -> bool {
if index == len(s) { ret true; }
let b = s[index];
ret b < 128u8 || b >= 192u8;
}
-#[doc = "
-Pluck a character out of a string and return the index of the next character.
-
-This function can be used to iterate over the unicode characters of a string.
-
-# Example
-
-~~~
-let s = \"中华Việt Nam\";
-let i = 0u;
-while i < str::len(s) {
- let {ch, next} = str::char_range_at(s, i);
- std::io::println(#fmt(\"%u: %c\",i,ch));
- i = next;
-}
-~~~
-
-# Example output
-
-~~~
-0: 中
-3: 华
-6: V
-7: i
-8: ệ
-11: t
-12:
-13: N
-14: a
-15: m
-~~~
-
-# Arguments
-
-* s - The string
-* i - The byte offset of the char to extract
-
-# Return value
-
-A record {ch: char, next: uint} containing the char value and the byte
-index of the next unicode character.
-
-# Failure
-
-If `i` is greater than or equal to the length of the string.
-If `i` is not the index of the beginning of a valid UTF-8 character.
-"]
+/**
+ * Pluck a character out of a string and return the index of the next
+ * character.
+ *
+ * This function can be used to iterate over the unicode characters of a
+ * string.
+ *
+ * # Example
+ *
+ * ~~~
+ * let s = "中华Việt Nam";
+ * let i = 0u;
+ * while i < str::len(s) {
+ * let {ch, next} = str::char_range_at(s, i);
+ * std::io::println(#fmt("%u: %c",i,ch));
+ * i = next;
+ * }
+ * ~~~
+ *
+ * # Example output
+ *
+ * ~~~
+ * 0: 中
+ * 3: 华
+ * 6: V
+ * 7: i
+ * 8: ệ
+ * 11: t
+ * 12:
+ * 13: N
+ * 14: a
+ * 15: m
+ * ~~~
+ *
+ * # Arguments
+ *
+ * * s - The string
+ * * i - The byte offset of the char to extract
+ *
+ * # Return value
+ *
+ * A record {ch: char, next: uint} containing the char value and the byte
+ * index of the next unicode character.
+ *
+ * # Failure
+ *
+ * If `i` is greater than or equal to the length of the string.
+ * If `i` is not the index of the beginning of a valid UTF-8 character.
+ */
pure fn char_range_at(s: str/&, i: uint) -> {ch: char, next: uint} {
let b0 = s[i];
let w = utf8_char_width(b0);
ret {ch: val as char, next: i};
}
-#[doc = "Pluck a character out of a string"]
+/// Pluck a character out of a string
pure fn char_at(s: str/&, i: uint) -> char { ret char_range_at(s, i).ch; }
-#[doc = "
-Given a byte position and a str, return the previous char and its position
-
-This function can be used to iterate over a unicode string in reverse.
-"]
+/**
+ * Given a byte position and a str, return the previous char and its position
+ *
+ * This function can be used to iterate over a unicode string in reverse.
+ */
pure fn char_range_at_reverse(ss: str/&, start: uint)
-> {ch: char, prev: uint} {
ret {ch:ch, prev:prev};
}
-#[doc = "
-Loop through a substring, char by char
-
-# Safety note
-
-* This function does not check whether the substring is valid.
-* This function fails if `start` or `end` do not
- represent valid positions inside `s`
-
-# Arguments
-
-* s - A string to traverse. It may be empty.
-* start - The byte offset at which to start in the string.
-* end - The end of the range to traverse
-* it - A block to execute with each consecutive character of `s`.
- Return `true` to continue, `false` to stop.
-
-# Return value
-
-`true` If execution proceeded correctly, `false` if it was interrupted,
-that is if `it` returned `false` at any point.
-"]
+/**
+ * Loop through a substring, char by char
+ *
+ * # Safety note
+ *
+ * * This function does not check whether the substring is valid.
+ * * This function fails if `start` or `end` do not
+ * represent valid positions inside `s`
+ *
+ * # Arguments
+ *
+ * * s - A string to traverse. It may be empty.
+ * * start - The byte offset at which to start in the string.
+ * * end - The end of the range to traverse
+ * * it - A block to execute with each consecutive character of `s`.
+ * Return `true` to continue, `false` to stop.
+ *
+ * # Return value
+ *
+ * `true` If execution proceeded correctly, `false` if it was interrupted,
+ * that is if `it` returned `false` at any point.
+ */
pure fn all_between(s: str/&, start: uint, end: uint,
it: fn(char) -> bool) -> bool {
assert is_char_boundary(s, start);
ret true;
}
-#[doc = "
-Loop through a substring, char by char
-
-# Safety note
-
-* This function does not check whether the substring is valid.
-* This function fails if `start` or `end` do not
- represent valid positions inside `s`
-
-# Arguments
-
-* s - A string to traverse. It may be empty.
-* start - The byte offset at which to start in the string.
-* end - The end of the range to traverse
-* it - A block to execute with each consecutive character of `s`.
- Return `true` to continue, `false` to stop.
-
-# Return value
-
-`true` if `it` returns `true` for any character
-"]
+/**
+ * Loop through a substring, char by char
+ *
+ * # Safety note
+ *
+ * * This function does not check whether the substring is valid.
+ * * This function fails if `start` or `end` do not
+ * represent valid positions inside `s`
+ *
+ * # Arguments
+ *
+ * * s - A string to traverse. It may be empty.
+ * * start - The byte offset at which to start in the string.
+ * * end - The end of the range to traverse
+ * * it - A block to execute with each consecutive character of `s`.
+ * Return `true` to continue, `false` to stop.
+ *
+ * # Return value
+ *
+ * `true` if `it` returns `true` for any character
+ */
pure fn any_between(s: str/&, start: uint, end: uint,
it: fn(char) -> bool) -> bool {
!all_between(s, start, end, |c| !it(c))
const tag_six_b: uint = 252u;
-#[doc = "
-Work with the byte buffer of a string.
-
-Allows for unsafe manipulation of strings, which is useful for foreign
-interop.
-
-# Example
-
-~~~
-let i = str::as_bytes(\"Hello World\") { |bytes| vec::len(bytes) };
-~~~
-"]
+/**
+ * Work with the byte buffer of a string.
+ *
+ * Allows for unsafe manipulation of strings, which is useful for foreign
+ * interop.
+ *
+ * # Example
+ *
+ * ~~~
+ * let i = str::as_bytes("Hello World") { |bytes| vec::len(bytes) };
+ * ~~~
+ */
pure fn as_bytes<T>(s: str, f: fn(~[u8]) -> T) -> T {
unsafe {
let v: *~[u8] = ::unsafe::reinterpret_cast(ptr::addr_of(s));
}
}
-#[doc = "
-Work with the byte buffer of a string.
-
-Allows for unsafe manipulation of strings, which is useful for foreign
-interop.
-"]
+/**
+ * Work with the byte buffer of a string.
+ *
+ * Allows for unsafe manipulation of strings, which is useful for foreign
+ * interop.
+ */
pure fn as_buf<T>(s: str, f: fn(*u8) -> T) -> T {
as_bytes(s, |v| unsafe { vec::as_buf(v, f) })
}
-#[doc = "
-Work with the byte buffer of a string as a null-terminated C string.
-
-Allows for unsafe manipulation of strings, which is useful for foreign
-interop, without copying the original string.
-
-# Example
-
-~~~
-let s = str::as_buf(\"PATH\", { |path_buf| libc::getenv(path_buf) });
-~~~
-"]
+/**
+ * Work with the byte buffer of a string as a null-terminated C string.
+ *
+ * Allows for unsafe manipulation of strings, which is useful for foreign
+ * interop, without copying the original string.
+ *
+ * # Example
+ *
+ * ~~~
+ * let s = str::as_buf("PATH", { |path_buf| libc::getenv(path_buf) });
+ * ~~~
+ */
pure fn as_c_str<T>(s: str, f: fn(*libc::c_char) -> T) -> T {
as_buf(s, |buf| f(buf as *libc::c_char))
}
-#[doc = "
-Work with the byte buffer and length of a slice.
-
-The unpacked length is one byte longer than the 'official' indexable
-length of the string. This is to permit probing the byte past the
-indexable area for a null byte, as is the case in slices pointing
-to full strings, or suffixes of them.
-"]
+/**
+ * Work with the byte buffer and length of a slice.
+ *
+ * The unpacked length is one byte longer than the 'official' indexable
+ * length of the string. This is to permit probing the byte past the
+ * indexable area for a null byte, as is the case in slices pointing
+ * to full strings, or suffixes of them.
+ */
#[inline(always)]
pure fn unpack_slice<T>(s: str/&, f: fn(*u8, uint) -> T) -> T {
unsafe {
}
}
-#[doc = "
-Reserves capacity for exactly `n` bytes in the given string, not including
-the null terminator.
-
-Assuming single-byte characters, the resulting string will be large
-enough to hold a string of length `n`. To account for the null terminator,
-the underlying buffer will have the size `n` + 1.
-
-If the capacity for `s` is already equal to or greater than the requested
-capacity, then no action is taken.
-
-# Arguments
-
-* s - A string
-* n - The number of bytes to reserve space for
-"]
+/**
+ * Reserves capacity for exactly `n` bytes in the given string, not including
+ * the null terminator.
+ *
+ * Assuming single-byte characters, the resulting string will be large
+ * enough to hold a string of length `n`. To account for the null terminator,
+ * the underlying buffer will have the size `n` + 1.
+ *
+ * If the capacity for `s` is already equal to or greater than the requested
+ * capacity, then no action is taken.
+ *
+ * # Arguments
+ *
+ * * s - A string
+ * * n - The number of bytes to reserve space for
+ */
fn reserve(&s: str, n: uint) {
if capacity(s) < n {
rustrt::str_reserve_shared(s, n as size_t);
}
}
-#[doc = "
-Reserves capacity for at least `n` bytes in the given string, not including
-the null terminator.
-
-Assuming single-byte characters, the resulting string will be large
-enough to hold a string of length `n`. To account for the null terminator,
-the underlying buffer will have the size `n` + 1.
-
-This function will over-allocate in order to amortize the allocation costs
-in scenarios where the caller may need to repeatedly reserve additional
-space.
-
-If the capacity for `s` is already equal to or greater than the requested
-capacity, then no action is taken.
-
-# Arguments
-
-* s - A string
-* n - The number of bytes to reserve space for
-"]
+/**
+ * Reserves capacity for at least `n` bytes in the given string, not including
+ * the null terminator.
+ *
+ * Assuming single-byte characters, the resulting string will be large
+ * enough to hold a string of length `n`. To account for the null terminator,
+ * the underlying buffer will have the size `n` + 1.
+ *
+ * This function will over-allocate in order to amortize the allocation costs
+ * in scenarios where the caller may need to repeatedly reserve additional
+ * space.
+ *
+ * If the capacity for `s` is already equal to or greater than the requested
+ * capacity, then no action is taken.
+ *
+ * # Arguments
+ *
+ * * s - A string
+ * * n - The number of bytes to reserve space for
+ */
fn reserve_at_least(&s: str, n: uint) {
reserve(s, uint::next_power_of_two(n + 1u) - 1u)
}
-#[doc = "
-Returns the number of single-byte characters the string can hold without
-reallocating
-"]
+/**
+ * Returns the number of single-byte characters the string can hold without
+ * reallocating
+ */
pure fn capacity(&&s: str) -> uint {
do as_bytes(s) |buf| {
let vcap = vec::capacity(buf);
}
}
-#[doc = "Escape each char in `s` with char::escape_default."]
+/// Escape each char in `s` with char::escape_default.
pure fn escape_default(s: str/&) -> str {
let mut out: str = "";
unchecked {
ret out;
}
-#[doc = "Escape each char in `s` with char::escape_unicode."]
+/// Escape each char in `s` with char::escape_unicode.
pure fn escape_unicode(s: str/&) -> str {
let mut out: str = "";
unchecked {
ret out;
}
-#[doc = "Unsafe operations"]
+/// Unsafe operations
mod unsafe {
export
from_buf,
shift_byte,
set_len;
- #[doc = "Create a Rust string from a null-terminated *u8 buffer"]
+ /// Create a Rust string from a null-terminated *u8 buffer
unsafe fn from_buf(buf: *u8) -> str {
let mut curr = buf, i = 0u;
while *curr != 0u8 {
ret from_buf_len(buf, i);
}
- #[doc = "Create a Rust string from a *u8 buffer of the given length"]
+ /// Create a Rust string from a *u8 buffer of the given length
unsafe fn from_buf_len(buf: *u8, len: uint) -> str {
let mut v: ~[u8] = ~[];
vec::reserve(v, len + 1u);
ret ::unsafe::transmute(v);
}
- #[doc = "Create a Rust string from a null-terminated C string"]
+ /// Create a Rust string from a null-terminated C string
unsafe fn from_c_str(c_str: *libc::c_char) -> str {
from_buf(::unsafe::reinterpret_cast(c_str))
}
- #[doc = "
- Create a Rust string from a `*c_char` buffer of the given length
- "]
+ /// Create a Rust string from a `*c_char` buffer of the given length
unsafe fn from_c_str_len(c_str: *libc::c_char, len: uint) -> str {
from_buf_len(::unsafe::reinterpret_cast(c_str), len)
}
- #[doc = "
- Converts a vector of bytes to a string.
-
- Does not verify that the vector contains valid UTF-8.
- "]
+ /**
+ * Converts a vector of bytes to a string.
+ *
+ * Does not verify that the vector contains valid UTF-8.
+ */
unsafe fn from_bytes(+v: ~[const u8]) -> str {
unsafe {
let mut vcopy = ::unsafe::transmute(v);
}
}
- #[doc = "
- Converts a byte to a string.
-
- Does not verify that the byte is valid UTF-8.
- "]
+ /**
+ * Converts a byte to a string.
+ *
+ * Does not verify that the byte is valid UTF-8.
+ */
unsafe fn from_byte(u: u8) -> str { unsafe::from_bytes(~[u]) }
- #[doc = "
- Takes a bytewise (not UTF-8) slice from a string.
-
- Returns the substring from [`begin`..`end`).
-
- # Failure
-
- If begin is greater than end.
- If end is greater than the length of the string.
- "]
+ /**
+ * Takes a bytewise (not UTF-8) slice from a string.
+ *
+ * Returns the substring from [`begin`..`end`).
+ *
+ * # Failure
+ *
+ * If begin is greater than end.
+ * If end is greater than the length of the string.
+ */
unsafe fn slice_bytes(s: str/&, begin: uint, end: uint) -> str {
do unpack_slice(s) |sbuf, n| {
assert (begin <= end);
}
}
- #[doc = "Appends a byte to a string. (Not UTF-8 safe)."]
+ /// Appends a byte to a string. (Not UTF-8 safe).
unsafe fn push_byte(&s: str, b: u8) {
rustrt::rust_str_push(s, b);
}
- #[doc = "Appends a vector of bytes to a string. (Not UTF-8 safe)."]
+ /// Appends a vector of bytes to a string. (Not UTF-8 safe).
unsafe fn push_bytes(&s: str, bytes: ~[u8]) {
for vec::each(bytes) |byte| { rustrt::rust_str_push(s, byte); }
}
- #[doc = "
- Removes the last byte from a string and returns it. (Not UTF-8 safe).
- "]
+ /// Removes the last byte from a string and returns it. (Not UTF-8 safe).
unsafe fn pop_byte(&s: str) -> u8 {
let len = len(s);
assert (len > 0u);
ret b;
}
- #[doc = "
- Removes the first byte from a string and returns it. (Not UTF-8 safe).
- "]
+ /// Removes the first byte from a string and returns it. (Not UTF-8 safe).
unsafe fn shift_byte(&s: str) -> u8 {
let len = len(s);
assert (len > 0u);
ret b;
}
- #[doc = "
- Sets the length of the string and adds the null terminator
- "]
+ /// Sets the length of the string and adds the null terminator
unsafe fn set_len(&v: str, new_len: uint) {
let repr: *vec::unsafe::vec_repr = ::unsafe::reinterpret_cast(v);
(*repr).fill = new_len + 1u;
}
-#[doc = "Extension methods for strings"]
+/// Extension methods for strings
impl extensions for str {
- #[doc = "Returns a string with leading and trailing whitespace removed"]
+ /// Returns a string with leading and trailing whitespace removed
#[inline]
fn trim() -> str { trim(self) }
- #[doc = "Returns a string with leading whitespace removed"]
+ /// Returns a string with leading whitespace removed
#[inline]
fn trim_left() -> str { trim_left(self) }
- #[doc = "Returns a string with trailing whitespace removed"]
+ /// Returns a string with trailing whitespace removed
#[inline]
fn trim_right() -> str { trim_right(self) }
}
-#[doc = "Extension methods for strings"]
+/// Extension methods for strings
impl extensions/& for str/& {
- #[doc = "
- Return true if a predicate matches all characters or if the string
- contains no characters
- "]
+ /**
+ * Return true if a predicate matches all characters or if the string
+ * contains no characters
+ */
#[inline]
fn all(it: fn(char) -> bool) -> bool { all(self, it) }
- #[doc = "
- Return true if a predicate matches any character (and false if it
- matches none or there are no characters)
- "]
+ /**
+ * Return true if a predicate matches any character (and false if it
+ * matches none or there are no characters)
+ */
#[inline]
fn any(it: fn(char) -> bool) -> bool { any(self, it) }
- #[doc = "Returns true if one string contains another"]
+ /// Returns true if one string contains another
#[inline]
fn contains(needle: str/&a) -> bool { contains(self, needle) }
- #[doc = "Returns true if a string contains a char"]
+ /// Returns true if a string contains a char
#[inline]
fn contains_char(needle: char) -> bool { contains_char(self, needle) }
- #[doc = "Iterate over the bytes in a string"]
+ /// Iterate over the bytes in a string
#[inline]
fn each(it: fn(u8) -> bool) { each(self, it) }
- #[doc = "Iterate over the bytes in a string, with indices"]
+ /// Iterate over the bytes in a string, with indices
#[inline]
fn eachi(it: fn(uint, u8) -> bool) { eachi(self, it) }
- #[doc = "Iterate over the chars in a string"]
+ /// Iterate over the chars in a string
#[inline]
fn each_char(it: fn(char) -> bool) { each_char(self, it) }
- #[doc = "Iterate over the chars in a string, with indices"]
+ /// Iterate over the chars in a string, with indices
#[inline]
fn each_chari(it: fn(uint, char) -> bool) { each_chari(self, it) }
- #[doc = "Returns true if one string ends with another"]
+ /// Returns true if one string ends with another
#[inline]
fn ends_with(needle: str/&) -> bool { ends_with(self, needle) }
- #[doc = "Returns true if the string has length 0"]
+ /// Returns true if the string has length 0
#[inline]
fn is_empty() -> bool { is_empty(self) }
- #[doc = "Returns true if the string has length greater than 0"]
+ /// Returns true if the string has length greater than 0
#[inline]
fn is_not_empty() -> bool { is_not_empty(self) }
- #[doc = "
- Returns true if the string contains only whitespace
-
- Whitespace characters are determined by `char::is_whitespace`
- "]
+ /**
+ * Returns true if the string contains only whitespace
+ *
+ * Whitespace characters are determined by `char::is_whitespace`
+ */
#[inline]
fn is_whitespace() -> bool { is_whitespace(self) }
- #[doc = "
- Returns true if the string contains only alphanumerics
-
- Alphanumeric characters are determined by `char::is_alphanumeric`
- "]
+ /**
+ * Returns true if the string contains only alphanumerics
+ *
+ * Alphanumeric characters are determined by `char::is_alphanumeric`
+ */
#[inline]
fn is_alphanumeric() -> bool { is_alphanumeric(self) }
#[inline]
- #[doc ="Returns the size in bytes not counting the null terminator"]
+ /// Returns the size in bytes not counting the null terminator
pure fn len() -> uint { len(self) }
- #[doc = "
- Returns a slice of the given string from the byte range [`begin`..`end`)
-
- Fails when `begin` and `end` do not point to valid characters or
- beyond the last character of the string
- "]
+ /**
+ * Returns a slice of the given string from the byte range
+ * [`begin`..`end`)
+ *
+ * Fails when `begin` and `end` do not point to valid characters or
+ * beyond the last character of the string
+ */
#[inline]
fn slice(begin: uint, end: uint) -> str { slice(self, begin, end) }
- #[doc = "Splits a string into substrings using a character function"]
+ /// Splits a string into substrings using a character function
#[inline]
fn split(sepfn: fn(char) -> bool) -> ~[str] { split(self, sepfn) }
- #[doc = "
- Splits a string into substrings at each occurrence of a given character
- "]
+ /**
+ * Splits a string into substrings at each occurrence of a given character
+ */
#[inline]
fn split_char(sep: char) -> ~[str] { split_char(self, sep) }
- #[doc = "
- Splits a string into a vector of the substrings separated by a given
- string
- "]
+ /**
+ * Splits a string into a vector of the substrings separated by a given
+ * string
+ */
#[inline]
fn split_str(sep: str/&a) -> ~[str] { split_str(self, sep) }
- #[doc = "Returns true if one string starts with another"]
+ /// Returns true if one string starts with another
#[inline]
fn starts_with(needle: str/&a) -> bool { starts_with(self, needle) }
- #[doc = "
- Take a substring of another.
-
- Returns a string containing `n` characters starting at byte offset
- `begin`.
- "]
+ /**
+ * Take a substring of another.
+ *
+ * Returns a string containing `n` characters starting at byte offset
+ * `begin`.
+ */
#[inline]
fn substr(begin: uint, n: uint) -> str { substr(self, begin, n) }
- #[doc = "Convert a string to lowercase"]
+ /// Convert a string to lowercase
#[inline]
fn to_lower() -> str { to_lower(self) }
- #[doc = "Convert a string to uppercase"]
+ /// Convert a string to uppercase
#[inline]
fn to_upper() -> str { to_upper(self) }
- #[doc = "Escape each char in `s` with char::escape_default."]
+ /// Escape each char in `s` with char::escape_default.
#[inline]
fn escape_default() -> str { escape_default(self) }
- #[doc = "Escape each char in `s` with char::escape_unicode."]
+ /// Escape each char in `s` with char::escape_unicode.
#[inline]
fn escape_unicode() -> str { escape_unicode(self) }
}
-#[doc = "Misc low level stuff"];
+//! Misc low level stuff
export type_desc;
export get_type_desc;
fn min_align_of<T>() -> uint;
}
-#[doc = "
-Returns a pointer to a type descriptor.
-
-Useful for calling certain function in the Rust runtime or otherwise
-performing dark magick.
-"]
+/**
+ * Returns a pointer to a type descriptor.
+ *
+ * Useful for calling certain function in the Rust runtime or otherwise
+ * performing dark magick.
+ */
pure fn get_type_desc<T>() -> *type_desc {
unchecked { rusti::get_tydesc::<T>() as *type_desc }
}
-#[doc = "Returns the size of a type"]
+/// Returns the size of a type
#[inline(always)]
pure fn size_of<T>() -> uint {
unchecked { rusti::size_of::<T>() }
}
-#[doc = "
-Returns the ABI-required minimum alignment of a type
-
-This is the alignment used for struct fields. It may be smaller
-than the preferred alignment.
-"]
+/**
+ * Returns the ABI-required minimum alignment of a type
+ *
+ * This is the alignment used for struct fields. It may be smaller
+ * than the preferred alignment.
+ */
pure fn min_align_of<T>() -> uint {
unchecked { rusti::min_align_of::<T>() }
}
-#[doc = "Returns the preferred alignment of a type"]
+/// Returns the preferred alignment of a type
pure fn pref_align_of<T>() -> uint {
unchecked { rusti::pref_align_of::<T>() }
}
-#[doc = "Returns the refcount of a shared box (as just before calling this)"]
+/// Returns the refcount of a shared box (as just before calling this)
pure fn refcount<T>(+t: @T) -> uint {
unsafe {
let ref_ptr: *uint = unsafe::reinterpret_cast(t);
-#[doc = "
-Task management.
-
-An executing Rust program consists of a tree of tasks, each with their own
-stack, and sole ownership of their allocated heap data. Tasks communicate
-with each other using ports and channels.
-
-When a task fails, that failure will propagate to its parent (the task
-that spawned it) and the parent will fail as well. The reverse is not
-true: when a parent task fails its children will continue executing. When
-the root (main) task fails, all tasks fail, and then so does the entire
-process.
-
-Tasks may execute in parallel and are scheduled automatically by the runtime.
-
-# Example
-
-~~~
-spawn {||
- log(error, \"Hello, World!\");
-}
-~~~
-"];
+/*!
+ * Task management.
+ *
+ * An executing Rust program consists of a tree of tasks, each with their own
+ * stack, and sole ownership of their allocated heap data. Tasks communicate
+ * with each other using ports and channels.
+ *
+ * When a task fails, that failure will propagate to its parent (the task
+ * that spawned it) and the parent will fail as well. The reverse is not
+ * true: when a parent task fails its children will continue executing. When
+ * the root (main) task fails, all tasks fail, and then so does the entire
+ * process.
+ *
+ * Tasks may execute in parallel and are scheduled automatically by the
+ * runtime.
+ *
+ * # Example
+ *
+ * ~~~
+ * spawn {||
+ * log(error, "Hello, World!");
+ * }
+ * ~~~
+ */
import result::result;
import dvec::extensions;
/* Data types */
-#[doc = "A handle to a task"]
+/// A handle to a task
enum task = task_id;
-#[doc = "
-Indicates the manner in which a task exited.
-
-A task that completes without failing and whose supervised children complete
-without failing is considered to exit successfully.
-
-FIXME (See #1868): This description does not indicate the current behavior
-for linked failure.
-"]
+/**
+ * Indicates the manner in which a task exited.
+ *
+ * A task that completes without failing and whose supervised children
+ * complete without failing is considered to exit successfully.
+ *
+ * FIXME (See #1868): This description does not indicate the current behavior
+ * for linked failure.
+ */
enum task_result {
success,
failure,
}
-#[doc = "A message type for notifying of task lifecycle events"]
+/// A message type for notifying of task lifecycle events
enum notification {
- #[doc = "Sent when a task exits with the task handle and result"]
+ /// Sent when a task exits with the task handle and result
exit(task, task_result)
}
-#[doc = "Scheduler modes"]
+/// Scheduler modes
enum sched_mode {
- #[doc = "1:N -- All tasks run in the same OS thread"]
+ /// All tasks run in the same OS thread
single_threaded,
- #[doc = "M:N -- Tasks are distributed among available CPUs"]
+ /// Tasks are distributed among available CPUs
thread_per_core,
- #[doc = "N:N -- Each task runs in its own OS thread"]
+ /// Each task runs in its own OS thread
thread_per_task,
- #[doc = "?:N -- Tasks are distributed among a fixed number of OS threads"]
+ /// Tasks are distributed among a fixed number of OS threads
manual_threads(uint),
- #[doc = "
- Tasks are scheduled on the main OS thread
-
- The main OS thread is the thread used to launch the runtime which,
- in most cases, is the process's initial thread as created by the OS.
- "]
+ /**
+ * Tasks are scheduled on the main OS thread
+ *
+ * The main OS thread is the thread used to launch the runtime which,
+ * in most cases, is the process's initial thread as created by the OS.
+ */
osmain
}
-#[doc = "
-Scheduler configuration options
-
-# Fields
-
-* sched_mode - The operating mode of the scheduler
-
-* foreign_stack_size - The size of the foreign stack, in bytes
-
- Rust code runs on Rust-specific stacks. When Rust code calls foreign code
- (via functions in foreign modules) it switches to a typical, large stack
- appropriate for running code written in languages like C. By default these
- foreign stacks have unspecified size, but with this option their size can
- be precisely specified.
-"]
+/**
+ * Scheduler configuration options
+ *
+ * # Fields
+ *
+ * * sched_mode - The operating mode of the scheduler
+ *
+ * * foreign_stack_size - The size of the foreign stack, in bytes
+ *
+ * Rust code runs on Rust-specific stacks. When Rust code calls foreign
+ * code (via functions in foreign modules) it switches to a typical, large
+ * stack appropriate for running code written in languages like C. By
+ * default these foreign stacks have unspecified size, but with this
+ * option their size can be precisely specified.
+ */
type sched_opts = {
mode: sched_mode,
foreign_stack_size: option<uint>
};
-#[doc = "
-Task configuration options
-
-# Fields
-
-* supervise - Do not propagate failure to the parent task
-
- All tasks are linked together via a tree, from parents to children. By
- default children are 'supervised' by their parent and when they fail
- so too will their parents. Settings this flag to false disables that
- behavior.
-
-* notify_chan - Enable lifecycle notifications on the given channel
-
-* sched - Specify the configuration of a new scheduler to create the task in
-
- By default, every task is created in the same scheduler as its
- parent, where it is scheduled cooperatively with all other tasks
- in that scheduler. Some specialized applications may want more
- control over their scheduling, in which case they can be spawned
- into a new scheduler with the specific properties required.
-
- This is of particular importance for libraries which want to call
- into foreign code that blocks. Without doing so in a different
- scheduler other tasks will be impeded or even blocked indefinitely.
-
-"]
+/**
+ * Task configuration options
+ *
+ * # Fields
+ *
+ * * supervise - Do not propagate failure to the parent task
+ *
+ * All tasks are linked together via a tree, from parents to children. By
+ * default children are 'supervised' by their parent and when they fail
+ * so too will their parents. Settings this flag to false disables that
+ * behavior.
+ *
+ * * notify_chan - Enable lifecycle notifications on the given channel
+ *
+ * * sched - Specify the configuration of a new scheduler to create the task
+ * in
+ *
+ * By default, every task is created in the same scheduler as its
+ * parent, where it is scheduled cooperatively with all other tasks
+ * in that scheduler. Some specialized applications may want more
+ * control over their scheduling, in which case they can be spawned
+ * into a new scheduler with the specific properties required.
+ *
+ * This is of particular importance for libraries which want to call
+ * into foreign code that blocks. Without doing so in a different
+ * scheduler other tasks will be impeded or even blocked indefinitely.
+ */
type task_opts = {
supervise: bool,
notify_chan: option<comm::chan<notification>>,
sched: option<sched_opts>,
};
-#[doc = "
-The task builder type.
-
-Provides detailed control over the properties and behavior of new tasks.
-"]
+/**
+ * The task builder type.
+ *
+ * Provides detailed control over the properties and behavior of new tasks.
+ */
// NB: Builders are designed to be single-use because they do stateful
// things that get weird when reusing - e.g. if you create a result future
// it only applies to a single task, so then you have to maintain some
/* Task construction */
fn default_task_opts() -> task_opts {
- #[doc = "
- The default task options
-
- By default all tasks are supervised by their parent, are spawned
- into the same scheduler, and do not post lifecycle notifications.
- "];
+ /*!
+ * The default task options
+ *
+ * By default all tasks are supervised by their parent, are spawned
+ * into the same scheduler, and do not post lifecycle notifications.
+ */
{
supervise: true,
}
fn builder() -> builder {
- #[doc = "Construct a builder"];
+ //! Construct a builder
let body_identity = fn@(+body: fn~()) -> fn~() { body };
}
fn get_opts(builder: builder) -> task_opts {
- #[doc = "Get the task_opts associated with a builder"];
+ //! Get the task_opts associated with a builder
builder.opts
}
fn set_opts(builder: builder, opts: task_opts) {
- #[doc = "
- Set the task_opts associated with a builder
-
- To update a single option use a pattern like the following:
-
- set_opts(builder, {
- supervise: false
- with get_opts(builder)
- });
- "];
+ /*!
+ * Set the task_opts associated with a builder
+ *
+ * To update a single option use a pattern like the following:
+ *
+ * set_opts(builder, {
+ * supervise: false
+ * with get_opts(builder)
+ * });
+ */
builder.opts = opts;
}
fn add_wrapper(builder: builder, gen_body: fn@(+fn~()) -> fn~()) {
- #[doc = "
- Add a wrapper to the body of the spawned task.
-
- Before the task is spawned it is passed through a 'body generator'
- function that may perform local setup operations as well as wrap
- the task body in remote setup operations. With this the behavior
- of tasks can be extended in simple ways.
-
- This function augments the current body generator with a new body
- generator by applying the task body which results from the
- existing body generator to the new body generator.
- "];
+ /*!
+ * Add a wrapper to the body of the spawned task.
+ *
+ * Before the task is spawned it is passed through a 'body generator'
+ * function that may perform local setup operations as well as wrap
+ * the task body in remote setup operations. With this the behavior
+ * of tasks can be extended in simple ways.
+ *
+ * This function augments the current body generator with a new body
+ * generator by applying the task body which results from the
+ * existing body generator to the new body generator.
+ */
let prev_gen_body = builder.gen_body;
builder.gen_body = fn@(+body: fn~()) -> fn~() {
}
fn run(-builder: builder, +f: fn~()) {
- #[doc = "
- Creates and exucutes a new child task
-
- Sets up a new task with its own call stack and schedules it to run
- the provided unique closure. The task has the properties and behavior
- specified by `builder`.
-
- # Failure
-
- When spawning into a new scheduler, the number of threads requested
- must be greater than zero.
- "];
+ /*!
+ * Creates and exucutes a new child task
+ *
+ * Sets up a new task with its own call stack and schedules it to run
+ * the provided unique closure. The task has the properties and behavior
+ * specified by `builder`.
+ *
+ * # Failure
+ *
+ * When spawning into a new scheduler, the number of threads requested
+ * must be greater than zero.
+ */
let body = builder.gen_body(f);
spawn_raw(builder.opts, body);
/* Builder convenience functions */
fn future_result(builder: builder) -> future::future<task_result> {
- #[doc = "
- Get a future representing the exit status of the task.
-
- Taking the value of the future will block until the child task terminates.
-
- Note that the future returning by this function is only useful for
- obtaining the value of the next task to be spawning with the
- builder. If additional tasks are spawned with the same builder
- then a new result future must be obtained prior to spawning each
- task.
- "];
+ /*!
+ * Get a future representing the exit status of the task.
+ *
+ * Taking the value of the future will block until the child task
+ * terminates.
+ *
+ * Note that the future returning by this function is only useful for
+ * obtaining the value of the next task to be spawning with the
+ * builder. If additional tasks are spawned with the same builder
+ * then a new result future must be obtained prior to spawning each
+ * task.
+ */
// FIXME (#1087, #1857): Once linked failure and notification are
// handled in the library, I can imagine implementing this by just
}
fn future_task(builder: builder) -> future::future<task> {
- #[doc = "Get a future representing the handle to the new task"];
+ //! Get a future representing the handle to the new task
let mut po = comm::port();
let ch = comm::chan(po);
}
fn unsupervise(builder: builder) {
- #[doc = "Configures the new task to not propagate failure to its parent"];
+ //! Configures the new task to not propagate failure to its parent
set_opts(builder, {
supervise: false
fn run_listener<A:send>(-builder: builder,
+f: fn~(comm::port<A>)) -> comm::chan<A> {
- #[doc = "
- Runs a new task while providing a channel from the parent to the child
-
- Sets up a communication channel from the current task to the new
- child task, passes the port to child's body, and returns a channel
- linked to the port to the parent.
-
- This encapsulates some boilerplate handshaking logic that would
- otherwise be required to establish communication from the parent
- to the child.
- "];
+ /*!
+ * Runs a new task while providing a channel from the parent to the child
+ *
+ * Sets up a communication channel from the current task to the new
+ * child task, passes the port to child's body, and returns a channel
+ * linked to the port to the parent.
+ *
+ * This encapsulates some boilerplate handshaking logic that would
+ * otherwise be required to establish communication from the parent
+ * to the child.
+ */
let setup_po = comm::port();
let setup_ch = comm::chan(setup_po);
/* Spawn convenience functions */
fn spawn(+f: fn~()) {
- #[doc = "
- Creates and executes a new child task
-
- Sets up a new task with its own call stack and schedules it to run
- the provided unique closure.
-
- This function is equivalent to `run(new_builder(), f)`.
- "];
+ /*!
+ * Creates and executes a new child task
+ *
+ * Sets up a new task with its own call stack and schedules it to run
+ * the provided unique closure.
+ *
+ * This function is equivalent to `run(new_builder(), f)`.
+ */
run(builder(), f);
}
fn spawn_listener<A:send>(+f: fn~(comm::port<A>)) -> comm::chan<A> {
- #[doc = "
- Runs a new task while providing a channel from the parent to the child
-
- Sets up a communication channel from the current task to the new
- child task, passes the port to child's body, and returns a channel
- linked to the port to the parent.
-
- This encapsulates some boilerplate handshaking logic that would
- otherwise be required to establish communication from the parent
- to the child.
-
- The simplest way to establish bidirectional communication between
- a parent in child is as follows:
-
- let po = comm::port();
- let ch = comm::chan(po);
- let ch = spawn_listener {|po|
- // Now the child has a port called 'po' to read from and
- // an environment-captured channel called 'ch'.
- };
- // Likewise, the parent has both a 'po' and 'ch'
-
- This function is equivalent to `run_listener(builder(), f)`.
- "];
+ /*!
+ * Runs a new task while providing a channel from the parent to the child
+ *
+ * Sets up a communication channel from the current task to the new
+ * child task, passes the port to child's body, and returns a channel
+ * linked to the port to the parent.
+ *
+ * This encapsulates some boilerplate handshaking logic that would
+ * otherwise be required to establish communication from the parent
+ * to the child.
+ *
+ * The simplest way to establish bidirectional communication between
+ * a parent in child is as follows:
+ *
+ * let po = comm::port();
+ * let ch = comm::chan(po);
+ * let ch = spawn_listener {|po|
+ * // Now the child has a port called 'po' to read from and
+ * // an environment-captured channel called 'ch'.
+ * };
+ * // Likewise, the parent has both a 'po' and 'ch'
+ *
+ * This function is equivalent to `run_listener(builder(), f)`.
+ */
run_listener(builder(), f)
}
fn spawn_sched(mode: sched_mode, +f: fn~()) {
- #[doc = "
- Creates a new scheduler and executes a task on it
-
- Tasks subsequently spawned by that task will also execute on
- the new scheduler. When there are no more tasks to execute the
- scheduler terminates.
-
- # Failure
-
- In manual threads mode the number of threads requested must be
- greater than zero.
- "];
+ /*!
+ * Creates a new scheduler and executes a task on it
+ *
+ * Tasks subsequently spawned by that task will also execute on
+ * the new scheduler. When there are no more tasks to execute the
+ * scheduler terminates.
+ *
+ * # Failure
+ *
+ * In manual threads mode the number of threads requested must be
+ * greater than zero.
+ */
let mut builder = builder();
set_opts(builder, {
}
fn try<T:send>(+f: fn~() -> T) -> result<T,()> {
- #[doc = "
- Execute a function in another task and return either the return value
- of the function or result::err.
-
- # Return value
-
- If the function executed successfully then try returns result::ok
- containing the value returned by the function. If the function fails
- then try returns result::err containing nil.
- "];
+ /*!
+ * Execute a function in another task and return either the return value
+ * of the function or result::err.
+ *
+ * # Return value
+ *
+ * If the function executed successfully then try returns result::ok
+ * containing the value returned by the function. If the function fails
+ * then try returns result::err containing nil.
+ */
let po = comm::port();
let ch = comm::chan(po);
/* Lifecycle functions */
fn yield() {
- #[doc = "Yield control to the task scheduler"];
+ //! Yield control to the task scheduler
let task_ = rustrt::rust_get_task();
let mut killed = false;
}
fn failing() -> bool {
- #[doc = "True if the running task has failed"];
+ //! True if the running task has failed
rustrt::rust_task_is_unwinding(rustrt::rust_get_task())
}
fn get_task() -> task {
- #[doc = "Get a handle to the running task"];
+ //! Get a handle to the running task
task(rustrt::get_task_id())
}
-#[doc = "
-Temporarily make the task unkillable
-
-# Example
-
- task::unkillable {||
- // detach / yield / destroy must all be called together
- rustrt::rust_port_detach(po);
- // This must not result in the current task being killed
- task::yield();
- rustrt::rust_port_destroy(po);
- }
-
-"]
+/**
+ * Temporarily make the task unkillable
+ *
+ * # Example
+ *
+ * task::unkillable {||
+ * // detach / yield / destroy must all be called together
+ * rustrt::rust_port_detach(po);
+ * // This must not result in the current task being killed
+ * task::yield();
+ * rustrt::rust_port_destroy(po);
+ * }
+ */
unsafe fn unkillable(f: fn()) {
class allow_failure {
let i: (); // since a class must have at least one field
* Casting 'Arcane Sight' reveals an overwhelming aura of Transmutation magic.
****************************************************************************/
-#[doc = "Indexes a task-local data slot. The function itself is used to
-automatically finalise stored values; also, its code pointer is used for
-comparison. Recommended use is to write an empty function for each desired
-task-local data slot (and use class destructors, instead of code inside the
-finaliser, if specific teardown is needed). DO NOT use multiple instantiations
-of a single polymorphic function to index data of different types; arbitrary
-type coercion is possible this way. The interface is safe as long as all key
-functions are monomorphic."]
+/**
+ * Indexes a task-local data slot. The function itself is used to
+ * automatically finalise stored values; also, its code pointer is used for
+ * comparison. Recommended use is to write an empty function for each desired
+ * task-local data slot (and use class destructors, instead of code inside the
+ * finaliser, if specific teardown is needed). DO NOT use multiple
+ * instantiations of a single polymorphic function to index data of different
+ * types; arbitrary type coercion is possible this way. The interface is safe
+ * as long as all key functions are monomorphic.
+ */
type local_data_key<T> = fn@(+@T);
// We use dvec because it's the best data structure in core. If TLS is used
}
/* Exported interface for task-local data (plus local_data_key above). */
-#[doc = "Remove a task-local data value from the table, returning the
-reference that was originally created to insert it."]
+/**
+ * Remove a task-local data value from the table, returning the
+ * reference that was originally created to insert it.
+ */
unsafe fn local_data_pop<T>(key: local_data_key<T>) -> option<@T> {
local_pop(rustrt::rust_get_task(), key)
}
-#[doc = "Retrieve a task-local data value. It will also be kept alive in the
-table until explicitly removed."]
+/**
+ * Retrieve a task-local data value. It will also be kept alive in the
+ * table until explicitly removed.
+ */
unsafe fn local_data_get<T>(key: local_data_key<T>) -> option<@T> {
local_get(rustrt::rust_get_task(), key)
}
-#[doc = "Store a value in task-local data. If this key already has a value,
-that value is overwritten (and its destructor is run)."]
+/**
+ * Store a value in task-local data. If this key already has a value,
+ * that value is overwritten (and its destructor is run).
+ */
unsafe fn local_data_set<T>(key: local_data_key<T>, -data: @T) {
local_set(rustrt::rust_get_task(), key, data)
}
-#[doc = "Modify a task-local data value. If the function returns 'none', the
-data is removed (and its reference dropped)."]
+/**
+ * Modify a task-local data value. If the function returns 'none', the
+ * data is removed (and its reference dropped).
+ */
unsafe fn local_data_modify<T>(key: local_data_key<T>,
modify_fn: fn(option<@T>) -> option<@T>) {
local_modify(rustrt::rust_get_task(), key, modify_fn)
-#[doc = "Operations on tuples"];
+//! Operations on tuples
-#[doc = "Return the first element of a pair"]
+/// Return the first element of a pair
pure fn first<T:copy, U:copy>(pair: (T, U)) -> T {
let (t, _) = pair;
ret t;
}
-#[doc = "Return the second element of a pair"]
+/// Return the second element of a pair
pure fn second<T:copy, U:copy>(pair: (T, U)) -> U {
let (_, u) = pair;
ret u;
}
-#[doc = "Return the results of swapping the two elements of a pair"]
+/// Return the results of swapping the two elements of a pair
pure fn swap<T:copy, U:copy>(pair: (T, U)) -> (U, T) {
let (t, u) = pair;
ret (u, t);
pure fn is_nonnegative(x: T) -> bool { x >= 0 as T }
#[inline(always)]
-#[doc = "Iterate over the range [`lo`..`hi`)"]
+/// Iterate over the range [`lo`..`hi`)
fn range(lo: T, hi: T, it: fn(T) -> bool) {
let mut i = lo;
while i < hi {
}
}
-#[doc = "Computes the bitwise complement"]
+/// Computes the bitwise complement
pure fn compl(i: T) -> T {
max_value ^ i
}
fn from_int(n: int) -> T { ret n as T; }
}
-#[doc = "
-Parse a buffer of bytes
-
-# Arguments
-
-* buf - A byte buffer
-* radix - The base of the number
-
-# Failure
-
-`buf` must not be empty
-"]
+/**
+ * Parse a buffer of bytes
+ *
+ * # Arguments
+ *
+ * * buf - A byte buffer
+ * * radix - The base of the number
+ *
+ * # Failure
+ *
+ * `buf` must not be empty
+ */
fn parse_buf(buf: ~[u8], radix: uint) -> option<T> {
if vec::len(buf) == 0u { ret none; }
let mut i = vec::len(buf) - 1u;
};
}
-#[doc = "Parse a string to an int"]
+/// Parse a string to an int
fn from_str(s: str) -> option<T> { parse_buf(str::bytes(s), 10u) }
-#[doc = "Parse a string as an unsigned integer."]
+/// Parse a string as an unsigned integer.
fn from_str_radix(buf: str, radix: u64) -> option<u64> {
if str::len(buf) == 0u { ret none; }
let mut i = str::len(buf) - 1u;
};
}
-#[doc = "
-Convert to a string in a given base
-
-# Failure
-
-Fails if `radix` < 2 or `radix` > 16
-"]
+/**
+ * Convert to a string in a given base
+ *
+ * # Failure
+ *
+ * Fails if `radix` < 2 or `radix` > 16
+ */
fn to_str(num: T, radix: uint) -> str {
do to_str_bytes(false, num, radix) |slice| {
do vec::unpack_slice(slice) |p, len| {
}
}
-#[doc = "Low-level helper routine for string conversion."]
+/// Low-level helper routine for string conversion.
fn to_str_bytes<U>(neg: bool, num: T, radix: uint,
f: fn(v: &[u8]) -> U) -> U {
}
}
-#[doc = "Convert to a string"]
+/// Convert to a string
fn str(i: T) -> str { ret to_str(i, 10u); }
#[test]
type T = uint;
-#[doc = "
-Divide two numbers, return the result, rounded up.
-
-# Arguments
-
-* x - an integer
-* y - an integer distinct from 0u
-
-# Return value
-
-The smallest integer `q` such that `x/y <= q`.
-"]
+/**
+ * Divide two numbers, return the result, rounded up.
+ *
+ * # Arguments
+ *
+ * * x - an integer
+ * * y - an integer distinct from 0u
+ *
+ * # Return value
+ *
+ * The smallest integer `q` such that `x/y <= q`.
+ */
pure fn div_ceil(x: uint, y: uint) -> uint {
let div = div(x, y);
if x % y == 0u { ret div;}
else { ret div + 1u; }
}
-#[doc = "
-Divide two numbers, return the result, rounded to the closest integer.
-
-# Arguments
-
-* x - an integer
-* y - an integer distinct from 0u
-
-# Return value
-
-The integer `q` closest to `x/y`.
-"]
+/**
+ * Divide two numbers, return the result, rounded to the closest integer.
+ *
+ * # Arguments
+ *
+ * * x - an integer
+ * * y - an integer distinct from 0u
+ *
+ * # Return value
+ *
+ * The integer `q` closest to `x/y`.
+ */
pure fn div_round(x: uint, y: uint) -> uint {
let div = div(x, y);
if x % y * 2u < y { ret div;}
else { ret div + 1u; }
}
-#[doc = "
-Divide two numbers, return the result, rounded down.
-
-Note: This is the same function as `div`.
-
-# Arguments
-
-* x - an integer
-* y - an integer distinct from 0u
-
-# Return value
-
-The smallest integer `q` such that `x/y <= q`. This
-is either `x/y` or `x/y + 1`.
-"]
+/**
+ * Divide two numbers, return the result, rounded down.
+ *
+ * Note: This is the same function as `div`.
+ *
+ * # Arguments
+ *
+ * * x - an integer
+ * * y - an integer distinct from 0u
+ *
+ * # Return value
+ *
+ * The smallest integer `q` such that `x/y <= q`. This
+ * is either `x/y` or `x/y + 1`.
+ */
pure fn div_floor(x: uint, y: uint) -> uint { ret x / y; }
-#[doc = "Produce a uint suitable for use in a hash table"]
+/// Produce a uint suitable for use in a hash table
pure fn hash(&&x: uint) -> uint { ret x; }
-#[doc = "
-Iterate over the range [`lo`..`hi`), or stop when requested
-
-# Arguments
-
-* lo - The integer at which to start the loop (included)
-* hi - The integer at which to stop the loop (excluded)
-* it - A block to execute with each consecutive integer of the range.
- Return `true` to continue, `false` to stop.
-
-# Return value
-
-`true` If execution proceeded correctly, `false` if it was interrupted,
-that is if `it` returned `false` at any point.
-"]
+/**
+ * Iterate over the range [`lo`..`hi`), or stop when requested
+ *
+ * # Arguments
+ *
+ * * lo - The integer at which to start the loop (included)
+ * * hi - The integer at which to stop the loop (excluded)
+ * * it - A block to execute with each consecutive integer of the range.
+ * Return `true` to continue, `false` to stop.
+ *
+ * # Return value
+ *
+ * `true` If execution proceeded correctly, `false` if it was interrupted,
+ * that is if `it` returned `false` at any point.
+ */
fn iterate(lo: uint, hi: uint, it: fn(uint) -> bool) -> bool {
let mut i = lo;
while i < hi {
ret true;
}
-#[doc = "Returns the smallest power of 2 greater than or equal to `n`"]
+/// Returns the smallest power of 2 greater than or equal to `n`
#[inline(always)]
fn next_power_of_two(n: uint) -> uint {
let halfbits: uint = sys::size_of::<uint>() * 4u;
}
mod derived_property {
- #[doc = "Check if a character has the alphabetic unicode property"]
+ /// Check if a character has the alphabetic unicode property
pure fn Alphabetic(c: char) -> bool {
ret alt c {
'\x41' to '\x5a'
-#[doc = "Unsafe operations"];
+//! Unsafe operations
export reinterpret_cast, forget, bump_box_refcount, transmute;
fn reinterpret_cast<T, U>(e: T) -> U;
}
-#[doc = "
-Casts the value at `src` to U. The two types must have the same length.
-"]
+/// Casts the value at `src` to U. The two types must have the same length.
#[inline(always)]
unsafe fn reinterpret_cast<T, U>(src: T) -> U {
rusti::reinterpret_cast(src)
}
-#[doc ="
-Move a thing into the void
-
-The forget function will take ownership of the provided value but neglect
-to run any required cleanup or memory-management operations on it. This
-can be used for various acts of magick, particularly when using
-reinterpret_cast on managed pointer types.
-"]
+/**
+ * Move a thing into the void
+ *
+ * The forget function will take ownership of the provided value but neglect
+ * to run any required cleanup or memory-management operations on it. This
+ * can be used for various acts of magick, particularly when using
+ * reinterpret_cast on managed pointer types.
+ */
#[inline(always)]
unsafe fn forget<T>(-thing: T) { rusti::forget(thing); }
-#[doc = "Force-increment the reference count on a shared box. If used
-uncarefully, this can leak the box. Use this in conjunction with transmute
-and/or reinterpret_cast when such calls would otherwise scramble a box's
-reference count"]
+/**
+ * Force-increment the reference count on a shared box. If used
+ * uncarefully, this can leak the box. Use this in conjunction with transmute
+ * and/or reinterpret_cast when such calls would otherwise scramble a box's
+ * reference count
+ */
unsafe fn bump_box_refcount<T>(+t: @T) { forget(t); }
-#[doc = "
-Transform a value of one type into a value of another type.
-Both types must have the same size and alignment.
-
-# Example
-
- assert transmute(\"L\") == [76u8, 0u8]/~;
-"]
+/**
+ * Transform a value of one type into a value of another type.
+ * Both types must have the same size and alignment.
+ *
+ * # Example
+ *
+ * assert transmute("L") == [76u8, 0u8]/~;
+ */
unsafe fn transmute<L, G>(-thing: L) -> G {
let newthing = reinterpret_cast(thing);
forget(thing);
-#[doc = "Vectors"];
+//! Vectors
import option::{some, none};
import ptr::addr_of;
fn move_val_init<T>(&dst: T, -src: T);
}
-#[doc = "A function used to initialize the elements of a vector"]
+/// A function used to initialize the elements of a vector
type init_op<T> = fn(uint) -> T;
-#[doc = "Returns true if a vector contains no elements"]
+/// Returns true if a vector contains no elements
pure fn is_empty<T>(v: &[const T]) -> bool {
unpack_const_slice(v, |_p, len| len == 0u)
}
-#[doc = "Returns true if a vector contains some elements"]
+/// Returns true if a vector contains some elements
pure fn is_not_empty<T>(v: &[const T]) -> bool {
unpack_const_slice(v, |_p, len| len > 0u)
}
-#[doc = "Returns true if two vectors have the same length"]
+/// Returns true if two vectors have the same length
pure fn same_length<T, U>(xs: &[const T], ys: &[const U]) -> bool {
len(xs) == len(ys)
}
-#[doc = "
-Reserves capacity for exactly `n` elements in the given vector.
-
-If the capacity for `v` is already equal to or greater than the requested
-capacity, then no action is taken.
-
-# Arguments
-
-* v - A vector
-* n - The number of elements to reserve space for
-"]
+/**
+ * Reserves capacity for exactly `n` elements in the given vector.
+ *
+ * If the capacity for `v` is already equal to or greater than the requested
+ * capacity, then no action is taken.
+ *
+ * # Arguments
+ *
+ * * v - A vector
+ * * n - The number of elements to reserve space for
+ */
fn reserve<T>(&v: ~[const T], n: uint) {
// Only make the (slow) call into the runtime if we have to
if capacity(v) < n {
}
}
-#[doc = "
-Reserves capacity for at least `n` elements in the given vector.
-
-This function will over-allocate in order to amortize the allocation costs
-in scenarios where the caller may need to repeatedly reserve additional
-space.
-
-If the capacity for `v` is already equal to or greater than the requested
-capacity, then no action is taken.
-
-# Arguments
-
-* v - A vector
-* n - The number of elements to reserve space for
-"]
+/**
+ * Reserves capacity for at least `n` elements in the given vector.
+ *
+ * This function will over-allocate in order to amortize the allocation costs
+ * in scenarios where the caller may need to repeatedly reserve additional
+ * space.
+ *
+ * If the capacity for `v` is already equal to or greater than the requested
+ * capacity, then no action is taken.
+ *
+ * # Arguments
+ *
+ * * v - A vector
+ * * n - The number of elements to reserve space for
+ */
fn reserve_at_least<T>(&v: ~[const T], n: uint) {
reserve(v, uint::next_power_of_two(n));
}
-#[doc = "
-Returns the number of elements the vector can hold without reallocating
-"]
+/// Returns the number of elements the vector can hold without reallocating
#[inline(always)]
pure fn capacity<T>(&&v: ~[const T]) -> uint {
unsafe {
}
}
-#[doc = "Returns the length of a vector"]
+/// Returns the length of a vector
#[inline(always)]
pure fn len<T>(&&v: &[const T]) -> uint {
unpack_const_slice(v, |_p, len| len)
}
-#[doc = "
-Creates and initializes an immutable vector.
-
-Creates an immutable vector of size `n_elts` and initializes the elements
-to the value returned by the function `op`.
-"]
+/**
+ * Creates and initializes an immutable vector.
+ *
+ * Creates an immutable vector of size `n_elts` and initializes the elements
+ * to the value returned by the function `op`.
+ */
pure fn from_fn<T>(n_elts: uint, op: init_op<T>) -> ~[T] {
let mut v = ~[];
unchecked{reserve(v, n_elts);}
ret v;
}
-#[doc = "
-Creates and initializes an immutable vector.
-
-Creates an immutable vector of size `n_elts` and initializes the elements
-to the value `t`.
-"]
+/**
+ * Creates and initializes an immutable vector.
+ *
+ * Creates an immutable vector of size `n_elts` and initializes the elements
+ * to the value `t`.
+ */
pure fn from_elem<T: copy>(n_elts: uint, t: T) -> ~[T] {
let mut v = ~[];
unchecked{reserve(v, n_elts)}
ret v;
}
-#[doc = "Produces a mut vector from an immutable vector."]
+/// Produces a mut vector from an immutable vector.
fn to_mut<T>(+v: ~[T]) -> ~[mut T] {
unsafe { ::unsafe::transmute(v) }
}
-#[doc = "Produces an immutable vector from a mut vector."]
+/// Produces an immutable vector from a mut vector.
fn from_mut<T>(+v: ~[mut T]) -> ~[T] {
unsafe { ::unsafe::transmute(v) }
}
// Accessors
-#[doc = "Returns the first element of a vector"]
+/// Returns the first element of a vector
pure fn head<T: copy>(v: &[const T]) -> T { v[0] }
-#[doc = "Returns a vector containing all but the first element of a slice"]
+/// Returns a vector containing all but the first element of a slice
pure fn tail<T: copy>(v: &[const T]) -> ~[T] {
ret slice(v, 1u, len(v));
}
-#[doc = "Returns a vector containing all but the first `n` \
- elements of a slice"]
+/**
+ * Returns a vector containing all but the first `n` \
+ * elements of a slice
+ */
pure fn tailn<T: copy>(v: &[const T], n: uint) -> ~[T] {
slice(v, n, len(v))
}
-#[doc = "Returns a vector containing all but the last element of a slice"]
+/// Returns a vector containing all but the last element of a slice
pure fn init<T: copy>(v: &[const T]) -> ~[T] {
assert len(v) != 0u;
slice(v, 0u, len(v) - 1u)
}
-#[doc = "
-Returns the last element of the slice `v`, failing if the slice is empty.
-"]
+/// Returns the last element of the slice `v`, failing if the slice is empty.
pure fn last<T: copy>(v: &[const T]) -> T {
if len(v) == 0u { fail "last_unsafe: empty vector" }
v[len(v) - 1u]
}
-#[doc = "
-Returns `some(x)` where `x` is the last element of the slice `v`,
-or `none` if the vector is empty.
-"]
+/**
+ * Returns `some(x)` where `x` is the last element of the slice `v`,
+ * or `none` if the vector is empty.
+ */
pure fn last_opt<T: copy>(v: &[const T]) -> option<T> {
if len(v) == 0u { ret none; }
some(v[len(v) - 1u])
}
-#[doc = "Returns a copy of the elements from [`start`..`end`) from `v`."]
+/// Returns a copy of the elements from [`start`..`end`) from `v`.
pure fn slice<T: copy>(v: &[const T], start: uint, end: uint) -> ~[T] {
assert (start <= end);
assert (end <= len(v));
ret result;
}
-#[doc = "Return a slice that points into another slice."]
+/// Return a slice that points into another slice.
pure fn view<T: copy>(v: &[const T], start: uint, end: uint) -> &a.[T] {
assert (start <= end);
assert (end <= len(v));
}
}
-#[doc = "
-Split the vector `v` by applying each element against the predicate `f`.
-"]
+/// Split the vector `v` by applying each element against the predicate `f`.
fn split<T: copy>(v: &[T], f: fn(T) -> bool) -> ~[~[T]] {
let ln = len(v);
if (ln == 0u) { ret ~[] }
result
}
-#[doc = "
-Split the vector `v` by applying each element against the predicate `f` up
-to `n` times.
-"]
+/**
+ * Split the vector `v` by applying each element against the predicate `f` up
+ * to `n` times.
+ */
fn splitn<T: copy>(v: &[T], n: uint, f: fn(T) -> bool) -> ~[~[T]] {
let ln = len(v);
if (ln == 0u) { ret ~[] }
result
}
-#[doc = "
-Reverse split the vector `v` by applying each element against the predicate
-`f`.
-"]
+/**
+ * Reverse split the vector `v` by applying each element against the predicate
+ * `f`.
+ */
fn rsplit<T: copy>(v: &[T], f: fn(T) -> bool) -> ~[~[T]] {
let ln = len(v);
if (ln == 0u) { ret ~[] }
reversed(result)
}
-#[doc = "
-Reverse split the vector `v` by applying each element against the predicate
-`f` up to `n times.
-"]
+/**
+ * Reverse split the vector `v` by applying each element against the predicate
+ * `f` up to `n times.
+ */
fn rsplitn<T: copy>(v: &[T], n: uint, f: fn(T) -> bool) -> ~[~[T]] {
let ln = len(v);
if (ln == 0u) { ret ~[] }
// Mutators
-#[doc = "Removes the first element from a vector and return it"]
+/// Removes the first element from a vector and return it
fn shift<T>(&v: ~[T]) -> T {
let ln = len::<T>(v);
assert (ln > 0u);
}
}
-#[doc = "Prepend an element to the vector"]
+/// Prepend an element to the vector
fn unshift<T>(&v: ~[T], +x: T) {
let mut vv = ~[x];
v <-> vv;
}
}
-#[doc = "Remove the last element from a vector and return it"]
+/// Remove the last element from a vector and return it
fn pop<T>(&v: ~[const T]) -> T {
let ln = len(v);
assert ln > 0u;
}
}
-#[doc = "Append an element to a vector"]
+/// Append an element to a vector
#[inline(always)]
fn push<T>(&v: ~[const T], +initval: T) {
unsafe {
ret v;
}
-#[doc = "
-Expands a vector in place, initializing the new elements to a given value
-
-# Arguments
-
-* v - The vector to grow
-* n - The number of elements to add
-* initval - The value for the new elements
-"]
+/**
+ * Expands a vector in place, initializing the new elements to a given value
+ *
+ * # Arguments
+ *
+ * * v - The vector to grow
+ * * n - The number of elements to add
+ * * initval - The value for the new elements
+ */
fn grow<T: copy>(&v: ~[const T], n: uint, initval: T) {
reserve_at_least(v, len(v) + n);
let mut i: uint = 0u;
while i < n { push(v, initval); i += 1u; }
}
-#[doc = "
-Expands a vector in place, initializing the new elements to the result of
-a function
-
-Function `init_op` is called `n` times with the values [0..`n`)
-
-# Arguments
-
-* v - The vector to grow
-* n - The number of elements to add
-* init_op - A function to call to retreive each appended element's
- value
-"]
+/**
+ * Expands a vector in place, initializing the new elements to the result of
+ * a function
+ *
+ * Function `init_op` is called `n` times with the values [0..`n`)
+ *
+ * # Arguments
+ *
+ * * v - The vector to grow
+ * * n - The number of elements to add
+ * * init_op - A function to call to retreive each appended element's
+ * value
+ */
fn grow_fn<T>(&v: ~[const T], n: uint, op: init_op<T>) {
reserve_at_least(v, len(v) + n);
let mut i: uint = 0u;
while i < n { push(v, op(i)); i += 1u; }
}
-#[doc = "
-Sets the value of a vector element at a given index, growing the vector as
-needed
-
-Sets the element at position `index` to `val`. If `index` is past the end
-of the vector, expands the vector by replicating `initval` to fill the
-intervening space.
-"]
+/**
+ * Sets the value of a vector element at a given index, growing the vector as
+ * needed
+ *
+ * Sets the element at position `index` to `val`. If `index` is past the end
+ * of the vector, expands the vector by replicating `initval` to fill the
+ * intervening space.
+ */
#[inline(always)]
fn grow_set<T: copy>(&v: ~[mut T], index: uint, initval: T, val: T) {
if index >= len(v) { grow(v, index - len(v) + 1u, initval); }
// Functional utilities
-#[doc = "
-Apply a function to each element of a vector and return the results
-"]
+/// Apply a function to each element of a vector and return the results
pure fn map<T, U>(v: &[T], f: fn(T) -> U) -> ~[U] {
let mut result = ~[];
unchecked{reserve(result, len(v));}
ret result;
}
-#[doc = "
-Apply a function to each element of a vector and return the results
-"]
+/// Apply a function to each element of a vector and return the results
pure fn mapi<T, U>(v: &[T], f: fn(uint, T) -> U) -> ~[U] {
let mut result = ~[];
unchecked{reserve(result, len(v));}
ret result;
}
-#[doc = "
-Apply a function to each element of a vector and return a concatenation
-of each result vector
-"]
+/**
+ * Apply a function to each element of a vector and return a concatenation
+ * of each result vector
+ */
pure fn flat_map<T, U>(v: &[T], f: fn(T) -> ~[U]) -> ~[U] {
let mut result = ~[];
for each(v) |elem| { unchecked{ push_all_move(result, f(elem)); } }
ret result;
}
-#[doc = "
-Apply a function to each pair of elements and return the results
-"]
+/// Apply a function to each pair of elements and return the results
pure fn map2<T: copy, U: copy, V>(v0: &[T], v1: &[U],
f: fn(T, U) -> V) -> ~[V] {
let v0_len = len(v0);
ret u;
}
-#[doc = "
-Apply a function to each element of a vector and return the results
-
-If function `f` returns `none` then that element is excluded from
-the resulting vector.
-"]
+/**
+ * Apply a function to each element of a vector and return the results
+ *
+ * If function `f` returns `none` then that element is excluded from
+ * the resulting vector.
+ */
pure fn filter_map<T, U: copy>(v: &[T], f: fn(T) -> option<U>)
-> ~[U] {
let mut result = ~[];
ret result;
}
-#[doc = "
-Construct a new vector from the elements of a vector for which some predicate
-holds.
-
-Apply function `f` to each element of `v` and return a vector containing
-only those elements for which `f` returned true.
-"]
+/**
+ * Construct a new vector from the elements of a vector for which some
+ * predicate holds.
+ *
+ * Apply function `f` to each element of `v` and return a vector containing
+ * only those elements for which `f` returned true.
+ */
pure fn filter<T: copy>(v: &[T], f: fn(T) -> bool) -> ~[T] {
let mut result = ~[];
for each(v) |elem| {
ret result;
}
-#[doc = "
-Concatenate a vector of vectors.
-
-Flattens a vector of vectors of T into a single vector of T.
-"]
+/**
+ * Concatenate a vector of vectors.
+ *
+ * Flattens a vector of vectors of T into a single vector of T.
+ */
pure fn concat<T: copy>(v: &[[T]/~]) -> ~[T] {
let mut r = ~[];
for each(v) |inner| { unsafe { push_all(r, inner); } }
ret r;
}
-#[doc = "
-Concatenate a vector of vectors, placing a given separator between each
-"]
+/// Concatenate a vector of vectors, placing a given separator between each
pure fn connect<T: copy>(v: &[[T]/~], sep: T) -> ~[T] {
let mut r: ~[T] = ~[];
let mut first = true;
ret r;
}
-#[doc = "Reduce a vector from left to right"]
+/// Reduce a vector from left to right
pure fn foldl<T: copy, U>(z: T, v: &[U], p: fn(T, U) -> T) -> T {
let mut accum = z;
do iter(v) |elt| {
ret accum;
}
-#[doc = "Reduce a vector from right to left"]
+/// Reduce a vector from right to left
pure fn foldr<T, U: copy>(v: &[T], z: U, p: fn(T, U) -> U) -> U {
let mut accum = z;
do riter(v) |elt| {
ret accum;
}
-#[doc = "
-Return true if a predicate matches any elements
-
-If the vector contains no elements then false is returned.
-"]
+/**
+ * Return true if a predicate matches any elements
+ *
+ * If the vector contains no elements then false is returned.
+ */
pure fn any<T>(v: &[T], f: fn(T) -> bool) -> bool {
for each(v) |elem| { if f(elem) { ret true; } }
ret false;
}
-#[doc = "
-Return true if a predicate matches any elements in both vectors.
-
-If the vectors contains no elements then false is returned.
-"]
+/**
+ * Return true if a predicate matches any elements in both vectors.
+ *
+ * If the vectors contains no elements then false is returned.
+ */
pure fn any2<T, U>(v0: &[T], v1: &[U],
f: fn(T, U) -> bool) -> bool {
let v0_len = len(v0);
ret false;
}
-#[doc = "
-Return true if a predicate matches all elements
-
-If the vector contains no elements then true is returned.
-"]
+/**
+ * Return true if a predicate matches all elements
+ *
+ * If the vector contains no elements then true is returned.
+ */
pure fn all<T>(v: &[T], f: fn(T) -> bool) -> bool {
for each(v) |elem| { if !f(elem) { ret false; } }
ret true;
}
-#[doc = "
-Return true if a predicate matches all elements
-
-If the vector contains no elements then true is returned.
-"]
+/**
+ * Return true if a predicate matches all elements
+ *
+ * If the vector contains no elements then true is returned.
+ */
pure fn alli<T>(v: &[T], f: fn(uint, T) -> bool) -> bool {
for eachi(v) |i, elem| { if !f(i, elem) { ret false; } }
ret true;
}
-#[doc = "
-Return true if a predicate matches all elements in both vectors.
-
-If the vectors are not the same size then false is returned.
-"]
+/**
+ * Return true if a predicate matches all elements in both vectors.
+ *
+ * If the vectors are not the same size then false is returned.
+ */
pure fn all2<T, U>(v0: &[T], v1: &[U],
f: fn(T, U) -> bool) -> bool {
let v0_len = len(v0);
ret true;
}
-#[doc = "Return true if a vector contains an element with the given value"]
+/// Return true if a vector contains an element with the given value
pure fn contains<T>(v: &[T], x: T) -> bool {
for each(v) |elt| { if x == elt { ret true; } }
ret false;
}
-#[doc = "Returns the number of elements that are equal to a given value"]
+/// Returns the number of elements that are equal to a given value
pure fn count<T>(v: &[T], x: T) -> uint {
let mut cnt = 0u;
for each(v) |elt| { if x == elt { cnt += 1u; } }
ret cnt;
}
-#[doc = "
-Search for the first element that matches a given predicate
-
-Apply function `f` to each element of `v`, starting from the first.
-When function `f` returns true then an option containing the element
-is returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Search for the first element that matches a given predicate
+ *
+ * Apply function `f` to each element of `v`, starting from the first.
+ * When function `f` returns true then an option containing the element
+ * is returned. If `f` matches no elements then none is returned.
+ */
pure fn find<T: copy>(v: &[T], f: fn(T) -> bool) -> option<T> {
find_between(v, 0u, len(v), f)
}
-#[doc = "
-Search for the first element that matches a given predicate within a range
-
-Apply function `f` to each element of `v` within the range [`start`, `end`).
-When function `f` returns true then an option containing the element
-is returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Search for the first element that matches a given predicate within a range
+ *
+ * Apply function `f` to each element of `v` within the range
+ * [`start`, `end`). When function `f` returns true then an option containing
+ * the element is returned. If `f` matches no elements then none is returned.
+ */
pure fn find_between<T: copy>(v: &[T], start: uint, end: uint,
f: fn(T) -> bool) -> option<T> {
option::map(position_between(v, start, end, f), |i| v[i])
}
-#[doc = "
-Search for the last element that matches a given predicate
-
-Apply function `f` to each element of `v` in reverse order. When function `f`
-returns true then an option containing the element is returned. If `f`
-matches no elements then none is returned.
-"]
+/**
+ * Search for the last element that matches a given predicate
+ *
+ * Apply function `f` to each element of `v` in reverse order. When function
+ * `f` returns true then an option containing the element is returned. If `f`
+ * matches no elements then none is returned.
+ */
pure fn rfind<T: copy>(v: &[T], f: fn(T) -> bool) -> option<T> {
rfind_between(v, 0u, len(v), f)
}
-#[doc = "
-Search for the last element that matches a given predicate within a range
-
-Apply function `f` to each element of `v` in reverse order within the range
-[`start`, `end`). When function `f` returns true then an option containing
-the element is returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Search for the last element that matches a given predicate within a range
+ *
+ * Apply function `f` to each element of `v` in reverse order within the range
+ * [`start`, `end`). When function `f` returns true then an option containing
+ * the element is returned. If `f` matches no elements then none is returned.
+ */
pure fn rfind_between<T: copy>(v: &[T], start: uint, end: uint,
f: fn(T) -> bool) -> option<T> {
option::map(rposition_between(v, start, end, f), |i| v[i])
}
-#[doc = "Find the first index containing a matching value"]
+/// Find the first index containing a matching value
pure fn position_elem<T>(v: &[T], x: T) -> option<uint> {
position(v, |y| x == y)
}
-#[doc = "
-Find the first index matching some predicate
-
-Apply function `f` to each element of `v`. When function `f` returns true
-then an option containing the index is returned. If `f` matches no elements
-then none is returned.
-"]
+/**
+ * Find the first index matching some predicate
+ *
+ * Apply function `f` to each element of `v`. When function `f` returns true
+ * then an option containing the index is returned. If `f` matches no elements
+ * then none is returned.
+ */
pure fn position<T>(v: &[T], f: fn(T) -> bool) -> option<uint> {
position_between(v, 0u, len(v), f)
}
-#[doc = "
-Find the first index matching some predicate within a range
-
-Apply function `f` to each element of `v` between the range [`start`, `end`).
-When function `f` returns true then an option containing the index is
-returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Find the first index matching some predicate within a range
+ *
+ * Apply function `f` to each element of `v` between the range
+ * [`start`, `end`). When function `f` returns true then an option containing
+ * the index is returned. If `f` matches no elements then none is returned.
+ */
pure fn position_between<T>(v: &[T], start: uint, end: uint,
f: fn(T) -> bool) -> option<uint> {
assert start <= end;
ret none;
}
-#[doc = "Find the last index containing a matching value"]
+/// Find the last index containing a matching value
pure fn rposition_elem<T>(v: &[T], x: T) -> option<uint> {
rposition(v, |y| x == y)
}
-#[doc = "
-Find the last index matching some predicate
-
-Apply function `f` to each element of `v` in reverse order. When function
-`f` returns true then an option containing the index is returned. If `f`
-matches no elements then none is returned.
-"]
+/**
+ * Find the last index matching some predicate
+ *
+ * Apply function `f` to each element of `v` in reverse order. When function
+ * `f` returns true then an option containing the index is returned. If `f`
+ * matches no elements then none is returned.
+ */
pure fn rposition<T>(v: &[T], f: fn(T) -> bool) -> option<uint> {
rposition_between(v, 0u, len(v), f)
}
-#[doc = "
-Find the last index matching some predicate within a range
-
-Apply function `f` to each element of `v` in reverse order between the range
-[`start`, `end`). When function `f` returns true then an option containing
-the index is returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Find the last index matching some predicate within a range
+ *
+ * Apply function `f` to each element of `v` in reverse order between the
+ * range [`start`, `end`). When function `f` returns true then an option
+ * containing the index is returned. If `f` matches no elements then none is
+ * returned.
+ */
pure fn rposition_between<T>(v: &[T], start: uint, end: uint,
f: fn(T) -> bool) -> option<uint> {
assert start <= end;
// saying the two result lists have the same length -- or, could
// return a nominal record with a constraint saying that, instead of
// returning a tuple (contingent on issue #869)
-#[doc = "
-Convert a vector of pairs into a pair of vectors
-
-Returns a tuple containing two vectors where the i-th element of the first
-vector contains the first element of the i-th tuple of the input vector,
-and the i-th element of the second vector contains the second element
-of the i-th tuple of the input vector.
-"]
+/**
+ * Convert a vector of pairs into a pair of vectors
+ *
+ * Returns a tuple containing two vectors where the i-th element of the first
+ * vector contains the first element of the i-th tuple of the input vector,
+ * and the i-th element of the second vector contains the second element
+ * of the i-th tuple of the input vector.
+ */
pure fn unzip<T: copy, U: copy>(v: &[(T, U)]) -> (~[T], ~[U]) {
let mut as = ~[], bs = ~[];
for each(v) |p| {
ret (as, bs);
}
-#[doc = "
-Convert two vectors to a vector of pairs
-
-Returns a vector of tuples, where the i-th tuple contains contains the
-i-th elements from each of the input vectors.
-"]
+/**
+ * Convert two vectors to a vector of pairs
+ *
+ * Returns a vector of tuples, where the i-th tuple contains contains the
+ * i-th elements from each of the input vectors.
+ */
pure fn zip<T: copy, U: copy>(v: &[const T], u: &[const U]) -> ~[(T, U)] {
let mut zipped = ~[];
let sz = len(v);
ret zipped;
}
-#[doc = "
-Swaps two elements in a vector
-
-# Arguments
-
-* v The input vector
-* a - The index of the first element
-* b - The index of the second element
-"]
+/**
+ * Swaps two elements in a vector
+ *
+ * # Arguments
+ *
+ * * v The input vector
+ * * a - The index of the first element
+ * * b - The index of the second element
+ */
fn swap<T>(&&v: ~[mut T], a: uint, b: uint) {
v[a] <-> v[b];
}
-#[doc = "Reverse the order of elements in a vector, in place"]
+/// Reverse the order of elements in a vector, in place
fn reverse<T>(v: ~[mut T]) {
let mut i: uint = 0u;
let ln = len::<T>(v);
}
-#[doc = "Returns a vector with the order of elements reversed"]
+/// Returns a vector with the order of elements reversed
pure fn reversed<T: copy>(v: &[const T]) -> ~[T] {
let mut rs: ~[T] = ~[];
let mut i = len::<T>(v);
ret rs;
}
-#[doc = "
-Iterates over a slice
-
-Iterates over slice `v` and, for each element, calls function `f` with the
-element's value.
-"]
+/**
+ * Iterates over a slice
+ *
+ * Iterates over slice `v` and, for each element, calls function `f` with the
+ * element's value.
+ */
#[inline(always)]
pure fn iter<T>(v: &[T], f: fn(T)) {
iter_between(v, 0u, vec::len(v), f)
}
}
-#[doc = "
-Iterates over a vector, with option to break
-
-Return true to continue, false to break.
-"]
+/**
+ * Iterates over a vector, with option to break
+ *
+ * Return true to continue, false to break.
+ */
#[inline(always)]
pure fn each<T>(v: &[const T], f: fn(T) -> bool) {
do vec::unpack_slice(v) |p, n| {
}
}
-#[doc = "
-Iterates over a vector's elements and indices
-
-Return true to continue, false to break.
-"]
+/**
+ * Iterates over a vector's elements and indices
+ *
+ * Return true to continue, false to break.
+ */
#[inline(always)]
pure fn eachi<T>(v: &[const T], f: fn(uint, T) -> bool) {
do vec::unpack_slice(v) |p, n| {
}
}
-#[doc = "
-Iterates over two vectors simultaneously
-
-# Failure
-
-Both vectors must have the same length
-"]
+/**
+ * Iterates over two vectors simultaneously
+ *
+ * # Failure
+ *
+ * Both vectors must have the same length
+ */
#[inline]
fn iter2<U, T>(v1: &[U], v2: &[T], f: fn(U, T)) {
assert len(v1) == len(v2);
}
}
-#[doc = "
-Iterates over a vector's elements and indexes
-
-Iterates over vector `v` and, for each element, calls function `f` with the
-element's value and index.
-"]
+/**
+ * Iterates over a vector's elements and indexes
+ *
+ * Iterates over vector `v` and, for each element, calls function `f` with the
+ * element's value and index.
+ */
#[inline(always)]
pure fn iteri<T>(v: &[T], f: fn(uint, T)) {
let mut i = 0u;
while i < l { f(i, v[i]); i += 1u; }
}
-#[doc = "
-Iterates over a vector in reverse
-
-Iterates over vector `v` and, for each element, calls function `f` with the
-element's value.
-"]
+/**
+ * Iterates over a vector in reverse
+ *
+ * Iterates over vector `v` and, for each element, calls function `f` with the
+ * element's value.
+ */
pure fn riter<T>(v: &[T], f: fn(T)) {
riteri(v, |_i, v| f(v))
}
-#[doc ="
-Iterates over a vector's elements and indexes in reverse
-
-Iterates over vector `v` and, for each element, calls function `f` with the
-element's value and index.
-"]
+/**
+ * Iterates over a vector's elements and indexes in reverse
+ *
+ * Iterates over vector `v` and, for each element, calls function `f` with the
+ * element's value and index.
+ */
pure fn riteri<T>(v: &[T], f: fn(uint, T)) {
let mut i = len(v);
while 0u < i {
};
}
-#[doc = "
-Iterate over all permutations of vector `v`.
-
-Permutations are produced in lexicographic order with respect to the order of
-elements in `v` (so if `v` is sorted then the permutations are
-lexicographically sorted).
-
-The total number of permutations produced is `len(v)!`. If `v` contains
-repeated elements, then some permutations are repeated.
-"]
+/**
+ * Iterate over all permutations of vector `v`.
+ *
+ * Permutations are produced in lexicographic order with respect to the order
+ * of elements in `v` (so if `v` is sorted then the permutations are
+ * lexicographically sorted).
+ *
+ * The total number of permutations produced is `len(v)!`. If `v` contains
+ * repeated elements, then some permutations are repeated.
+ */
pure fn permute<T: copy>(v: &[T], put: fn(~[T])) {
let ln = len(v);
if ln == 0u {
ret ww;
}
-#[doc = "
-Work with the buffer of a vector.
-
-Allows for unsafe manipulation of vector contents, which is useful for
-foreign interop.
-"]
+/**
+ * Work with the buffer of a vector.
+ *
+ * Allows for unsafe manipulation of vector contents, which is useful for
+ * foreign interop.
+ */
fn as_buf<E,T>(v: &[E], f: fn(*E) -> T) -> T {
unpack_slice(v, |buf, _len| f(buf))
}
unpack_mut_slice(v, |buf, _len| f(buf))
}
-#[doc = "
-Work with the buffer and length of a slice.
-"]
+/// Work with the buffer and length of a slice.
#[inline(always)]
pure fn unpack_slice<T,U>(s: &[const T],
f: fn(*T, uint) -> U) -> U {
}
}
-#[doc = "
-Work with the buffer and length of a slice.
-"]
+/// Work with the buffer and length of a slice.
#[inline(always)]
pure fn unpack_const_slice<T,U>(s: &[const T],
f: fn(*const T, uint) -> U) -> U {
}
}
-#[doc = "
-Work with the buffer and length of a slice.
-"]
+/// Work with the buffer and length of a slice.
#[inline(always)]
pure fn unpack_mut_slice<T,U>(s: &[mut T],
f: fn(*mut T, uint) -> U) -> U {
}
}
-#[doc = "Extension methods for vectors"]
+/// Extension methods for vectors
impl extensions/&<T> for &[const T] {
- #[doc = "Returns true if a vector contains no elements"]
+ /// Returns true if a vector contains no elements
#[inline]
pure fn is_empty() -> bool { is_empty(self) }
- #[doc = "Returns true if a vector contains some elements"]
+ /// Returns true if a vector contains some elements
#[inline]
pure fn is_not_empty() -> bool { is_not_empty(self) }
- #[doc = "Returns the length of a vector"]
+ /// Returns the length of a vector
#[inline]
pure fn len() -> uint { len(self) }
}
-#[doc = "Extension methods for vectors"]
+/// Extension methods for vectors
impl extensions/&<T: copy> for &[const T] {
- #[doc = "Returns the first element of a vector"]
+ /// Returns the first element of a vector
#[inline]
pure fn head() -> T { head(self) }
- #[doc = "Returns all but the last elemnt of a vector"]
+ /// Returns all but the last elemnt of a vector
#[inline]
pure fn init() -> ~[T] { init(self) }
- #[doc = "
- Returns the last element of a `v`, failing if the vector is empty.
- "]
+ /// Returns the last element of a `v`, failing if the vector is empty.
#[inline]
pure fn last() -> T { last(self) }
- #[doc = "Returns a copy of the elements from [`start`..`end`) from `v`."]
+ /// Returns a copy of the elements from [`start`..`end`) from `v`.
#[inline]
pure fn slice(start: uint, end: uint) -> ~[T] { slice(self, start, end) }
- #[doc = "Returns all but the first element of a vector"]
+ /// Returns all but the first element of a vector
#[inline]
pure fn tail() -> ~[T] { tail(self) }
}
-#[doc = "Extension methods for vectors"]
+/// Extension methods for vectors
impl extensions/&<T> for &[T] {
- #[doc = "Reduce a vector from right to left"]
+ /// Reduce a vector from right to left
#[inline]
pure fn foldr<U: copy>(z: U, p: fn(T, U) -> U) -> U { foldr(self, z, p) }
- #[doc = "
- Iterates over a vector
-
- Iterates over vector `v` and, for each element, calls function `f` with
- the element's value.
- "]
+ /**
+ * Iterates over a vector
+ *
+ * Iterates over vector `v` and, for each element, calls function `f` with
+ * the element's value.
+ */
#[inline]
pure fn iter(f: fn(T)) { iter(self, f) }
- #[doc = "
- Iterates over a vector's elements and indexes
-
- Iterates over vector `v` and, for each element, calls function `f` with
- the element's value and index.
- "]
+ /**
+ * Iterates over a vector's elements and indexes
+ *
+ * Iterates over vector `v` and, for each element, calls function `f` with
+ * the element's value and index.
+ */
#[inline]
pure fn iteri(f: fn(uint, T)) { iteri(self, f) }
- #[doc = "
- Find the first index matching some predicate
-
- Apply function `f` to each element of `v`. When function `f` returns true
- then an option containing the index is returned. If `f` matches no
- elements then none is returned.
- "]
+ /**
+ * Find the first index matching some predicate
+ *
+ * Apply function `f` to each element of `v`. When function `f` returns
+ * true then an option containing the index is returned. If `f` matches no
+ * elements then none is returned.
+ */
#[inline]
pure fn position(f: fn(T) -> bool) -> option<uint> { position(self, f) }
- #[doc = "Find the first index containing a matching value"]
+ /// Find the first index containing a matching value
#[inline]
pure fn position_elem(x: T) -> option<uint> { position_elem(self, x) }
- #[doc = "
- Iterates over a vector in reverse
-
- Iterates over vector `v` and, for each element, calls function `f` with
- the element's value.
- "]
+ /**
+ * Iterates over a vector in reverse
+ *
+ * Iterates over vector `v` and, for each element, calls function `f` with
+ * the element's value.
+ */
#[inline]
pure fn riter(f: fn(T)) { riter(self, f) }
- #[doc ="
- Iterates over a vector's elements and indexes in reverse
-
- Iterates over vector `v` and, for each element, calls function `f` with
- the element's value and index.
- "]
+ /**
+ * Iterates over a vector's elements and indexes in reverse
+ *
+ * Iterates over vector `v` and, for each element, calls function `f` with
+ * the element's value and index.
+ */
#[inline]
pure fn riteri(f: fn(uint, T)) { riteri(self, f) }
- #[doc = "
- Find the last index matching some predicate
-
- Apply function `f` to each element of `v` in reverse order. When function
- `f` returns true then an option containing the index is returned. If `f`
- matches no elements then none is returned.
- "]
+ /**
+ * Find the last index matching some predicate
+ *
+ * Apply function `f` to each element of `v` in reverse order. When
+ * function `f` returns true then an option containing the index is
+ * returned. If `f` matches no elements then none is returned.
+ */
#[inline]
pure fn rposition(f: fn(T) -> bool) -> option<uint> { rposition(self, f) }
- #[doc = "Find the last index containing a matching value"]
+ /// Find the last index containing a matching value
#[inline]
pure fn rposition_elem(x: T) -> option<uint> { rposition_elem(self, x) }
- #[doc = "
- Apply a function to each element of a vector and return the results
- "]
+ /// Apply a function to each element of a vector and return the results
#[inline]
pure fn map<U>(f: fn(T) -> U) -> ~[U] { map(self, f) }
- #[doc = "
- Apply a function to the index and value of each element in the vector
- and return the results
- "]
+ /**
+ * Apply a function to the index and value of each element in the vector
+ * and return the results
+ */
pure fn mapi<U>(f: fn(uint, T) -> U) -> ~[U] {
mapi(self, f)
}
- #[doc = "Returns true if the function returns true for all elements.
-
- If the vector is empty, true is returned."]
+ /**
+ * Returns true if the function returns true for all elements.
+ *
+ * If the vector is empty, true is returned.
+ */
pure fn alli(f: fn(uint, T) -> bool) -> bool {
alli(self, f)
}
- #[doc = "
- Apply a function to each element of a vector and return a concatenation
- of each result vector
- "]
+ /**
+ * Apply a function to each element of a vector and return a concatenation
+ * of each result vector
+ */
#[inline]
pure fn flat_map<U>(f: fn(T) -> ~[U]) -> ~[U] { flat_map(self, f) }
- #[doc = "
- Apply a function to each element of a vector and return the results
-
- If function `f` returns `none` then that element is excluded from
- the resulting vector.
- "]
+ /**
+ * Apply a function to each element of a vector and return the results
+ *
+ * If function `f` returns `none` then that element is excluded from
+ * the resulting vector.
+ */
#[inline]
pure fn filter_map<U: copy>(f: fn(T) -> option<U>) -> ~[U] {
filter_map(self, f)
}
}
-#[doc = "Extension methods for vectors"]
+/// Extension methods for vectors
impl extensions/&<T: copy> for &[T] {
- #[doc = "
- Construct a new vector from the elements of a vector for which some
- predicate holds.
-
- Apply function `f` to each element of `v` and return a vector containing
- only those elements for which `f` returned true.
- "]
+ /**
+ * Construct a new vector from the elements of a vector for which some
+ * predicate holds.
+ *
+ * Apply function `f` to each element of `v` and return a vector
+ * containing only those elements for which `f` returned true.
+ */
#[inline]
pure fn filter(f: fn(T) -> bool) -> ~[T] { filter(self, f) }
- #[doc = "
- Search for the first element that matches a given predicate
-
- Apply function `f` to each element of `v`, starting from the first.
- When function `f` returns true then an option containing the element
- is returned. If `f` matches no elements then none is returned.
- "]
+ /**
+ * Search for the first element that matches a given predicate
+ *
+ * Apply function `f` to each element of `v`, starting from the first.
+ * When function `f` returns true then an option containing the element
+ * is returned. If `f` matches no elements then none is returned.
+ */
#[inline]
pure fn find(f: fn(T) -> bool) -> option<T> { find(self, f) }
- #[doc = "
- Search for the last element that matches a given predicate
-
- Apply function `f` to each element of `v` in reverse order. When function
- `f` returns true then an option containing the element is returned. If `f`
- matches no elements then none is returned.
- "]
+ /**
+ * Search for the last element that matches a given predicate
+ *
+ * Apply function `f` to each element of `v` in reverse order. When
+ * function `f` returns true then an option containing the element is
+ * returned. If `f` matches no elements then none is returned.
+ */
#[inline]
pure fn rfind(f: fn(T) -> bool) -> option<T> { rfind(self, f) }
}
-#[doc = "Unsafe operations"]
+/// Unsafe operations
mod unsafe {
// FIXME: This should have crate visibility (#1893 blocks that)
- #[doc = "The internal representation of a vector"]
+ /// The internal representation of a vector
type vec_repr = {
box_header: (uint, uint, uint, uint),
mut fill: uint,
data: u8
};
- #[doc = "
- Constructs a vector from an unsafe pointer to a buffer
-
- # Arguments
-
- * ptr - An unsafe pointer to a buffer of `T`
- * elts - The number of elements in the buffer
- "]
+ /**
+ * Constructs a vector from an unsafe pointer to a buffer
+ *
+ * # Arguments
+ *
+ * * ptr - An unsafe pointer to a buffer of `T`
+ * * elts - The number of elements in the buffer
+ */
#[inline(always)]
unsafe fn from_buf<T>(ptr: *T, elts: uint) -> ~[T] {
ret ::unsafe::reinterpret_cast(
elts as size_t));
}
- #[doc = "
- Sets the length of a vector
-
- This will explicitly set the size of the vector, without actually
- modifing its buffers, so it is up to the caller to ensure that
- the vector is actually the specified size.
- "]
+ /**
+ * Sets the length of a vector
+ *
+ * This will explicitly set the size of the vector, without actually
+ * modifing its buffers, so it is up to the caller to ensure that
+ * the vector is actually the specified size.
+ */
#[inline(always)]
unsafe fn set_len<T>(&&v: ~[const T], new_len: uint) {
let repr: **vec_repr = ::unsafe::reinterpret_cast(addr_of(v));
(**repr).fill = new_len * sys::size_of::<T>();
}
- #[doc = "
- Returns an unsafe pointer to the vector's buffer
-
- The caller must ensure that the vector outlives the pointer this
- function returns, or else it will end up pointing to garbage.
-
- Modifying the vector may cause its buffer to be reallocated, which
- would also make any pointers to it invalid.
- "]
+ /**
+ * Returns an unsafe pointer to the vector's buffer
+ *
+ * The caller must ensure that the vector outlives the pointer this
+ * function returns, or else it will end up pointing to garbage.
+ *
+ * Modifying the vector may cause its buffer to be reallocated, which
+ * would also make any pointers to it invalid.
+ */
#[inline(always)]
unsafe fn to_ptr<T>(v: ~[const T]) -> *T {
let repr: **vec_repr = ::unsafe::reinterpret_cast(addr_of(v));
}
- #[doc = "
- Form a slice from a pointer and length (as a number of units, not bytes).
- "]
+ /**
+ * Form a slice from a pointer and length (as a number of units,
+ * not bytes).
+ */
#[inline(always)]
unsafe fn form_slice<T,U>(p: *T, len: uint, f: fn(&& &[T]) -> U) -> U {
let pair = (p, len * sys::size_of::<T>());
}
}
-#[doc = "Operations on `[u8]`"]
+/// Operations on `[u8]`
mod u8 {
export cmp;
export lt, le, eq, ne, ge, gt;
export hash;
- #[doc = "Bytewise string comparison"]
+ /// Bytewise string comparison
pure fn cmp(&&a: ~[u8], &&b: ~[u8]) -> int {
let a_len = len(a);
let b_len = len(b);
}
}
- #[doc = "Bytewise less than or equal"]
+ /// Bytewise less than or equal
pure fn lt(&&a: ~[u8], &&b: ~[u8]) -> bool { cmp(a, b) < 0 }
- #[doc = "Bytewise less than or equal"]
+ /// Bytewise less than or equal
pure fn le(&&a: ~[u8], &&b: ~[u8]) -> bool { cmp(a, b) <= 0 }
- #[doc = "Bytewise equality"]
+ /// Bytewise equality
pure fn eq(&&a: ~[u8], &&b: ~[u8]) -> bool { unsafe { cmp(a, b) == 0 } }
- #[doc = "Bytewise inequality"]
+ /// Bytewise inequality
pure fn ne(&&a: ~[u8], &&b: ~[u8]) -> bool { unsafe { cmp(a, b) != 0 } }
- #[doc ="Bytewise greater than or equal"]
+ /// Bytewise greater than or equal
pure fn ge(&&a: ~[u8], &&b: ~[u8]) -> bool { cmp(a, b) >= 0 }
- #[doc = "Bytewise greater than"]
+ /// Bytewise greater than
pure fn gt(&&a: ~[u8], &&b: ~[u8]) -> bool { cmp(a, b) > 0 }
- #[doc = "String hash function"]
+ /// String hash function
fn hash(&&s: ~[u8]) -> uint {
/* Seems to have been tragically copy/pasted from str.rs,
or vice versa. But I couldn't figure out how to abstract
// write an optimizing version of this module that produces a different obj
// for the case where nbits <= 32.
-#[doc = "The bitvector type"]
+/// The bitvector type
type bitv = @{storage: ~[mut uint], nbits: uint};
const uint_bits: uint = 32u + (1u << 32u >> 27u);
-#[doc = "
-Constructs a bitvector
-
-# Arguments
-
-* nbits - The number of bits in the bitvector
-* init - If true then the bits are initialized to 1, otherwise 0
-"]
+/**
+ * Constructs a bitvector
+ *
+ * # Arguments
+ *
+ * * nbits - The number of bits in the bitvector
+ * * init - If true then the bits are initialized to 1, otherwise 0
+ */
fn bitv(nbits: uint, init: bool) -> bitv {
let elt = if init { !0u } else { 0u };
let storage = vec::to_mut(vec::from_elem(nbits / uint_bits + 1u, elt));
fn land(w0: uint, w1: uint) -> uint { ret w0 & w1; }
-#[doc = "
-Calculates the intersection of two bitvectors
-
-Sets `v0` to the intersection of `v0` and `v1`. Both bitvectors must be the
-same length. Returns 'true' if `v0` was changed.
-"]
+/**
+ * Calculates the intersection of two bitvectors
+ *
+ * Sets `v0` to the intersection of `v0` and `v1`. Both bitvectors must be the
+ * same length. Returns 'true' if `v0` was changed.
+ */
fn intersect(v0: bitv, v1: bitv) -> bool {
let sub = land;
ret process(v0, v1, sub);
fn right(_w0: uint, w1: uint) -> uint { ret w1; }
-#[doc = "
-Assigns the value of `v1` to `v0`
-
-Both bitvectors must be the same length. Returns `true` if `v0` was changed
-"]
+/**
+ * Assigns the value of `v1` to `v0`
+ *
+ * Both bitvectors must be the same length. Returns `true` if `v0` was changed
+ */
fn assign(v0: bitv, v1: bitv) -> bool {
let sub = right; ret process(v0, v1, sub);
}
-#[doc = "Makes a copy of a bitvector"]
+/// Makes a copy of a bitvector
fn clone(v: bitv) -> bitv {
let storage = vec::to_mut(vec::from_elem(v.nbits / uint_bits + 1u, 0u));
let len = vec::len(v.storage);
ret @{storage: storage, nbits: v.nbits};
}
-#[doc = "Retrieve the value at index `i`"]
+/// Retrieve the value at index `i`
#[inline(always)]
pure fn get(v: bitv, i: uint) -> bool {
assert (i < v.nbits);
ret x == 1u;
}
-#[doc = "
-Compares two bitvectors
-
-Both bitvectors must be the same length. Returns `true` if both bitvectors
-contain identical elements.
-"]
+/**
+ * Compares two bitvectors
+ *
+ * Both bitvectors must be the same length. Returns `true` if both bitvectors
+ * contain identical elements.
+ */
fn equal(v0: bitv, v1: bitv) -> bool {
if v0.nbits != v1.nbits { ret false; }
let len = vec::len(v1.storage);
}
}
-#[doc = "Set all bits to 0"]
+/// Set all bits to 0
#[inline(always)]
fn clear(v: bitv) { for each_storage(v) |w| { w = 0u } }
-#[doc = "Set all bits to 1"]
+/// Set all bits to 1
#[inline(always)]
fn set_all(v: bitv) { for each_storage(v) |w| { w = !0u } }
-#[doc = "Invert all bits"]
+/// Invert all bits
#[inline(always)]
fn invert(v: bitv) { for each_storage(v) |w| { w = !w } }
-#[doc = "
-Calculate the difference between two bitvectors
-
-Sets each element of `v0` to the value of that element minus the element
-of `v1` at the same index. Both bitvectors must be the same length.
-
-Returns `true` if `v0` was changed.
-"]
+/**
+ * Calculate the difference between two bitvectors
+ *
+ * Sets each element of `v0` to the value of that element minus the element
+ * of `v1` at the same index. Both bitvectors must be the same length.
+ *
+ * Returns `true` if `v0` was changed.
+ */
fn difference(v0: bitv, v1: bitv) -> bool {
invert(v1);
let b = intersect(v0, v1);
ret b;
}
-#[doc = "
-Set the value of a bit at a given index
-
-`i` must be less than the length of the bitvector.
-"]
+/**
+ * Set the value of a bit at a given index
+ *
+ * `i` must be less than the length of the bitvector.
+ */
#[inline(always)]
fn set(v: bitv, i: uint, x: bool) {
assert (i < v.nbits);
}
-#[doc = "Returns true if all bits are 1"]
+/// Returns true if all bits are 1
fn is_true(v: bitv) -> bool {
for each(v) |i| { if !i { ret false; } }
ret true;
}
-#[doc = "Returns true if all bits are 0"]
+/// Returns true if all bits are 0
fn is_false(v: bitv) -> bool {
for each(v) |i| { if i { ret false; } }
ret true;
ret if get(v, i) { 1u } else { 0u };
}
-#[doc = "
-Converts the bitvector to a vector of uint with the same length.
-
-Each uint in the resulting vector has either value 0u or 1u.
-"]
+/**
+ * Converts the bitvector to a vector of uint with the same length.
+ *
+ * Each uint in the resulting vector has either value 0u or 1u.
+ */
fn to_vec(v: bitv) -> ~[uint] {
let sub = |x| init_to_vec(v, x);
ret vec::from_fn::<uint>(v.nbits, sub);
}
}
-#[doc = "
-Converts the bitvector to a string.
-
-The resulting string has the same length as the bitvector, and each character
-is either '0' or '1'.
-"]
+/**
+ * Converts the bitvector to a string.
+ *
+ * The resulting string has the same length as the bitvector, and each
+ * character is either '0' or '1'.
+ */
fn to_str(v: bitv) -> str {
let mut rs = "";
for each(v) |i| { if i { rs += "1"; } else { rs += "0"; } }
ret rs;
}
-#[doc = "
-Compare a bitvector to a vector of uint
-
-The uint vector is expected to only contain the values 0u and 1u. Both the
-bitvector and vector must have the same length
-"]
+/**
+ * Compare a bitvector to a vector of uint
+ *
+ * The uint vector is expected to only contain the values 0u and 1u. Both the
+ * bitvector and vector must have the same length
+ */
fn eq_vec(v0: bitv, v1: ~[uint]) -> bool {
assert (v0.nbits == vec::len::<uint>(v1));
let len = v0.nbits;
-#[doc = "
-Library to interface with chunks of memory allocated in C.
-
-It is often desirable to safely interface with memory allocated from C,
-encapsulating the unsafety into allocation and destruction time. Indeed,
-allocating memory externally is currently the only way to give Rust shared
-mut state with C programs that keep their own references; vectors are
-unsuitable because they could be reallocated or moved at any time, and
-importing C memory into a vector takes a one-time snapshot of the memory.
-
-This module simplifies the usage of such external blocks of memory. Memory
-is encapsulated into an opaque object after creation; the lifecycle of the
-memory can be optionally managed by Rust, if an appropriate destructor
-closure is provided. Safety is ensured by bounds-checking accesses, which
-are marshalled through get and set functions.
-
-There are three unsafe functions: the two introduction forms, and the
-pointer elimination form. The introduction forms are unsafe for the obvious
-reason (they act on a pointer that cannot be checked inside the method), but
-the elimination form is somewhat more subtle in its unsafety. By using a
-pointer taken from a c_vec::t without keeping a reference to the c_vec::t
-itself around, the c_vec could be garbage collected, and the memory within
-could be destroyed. There are legitimate uses for the pointer elimination
-form -- for instance, to pass memory back into C -- but great care must be
-taken to ensure that a reference to the c_vec::t is still held if needed.
-"];
+/*!
+ * Library to interface with chunks of memory allocated in C.
+ *
+ * It is often desirable to safely interface with memory allocated from C,
+ * encapsulating the unsafety into allocation and destruction time. Indeed,
+ * allocating memory externally is currently the only way to give Rust shared
+ * mut state with C programs that keep their own references; vectors are
+ * unsuitable because they could be reallocated or moved at any time, and
+ * importing C memory into a vector takes a one-time snapshot of the memory.
+ *
+ * This module simplifies the usage of such external blocks of memory. Memory
+ * is encapsulated into an opaque object after creation; the lifecycle of the
+ * memory can be optionally managed by Rust, if an appropriate destructor
+ * closure is provided. Safety is ensured by bounds-checking accesses, which
+ * are marshalled through get and set functions.
+ *
+ * There are three unsafe functions: the two introduction forms, and the
+ * pointer elimination form. The introduction forms are unsafe for the
+ * obvious reason (they act on a pointer that cannot be checked inside the
+ * method), but the elimination form is somewhat more subtle in its unsafety.
+ * By using a pointer taken from a c_vec::t without keeping a reference to the
+ * c_vec::t itself around, the c_vec could be garbage collected, and the
+ * memory within could be destroyed. There are legitimate uses for the
+ * pointer elimination form -- for instance, to pass memory back into C -- but
+ * great care must be taken to ensure that a reference to the c_vec::t is
+ * still held if needed.
+ */
export c_vec;
export c_vec, c_vec_with_dtor;
export len;
export ptr;
-#[doc = "
-The type representing a foreign chunk of memory
-
-Wrapped in a enum for opacity; FIXME #818 when it is possible to have
-truly opaque types, this should be revisited.
-"]
+/**
+ * The type representing a foreign chunk of memory
+ *
+ * Wrapped in a enum for opacity; FIXME #818 when it is possible to have
+ * truly opaque types, this should be revisited.
+ */
enum c_vec<T> {
c_vec_({ base: *mut T, len: uint, rsrc: @dtor_res})
}
Section: Introduction forms
*/
-#[doc = "
-Create a `c_vec` from a foreign buffer with a given length.
-
-# Arguments
-
-* base - A foreign pointer to a buffer
-* len - The number of elements in the buffer
-"]
+/**
+ * Create a `c_vec` from a foreign buffer with a given length.
+ *
+ * # Arguments
+ *
+ * * base - A foreign pointer to a buffer
+ * * len - The number of elements in the buffer
+ */
unsafe fn c_vec<T>(base: *mut T, len: uint) -> c_vec<T> {
ret c_vec_({
base: base,
});
}
-#[doc = "
-Create a `c_vec` from a foreign buffer, with a given length,
-and a function to run upon destruction.
-
-# Arguments
-
-* base - A foreign pointer to a buffer
-* len - The number of elements in the buffer
-* dtor - A function to run when the value is destructed, useful
- for freeing the buffer, etc.
-"]
+/**
+ * Create a `c_vec` from a foreign buffer, with a given length,
+ * and a function to run upon destruction.
+ *
+ * # Arguments
+ *
+ * * base - A foreign pointer to a buffer
+ * * len - The number of elements in the buffer
+ * * dtor - A function to run when the value is destructed, useful
+ * for freeing the buffer, etc.
+ */
unsafe fn c_vec_with_dtor<T>(base: *mut T, len: uint, dtor: fn@())
-> c_vec<T> {
ret c_vec_({
Section: Operations
*/
-#[doc = "
-Retrieves an element at a given index
-
-Fails if `ofs` is greater or equal to the length of the vector
-"]
+/**
+ * Retrieves an element at a given index
+ *
+ * Fails if `ofs` is greater or equal to the length of the vector
+ */
fn get<T: copy>(t: c_vec<T>, ofs: uint) -> T {
assert ofs < len(t);
ret unsafe { *ptr::mut_offset((*t).base, ofs) };
}
-#[doc = "
-Sets the value of an element at a given index
-
-Fails if `ofs` is greater or equal to the length of the vector
-"]
+/**
+ * Sets the value of an element at a given index
+ *
+ * Fails if `ofs` is greater or equal to the length of the vector
+ */
fn set<T: copy>(t: c_vec<T>, ofs: uint, v: T) {
assert ofs < len(t);
unsafe { *ptr::mut_offset((*t).base, ofs) = v };
Section: Elimination forms
*/
-#[doc = "Returns the length of the vector"]
+/// Returns the length of the vector
fn len<T>(t: c_vec<T>) -> uint {
ret (*t).len;
}
-#[doc = "Returns a pointer to the first element of the vector"]
+/// Returns a pointer to the first element of the vector
unsafe fn ptr<T>(t: c_vec<T>) -> *mut T {
ret (*t).base;
}
set(cv, 2u, 34u8); /* safety */
}
-}
\ No newline at end of file
+}
-#[doc="Additional general-purpose comparison functionality."]
+/// Additional general-purpose comparison functionality.
const fuzzy_epsilon: float = 1.0e-6;
-#[doc = "Unsafe debugging functions for inspecting values."];
+//! Unsafe debugging functions for inspecting values.
import unsafe::reinterpret_cast;
reinterpret_cast(x)))
}
-#[doc = "Triggers a debugger breakpoint"]
+/// Triggers a debugger breakpoint
fn breakpoint() {
rustrt::rust_dbg_breakpoint();
}
-#[doc = "A deque. Untested as of yet. Likely buggy"];
+//! A deque. Untested as of yet. Likely buggy
import option::{some, none};
import dvec::{dvec, extensions};
-#[doc = "
-A functional key,value store that works on anything.
-
-This works using a binary search tree. In the first version, it's a
-very naive algorithm, but it will probably be updated to be a
-red-black tree or something else.
-
-This is copied and modified from treemap right now. It's missing a lot
-of features.
-"];
+/*!
+ * A functional key,value store that works on anything.
+ *
+ * This works using a binary search tree. In the first version, it's a
+ * very naive algorithm, but it will probably be updated to be a
+ * red-black tree or something else.
+ *
+ * This is copied and modified from treemap right now. It's missing a lot
+ * of features.
+ */
import option::{some, none};
import option = option;
node(@K, @V, @tree_node<K, V>, @tree_node<K, V>)
}
-#[doc = "Create a treemap"]
+/// Create a treemap
fn init<K, V>() -> treemap<K, V> { @empty }
-#[doc = "Insert a value into the map"]
+/// Insert a value into the map
fn insert<K: copy, V: copy>(m: treemap<K, V>, k: K, v: V) -> treemap<K, V> {
@alt m {
@empty { node(@k, @v, @empty, @empty) }
}
}
-#[doc = "Find a value based on the key"]
+/// Find a value based on the key
fn find<K, V: copy>(m: treemap<K, V>, k: K) -> option<V> {
alt *m {
empty { none }
}
}
-#[doc = "Visit all pairs in the map in order."]
+/// Visit all pairs in the map in order.
fn traverse<K, V: copy>(m: treemap<K, V>, f: fn(K, V)) {
alt *m {
empty { }
-#[doc = "
-Simple getopt alternative.
-
-Construct a vector of options, either by using reqopt, optopt, and optflag or
-by building them from components yourself, and pass them to getopts, along
-with a vector of actual arguments (not including argv[0]). You'll either get a
-failure code back, or a match. You'll have to verify whether the amount of
-'free' arguments in the match is what you expect. Use opt_* accessors to get
-argument values out of the match object.
-
-Single-character options are expected to appear on the command line with a
-single preceding dash; multiple-character options are expected to be
-proceeded by two dashes. Options that expect an argument accept their argument
-following either a space or an equals sign.
-
-# Example
-
-The following example shows simple command line parsing for an application
-that requires an input file to be specified, accepts an optional output file
-name following -o, and accepts both -h and --help as optional flags.
-
- use std;
- import std::getopts::{optopt,optflag,getopts,opt_present,opt_maybe_str,
- fail_str};
-
- fn do_work(in: str, out: option<str>) {
- // ...
- }
-
- fn print_usage(program: str) {
- io::println(\"Usage: \" + program + \" [options]/~\");
- io::println(\"-o\t\tOutput\");
- io::println(\"-h --help\tUsage\");
- }
-
- fn main(args: [str]/~) {
- check vec::is_not_empty(args);
-
- let program : str = vec::head(args);
-
- let opts = [
- optopt(\"o\"),
- optflag(\"h\"),
- optflag(\"help\")
- ]/~;
- let match = alt getopts(vec::tail(args), opts) {
- result::ok(m) { m }
- result::err(f) { fail fail_str(f) }
- };
- if opt_present(match, \"h\") || opt_present(match, \"help\") {
- print_usage(program);
- ret;
- }
- let output = opt_maybe_str(match, \"o\");
- let input = if vec::is_not_empty(match.free) {
- match.free[0]
- } else {
- print_usage(program);
- ret;
- };
- do_work(input, output);
- }
-
-"];
+/*!
+ * Simple getopt alternative.
+ *
+ * Construct a vector of options, either by using reqopt, optopt, and optflag
+ * or by building them from components yourself, and pass them to getopts,
+ * along with a vector of actual arguments (not including argv[0]). You'll
+ * either get a failure code back, or a match. You'll have to verify whether
+ * the amount of 'free' arguments in the match is what you expect. Use opt_*
+ * accessors to get argument values out of the match object.
+ *
+ * Single-character options are expected to appear on the command line with a
+ * single preceding dash; multiple-character options are expected to be
+ * proceeded by two dashes. Options that expect an argument accept their
+ * argument following either a space or an equals sign.
+ *
+ * # Example
+ *
+ * The following example shows simple command line parsing for an application
+ * that requires an input file to be specified, accepts an optional output
+ * file name following -o, and accepts both -h and --help as optional flags.
+ *
+ * use std;
+ * import std::getopts::{optopt,optflag,getopts,opt_present,opt_maybe_str,
+ * fail_str};
+ *
+ * fn do_work(in: str, out: option<str>) {
+ * // ...
+ * }
+ *
+ * fn print_usage(program: str) {
+ * io::println("Usage: " + program + " [options]/~");
+ * io::println("-o\t\tOutput");
+ * io::println("-h --help\tUsage");
+ * }
+ *
+ * fn main(args: [str]/~) {
+ * check vec::is_not_empty(args);
+ *
+ * let program : str = vec::head(args);
+ *
+ * let opts = [
+ * optopt("o"),
+ * optflag("h"),
+ * optflag("help")
+ * ]/~;
+ * let match = alt getopts(vec::tail(args), opts) {
+ * result::ok(m) { m }
+ * result::err(f) { fail fail_str(f) }
+ * };
+ * if opt_present(match, "h") || opt_present(match, "help") {
+ * print_usage(program);
+ * ret;
+ * }
+ * let output = opt_maybe_str(match, "o");
+ * let input = if vec::is_not_empty(match.free) {
+ * match.free[0]
+ * } else {
+ * print_usage(program);
+ * ret;
+ * };
+ * do_work(input, output);
+ * }
+ */
import core::result::{err, ok};
import core::option;
enum occur { req, optional, multi, }
-#[doc = "A description of a possible option"]
+/// A description of a possible option
type opt = {name: name, hasarg: hasarg, occur: occur};
fn mkname(nm: str) -> name {
} else { long(nm) };
}
-#[doc = "Create an option that is required and takes an argument"]
+/// Create an option that is required and takes an argument
fn reqopt(name: str) -> opt {
ret {name: mkname(name), hasarg: yes, occur: req};
}
-#[doc = "Create an option that is optional and takes an argument"]
+/// Create an option that is optional and takes an argument
fn optopt(name: str) -> opt {
ret {name: mkname(name), hasarg: yes, occur: optional};
}
-#[doc = "Create an option that is optional and does not take an argument"]
+/// Create an option that is optional and does not take an argument
fn optflag(name: str) -> opt {
ret {name: mkname(name), hasarg: no, occur: optional};
}
-#[doc = "Create an option that is optional and takes an optional argument"]
+/// Create an option that is optional and takes an optional argument
fn optflagopt(name: str) -> opt {
ret {name: mkname(name), hasarg: maybe, occur: optional};
}
-#[doc = "
-Create an option that is optional, takes an argument, and may occur
-multiple times
-"]
+/**
+ * Create an option that is optional, takes an argument, and may occur
+ * multiple times
+ */
fn optmulti(name: str) -> opt {
ret {name: mkname(name), hasarg: yes, occur: multi};
}
enum optval { val(str), given, }
-#[doc = "
-The result of checking command line arguments. Contains a vector
-of matches and a vector of free strings.
-"]
+/**
+ * The result of checking command line arguments. Contains a vector
+ * of matches and a vector of free strings.
+ */
type match = {opts: ~[opt], vals: ~[~[optval]], free: ~[str]};
fn is_arg(arg: str) -> bool {
vec::position(opts, |opt| opt.name == nm)
}
-#[doc = "
-The type returned when the command line does not conform to the
-expected format. Pass this value to <fail_str> to get an error message.
-"]
+/**
+ * The type returned when the command line does not conform to the
+ * expected format. Pass this value to <fail_str> to get an error message.
+ */
enum fail_ {
argument_missing(str),
unrecognized_option(str),
unexpected_argument(str),
}
-#[doc = "Convert a `fail_` enum into an error string"]
+/// Convert a `fail_` enum into an error string
fn fail_str(f: fail_) -> str {
ret alt f {
argument_missing(nm) { "Argument to option '" + nm + "' missing." }
};
}
-#[doc = "
-The result of parsing a command line with a set of options
-(result::t<match, fail_>)
-"]
+/**
+ * The result of parsing a command line with a set of options
+ * (result::t<match, fail_>)
+ */
type result = result::result<match, fail_>;
-#[doc = "
-Parse command line arguments according to the provided options
-
-On success returns `ok(opt)`. Use functions such as `opt_present` `opt_str`,
-etc. to interrogate results. Returns `err(fail_)` on failure. Use <fail_str>
-to get an error message.
-"]
+/**
+ * Parse command line arguments according to the provided options
+ *
+ * On success returns `ok(opt)`. Use functions such as `opt_present`
+ * `opt_str`, etc. to interrogate results. Returns `err(fail_)` on failure.
+ * Use <fail_str> to get an error message.
+ */
fn getopts(args: ~[str], opts: ~[opt]) -> result unsafe {
let n_opts = vec::len::<opt>(opts);
fn f(_x: uint) -> ~[optval] { ret ~[]; }
fn opt_val(m: match, nm: str) -> optval { ret opt_vals(m, nm)[0]; }
-#[doc = "Returns true if an option was matched"]
+/// Returns true if an option was matched
fn opt_present(m: match, nm: str) -> bool {
ret vec::len::<optval>(opt_vals(m, nm)) > 0u;
}
-#[doc = "Returns true if any of several options were matched"]
+/// Returns true if any of several options were matched
fn opts_present(m: match, names: ~[str]) -> bool {
for vec::each(names) |nm| {
alt find_opt(m.opts, mkname(nm)) {
}
-#[doc = "
-Returns the string argument supplied to a matching option
-
-Fails if the option was not matched or if the match did not take an argument
-"]
+/**
+ * Returns the string argument supplied to a matching option
+ *
+ * Fails if the option was not matched or if the match did not take an
+ * argument
+ */
fn opt_str(m: match, nm: str) -> str {
ret alt opt_val(m, nm) { val(s) { s } _ { fail } };
}
-#[doc = "
-Returns the string argument supplied to one of several matching options
-
-Fails if the no option was provided from the given list, or if the no such
-option took an argument
-"]
+/**
+ * Returns the string argument supplied to one of several matching options
+ *
+ * Fails if the no option was provided from the given list, or if the no such
+ * option took an argument
+ */
fn opts_str(m: match, names: ~[str]) -> str {
for vec::each(names) |nm| {
alt opt_val(m, nm) {
}
-#[doc = "
-Returns a vector of the arguments provided to all matches of the given option.
-
-Used when an option accepts multiple values.
-"]
+/**
+ * Returns a vector of the arguments provided to all matches of the given
+ * option.
+ *
+ * Used when an option accepts multiple values.
+ */
fn opt_strs(m: match, nm: str) -> ~[str] {
let mut acc: ~[str] = ~[];
for vec::each(opt_vals(m, nm)) |v| {
ret acc;
}
-#[doc = "
-Returns the string argument supplied to a matching option or none
-"]
+/// Returns the string argument supplied to a matching option or none
fn opt_maybe_str(m: match, nm: str) -> option<str> {
let vals = opt_vals(m, nm);
if vec::len::<optval>(vals) == 0u { ret none::<str>; }
}
-#[doc = "
-Returns the matching string, a default, or none
-
-Returns none if the option was not present, `def` if the option was
-present but no argument was provided, and the argument if the option was
-present and an argument was provided.
-"]
+/**
+ * Returns the matching string, a default, or none
+ *
+ * Returns none if the option was not present, `def` if the option was
+ * present but no argument was provided, and the argument if the option was
+ * present and an argument was provided.
+ */
fn opt_default(m: match, nm: str, def: str) -> option<str> {
let vals = opt_vals(m, nm);
if vec::len::<optval>(vals) == 0u { ret none::<str>; }
// Rust JSON serialization library
// Copyright (c) 2011 Google Inc.
-#[doc = "json serialization"];
+//! json serialization
import result::{result, ok, err};
import io;
export dict;
export null;
-#[doc = "Represents a json value"]
+/// Represents a json value
enum json {
num(float),
string(@str),
msg: @str,
};
-#[doc = "Serializes a json value into a io::writer"]
+/// Serializes a json value into a io::writer
fn to_writer(wr: io::writer, j: json) {
alt j {
num(n) { wr.write_str(float::to_str(n, 6u)); }
escaped
}
-#[doc = "Serializes a json value into a string"]
+/// Serializes a json value into a string
fn to_str(j: json) -> str {
io::with_str_writer(|wr| to_writer(wr, j))
}
}
}
-#[doc = "Deserializes a json value from an io::reader"]
+/// Deserializes a json value from an io::reader
fn from_reader(rdr: io::reader) -> result<json, error> {
let parser = {
rdr: rdr,
parser.parse()
}
-#[doc = "Deserializes a json value from a string"]
+/// Deserializes a json value from a string
fn from_str(s: str) -> result<json, error> {
io::with_str_reader(s, from_reader)
}
-#[doc = "Test if two json values are equal"]
+/// Test if two json values are equal
fn eq(value0: json, value1: json) -> bool {
alt (value0, value1) {
(num(f0), num(f1)) { f0 == f1 }
-#[doc = "A standard linked list"];
+//! A standard linked list
import core::option;
import option::*;
nil,
}
-#[doc = "Create a list from a vector"]
+/// Create a list from a vector
fn from_vec<T: copy>(v: &[T]) -> @list<T> {
vec::foldr(v, @nil::<T>, |h, t| @cons(h, t))
}
-#[doc = "
-Left fold
-
-Applies `f` to `u` and the first element in the list, then applies `f` to the
-result of the previous call and the second element, and so on, returning the
-accumulated result.
-
-# Arguments
-
-* ls - The list to fold
-* z - The initial value
-* f - The function to apply
-"]
+/**
+ * Left fold
+ *
+ * Applies `f` to `u` and the first element in the list, then applies `f` to
+ * the result of the previous call and the second element, and so on,
+ * returning the accumulated result.
+ *
+ * # Arguments
+ *
+ * * ls - The list to fold
+ * * z - The initial value
+ * * f - The function to apply
+ */
fn foldl<T: copy, U>(z: T, ls: @list<U>, f: fn(T, U) -> T) -> T {
let mut accum: T = z;
do iter(ls) |elt| { accum = f(accum, elt);}
accum
}
-#[doc = "
-Search for an element that matches a given predicate
-
-Apply function `f` to each element of `v`, starting from the first.
-When function `f` returns true then an option containing the element
-is returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Search for an element that matches a given predicate
+ *
+ * Apply function `f` to each element of `v`, starting from the first.
+ * When function `f` returns true then an option containing the element
+ * is returned. If `f` matches no elements then none is returned.
+ */
fn find<T: copy>(ls: @list<T>, f: fn(T) -> bool) -> option<T> {
let mut ls = ls;
loop {
};
}
-#[doc = "Returns true if a list contains an element with the given value"]
+/// Returns true if a list contains an element with the given value
fn has<T: copy>(ls: @list<T>, elt: T) -> bool {
for each(ls) |e| {
if e == elt { ret true; }
ret false;
}
-#[doc = "Returns true if the list is empty"]
+/// Returns true if the list is empty
pure fn is_empty<T: copy>(ls: @list<T>) -> bool {
alt *ls {
nil { true }
}
}
-#[doc = "Returns true if the list is not empty"]
+/// Returns true if the list is not empty
pure fn is_not_empty<T: copy>(ls: @list<T>) -> bool {
ret !is_empty(ls);
}
-#[doc = "Returns the length of a list"]
+/// Returns the length of a list
fn len<T>(ls: @list<T>) -> uint {
let mut count = 0u;
iter(ls, |_e| count += 1u);
count
}
-#[doc = "Returns all but the first element of a list"]
+/// Returns all but the first element of a list
pure fn tail<T: copy>(ls: @list<T>) -> @list<T> {
alt *ls {
cons(_, tl) { ret tl; }
}
}
-#[doc = "Returns the first element of a list"]
+/// Returns the first element of a list
pure fn head<T: copy>(ls: @list<T>) -> T {
alt check *ls { cons(hd, _) { hd } }
}
-#[doc = "Appends one list to another"]
+/// Appends one list to another
pure fn append<T: copy>(l: @list<T>, m: @list<T>) -> @list<T> {
alt *l {
nil { ret m; }
}
}
-#[doc = "Push an element to the front of a list"]
+/// Push an element to the front of a list
fn push<T: copy>(&l: list<T>, v: T) {
l = cons(v, @l);
}
-#[doc = "Iterate over a list"]
+/// Iterate over a list
fn iter<T>(l: @list<T>, f: fn(T)) {
let mut cur = l;
loop {
}
}
-#[doc = "Iterate over a list"]
+/// Iterate over a list
fn each<T>(l: @list<T>, f: fn(T) -> bool) {
let mut cur = l;
loop {
-#[doc = "A map type"];
+//! A map type
import chained::hashmap;
export hashmap, hashfn, eqfn, set, map, chained, hashmap, str_hash;
export hash_from_ints, hash_from_uints;
export vec_from_set;
-#[doc = "
-A function that returns a hash of a value
-
-The hash should concentrate entropy in the lower bits.
-"]
+/**
+ * A function that returns a hash of a value
+ *
+ * The hash should concentrate entropy in the lower bits.
+ */
type hashfn<K> = fn@(K) -> uint;
type eqfn<K> = fn@(K, K) -> bool;
-#[doc = "A convenience type to treat a hashmap as a set"]
+/// A convenience type to treat a hashmap as a set
type set<K> = hashmap<K, ()>;
type hashmap<K, V> = chained::t<K, V>;
iface map<K, V: copy> {
- #[doc = "Return the number of elements in the map"]
+ /// Return the number of elements in the map
fn size() -> uint;
- #[doc = "
- Add a value to the map.
-
- If the map already contains a value for the specified key then the
- original value is replaced.
-
- Returns true if the key did not already exist in the map
- "]
+ /**
+ * Add a value to the map.
+ *
+ * If the map already contains a value for the specified key then the
+ * original value is replaced.
+ *
+ * Returns true if the key did not already exist in the map
+ */
fn insert(+K, +V) -> bool;
- #[doc = "Returns true if the map contains a value for the specified key"]
+ /// Returns true if the map contains a value for the specified key
fn contains_key(K) -> bool;
- #[doc = "
- Get the value for the specified key. Fails if the key does not exist in
- the map.
- "]
+ /**
+ * Get the value for the specified key. Fails if the key does not exist in
+ * the map.
+ */
fn get(K) -> V;
- #[doc = "Like get, but as an operator."]
+ /// Like get, but as an operator.
fn [](K) -> V;
- #[doc = "
- Get the value for the specified key. If the key does not exist in
- the map then returns none.
- "]
+ /**
+ * Get the value for the specified key. If the key does not exist in
+ * the map then returns none.
+ */
fn find(K) -> option<V>;
- #[doc = "
- Remove and return a value from the map. If the key does not exist
- in the map then returns none.
- "]
+ /**
+ * Remove and return a value from the map. If the key does not exist
+ * in the map then returns none.
+ */
fn remove(K) -> option<V>;
- #[doc = "Iterate over all the key/value pairs in the map"]
+ /// Iterate over all the key/value pairs in the map
fn each(fn(K, V) -> bool);
- #[doc = "Iterate over all the keys in the map"]
+ /// Iterate over all the keys in the map
fn each_key(fn(K) -> bool);
- #[doc = "Iterate over all the values in the map"]
+ /// Iterate over all the values in the map
fn each_value(fn(V) -> bool);
}
chained::mk(hasher, eqer)
}
-#[doc = "Construct a hashmap for string keys"]
+/// Construct a hashmap for string keys
fn str_hash<V: copy>() -> hashmap<str, V> {
ret hashmap(str::hash, str::eq);
}
-#[doc = "Construct a hashmap for boxed string keys"]
+/// Construct a hashmap for boxed string keys
fn box_str_hash<V: copy>() -> hashmap<@str, V> {
ret hashmap(|x: @str| str::hash(*x), |x,y| str::eq(*x,*y));
}
-#[doc = "Construct a hashmap for byte string keys"]
+/// Construct a hashmap for byte string keys
fn bytes_hash<V: copy>() -> hashmap<~[u8], V> {
ret hashmap(vec::u8::hash, vec::u8::eq);
}
-#[doc = "Construct a hashmap for int keys"]
+/// Construct a hashmap for int keys
fn int_hash<V: copy>() -> hashmap<int, V> {
ret hashmap(int::hash, int::eq);
}
-#[doc = "Construct a hashmap for uint keys"]
+/// Construct a hashmap for uint keys
fn uint_hash<V: copy>() -> hashmap<uint, V> {
ret hashmap(uint::hash, uint::eq);
}
-#[doc = "
-Convenience function for adding keys to a hashmap with nil type keys
-"]
+/// Convenience function for adding keys to a hashmap with nil type keys
fn set_add<K: const copy>(set: set<K>, key: K) -> bool {
ret set.insert(key, ());
}
-#[doc = "
-Convert a set into a vector.
-"]
+/// Convert a set into a vector.
fn vec_from_set<T: copy>(s: set<T>) -> ~[T] {
let mut v = ~[];
do s.each_key() |k| {
v
}
-#[doc = "Construct a hashmap from a vector"]
+/// Construct a hashmap from a vector
fn hash_from_vec<K: const copy, V: copy>(hasher: hashfn<K>, eqer: eqfn<K>,
items: ~[(K, V)]) -> hashmap<K, V> {
let map = hashmap(hasher, eqer);
map
}
-#[doc = "Construct a hashmap from a vector with string keys"]
+/// Construct a hashmap from a vector with string keys
fn hash_from_strs<V: copy>(items: ~[(str, V)]) -> hashmap<str, V> {
hash_from_vec(str::hash, str::eq, items)
}
-#[doc = "Construct a hashmap from a vector with byte keys"]
+/// Construct a hashmap from a vector with byte keys
fn hash_from_bytes<V: copy>(items: ~[(~[u8], V)]) -> hashmap<~[u8], V> {
hash_from_vec(vec::u8::hash, vec::u8::eq, items)
}
-#[doc = "Construct a hashmap from a vector with int keys"]
+/// Construct a hashmap from a vector with int keys
fn hash_from_ints<V: copy>(items: ~[(int, V)]) -> hashmap<int, V> {
hash_from_vec(int::hash, int::eq, items)
}
-#[doc = "Construct a hashmap from a vector with uint keys"]
+/// Construct a hashmap from a vector with uint keys
fn hash_from_uints<V: copy>(items: ~[(uint, V)]) -> hashmap<uint, V> {
hash_from_vec(uint::hash, uint::eq, items)
}
-#[doc="
-Top-level module for network-related functionality
-"];
+//! Top-level module for network-related functionality
import tcp = net_tcp;
export tcp;
-#[doc="
-Types/fns concerning Internet Protocol (IP), versions 4 & 6
-"];
+//! Types/fns concerning Internet Protocol (IP), versions 4 & 6
import vec;
import uint;
export v4, v6;
export get_addr;
-#[doc = "An IP address"]
+/// An IP address
enum ip_addr {
- #[doc="An IPv4 address"]
+ /// An IPv4 address
ipv4(sockaddr_in),
ipv6(sockaddr_in6)
}
-#[doc="
-Human-friendly feedback on why a parse_addr attempt failed
-"]
+/// Human-friendly feedback on why a parse_addr attempt failed
type parse_addr_err = {
err_msg: str
};
-#[doc="
-Convert a `ip_addr` to a str
-
-# Arguments
-
-* ip - a `std::net::ip::ip_addr`
-"]
+/**
+ * Convert a `ip_addr` to a str
+ *
+ * # Arguments
+ *
+ * * ip - a `std::net::ip::ip_addr`
+ */
fn format_addr(ip: ip_addr) -> str {
alt ip {
ipv4(addr) {
}
}
-#[doc="
-Represents errors returned from `net::ip::get_addr()`
-"]
+/// Represents errors returned from `net::ip::get_addr()`
enum ip_get_addr_err {
get_addr_unknown_error
}
-#[doc="
-Attempts name resolution on the provided `node` string
-
-# Arguments
-
-* `node` - a string representing some host address
-* `iotask` - a `uv::iotask` used to interact with the underlying event loop
-
-# Returns
-
-A `result<[ip_addr]/~, ip_get_addr_err>` instance that will contain
-a vector of `ip_addr` results, in the case of success, or an error
-object in the case of failure
-"]
+/**
+ * Attempts name resolution on the provided `node` string
+ *
+ * # Arguments
+ *
+ * * `node` - a string representing some host address
+ * * `iotask` - a `uv::iotask` used to interact with the underlying event loop
+ *
+ * # Returns
+ *
+ * A `result<[ip_addr]/~, ip_get_addr_err>` instance that will contain
+ * a vector of `ip_addr` results, in the case of success, or an error
+ * object in the case of failure
+ */
fn get_addr(++node: str, iotask: iotask)
-> result::result<[ip_addr]/~, ip_get_addr_err> unsafe {
do comm::listen |output_ch| {
}
mod v4 {
- #[doc = "
- Convert a str to `ip_addr`
-
- # Failure
-
- Fails if the string is not a valid IPv4 address
-
- # Arguments
-
- * ip - a string of the format `x.x.x.x`
-
- # Returns
-
- * an `ip_addr` of the `ipv4` variant
- "]
+ /**
+ * Convert a str to `ip_addr`
+ *
+ * # Failure
+ *
+ * Fails if the string is not a valid IPv4 address
+ *
+ * # Arguments
+ *
+ * * ip - a string of the format `x.x.x.x`
+ *
+ * # Returns
+ *
+ * * an `ip_addr` of the `ipv4` variant
+ */
fn parse_addr(ip: str) -> ip_addr {
alt try_parse_addr(ip) {
result::ok(addr) { copy(addr) }
}
}
mod v6 {
- #[doc = "
- Convert a str to `ip_addr`
-
- # Failure
-
- Fails if the string is not a valid IPv6 address
-
- # Arguments
-
- * ip - an ipv6 string. See RFC2460 for spec.
-
- # Returns
-
- * an `ip_addr` of the `ipv6` variant
- "]
+ /**
+ * Convert a str to `ip_addr`
+ *
+ * # Failure
+ *
+ * Fails if the string is not a valid IPv6 address
+ *
+ * # Arguments
+ *
+ * * ip - an ipv6 string. See RFC2460 for spec.
+ *
+ * # Returns
+ *
+ * * an `ip_addr` of the `ipv6` variant
+ */
fn parse_addr(ip: str) -> ip_addr {
alt try_parse_addr(ip) {
result::ok(addr) { copy(addr) }
-#[doc="
-High-level interface to libuv's TCP functionality
-"];
+//! High-level interface to libuv's TCP functionality
import ip = net_ip;
import uv::iotask;
fn rust_uv_helper_uv_tcp_t_size() -> libc::c_uint;
}
-#[doc="
-Encapsulates an open TCP/IP connection through libuv
-
-`tcp_socket` is non-copyable/sendable and automagically handles closing the
-underlying libuv data structures when it goes out of scope. This is the
-data structure that is used for read/write operations over a TCP stream.
-"]
+/**
+ * Encapsulates an open TCP/IP connection through libuv
+ *
+ * `tcp_socket` is non-copyable/sendable and automagically handles closing the
+ * underlying libuv data structures when it goes out of scope. This is the
+ * data structure that is used for read/write operations over a TCP stream.
+ */
class tcp_socket {
let socket_data: @tcp_socket_data;
new(socket_data: @tcp_socket_data) { self.socket_data = socket_data; }
}
}
-#[doc="
-A buffered wrapper for `net::tcp::tcp_socket`
-
-It is created with a call to `net::tcp::socket_buf()` and has impls that
-satisfy both the `io::reader` and `io::writer` ifaces.
-"]
+/**
+ * A buffered wrapper for `net::tcp::tcp_socket`
+ *
+ * It is created with a call to `net::tcp::socket_buf()` and has impls that
+ * satisfy both the `io::reader` and `io::writer` ifaces.
+ */
class tcp_socket_buf {
let data: @tcp_buffered_socket_data;
new(data: @tcp_buffered_socket_data) { self.data = data; }
}
-#[doc="
-Contains raw, string-based, error information returned from libuv
-"]
+/// Contains raw, string-based, error information returned from libuv
type tcp_err_data = {
err_name: str,
err_msg: str
};
-#[doc="
-Details returned as part of a `result::err` result from `tcp::listen`
-"]
+/// Details returned as part of a `result::err` result from `tcp::listen`
enum tcp_listen_err_data {
- #[doc="
- Some unplanned-for error. The first and second fields correspond
- to libuv's `err_name` and `err_msg` fields, respectively.
- "]
+ /**
+ * Some unplanned-for error. The first and second fields correspond
+ * to libuv's `err_name` and `err_msg` fields, respectively.
+ */
generic_listen_err(str, str),
- #[doc="
- Failed to bind to the requested IP/Port, because it is already in use.
-
- # Possible Causes
-
- * Attempting to bind to a port already bound to another listener
- "]
+ /**
+ * Failed to bind to the requested IP/Port, because it is already in use.
+ *
+ * # Possible Causes
+ *
+ * * Attempting to bind to a port already bound to another listener
+ */
address_in_use,
- #[doc="
- Request to bind to an IP/Port was denied by the system.
-
- # Possible Causes
-
- * Attemping to binding to an IP/Port as a non-Administrator
- on Windows Vista+
- * Attempting to bind, as a non-priv'd
- user, to 'privileged' ports (< 1024) on *nix
- "]
+ /**
+ * Request to bind to an IP/Port was denied by the system.
+ *
+ * # Possible Causes
+ *
+ * * Attemping to binding to an IP/Port as a non-Administrator
+ * on Windows Vista+
+ * * Attempting to bind, as a non-priv'd
+ * user, to 'privileged' ports (< 1024) on *nix
+ */
access_denied
}
-#[doc="
-Details returned as part of a `result::err` result from `tcp::connect`
-"]
+/// Details returned as part of a `result::err` result from `tcp::connect`
enum tcp_connect_err_data {
- #[doc="
- Some unplanned-for error. The first and second fields correspond
- to libuv's `err_name` and `err_msg` fields, respectively.
- "]
+ /**
+ * Some unplanned-for error. The first and second fields correspond
+ * to libuv's `err_name` and `err_msg` fields, respectively.
+ */
generic_connect_err(str, str),
- #[doc="
- Invalid IP or invalid port
- "]
+ /// Invalid IP or invalid port
connection_refused
}
-#[doc="
-Initiate a client connection over TCP/IP
-
-# Arguments
-
-* `input_ip` - The IP address (versions 4 or 6) of the remote host
-* `port` - the unsigned integer of the desired remote host port
-* `iotask` - a `uv::iotask` that the tcp request will run on
-
-# Returns
-
-A `result` that, if the operation succeeds, contains a `net::net::tcp_socket`
-that can be used to send and receive data to/from the remote host. In the
-event of failure, a `net::tcp::tcp_connect_err_data` instance will be
-returned
-"]
+/**
+ * Initiate a client connection over TCP/IP
+ *
+ * # Arguments
+ *
+ * * `input_ip` - The IP address (versions 4 or 6) of the remote host
+ * * `port` - the unsigned integer of the desired remote host port
+ * * `iotask` - a `uv::iotask` that the tcp request will run on
+ *
+ * # Returns
+ *
+ * A `result` that, if the operation succeeds, contains a
+ * `net::net::tcp_socket` that can be used to send and receive data to/from
+ * the remote host. In the event of failure, a
+ * `net::tcp::tcp_connect_err_data` instance will be returned
+ */
fn connect(-input_ip: ip::ip_addr, port: uint,
iotask: iotask)
-> result::result<tcp_socket, tcp_connect_err_data> unsafe {
}
}
-#[doc="
-Write binary data to a tcp stream; Blocks until operation completes
-
-# Arguments
-
-* sock - a `tcp_socket` to write to
-* raw_write_data - a vector of `[u8]/~` that will be written to the stream.
-This value must remain valid for the duration of the `write` call
-
-# Returns
-
-A `result` object with a `nil` value as the `ok` variant, or a `tcp_err_data`
-value as the `err` variant
-"]
+/**
+ * Write binary data to a tcp stream; Blocks until operation completes
+ *
+ * # Arguments
+ *
+ * * sock - a `tcp_socket` to write to
+ * * raw_write_data - a vector of `[u8]/~` that will be written to the stream.
+ * This value must remain valid for the duration of the `write` call
+ *
+ * # Returns
+ *
+ * A `result` object with a `nil` value as the `ok` variant, or a
+ * `tcp_err_data` value as the `err` variant
+ */
fn write(sock: tcp_socket, raw_write_data: ~[u8])
-> result::result<(), tcp_err_data> unsafe {
let socket_data_ptr = ptr::addr_of(*(sock.socket_data));
write_common_impl(socket_data_ptr, raw_write_data)
}
-#[doc="
-Write binary data to tcp stream; Returns a `future::future` value immediately
-
-# Safety
-
-This function can produce unsafe results if:
-
-1. the call to `write_future` is made
-2. the `future::future` value returned is never resolved via
-`future::get`
-3. and then the `tcp_socket` passed in to `write_future` leaves
-scope and is destructed before the task that runs the libuv write
-operation completes.
-
-As such: If using `write_future`, always be sure to resolve the returned
-`future` so as to ensure libuv doesn't try to access a released write handle.
-Otherwise, use the blocking `tcp::write` function instead.
-
-# Arguments
-
-* sock - a `tcp_socket` to write to
-* raw_write_data - a vector of `[u8]/~` that will be written to the stream.
-This value must remain valid for the duration of the `write` call
-
-# Returns
-
-A `future` value that, once the `write` operation completes, resolves to a
-`result` object with a `nil` value as the `ok` variant, or a `tcp_err_data`
-value as the `err` variant
-"]
+/**
+ * Write binary data to tcp stream; Returns a `future::future` value
+ * immediately
+ *
+ * # Safety
+ *
+ * This function can produce unsafe results if:
+ *
+ * 1. the call to `write_future` is made
+ * 2. the `future::future` value returned is never resolved via
+ * `future::get`
+ * 3. and then the `tcp_socket` passed in to `write_future` leaves
+ * scope and is destructed before the task that runs the libuv write
+ * operation completes.
+ *
+ * As such: If using `write_future`, always be sure to resolve the returned
+ * `future` so as to ensure libuv doesn't try to access a released write
+ * handle. Otherwise, use the blocking `tcp::write` function instead.
+ *
+ * # Arguments
+ *
+ * * sock - a `tcp_socket` to write to
+ * * raw_write_data - a vector of `[u8]/~` that will be written to the stream.
+ * This value must remain valid for the duration of the `write` call
+ *
+ * # Returns
+ *
+ * A `future` value that, once the `write` operation completes, resolves to a
+ * `result` object with a `nil` value as the `ok` variant, or a `tcp_err_data`
+ * value as the `err` variant
+ */
fn write_future(sock: tcp_socket, raw_write_data: ~[u8])
-> future::future<result::result<(), tcp_err_data>> unsafe {
let socket_data_ptr = ptr::addr_of(*(sock.socket_data));
}
}
-#[doc="
-Begin reading binary data from an open TCP connection; used with `read_stop`
-
-# Arguments
-
-* sock -- a `net::tcp::tcp_socket` for the connection to read from
-
-# Returns
-
-* A `result` instance that will either contain a
-`comm::port<tcp_read_result>` that the user can read (and optionally, loop
-on) from until `read_stop` is called, or a `tcp_err_data` record
-"]
+/**
+ * Begin reading binary data from an open TCP connection; used with
+ * `read_stop`
+ *
+ * # Arguments
+ *
+ * * sock -- a `net::tcp::tcp_socket` for the connection to read from
+ *
+ * # Returns
+ *
+ * * A `result` instance that will either contain a
+ * `comm::port<tcp_read_result>` that the user can read (and optionally, loop
+ * on) from until `read_stop` is called, or a `tcp_err_data` record
+ */
fn read_start(sock: tcp_socket)
-> result::result<comm::port<
result::result<~[u8], tcp_err_data>>, tcp_err_data> unsafe {
read_start_common_impl(socket_data)
}
-#[doc="
-Stop reading from an open TCP connection; used with `read_start`
-
-# Arguments
-
-* `sock` - a `net::tcp::tcp_socket` that you wish to stop reading on
-"]
+/**
+ * Stop reading from an open TCP connection; used with `read_start`
+ *
+ * # Arguments
+ *
+ * * `sock` - a `net::tcp::tcp_socket` that you wish to stop reading on
+ */
fn read_stop(sock: tcp_socket,
-read_port: comm::port<result::result<[u8]/~, tcp_err_data>>) ->
result::result<(), tcp_err_data> unsafe {
read_stop_common_impl(socket_data)
}
-#[doc="
-Reads a single chunk of data from `tcp_socket`; block until data/error recv'd
-
-Does a blocking read operation for a single chunk of data from a `tcp_socket`
-until a data arrives or an error is received. The provided `timeout_msecs`
-value is used to raise an error if the timeout period passes without any
-data received.
-
-# Arguments
-
-* `sock` - a `net::tcp::tcp_socket` that you wish to read from
-* `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
-read attempt. Pass `0u` to wait indefinitely
-"]
+/**
+ * Reads a single chunk of data from `tcp_socket`; block until data/error
+ * recv'd
+ *
+ * Does a blocking read operation for a single chunk of data from a
+ * `tcp_socket` until a data arrives or an error is received. The provided
+ * `timeout_msecs` value is used to raise an error if the timeout period
+ * passes without any data received.
+ *
+ * # Arguments
+ *
+ * * `sock` - a `net::tcp::tcp_socket` that you wish to read from
+ * * `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
+ * read attempt. Pass `0u` to wait indefinitely
+ */
fn read(sock: tcp_socket, timeout_msecs: uint)
-> result::result<~[u8],tcp_err_data> {
let socket_data = ptr::addr_of(*(sock.socket_data));
read_common_impl(socket_data, timeout_msecs)
}
-#[doc="
-Reads a single chunk of data; returns a `future::future<[u8]/~>` immediately
-
-Does a non-blocking read operation for a single chunk of data from a
-`tcp_socket` and immediately returns a `future` value representing the
-result. When resolving the returned `future`, it will block until data
-arrives or an error is received. The provided `timeout_msecs`
-value is used to raise an error if the timeout period passes without any
-data received.
-
-# Safety
-
-This function can produce unsafe results if the call to `read_future` is
-made, the `future::future` value returned is never resolved via
-`future::get`, and then the `tcp_socket` passed in to `read_future` leaves
-scope and is destructed before the task that runs the libuv read
-operation completes.
-
-As such: If using `read_future`, always be sure to resolve the returned
-`future` so as to ensure libuv doesn't try to access a released read handle.
-Otherwise, use the blocking `tcp::read` function instead.
-
-# Arguments
-
-* `sock` - a `net::tcp::tcp_socket` that you wish to read from
-* `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
-read attempt. Pass `0u` to wait indefinitely
-"]
+/**
+ * Reads a single chunk of data; returns a `future::future<[u8]/~>`
+ * immediately
+ *
+ * Does a non-blocking read operation for a single chunk of data from a
+ * `tcp_socket` and immediately returns a `future` value representing the
+ * result. When resolving the returned `future`, it will block until data
+ * arrives or an error is received. The provided `timeout_msecs`
+ * value is used to raise an error if the timeout period passes without any
+ * data received.
+ *
+ * # Safety
+ *
+ * This function can produce unsafe results if the call to `read_future` is
+ * made, the `future::future` value returned is never resolved via
+ * `future::get`, and then the `tcp_socket` passed in to `read_future` leaves
+ * scope and is destructed before the task that runs the libuv read
+ * operation completes.
+ *
+ * As such: If using `read_future`, always be sure to resolve the returned
+ * `future` so as to ensure libuv doesn't try to access a released read
+ * handle. Otherwise, use the blocking `tcp::read` function instead.
+ *
+ * # Arguments
+ *
+ * * `sock` - a `net::tcp::tcp_socket` that you wish to read from
+ * * `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
+ * read attempt. Pass `0u` to wait indefinitely
+ */
fn read_future(sock: tcp_socket, timeout_msecs: uint)
-> future::future<result::result<~[u8],tcp_err_data>> {
let socket_data = ptr::addr_of(*(sock.socket_data));
}
}
-#[doc="
-Bind an incoming client connection to a `net::tcp::tcp_socket`
-
-# Notes
-
-It is safe to call `net::tcp::accept` _only_ within the context of the
-`new_connect_cb` callback provided as the final argument to the
-`net::tcp::listen` function.
-
-The `new_conn` opaque value is provided _only_ as the first argument to the
-`new_connect_cb` provided as a part of `net::tcp::listen`.
-It can be safely sent to another task but it _must_ be
-used (via `net::tcp::accept`) before the `new_connect_cb` call it was
-provided to returns.
-
-This implies that a port/chan pair must be used to make sure that the
-`new_connect_cb` call blocks until an attempt to create a
-`net::tcp::tcp_socket` is completed.
-
-# Example
-
-Here, the `new_conn` is used in conjunction with `accept` from within
-a task spawned by the `new_connect_cb` passed into `listen`
-
-~~~~~~~~~~~
-net::tcp::listen(remote_ip, remote_port, backlog)
- // this callback is ran once after the connection is successfully
- // set up
- {|kill_ch|
- // pass the kill_ch to your main loop or wherever you want
- // to be able to externally kill the server from
- }
- // this callback is ran when a new connection arrives
- {|new_conn, kill_ch|
- let cont_po = comm::port::<option<tcp_err_data>>();
- let cont_ch = comm::chan(cont_po);
- task::spawn {||
- let accept_result = net::tcp::accept(new_conn);
- if accept_result.is_err() {
- comm::send(cont_ch, result::get_err(accept_result));
- // fail?
- }
- else {
- let sock = result::get(accept_result);
- comm::send(cont_ch, true);
- // do work here
- }
- };
- alt comm::recv(cont_po) {
- // shut down listen()
- some(err_data) { comm::send(kill_chan, some(err_data)) }
- // wait for next connection
- none {}
- }
-};
-~~~~~~~~~~~
-
-# Arguments
-
-* `new_conn` - an opaque value used to create a new `tcp_socket`
-
-# Returns
-
-On success, this function will return a `net::tcp::tcp_socket` as the
-`ok` variant of a `result`. The `net::tcp::tcp_socket` is anchored within
-the task that `accept` was called within for its lifetime. On failure,
-this function will return a `net::tcp::tcp_err_data` record
-as the `err` variant of a `result`.
-"]
+/**
+ * Bind an incoming client connection to a `net::tcp::tcp_socket`
+ *
+ * # Notes
+ *
+ * It is safe to call `net::tcp::accept` _only_ within the context of the
+ * `new_connect_cb` callback provided as the final argument to the
+ * `net::tcp::listen` function.
+ *
+ * The `new_conn` opaque value is provided _only_ as the first argument to the
+ * `new_connect_cb` provided as a part of `net::tcp::listen`.
+ * It can be safely sent to another task but it _must_ be
+ * used (via `net::tcp::accept`) before the `new_connect_cb` call it was
+ * provided to returns.
+ *
+ * This implies that a port/chan pair must be used to make sure that the
+ * `new_connect_cb` call blocks until an attempt to create a
+ * `net::tcp::tcp_socket` is completed.
+ *
+ * # Example
+ *
+ * Here, the `new_conn` is used in conjunction with `accept` from within
+ * a task spawned by the `new_connect_cb` passed into `listen`
+ *
+ * ~~~~~~~~~~~
+ * net::tcp::listen(remote_ip, remote_port, backlog)
+ * // this callback is ran once after the connection is successfully
+ * // set up
+ * {|kill_ch|
+ * // pass the kill_ch to your main loop or wherever you want
+ * // to be able to externally kill the server from
+ * }
+ * // this callback is ran when a new connection arrives
+ * {|new_conn, kill_ch|
+ * let cont_po = comm::port::<option<tcp_err_data>>();
+ * let cont_ch = comm::chan(cont_po);
+ * task::spawn {||
+ * let accept_result = net::tcp::accept(new_conn);
+ * if accept_result.is_err() {
+ * comm::send(cont_ch, result::get_err(accept_result));
+ * // fail?
+ * }
+ * else {
+ * let sock = result::get(accept_result);
+ * comm::send(cont_ch, true);
+ * // do work here
+ * }
+ * };
+ * alt comm::recv(cont_po) {
+ * // shut down listen()
+ * some(err_data) { comm::send(kill_chan, some(err_data)) }
+ * // wait for next connection
+ * none {}
+ * }
+ * };
+ * ~~~~~~~~~~~
+ *
+ * # Arguments
+ *
+ * * `new_conn` - an opaque value used to create a new `tcp_socket`
+ *
+ * # Returns
+ *
+ * On success, this function will return a `net::tcp::tcp_socket` as the
+ * `ok` variant of a `result`. The `net::tcp::tcp_socket` is anchored within
+ * the task that `accept` was called within for its lifetime. On failure,
+ * this function will return a `net::tcp::tcp_err_data` record
+ * as the `err` variant of a `result`.
+ */
fn accept(new_conn: tcp_new_connection)
-> result::result<tcp_socket, tcp_err_data> unsafe {
}
}
-#[doc="
-Bind to a given IP/port and listen for new connections
-
-# Arguments
-
-* `host_ip` - a `net::ip::ip_addr` representing a unique IP
-(versions 4 or 6)
-* `port` - a uint representing the port to listen on
-* `backlog` - a uint representing the number of incoming connections
-to cache in memory
-* `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
-* `on_establish_cb` - a callback that is evaluated if/when the listener
-is successfully established. it takes no parameters
-* `new_connect_cb` - a callback to be evaluated, on the libuv thread,
-whenever a client attempts to conect on the provided ip/port. the
-callback's arguments are:
- * `new_conn` - an opaque type that can be passed to
- `net::tcp::accept` in order to be converted to a `tcp_socket`.
- * `kill_ch` - channel of type `comm::chan<option<tcp_err_data>>`. this
- channel can be used to send a message to cause `listen` to begin
- closing the underlying libuv data structures.
-
-# returns
-
-a `result` instance containing empty data of type `()` on a
-successful/normal shutdown, and a `tcp_listen_err_data` enum in the event
-of listen exiting because of an error
-"]
+/**
+ * Bind to a given IP/port and listen for new connections
+ *
+ * # Arguments
+ *
+ * * `host_ip` - a `net::ip::ip_addr` representing a unique IP
+ * (versions 4 or 6)
+ * * `port` - a uint representing the port to listen on
+ * * `backlog` - a uint representing the number of incoming connections
+ * to cache in memory
+ * * `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
+ * * `on_establish_cb` - a callback that is evaluated if/when the listener
+ * is successfully established. it takes no parameters
+ * * `new_connect_cb` - a callback to be evaluated, on the libuv thread,
+ * whenever a client attempts to conect on the provided ip/port. the
+ * callback's arguments are:
+ * * `new_conn` - an opaque type that can be passed to
+ * `net::tcp::accept` in order to be converted to a `tcp_socket`.
+ * * `kill_ch` - channel of type `comm::chan<option<tcp_err_data>>`. this
+ * channel can be used to send a message to cause `listen` to begin
+ * closing the underlying libuv data structures.
+ *
+ * # returns
+ *
+ * a `result` instance containing empty data of type `()` on a
+ * successful/normal shutdown, and a `tcp_listen_err_data` enum in the event
+ * of listen exiting because of an error
+ */
fn listen(-host_ip: ip::ip_addr, port: uint, backlog: uint,
iotask: iotask,
on_establish_cb: fn~(comm::chan<option<tcp_err_data>>),
}
}
-#[doc="
-Convert a `net::tcp::tcp_socket` to a `net::tcp::tcp_socket_buf`.
-
-This function takes ownership of a `net::tcp::tcp_socket`, returning it
-stored within a buffered wrapper, which can be converted to a `io::reader`
-or `io::writer`
-
-# Arguments
-
-* `sock` -- a `net::tcp::tcp_socket` that you want to buffer
-
-# Returns
-
-A buffered wrapper that you can cast as an `io::reader` or `io::writer`
-"]
+/**
+ * Convert a `net::tcp::tcp_socket` to a `net::tcp::tcp_socket_buf`.
+ *
+ * This function takes ownership of a `net::tcp::tcp_socket`, returning it
+ * stored within a buffered wrapper, which can be converted to a `io::reader`
+ * or `io::writer`
+ *
+ * # Arguments
+ *
+ * * `sock` -- a `net::tcp::tcp_socket` that you want to buffer
+ *
+ * # Returns
+ *
+ * A buffered wrapper that you can cast as an `io::reader` or `io::writer`
+ */
fn socket_buf(-sock: tcp_socket) -> tcp_socket_buf {
tcp_socket_buf(@{ sock: sock, mut buf: []/~ })
}
-#[doc="
-Convenience methods extending `net::tcp::tcp_socket`
-"]
+/// Convenience methods extending `net::tcp::tcp_socket`
impl tcp_socket for tcp_socket {
fn read_start() -> result::result<comm::port<
result::result<~[u8], tcp_err_data>>, tcp_err_data> {
}
}
-#[doc="
-Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
-"]
+/// Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
impl tcp_socket_buf of io::reader for @tcp_socket_buf {
fn read_bytes(amt: uint) -> [u8]/~ {
let has_amt_available =
}
}
-#[doc="
-Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
-"]
+/// Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
impl tcp_socket_buf of io::writer for @tcp_socket_buf {
fn write(data: [const u8]/&) unsafe {
let socket_data_ptr =
export map, mapi, alli, any, mapi_factory;
-#[doc="The maximum number of tasks this module will spawn for a single
-operation."]
+/**
+ * The maximum number of tasks this module will spawn for a single
+ * operation.
+ */
const max_tasks : uint = 32u;
-#[doc="The minimum number of elements each task will process."]
+/// The minimum number of elements each task will process.
const min_granularity : uint = 1024u;
-#[doc="An internal helper to map a function over a large vector and
-return the intermediate results.
-
-This is used to build most of the other parallel vector functions,
-like map or alli."]
+/**
+ * An internal helper to map a function over a large vector and
+ * return the intermediate results.
+ *
+ * This is used to build most of the other parallel vector functions,
+ * like map or alli.
+ */
fn map_slices<A: copy send, B: copy send>(
xs: ~[A],
f: fn() -> fn~(uint, v: &[A]) -> B)
}
}
-#[doc="A parallel version of map."]
+/// A parallel version of map.
fn map<A: copy send, B: copy send>(xs: ~[A], f: fn~(A) -> B) -> ~[B] {
vec::concat(map_slices(xs, || {
fn~(_base: uint, slice : &[A], copy f) -> ~[B] {
}))
}
-#[doc="A parallel version of mapi."]
+/// A parallel version of mapi.
fn mapi<A: copy send, B: copy send>(xs: ~[A],
f: fn~(uint, A) -> B) -> ~[B] {
let slices = map_slices(xs, || {
r
}
-#[doc="A parallel version of mapi.
-
-In this case, f is a function that creates functions to run over the
-inner elements. This is to skirt the need for copy constructors."]
+/**
+ * A parallel version of mapi.
+ *
+ * In this case, f is a function that creates functions to run over the
+ * inner elements. This is to skirt the need for copy constructors.
+ */
fn mapi_factory<A: copy send, B: copy send>(
xs: ~[A], f: fn() -> fn~(uint, A) -> B) -> ~[B] {
let slices = map_slices(xs, || {
r
}
-#[doc="Returns true if the function holds for all elements in the vector."]
+/// Returns true if the function holds for all elements in the vector.
fn alli<A: copy send>(xs: ~[A], f: fn~(uint, A) -> bool) -> bool {
do vec::all(map_slices(xs, || {
fn~(base: uint, slice : &[A], copy f) -> bool {
})) |x| { x }
}
-#[doc="Returns true if the function holds for any elements in the vector."]
+/// Returns true if the function holds for any elements in the vector.
fn any<A: copy send>(xs: ~[A], f: fn~(A) -> bool) -> bool {
do vec::any(map_slices(xs, || {
fn~(_base : uint, slice: &[A], copy f) -> bool {
-#[doc = "
-High-level text containers.
-
-Ropes are a high-level representation of text that offers
-much better performance than strings for common operations,
-and generally reduce memory allocations and copies, while only
-entailing a small degradation of less common operations.
-
-More precisely, where a string is represented as a memory buffer,
-a rope is a tree structure whose leaves are slices of immutable
-strings. Therefore, concatenation, appending, prepending, substrings,
-etc. are operations that require only trivial tree manipulation,
-generally without having to copy memory. In addition, the tree
-structure of ropes makes them suitable as a form of index to speed-up
-access to Unicode characters by index in long chunks of text.
-
-The following operations are algorithmically faster in ropes:
-
-* extracting a subrope is logarithmic (linear in strings);
-* appending/prepending is near-constant time (linear in strings);
-* concatenation is near-constant time (linear in strings);
-* char length is constant-time (linear in strings);
-* access to a character by index is logarithmic (linear in strings);
-"];
+/*!
+ * High-level text containers.
+ *
+ * Ropes are a high-level representation of text that offers
+ * much better performance than strings for common operations,
+ * and generally reduce memory allocations and copies, while only
+ * entailing a small degradation of less common operations.
+ *
+ * More precisely, where a string is represented as a memory buffer,
+ * a rope is a tree structure whose leaves are slices of immutable
+ * strings. Therefore, concatenation, appending, prepending, substrings,
+ * etc. are operations that require only trivial tree manipulation,
+ * generally without having to copy memory. In addition, the tree
+ * structure of ropes makes them suitable as a form of index to speed-up
+ * access to Unicode characters by index in long chunks of text.
+ *
+ * The following operations are algorithmically faster in ropes:
+ *
+ * * extracting a subrope is logarithmic (linear in strings);
+ * * appending/prepending is near-constant time (linear in strings);
+ * * concatenation is near-constant time (linear in strings);
+ * * char length is constant-time (linear in strings);
+ * * access to a character by index is logarithmic (linear in strings);
+ */
-#[doc = "The type of ropes."]
+/// The type of ropes.
type rope = node::root;
/*
Section: Creating a rope
*/
-#[doc = "Create an empty rope"]
+/// Create an empty rope
fn empty() -> rope {
ret node::empty;
}
-#[doc = "
-Adopt a string as a rope.
-
-# Arguments
-
-* str - A valid string.
-
-# Return value
-
-A rope representing the same string as `str`. Depending of the length
-of `str`, this rope may be empty, flat or complex.
-
-# Performance notes
-
-* this operation does not copy the string;
-* the function runs in linear time.
-"]
+/**
+ * Adopt a string as a rope.
+ *
+ * # Arguments
+ *
+ * * str - A valid string.
+ *
+ * # Return value
+ *
+ * A rope representing the same string as `str`. Depending of the length
+ * of `str`, this rope may be empty, flat or complex.
+ *
+ * # Performance notes
+ *
+ * * this operation does not copy the string;
+ * * the function runs in linear time.
+ */
fn of_str(str: @str) -> rope {
ret of_substr(str, 0u, str::len(*str));
}
-#[doc = "
-As `of_str` but for a substring.
-
-# Arguments
-* byte_offset - The offset of `str` at which the rope starts.
-* byte_len - The number of bytes of `str` to use.
-
-# Return value
-
-A rope representing the same string as `str::substr(str, byte_offset,
-byte_len)`. Depending on `byte_len`, this rope may be empty, flat or
-complex.
-
-# Performance note
-
-This operation does not copy the substring.
-
-# Safety notes
-
-* this function does _not_ check the validity of the substring;
-* this function fails if `byte_offset` or `byte_len` do not match `str`.
-"]
+/**
+ * As `of_str` but for a substring.
+ *
+ * # Arguments
+ * * byte_offset - The offset of `str` at which the rope starts.
+ * * byte_len - The number of bytes of `str` to use.
+ *
+ * # Return value
+ *
+ * A rope representing the same string as `str::substr(str, byte_offset,
+ * byte_len)`. Depending on `byte_len`, this rope may be empty, flat or
+ * complex.
+ *
+ * # Performance note
+ *
+ * This operation does not copy the substring.
+ *
+ * # Safety notes
+ *
+ * * this function does _not_ check the validity of the substring;
+ * * this function fails if `byte_offset` or `byte_len` do not match `str`.
+ */
fn of_substr(str: @str, byte_offset: uint, byte_len: uint) -> rope {
if byte_len == 0u { ret node::empty; }
if byte_offset + byte_len > str::len(*str) { fail; }
Section: Adding things to a rope
*/
-#[doc = "
-Add one char to the end of the rope
-
-# Performance note
-
-* this function executes in near-constant time
-"]
+/**
+ * Add one char to the end of the rope
+ *
+ * # Performance note
+ *
+ * * this function executes in near-constant time
+ */
fn append_char(rope: rope, char: char) -> rope {
ret append_str(rope, @str::from_chars(~[char]));
}
-#[doc = "
-Add one string to the end of the rope
-
-# Performance note
-
-* this function executes in near-linear time
-"]
+/**
+ * Add one string to the end of the rope
+ *
+ * # Performance note
+ *
+ * * this function executes in near-linear time
+ */
fn append_str(rope: rope, str: @str) -> rope {
ret append_rope(rope, of_str(str))
}
-#[doc = "
-Add one char to the beginning of the rope
-
-# Performance note
-* this function executes in near-constant time
-"]
+/**
+ * Add one char to the beginning of the rope
+ *
+ * # Performance note
+ * * this function executes in near-constant time
+ */
fn prepend_char(rope: rope, char: char) -> rope {
ret prepend_str(rope, @str::from_chars(~[char]));
}
-#[doc = "
-Add one string to the beginning of the rope
-
-# Performance note
-* this function executes in near-linear time
-"]
+/**
+ * Add one string to the beginning of the rope
+ *
+ * # Performance note
+ * * this function executes in near-linear time
+ */
fn prepend_str(rope: rope, str: @str) -> rope {
ret append_rope(of_str(str), rope)
}
-#[doc = "Concatenate two ropes"]
+/// Concatenate two ropes
fn append_rope(left: rope, right: rope) -> rope {
alt(left) {
node::empty { ret right; }
}
}
-#[doc = "
-Concatenate many ropes.
-
-If the ropes are balanced initially and have the same height, the resulting
-rope remains balanced. However, this function does not take any further
-measure to ensure that the result is balanced.
-"]
+/**
+ * Concatenate many ropes.
+ *
+ * If the ropes are balanced initially and have the same height, the resulting
+ * rope remains balanced. However, this function does not take any further
+ * measure to ensure that the result is balanced.
+ */
fn concat(v: ~[rope]) -> rope {
//Copy `v` into a mut vector
let mut len = vec::len(v);
*/
-#[doc = "
-Balance a rope.
-
-# Return value
-
-A copy of the rope in which small nodes have been grouped in memory,
-and with a reduced height.
-
-If you perform numerous rope concatenations, it is generally a good idea
-to rebalance your rope at some point, before using it for other purposes.
-"]
+/**
+ * Balance a rope.
+ *
+ * # Return value
+ *
+ * A copy of the rope in which small nodes have been grouped in memory,
+ * and with a reduced height.
+ *
+ * If you perform numerous rope concatenations, it is generally a good idea
+ * to rebalance your rope at some point, before using it for other purposes.
+ */
fn bal(rope:rope) -> rope {
alt(rope) {
node::empty { ret rope }
*/
-#[doc = "
-Extract a subrope from a rope.
-
-# Performance note
-
-* on a balanced rope, this operation takes algorithmic time;
-* this operation does not involve any copying
-
-# Safety note
-
-* this function fails if char_offset/char_len do not represent
- valid positions in rope
-"]
+/**
+ * Extract a subrope from a rope.
+ *
+ * # Performance note
+ *
+ * * on a balanced rope, this operation takes algorithmic time;
+ * * this operation does not involve any copying
+ *
+ * # Safety note
+ *
+ * * this function fails if char_offset/char_len do not represent
+ * valid positions in rope
+ */
fn sub_chars(rope: rope, char_offset: uint, char_len: uint) -> rope {
if char_len == 0u { ret node::empty; }
alt(rope) {
}
}
-#[doc = "
-Extract a subrope from a rope.
-
-# Performance note
-
-* on a balanced rope, this operation takes algorithmic time;
-* this operation does not involve any copying
-
-# Safety note
-
-* this function fails if byte_offset/byte_len do not represent
- valid positions in rope
-"]
+/**
+ * Extract a subrope from a rope.
+ *
+ * # Performance note
+ *
+ * * on a balanced rope, this operation takes algorithmic time;
+ * * this operation does not involve any copying
+ *
+ * # Safety note
+ *
+ * * this function fails if byte_offset/byte_len do not represent
+ * valid positions in rope
+ */
fn sub_bytes(rope: rope, byte_offset: uint, byte_len: uint) -> rope {
if byte_len == 0u { ret node::empty; }
alt(rope) {
Section: Comparing ropes
*/
-#[doc = "
-Compare two ropes by Unicode lexicographical order.
-
-This function compares only the contents of the rope, not their structure.
-
-# Return value
-
-A negative value if `left < right`, 0 if eq(left, right) or a positive
-value if `left > right`
-"]
+/**
+ * Compare two ropes by Unicode lexicographical order.
+ *
+ * This function compares only the contents of the rope, not their structure.
+ *
+ * # Return value
+ *
+ * A negative value if `left < right`, 0 if eq(left, right) or a positive
+ * value if `left > right`
+ */
fn cmp(left: rope, right: rope) -> int {
alt((left, right)) {
(node::empty, node::empty) { ret 0; }
}
}
-#[doc = "
-Returns `true` if both ropes have the same content (regardless of
-their structure), `false` otherwise
-"]
+/**
+ * Returns `true` if both ropes have the same content (regardless of
+ * their structure), `false` otherwise
+ */
fn eq(left: rope, right: rope) -> bool {
ret cmp(left, right) == 0;
}
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
-`true` if `left <= right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ * `true` if `left <= right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
fn le(left: rope, right: rope) -> bool {
ret cmp(left, right) <= 0;
}
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
-`true` if `left < right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ * `true` if `left < right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
fn lt(left: rope, right: rope) -> bool {
ret cmp(left, right) < 0;
}
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
- `true` if `left >= right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ * `true` if `left >= right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
fn ge(left: rope, right: rope) -> bool {
ret cmp(left, right) >= 0;
}
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
-`true` if `left > right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ * `true` if `left > right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
fn gt(left: rope, right: rope) -> bool {
ret cmp(left, right) > 0;
}
Section: Iterating
*/
-#[doc = "
-Loop through a rope, char by char
-
-While other mechanisms are available, this is generally the best manner
-of looping through the contents of a rope char by char. If you prefer a
-loop that iterates through the contents string by string (e.g. to print
-the contents of the rope or output it to the system), however,
-you should rather use `traverse_components`.
-
-# Arguments
-
-* rope - A rope to traverse. It may be empty.
-* it - A block to execute with each consecutive character of the rope.
- Return `true` to continue, `false` to stop.
-
-# Return value
-
-`true` If execution proceeded correctly, `false` if it was interrupted,
-that is if `it` returned `false` at any point.
-"]
+/**
+ * Loop through a rope, char by char
+ *
+ * While other mechanisms are available, this is generally the best manner
+ * of looping through the contents of a rope char by char. If you prefer a
+ * loop that iterates through the contents string by string (e.g. to print
+ * the contents of the rope or output it to the system), however,
+ * you should rather use `traverse_components`.
+ *
+ * # Arguments
+ *
+ * * rope - A rope to traverse. It may be empty.
+ * * it - A block to execute with each consecutive character of the rope.
+ * Return `true` to continue, `false` to stop.
+ *
+ * # Return value
+ *
+ * `true` If execution proceeded correctly, `false` if it was interrupted,
+ * that is if `it` returned `false` at any point.
+ */
fn loop_chars(rope: rope, it: fn(char) -> bool) -> bool {
alt(rope) {
node::empty { ret true }
}
}
-#[doc = "
-Loop through a rope, char by char, until the end.
-
-# Arguments
-* rope - A rope to traverse. It may be empty
-* it - A block to execute with each consecutive character of the rope.
-"]
+/**
+ * Loop through a rope, char by char, until the end.
+ *
+ * # Arguments
+ * * rope - A rope to traverse. It may be empty
+ * * it - A block to execute with each consecutive character of the rope.
+ */
fn iter_chars(rope: rope, it: fn(char)) {
do loop_chars(rope) |x| {
it(x);
};
}
-#[doc ="
-Loop through a rope, string by string
-
-While other mechanisms are available, this is generally the best manner of
-looping through the contents of a rope string by string, which may be useful
-e.g. to print strings as you see them (without having to copy their
-contents into a new string), to send them to then network, to write them to
-a file, etc.. If you prefer a loop that iterates through the contents
-char by char (e.g. to search for a char), however, you should rather
-use `traverse`.
-
-# Arguments
-
-* rope - A rope to traverse. It may be empty
-* it - A block to execute with each consecutive string component of the rope.
- Return `true` to continue, `false` to stop
-
-# Return value
-
-`true` If execution proceeded correctly, `false` if it was interrupted,
-that is if `it` returned `false` at any point.
-"]
+/**
+ * Loop through a rope, string by string
+ *
+ * While other mechanisms are available, this is generally the best manner of
+ * looping through the contents of a rope string by string, which may be
+ * useful e.g. to print strings as you see them (without having to copy their
+ * contents into a new string), to send them to then network, to write them to
+ * a file, etc.. If you prefer a loop that iterates through the contents
+ * char by char (e.g. to search for a char), however, you should rather
+ * use `traverse`.
+ *
+ * # Arguments
+ *
+ * * rope - A rope to traverse. It may be empty
+ * * it - A block to execute with each consecutive string component of the
+ * rope. Return `true` to continue, `false` to stop
+ *
+ * # Return value
+ *
+ * `true` If execution proceeded correctly, `false` if it was interrupted,
+ * that is if `it` returned `false` at any point.
+ */
fn loop_leaves(rope: rope, it: fn(node::leaf) -> bool) -> bool{
alt(rope) {
node::empty { ret true }
Section: Rope properties
*/
-#[doc ="
-Returns the height of the rope.
-
-The height of the rope is a bound on the number of operations which
-must be performed during a character access before finding the leaf in
-which a character is contained.
-
-# Performance note
-
-Constant time.
-"]
+/**
+ * Returns the height of the rope.
+ *
+ * The height of the rope is a bound on the number of operations which
+ * must be performed during a character access before finding the leaf in
+ * which a character is contained.
+ *
+ * # Performance note
+ *
+ * Constant time.
+ */
fn height(rope: rope) -> uint {
alt(rope) {
node::empty { ret 0u; }
-#[doc ="
-The number of character in the rope
-
-# Performance note
-
-Constant time.
-"]
+/**
+ * The number of character in the rope
+ *
+ * # Performance note
+ *
+ * Constant time.
+ */
pure fn char_len(rope: rope) -> uint {
alt(rope) {
node::empty { ret 0u; }
}
}
-#[doc = "
-The number of bytes in the rope
-
-# Performance note
-
-Constant time.
-"]
+/**
+ * The number of bytes in the rope
+ *
+ * # Performance note
+ *
+ * Constant time.
+ */
pure fn byte_len(rope: rope) -> uint {
alt(rope) {
node::empty { ret 0u; }
}
}
-#[doc = "
-The character at position `pos`
-
-# Arguments
-
-* pos - A position in the rope
-
-# Safety notes
-
-The function will fail if `pos` is not a valid position in the rope.
-
-# Performance note
-
-This function executes in a time proportional to the height of the
-rope + the (bounded) length of the largest leaf.
-"]
+/**
+ * The character at position `pos`
+ *
+ * # Arguments
+ *
+ * * pos - A position in the rope
+ *
+ * # Safety notes
+ *
+ * The function will fail if `pos` is not a valid position in the rope.
+ *
+ * # Performance note
+ *
+ * This function executes in a time proportional to the height of the
+ * rope + the (bounded) length of the largest leaf.
+ */
fn char_at(rope: rope, pos: uint) -> char {
alt(rope) {
node::empty { fail }
*/
mod node {
- #[doc = "Implementation of type `rope`"]
+ /// Implementation of type `rope`
enum root {
- #[doc = "An empty rope"]
+ /// An empty rope
empty,
- #[doc = "A non-empty rope"]
+ /// A non-empty rope
content(@node),
}
- #[doc = "
- A text component in a rope.
-
- This is actually a slice in a rope, so as to ensure maximal sharing.
-
- # Fields
-
- * byte_offset = The number of bytes skippen in `content`
- * byte_len - The number of bytes of `content` to use
- * char_len - The number of chars in the leaf.
- * content - Contents of the leaf.
-
- Note that we can have `char_len < str::char_len(content)`, if
- this leaf is only a subset of the string. Also note that the
- string can be shared between several ropes, e.g. for indexing
- purposes.
- "]
+ /**
+ * A text component in a rope.
+ *
+ * This is actually a slice in a rope, so as to ensure maximal sharing.
+ *
+ * # Fields
+ *
+ * * byte_offset = The number of bytes skippen in `content`
+ * * byte_len - The number of bytes of `content` to use
+ * * char_len - The number of chars in the leaf.
+ * * content - Contents of the leaf.
+ *
+ * Note that we can have `char_len < str::char_len(content)`, if
+ * this leaf is only a subset of the string. Also note that the
+ * string can be shared between several ropes, e.g. for indexing
+ * purposes.
+ */
type leaf = {
byte_offset: uint,
byte_len: uint,
content: @str
};
- #[doc = "
- A node obtained from the concatenation of two other nodes
-
- # Fields
-
- * left - The node containing the beginning of the text.
- * right - The node containing the end of the text.
- * char_len - The number of chars contained in all leaves of this node.
- * byte_len - The number of bytes in the subrope.
-
- Used to pre-allocate the correct amount of storage for serialization.
-
- * height - Height of the subrope.
-
- Used for rebalancing and to allocate stacks for traversals.
- "]
+ /**
+ * A node obtained from the concatenation of two other nodes
+ *
+ * # Fields
+ *
+ * * left - The node containing the beginning of the text.
+ * * right - The node containing the end of the text.
+ * * char_len - The number of chars contained in all leaves of this node.
+ * * byte_len - The number of bytes in the subrope.
+ *
+ * Used to pre-allocate the correct amount of storage for
+ * serialization.
+ *
+ * * height - Height of the subrope.
+ *
+ * Used for rebalancing and to allocate stacks for traversals.
+ */
type concat = {
left: @node,//TODO: Perhaps a `vec` instead of `left`/`right`
right: @node,
};
enum node {
- #[doc = "A leaf consisting in a `str`"]
+ /// A leaf consisting in a `str`
leaf(leaf),
- #[doc = "The concatenation of two ropes"]
+ /// The concatenation of two ropes
concat(concat),
}
- #[doc = "
- The maximal number of chars that _should_ be permitted in a single node.
-
- This is not a strict value
- "]
+ /**
+ * The maximal number of chars that _should_ be permitted in a single node
+ *
+ * This is not a strict value
+ */
const hint_max_leaf_char_len: uint = 256u;
- #[doc = "
- The maximal height that _should_ be permitted in a tree.
-
- This is not a strict value
- "]
+ /**
+ * The maximal height that _should_ be permitted in a tree.
+ *
+ * This is not a strict value
+ */
const hint_max_node_height: uint = 16u;
- #[doc = "
- Adopt a string as a node.
-
- If the string is longer than `max_leaf_char_len`, it is
- logically split between as many leaves as necessary. Regardless,
- the string itself is not copied.
-
- Performance note: The complexity of this function is linear in
- the length of `str`.
- "]
+ /**
+ * Adopt a string as a node.
+ *
+ * If the string is longer than `max_leaf_char_len`, it is
+ * logically split between as many leaves as necessary. Regardless,
+ * the string itself is not copied.
+ *
+ * Performance note: The complexity of this function is linear in
+ * the length of `str`.
+ */
fn of_str(str: @str) -> @node {
ret of_substr(str, 0u, str::len(*str));
}
- #[doc ="
- Adopt a slice of a string as a node.
-
- If the slice is longer than `max_leaf_char_len`, it is logically split
- between as many leaves as necessary. Regardless, the string itself
- is not copied
-
- # Arguments
-
- * byte_start - The byte offset where the slice of `str` starts.
- * byte_len - The number of bytes from `str` to use.
-
- # Safety note
-
- Behavior is undefined if `byte_start` or `byte_len` do not represent
- valid positions in `str`
- "]
+ /**
+ * Adopt a slice of a string as a node.
+ *
+ * If the slice is longer than `max_leaf_char_len`, it is logically split
+ * between as many leaves as necessary. Regardless, the string itself
+ * is not copied
+ *
+ * # Arguments
+ *
+ * * byte_start - The byte offset where the slice of `str` starts.
+ * * byte_len - The number of bytes from `str` to use.
+ *
+ * # Safety note
+ *
+ * Behavior is undefined if `byte_start` or `byte_len` do not represent
+ * valid positions in `str`
+ */
fn of_substr(str: @str, byte_start: uint, byte_len: uint) -> @node {
ret of_substr_unsafer(str, byte_start, byte_len,
str::count_chars(*str, byte_start, byte_len));
}
- #[doc = "
- Adopt a slice of a string as a node.
-
- If the slice is longer than `max_leaf_char_len`, it is logically split
- between as many leaves as necessary. Regardless, the string itself
- is not copied
-
- # Arguments
-
- * byte_start - The byte offset where the slice of `str` starts.
- * byte_len - The number of bytes from `str` to use.
- * char_len - The number of chars in `str` in the interval
- [byte_start, byte_start+byte_len)
-
- # Safety notes
-
- * Behavior is undefined if `byte_start` or `byte_len` do not represent
- valid positions in `str`
- * Behavior is undefined if `char_len` does not accurately represent the
- number of chars between byte_start and byte_start+byte_len
- "]
+ /**
+ * Adopt a slice of a string as a node.
+ *
+ * If the slice is longer than `max_leaf_char_len`, it is logically split
+ * between as many leaves as necessary. Regardless, the string itself
+ * is not copied
+ *
+ * # Arguments
+ *
+ * * byte_start - The byte offset where the slice of `str` starts.
+ * * byte_len - The number of bytes from `str` to use.
+ * * char_len - The number of chars in `str` in the interval
+ * [byte_start, byte_start+byte_len)
+ *
+ * # Safety notes
+ *
+ * * Behavior is undefined if `byte_start` or `byte_len` do not represent
+ * valid positions in `str`
+ * * Behavior is undefined if `char_len` does not accurately represent the
+ * number of chars between byte_start and byte_start+byte_len
+ */
fn of_substr_unsafer(str: @str, byte_start: uint, byte_len: uint,
char_len: uint) -> @node {
assert(byte_start + byte_len <= str::len(*str));
}
}
- #[doc ="
- Concatenate a forest of nodes into one tree.
-
- # Arguments
-
- * forest - The forest. This vector is progressively rewritten during
- execution and should be discarded as meaningless afterwards.
- "]
+ /**
+ * Concatenate a forest of nodes into one tree.
+ *
+ * # Arguments
+ *
+ * * forest - The forest. This vector is progressively rewritten during
+ * execution and should be discarded as meaningless afterwards.
+ */
fn tree_from_forest_destructive(forest: ~[mut @node]) -> @node {
let mut i;
let mut len = vec::len(forest);
ret unsafe::transmute(buf);
}
- #[doc ="
- Replace a subtree by a single leaf with the same contents.
-
- * Performance note
-
- This function executes in linear time.
- "]
+ /**
+ * Replace a subtree by a single leaf with the same contents.
+ *
+ * * Performance note
+ *
+ * This function executes in linear time.
+ */
fn flatten(node: @node) -> @node unsafe {
alt(*node) {
leaf(_) { ret node }
}
}
- #[doc ="
- Balance a node.
-
- # Algorithm
-
- * if the node height is smaller than `hint_max_node_height`, do nothing
- * otherwise, gather all leaves as a forest, rebuild a balanced node,
- concatenating small leaves along the way
-
- # Return value
-
- * `option::none` if no transformation happened
- * `option::some(x)` otherwise, in which case `x` has the same contents
- as `node` bot lower height and/or fragmentation.
- "]
+ /**
+ * Balance a node.
+ *
+ * # Algorithm
+ *
+ * * if the node height is smaller than `hint_max_node_height`, do nothing
+ * * otherwise, gather all leaves as a forest, rebuild a balanced node,
+ * concatenating small leaves along the way
+ *
+ * # Return value
+ *
+ * * `option::none` if no transformation happened
+ * * `option::some(x)` otherwise, in which case `x` has the same contents
+ * as `node` bot lower height and/or fragmentation.
+ */
fn bal(node: @node) -> option<@node> {
if height(node) < hint_max_node_height { ret option::none; }
//1. Gather all leaves as a forest
}
- #[doc ="
- Compute the subnode of a node.
-
- # Arguments
-
- * node - A node
- * byte_offset - A byte offset in `node`
- * byte_len - The number of bytes to return
-
- # Performance notes
-
- * this function performs no copying;
- * this function executes in a time proportional to the height of `node`.
-
- # Safety notes
-
- This function fails if `byte_offset` or `byte_len` do not represent
- valid positions in `node`.
- "]
+ /**
+ * Compute the subnode of a node.
+ *
+ * # Arguments
+ *
+ * * node - A node
+ * * byte_offset - A byte offset in `node`
+ * * byte_len - The number of bytes to return
+ *
+ * # Performance notes
+ *
+ * * this function performs no copying;
+ * * this function executes in a time proportional to the height of `node`
+ *
+ * # Safety notes
+ *
+ * This function fails if `byte_offset` or `byte_len` do not represent
+ * valid positions in `node`.
+ */
fn sub_bytes(node: @node, byte_offset: uint, byte_len: uint) -> @node {
let mut node = node;
let mut byte_offset = byte_offset;
};
}
- #[doc ="
- Compute the subnode of a node.
-
- # Arguments
-
- * node - A node
- * char_offset - A char offset in `node`
- * char_len - The number of chars to return
-
- # Performance notes
-
- * this function performs no copying;
- * this function executes in a time proportional to the height of `node`.
-
- # Safety notes
-
- This function fails if `char_offset` or `char_len` do not represent
- valid positions in `node`.
- "]
+ /**
+ * Compute the subnode of a node.
+ *
+ * # Arguments
+ *
+ * * node - A node
+ * * char_offset - A char offset in `node`
+ * * char_len - The number of chars to return
+ *
+ * # Performance notes
+ *
+ * * this function performs no copying;
+ * * this function executes in a time proportional to the height of `node`
+ *
+ * # Safety notes
+ *
+ * This function fails if `char_offset` or `char_len` do not represent
+ * valid positions in `node`.
+ */
fn sub_chars(node: @node, char_offset: uint, char_len: uint) -> @node {
let mut node = node;
let mut char_offset = char_offset;
});
}
- #[doc ="
- Loop through a node, leaf by leaf
-
- # Arguments
-
- * rope - A node to traverse.
- * it - A block to execute with each consecutive leaf of the node.
- Return `true` to continue, `false` to stop
-
- # Arguments
-
- `true` If execution proceeded correctly, `false` if it was interrupted,
- that is if `it` returned `false` at any point.
- "]
+ /**
+ * Loop through a node, leaf by leaf
+ *
+ * # Arguments
+ *
+ * * rope - A node to traverse.
+ * * it - A block to execute with each consecutive leaf of the node.
+ * Return `true` to continue, `false` to stop
+ *
+ * # Arguments
+ *
+ * `true` If execution proceeded correctly, `false` if it was interrupted,
+ * that is if `it` returned `false` at any point.
+ */
fn loop_leaves(node: @node, it: fn(leaf) -> bool) -> bool{
let mut current = node;
loop {
};
}
- #[doc ="
- # Arguments
-
- * pos - A position in the rope
-
- # Return value
-
- The character at position `pos`
-
- # Safety notes
-
- The function will fail if `pos` is not a valid position in the rope.
-
- Performance note: This function executes in a time
- proportional to the height of the rope + the (bounded)
- length of the largest leaf.
- "]
+ /**
+ * # Arguments
+ *
+ * * pos - A position in the rope
+ *
+ * # Return value
+ *
+ * The character at position `pos`
+ *
+ * # Safety notes
+ *
+ * The function will fail if `pos` is not a valid position in the rope.
+ *
+ * Performance note: This function executes in a time
+ * proportional to the height of the rope + the (bounded)
+ * length of the largest leaf.
+ */
fn char_at(node: @node, pos: uint) -> char {
let mut node = node;
let mut pos = pos;
-#[doc = "Support code for serialization."];
+//! Support code for serialization.
use core;
-#[doc ="
-An implementation of the SHA-1 cryptographic hash.
-
-First create a `sha1` object using the `sha1` constructor, then
-feed it input using the `input` or `input_str` methods, which may be
-called any number of times.
-
-After the entire input has been fed to the hash read the result using
-the `result` or `result_str` methods.
-
-The `sha1` object may be reused to create multiple hashes by calling
-the `reset` method.
-"];
+/*!
+ * An implementation of the SHA-1 cryptographic hash.
+ *
+ * First create a `sha1` object using the `sha1` constructor, then
+ * feed it input using the `input` or `input_str` methods, which may be
+ * called any number of times.
+ *
+ * After the entire input has been fed to the hash read the result using
+ * the `result` or `result_str` methods.
+ *
+ * The `sha1` object may be reused to create multiple hashes by calling
+ * the `reset` method.
+ */
/*
* A SHA-1 implementation derived from Paul E. Jones's reference
*/
export sha1;
-#[doc = "The SHA-1 interface"]
+/// The SHA-1 interface
iface sha1 {
- #[doc = "Provide message input as bytes"]
+ /// Provide message input as bytes
fn input(~[u8]);
- #[doc = "Provide message input as string"]
+ /// Provide message input as string
fn input_str(str);
- #[doc = "
- Read the digest as a vector of 20 bytes. After calling this no further
- input may be provided until reset is called.
- "]
+ /**
+ * Read the digest as a vector of 20 bytes. After calling this no further
+ * input may be provided until reset is called.
+ */
fn result() -> ~[u8];
- #[doc = "
- Read the digest as a hex string. After calling this no further
- input may be provided until reset is called.
- "]
+ /**
+ * Read the digest as a hex string. After calling this no further
+ * input may be provided until reset is called.
+ */
fn result_str() -> str;
- #[doc = "Reset the SHA-1 state for reuse"]
+ /// Reset the SHA-1 state for reuse
fn reset();
}
const k3: u32 = 0xCA62C1D6u32;
-#[doc = "Construct a `sha` object"]
+/// Construct a `sha` object
fn sha1() -> sha1 {
type sha1state =
{h: ~[mut u32],
-#[doc = "
-A simple map based on a vector for small integer keys. Space requirements
-are O(highest integer key).
-"];
+/*!
+ * A simple map based on a vector for small integer keys. Space requirements
+ * are O(highest integer key).
+ */
import core::option;
import core::option::{some, none};
import dvec::{dvec, extensions};
// requires this to be.
type smallintmap<T: copy> = @{v: dvec<option<T>>};
-#[doc = "Create a smallintmap"]
+/// Create a smallintmap
fn mk<T: copy>() -> smallintmap<T> {
ret @{v: dvec()};
}
-#[doc = "
-Add a value to the map. If the map already contains a value for
-the specified key then the original value is replaced.
-"]
+/**
+ * Add a value to the map. If the map already contains a value for
+ * the specified key then the original value is replaced.
+ */
#[inline(always)]
fn insert<T: copy>(self: smallintmap<T>, key: uint, val: T) {
self.v.grow_set_elt(key, none, some(val));
}
-#[doc = "
-Get the value for the specified key. If the key does not exist
-in the map then returns none
-"]
+/**
+ * Get the value for the specified key. If the key does not exist
+ * in the map then returns none
+ */
fn find<T: copy>(self: smallintmap<T>, key: uint) -> option<T> {
if key < self.v.len() { ret self.v.get_elt(key); }
ret none::<T>;
}
-#[doc = "
-Get the value for the specified key
-
-# Failure
-
-If the key does not exist in the map
-"]
+/**
+ * Get the value for the specified key
+ *
+ * # Failure
+ *
+ * If the key does not exist in the map
+ */
fn get<T: copy>(self: smallintmap<T>, key: uint) -> T {
alt find(self, key) {
none { #error("smallintmap::get(): key not present"); fail; }
}
}
-#[doc = "
-Returns true if the map contains a value for the specified key
-"]
+/// Returns true if the map contains a value for the specified key
fn contains_key<T: copy>(self: smallintmap<T>, key: uint) -> bool {
ret !option::is_none(find(self, key));
}
-#[doc = "Implements the map::map interface for smallintmap"]
+/// Implements the map::map interface for smallintmap
impl <V: copy> of map::map<uint, V> for smallintmap<V> {
fn size() -> uint {
let mut sz = 0u;
}
}
-#[doc = "Cast the given smallintmap to a map::map"]
+/// Cast the given smallintmap to a map::map
fn as_map<V: copy>(s: smallintmap<V>) -> map::map<uint, V> {
s as map::map::<uint, V>
}
-#[doc = "Sorting methods"];
+//! Sorting methods
import vec::{len, push};
import int::{eq, ord};
type le<T> = fn(T, T) -> bool;
-#[doc = "
-Merge sort. Returns a new vector containing the sorted list.
-
-Has worst case O(n log n) performance, best case O(n), but
-is not space efficient. This is a stable sort.
-"]
+/**
+ * Merge sort. Returns a new vector containing the sorted list.
+ *
+ * Has worst case O(n log n) performance, best case O(n), but
+ * is not space efficient. This is a stable sort.
+ */
fn merge_sort<T: copy>(le: le<T>, v: ~[const T]) -> ~[T] {
type slice = (uint, uint);
}
}
-#[doc = "
-Quicksort. Sorts a mut vector in place.
-
-Has worst case O(n^2) performance, average case O(n log n).
-This is an unstable sort.
-"]
+/**
+ * Quicksort. Sorts a mut vector in place.
+ *
+ * Has worst case O(n^2) performance, average case O(n log n).
+ * This is an unstable sort.
+ */
fn quick_sort<T: copy>(compare_func: le<T>, arr: ~[mut T]) {
if len::<T>(arr) == 0u { ret; }
qsort::<T>(compare_func, arr, 0u, len::<T>(arr) - 1u);
qsort3::<T>(compare_func_lt, compare_func_eq, arr, i, right);
}
-#[doc = "
-Fancy quicksort. Sorts a mut vector in place.
-
-Based on algorithm presented by [Sedgewick and Bentley]/~
-(http://www.cs.princeton.edu/~rs/talks/QuicksortIsOptimal.pdf).
-According to these slides this is the algorithm of choice for
-'randomly ordered keys, abstract compare' & 'small number of key values'.
-
-This is an unstable sort.
-"]
+/**
+ * Fancy quicksort. Sorts a mut vector in place.
+ *
+ * Based on algorithm presented by [Sedgewick and Bentley]/~
+ * (http://www.cs.princeton.edu/~rs/talks/QuicksortIsOptimal.pdf).
+ * According to these slides this is the algorithm of choice for
+ * 'randomly ordered keys, abstract compare' & 'small number of key values'.
+ *
+ * This is an unstable sort.
+ */
fn quick_sort3<T: copy ord eq>(arr: ~[mut T]) {
if len::<T>(arr) == 0u { ret; }
qsort3::<T>(|x, y| x.lt(y), |x, y| x.eq(y), arr, 0,
#[comment = "The Rust standard library"];
#[license = "MIT"];
#[crate_type = "lib"];
-#[doc = "The Rust standard library"];
+//! The Rust standard library
#[no_core];
-#[doc = "Temporary files and directories"];
+//! Temporary files and directories
import core::option;
import option::{none, some};
-#[doc = "Simple ANSI color library"];
+//! Simple ANSI color library
import core::option;
fn esc(writer: io::writer) { writer.write([0x1bu8, '[' as u8]/~); }
-#[doc = "Reset the foreground and background colors to default"]
+/// Reset the foreground and background colors to default
fn reset(writer: io::writer) {
esc(writer);
writer.write(~['0' as u8, 'm' as u8]);
}
-#[doc = "Returns true if the terminal supports color"]
+/// Returns true if the terminal supports color
fn color_supported() -> bool {
let supported_terms = ~["xterm-color", "xterm",
"screen-bce", "xterm-256color"];
writer.write(~[first_char, ('0' as u8) + color, 'm' as u8]);
}
-#[doc = "Set the foreground color"]
+/// Set the foreground color
fn fg(writer: io::writer, color: u8) {
ret set_color(writer, '3' as u8, color);
}
-#[doc = "Set the background color"]
+/// Set the background color
fn bg(writer: io::writer, color: u8) {
ret set_color(writer, '4' as u8, color);
}
fn rust_mktime(&&tm: tm, &sec: i64);
}
-#[doc = "A record specifying a time value in seconds and microseconds."]
+/// A record specifying a time value in seconds and microseconds.
type timespec = {sec: i64, nsec: i32};
-#[doc = "
-Returns the current time as a `timespec` containing the seconds and
-microseconds since 1970-01-01T00:00:00Z.
-"]
+/**
+ * Returns the current time as a `timespec` containing the seconds and
+ * microseconds since 1970-01-01T00:00:00Z.
+ */
fn get_time() -> timespec {
let mut sec = 0i64;
let mut nsec = 0i32;
ret {sec: sec, nsec: nsec};
}
-#[doc = "
-Returns the current value of a high-resolution performance counter
-in nanoseconds since an unspecified epoch.
-"]
+/**
+ * Returns the current value of a high-resolution performance counter
+ * in nanoseconds since an unspecified epoch.
+ */
fn precise_time_ns() -> u64 {
let mut ns = 0u64;
rustrt::precise_time_ns(ns);
ns
}
-#[doc = "
-Returns the current value of a high-resolution performance counter
-in seconds since an unspecified epoch.
-"]
+/**
+ * Returns the current value of a high-resolution performance counter
+ * in seconds since an unspecified epoch.
+ */
fn precise_time_s() -> float {
ret (precise_time_ns() as float) / 1000000000.;
}
}
}
-#[doc = "Returns the specified time in UTC"]
+/// Returns the specified time in UTC
fn at_utc(clock: timespec) -> tm {
let mut {sec, nsec} = clock;
let mut tm = empty_tm();
tm
}
-#[doc = "Returns the current time in UTC"]
+/// Returns the current time in UTC
fn now_utc() -> tm {
at_utc(get_time())
}
-#[doc = "Returns the specified time in the local timezone"]
+/// Returns the specified time in the local timezone
fn at(clock: timespec) -> tm {
let mut {sec, nsec} = clock;
let mut tm = empty_tm();
tm
}
-#[doc = "Returns the current time in the local timezone"]
+/// Returns the current time in the local timezone
fn now() -> tm {
at(get_time())
}
-#[doc = "Parses the time from the string according to the format string."]
+/// Parses the time from the string according to the format string.
fn strptime(s: str, format: str) -> result<tm, str> {
type tm_mut = {
mut tm_sec: i32,
}
impl tm for tm {
- #[doc = "Convert time to the seconds from January 1, 1970"]
+ /// Convert time to the seconds from January 1, 1970
fn to_timespec() -> timespec {
let mut sec = 0i64;
if self.tm_gmtoff == 0_i32 {
{ sec: sec, nsec: self.tm_nsec }
}
- #[doc = "Convert time to the local timezone"]
+ /// Convert time to the local timezone
fn to_local() -> tm {
at(self.to_timespec())
}
- #[doc = "Convert time to the UTC"]
+ /// Convert time to the UTC
fn to_utc() -> tm {
at_utc(self.to_timespec())
}
- #[doc = "
- Return a string of the current time in the form
- \"Thu Jan 1 00:00:00 1970\".
- "]
+ /**
+ * Return a string of the current time in the form
+ * "Thu Jan 1 00:00:00 1970".
+ */
fn ctime() -> str { self.strftime("%c") }
- #[doc = "Formats the time according to the format string."]
+ /// Formats the time according to the format string.
fn strftime(format: str) -> str { strftime(format, self) }
- #[doc = "
- Returns a time string formatted according to RFC 822.
-
- local: \"Thu, 22 Mar 2012 07:53:18 PST\"
- utc: \"Thu, 22 Mar 2012 14:53:18 UTC\"
- "]
+ /**
+ * Returns a time string formatted according to RFC 822.
+ *
+ * local: "Thu, 22 Mar 2012 07:53:18 PST"
+ * utc: "Thu, 22 Mar 2012 14:53:18 UTC"
+ */
fn rfc822() -> str {
if self.tm_gmtoff == 0_i32 {
self.strftime("%a, %d %b %Y %T GMT")
}
}
- #[doc = "
- Returns a time string formatted according to RFC 822 with Zulu time.
-
- local: \"Thu, 22 Mar 2012 07:53:18 -0700\"
- utc: \"Thu, 22 Mar 2012 14:53:18 -0000\"
- "]
+ /**
+ * Returns a time string formatted according to RFC 822 with Zulu time.
+ *
+ * local: "Thu, 22 Mar 2012 07:53:18 -0700"
+ * utc: "Thu, 22 Mar 2012 14:53:18 -0000"
+ */
fn rfc822z() -> str {
self.strftime("%a, %d %b %Y %T %z")
}
- #[doc = "
- Returns a time string formatted according to ISO 8601.
-
- local: \"2012-02-22T07:53:18-07:00\"
- utc: \"2012-02-22T14:53:18Z\"
- "]
+ /**
+ * Returns a time string formatted according to ISO 8601.
+ *
+ * local: "2012-02-22T07:53:18-07:00"
+ * utc: "2012-02-22T14:53:18Z"
+ */
fn rfc3339() -> str {
if self.tm_gmtoff == 0_i32 {
self.strftime("%Y-%m-%dT%H:%M:%SZ")
-#[doc ="
-Utilities that leverage libuv's `uv_timer_*` API
-"];
+//! Utilities that leverage libuv's `uv_timer_*` API
import uv = uv;
import uv::iotask;
import iotask::iotask;
export delayed_send, sleep, recv_timeout;
-#[doc = "
-Wait for timeout period then send provided value over a channel
-
-This call returns immediately. Useful as the building block for a number
-of higher-level timer functions.
-
-Is not guaranteed to wait for exactly the specified time, but will wait
-for *at least* that period of time.
-
-# Arguments
-
-* `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
-* msecs - a timeout period, in milliseconds, to wait
-* ch - a channel of type T to send a `val` on
-* val - a value of type T to send over the provided `ch`
-"]
+/**
+ * Wait for timeout period then send provided value over a channel
+ *
+ * This call returns immediately. Useful as the building block for a number
+ * of higher-level timer functions.
+ *
+ * Is not guaranteed to wait for exactly the specified time, but will wait
+ * for *at least* that period of time.
+ *
+ * # Arguments
+ *
+ * * `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
+ * * msecs - a timeout period, in milliseconds, to wait
+ * * ch - a channel of type T to send a `val` on
+ * * val - a value of type T to send over the provided `ch`
+ */
fn delayed_send<T: copy send>(iotask: iotask,
msecs: uint, ch: comm::chan<T>, val: T) {
unsafe {
};
}
-#[doc = "
-Blocks the current task for (at least) the specified time period.
-
-Is not guaranteed to sleep for exactly the specified time, but will sleep
-for *at least* that period of time.
-
-# Arguments
-
-* `iotask` - a `uv::iotask` that the tcp request will run on
-* msecs - an amount of time, in milliseconds, for the current task to block
-"]
+/**
+ * Blocks the current task for (at least) the specified time period.
+ *
+ * Is not guaranteed to sleep for exactly the specified time, but will sleep
+ * for *at least* that period of time.
+ *
+ * # Arguments
+ *
+ * * `iotask` - a `uv::iotask` that the tcp request will run on
+ * * msecs - an amount of time, in milliseconds, for the current task to block
+ */
fn sleep(iotask: iotask, msecs: uint) {
let exit_po = comm::port::<()>();
let exit_ch = comm::chan(exit_po);
comm::recv(exit_po);
}
-#[doc = "
-Receive on a port for (up to) a specified time, then return an `option<T>`
-
-This call will block to receive on the provided port for up to the specified
-timeout. Depending on whether the provided port receives in that time period,
-`recv_timeout` will return an `option<T>` representing the result.
-
-# Arguments
-
-* `iotask' - `uv::iotask` that the tcp request will run on
-* msecs - an mount of time, in milliseconds, to wait to receive
-* wait_port - a `comm::port<T>` to receive on
-
-# Returns
-
-An `option<T>` representing the outcome of the call. If the call `recv`'d on
-the provided port in the allotted timeout period, then the result will be a
-`some(T)`. If not, then `none` will be returned.
-"]
+/**
+ * Receive on a port for (up to) a specified time, then return an `option<T>`
+ *
+ * This call will block to receive on the provided port for up to the
+ * specified timeout. Depending on whether the provided port receives in that
+ * time period, `recv_timeout` will return an `option<T>` representing the
+ * result.
+ *
+ * # Arguments
+ *
+ * * `iotask' - `uv::iotask` that the tcp request will run on
+ * * msecs - an mount of time, in milliseconds, to wait to receive
+ * * wait_port - a `comm::port<T>` to receive on
+ *
+ * # Returns
+ *
+ * An `option<T>` representing the outcome of the call. If the call `recv`'d
+ * on the provided port in the allotted timeout period, then the result will
+ * be a `some(T)`. If not, then `none` will be returned.
+ */
fn recv_timeout<T: copy send>(iotask: iotask,
msecs: uint,
wait_po: comm::port<T>) -> option<T> {
-#[doc = "
-A key,value store that works on anything.
-
-This works using a binary search tree. In the first version, it's a
-very naive algorithm, but it will probably be updated to be a
-red-black tree or something else.
-"];
+/*!
+ * A key,value store that works on anything.
+ *
+ * This works using a binary search tree. In the first version, it's a
+ * very naive algorithm, but it will probably be updated to be a
+ * red-black tree or something else.
+ */
import core::option::{some, none};
import option = core::option;
mut right: tree_edge<K, V>
};
-#[doc = "Create a treemap"]
+/// Create a treemap
fn treemap<K, V>() -> treemap<K, V> { @mut none }
-#[doc = "Insert a value into the map"]
+/// Insert a value into the map
fn insert<K: copy, V: copy>(m: &mut tree_edge<K, V>, k: K, v: V) {
alt copy *m {
none {
};
}
-#[doc = "Find a value based on the key"]
+/// Find a value based on the key
fn find<K: copy, V: copy>(m: &const tree_edge<K, V>, k: K) -> option<V> {
alt copy *m {
none { none }
}
}
-#[doc = "Visit all pairs in the map in order."]
+/// Visit all pairs in the map in order.
fn traverse<K, V: copy>(m: &const tree_edge<K, V>, f: fn(K, V)) {
alt copy *m {
none { }
-#[doc = "The identity function"]
+/// The identity function
pure fn id<T: copy>(x: T) -> T { x }
/* FIXME (issue #141): See test/run-pass/constrained-type.rs. Uncomment
* the constraint once fixed. */
-#[doc = "A rational number"]
+/// A rational number
type rational = {num: int, den: int}; // : int::positive(*.den);
pure fn rational_leq(x: rational, y: rational) -> bool {
-#[doc = "
-Rust bindings to libuv
-
-This is the base-module for various levels of bindings to
-the libuv library.
-
-These modules are seeing heavy work, currently, and the final
-API layout should not be inferred from its current form.
-
-This base module currently contains a historical, rust-based
-implementation of a few libuv operations that hews closely to
-the patterns of the libuv C-API. It was used, mostly, to explore
-some implementation details and will most likely be deprecated
-in the near future.
-
-The `ll` module contains low-level mappings for working directly
-with the libuv C-API.
-
-The `hl` module contains a set of tools library developers can
-use for interacting with an active libuv loop. This modules's
-API is meant to be used to write high-level,
-rust-idiomatic abstractions for utilizes libuv's asynchronous IO
-facilities.
-"];
+/*!
+ * Rust bindings to libuv
+ *
+ * This is the base-module for various levels of bindings to
+ * the libuv library.
+ *
+ * These modules are seeing heavy work, currently, and the final
+ * API layout should not be inferred from its current form.
+ *
+ * This base module currently contains a historical, rust-based
+ * implementation of a few libuv operations that hews closely to
+ * the patterns of the libuv C-API. It was used, mostly, to explore
+ * some implementation details and will most likely be deprecated
+ * in the near future.
+ *
+ * The `ll` module contains low-level mappings for working directly
+ * with the libuv C-API.
+ *
+ * The `hl` module contains a set of tools library developers can
+ * use for interacting with an active libuv loop. This modules's
+ * API is meant to be used to write high-level,
+ * rust-idiomatic abstractions for utilizes libuv's asynchronous IO
+ * facilities.
+ */
import ll = uv_ll;
export ll;
-#[doc="
-A process-wide libuv event loop for library use.
-"];
+//! A process-wide libuv event loop for library use.
export get;
fn rust_uv_get_kernel_global_chan_ptr() -> *libc::uintptr_t;
}
-#[doc ="
-Race-free helper to get access to a global task where a libuv
-loop is running.
-
-Use `uv::hl::interact` to do operations against the global
-loop that this function returns.
-
-# Return
-
-* A `hl::high_level_loop` that encapsulates communication with the global
-loop.
-"]
+/**
+ * Race-free helper to get access to a global task where a libuv
+ * loop is running.
+ *
+ * Use `uv::hl::interact` to do operations against the global
+ * loop that this function returns.
+ *
+ * # Return
+ *
+ * * A `hl::high_level_loop` that encapsulates communication with the global
+ * loop.
+ */
fn get() -> iotask {
ret get_monitor_task_gl();
}
-#[doc = "
-
-A task-based interface to the uv loop
-
-The I/O task runs in its own single-threaded scheduler. By using the
-`interact` function you can execute code in a uv callback.
-
-"];
+/*!
+ * A task-based interface to the uv loop
+ *
+ * The I/O task runs in its own single-threaded scheduler. By using the
+ * `interact` function you can execute code in a uv callback.
+ */
export iotask;
export spawn_iotask;
import comm::{port, chan, methods, listen};
import ll = uv_ll;
-#[doc = "
-Used to abstract-away direct interaction with a libuv loop.
-"]
+/// Used to abstract-away direct interaction with a libuv loop.
enum iotask {
iotask_({
async_handle: *ll::uv_async_t,
}
-#[doc = "
-Provide a callback to be processed by `iotask`
-
-The primary way to do operations again a running `iotask` that
-doesn't involve creating a uv handle via `safe_handle`
-
-# Warning
-
-This function is the only safe way to interact with _any_ `iotask`.
-Using functions in the `uv::ll` module outside of the `cb` passed into
-this function is _very dangerous_.
-
-# Arguments
-
-* iotask - a uv I/O task that you want to do operations against
-* cb - a function callback to be processed on the running loop's
-thread. The only parameter passed in is an opaque pointer representing the
-running `uv_loop_t*`. In the context of this callback, it is safe to use
-this pointer to do various uv_* API calls contained within the `uv::ll`
-module. It is not safe to send the `loop_ptr` param to this callback out
-via ports/chans.
-"]
+/**
+ * Provide a callback to be processed by `iotask`
+ *
+ * The primary way to do operations again a running `iotask` that
+ * doesn't involve creating a uv handle via `safe_handle`
+ *
+ * # Warning
+ *
+ * This function is the only safe way to interact with _any_ `iotask`.
+ * Using functions in the `uv::ll` module outside of the `cb` passed into
+ * this function is _very dangerous_.
+ *
+ * # Arguments
+ *
+ * * iotask - a uv I/O task that you want to do operations against
+ * * cb - a function callback to be processed on the running loop's
+ * thread. The only parameter passed in is an opaque pointer representing the
+ * running `uv_loop_t*`. In the context of this callback, it is safe to use
+ * this pointer to do various uv_* API calls contained within the `uv::ll`
+ * module. It is not safe to send the `loop_ptr` param to this callback out
+ * via ports/chans.
+ */
unsafe fn interact(iotask: iotask,
-cb: fn~(*c_void)) {
send_msg(iotask, interaction(cb));
}
-#[doc="
-Shut down the I/O task
-
-Is used to signal to the loop that it should close the internally-held
-async handle and do a sanity check to make sure that all other handles are
-closed, causing a failure otherwise.
-"]
+/**
+ * Shut down the I/O task
+ *
+ * Is used to signal to the loop that it should close the internally-held
+ * async handle and do a sanity check to make sure that all other handles are
+ * closed, causing a failure otherwise.
+ */
fn exit(iotask: iotask) unsafe {
send_msg(iotask, teardown_loop);
}
teardown_loop
}
-#[doc = "
-Run the loop and begin handling messages
-"]
+/// Run the loop and begin handling messages
fn run_loop(iotask_ch: chan<iotask>) unsafe {
let loop_ptr = ll::loop_new();
ll::async_send(iotask.async_handle);
}
-#[doc ="Dispatch all pending messages"]
+/// Dispatch all pending messages
extern fn wake_up_cb(async_handle: *ll::uv_async_t,
status: int) unsafe {
-#[doc = "
-Low-level bindings to the libuv library.
-
-This module contains a set of direct, 'bare-metal' wrappers around
-the libuv C-API.
-
-Also contained herein are a set of rust records that map, in
-approximate memory-size, to the libuv data structures. The record
-implementations are adjusted, per-platform, to match their respective
-representations.
-
-There are also a collection of helper functions to ease interacting
-with the low-level API (such as a function to return the latest
-libuv error as a rust-formatted string).
-
-As new functionality, existant in uv.h, is added to the rust stdlib,
-the mappings should be added in this module.
-
-This module's implementation will hopefully be, eventually, replaced
-with per-platform, generated source files from rust-bindgen.
-"];
+/*!
+ * Low-level bindings to the libuv library.
+ *
+ * This module contains a set of direct, 'bare-metal' wrappers around
+ * the libuv C-API.
+ *
+ * Also contained herein are a set of rust records that map, in
+ * approximate memory-size, to the libuv data structures. The record
+ * implementations are adjusted, per-platform, to match their respective
+ * representations.
+ *
+ * There are also a collection of helper functions to ease interacting
+ * with the low-level API (such as a function to return the latest
+ * libuv error as a rust-formatted string).
+ *
+ * As new functionality, existant in uv.h, is added to the rust stdlib,
+ * the mappings should be added in this module.
+ *
+ * This module's implementation will hopefully be, eventually, replaced
+ * with per-platform, generated source files from rust-bindgen.
+ */
import libc::size_t;
}
}
-#[doc = "Maps a binary operator to its precedence"]
+/// Maps a binary operator to its precedence
fn operator_prec(op: ast::binop) -> uint {
alt op {
mul | div | rem { 12u }
}
}
-#[doc = "
-Gets the string value if the meta_item is a meta_name_value variant
-containing a string, otherwise none
-"]
+/**
+ * Gets the string value if the meta_item is a meta_name_value variant
+ * containing a string, otherwise none
+ */
fn get_meta_item_value_str(meta: @ast::meta_item) -> option<@str> {
alt meta.node {
ast::meta_name_value(_, v) {
}
}
-#[doc = "Gets a list of inner meta items from a list meta_item type"]
+/// Gets a list of inner meta items from a list meta_item type
fn get_meta_item_list(meta: @ast::meta_item) -> option<~[@ast::meta_item]> {
alt meta.node {
ast::meta_list(_, l) { option::some(/* FIXME (#2543) */ copy l) }
}
}
-#[doc = "
-If the meta item is a nam-value type with a string value then returns
-a tuple containing the name and string value, otherwise `none`
-"]
+/**
+ * If the meta item is a nam-value type with a string value then returns
+ * a tuple containing the name and string value, otherwise `none`
+ */
fn get_name_value_str_pair(
item: @ast::meta_item
) -> option<(ast::ident, @str)> {
/* Searching */
-#[doc = "
-Search a list of attributes and return only those with a specific name
-"]
+/// Search a list of attributes and return only those with a specific name
fn find_attrs_by_name(attrs: ~[ast::attribute], +name: str) ->
~[ast::attribute] {
let filter = (
ret vec::filter_map(attrs, filter);
}
-#[doc = "
-Searcha list of meta items and return only those with a specific name
-"]
+/// Searcha list of meta items and return only those with a specific name
fn find_meta_items_by_name(metas: ~[@ast::meta_item], +name: str) ->
~[@ast::meta_item] {
let filter = fn@(&&m: @ast::meta_item) -> option<@ast::meta_item> {
ret vec::filter_map(metas, filter);
}
-#[doc = "
-Returns true if a list of meta items contains another meta item. The
-comparison is performed structurally.
-"]
+/**
+ * Returns true if a list of meta items contains another meta item. The
+ * comparison is performed structurally.
+ */
fn contains(haystack: ~[@ast::meta_item], needle: @ast::meta_item) -> bool {
#debug("looking for %s",
print::pprust::meta_item_to_str(*needle));
ret found;
}
-#[doc = "
-From a list of crate attributes get only the meta_items that impact crate
-linkage
-"]
+/**
+ * From a list of crate attributes get only the meta_items that impact crate
+ * linkage
+ */
fn find_linkage_metas(attrs: ~[ast::attribute]) -> ~[@ast::meta_item] {
do find_linkage_attrs(attrs).flat_map |attr| {
alt check attr.node.value.node {
ia_always
}
-#[doc = "True if something like #[inline] is found in the list of attrs."]
+/// True if something like #[inline] is found in the list of attrs.
fn find_inline_attr(attrs: ~[ast::attribute]) -> inline_attr {
// TODO---validate the usage of #[inline] and #[inline(always)]
do vec::foldl(ia_none, attrs) |ia,attr| {
-#[doc = "The main parser interface"];
+//! The main parser interface
import dvec::extensions;
export parse_sess;
}
/* TODO: figure out how to have a uniquely linked stack, and change to `~` */
-#[doc = "an unzipping of `token_tree`s"]
+/// an unzipping of `token_tree`s
type tt_frame = @{
readme: ~[ast::token_tree],
mut idx: uint,
}
fn parse_token_tree() -> token_tree {
- #[doc="what's the opposite delimiter?"]
+ /// what's the opposite delimiter?
fn flip(&t: token::token) -> token::token {
alt t {
token::LPAREN { token::RPAREN }
import token::token;
import ast::*;
-#[doc = "Unary operators have higher precedence than binary"]
+/// Unary operators have higher precedence than binary
const unop_prec: uint = 100u;
-#[doc = "
-Precedence of the `as` operator, which is a binary operator
-but is not represented in the precedence table.
-"]
+/**
+ * Precedence of the `as` operator, which is a binary operator
+ * but is not represented in the precedence table.
+ */
const as_prec: uint = 11u;
-#[doc = "Maps a token to a record specifying the corresponding binary
- operator and its precedence"]
+/**
+ * Maps a token to a record specifying the corresponding binary
+ * operator and its precedence
+ */
fn token_to_binop(tok: token) -> option<ast::binop> {
alt tok {
BINOP(STAR) { some(mul) }
}
#[auto_serialize]
-#[doc = "For interpolation during macro expansion."]
+/// For interpolation during macro expansion.
enum whole_nt {
w_item(@ast::item),
w_block(ast::blk),
alt t { BINOP(OR) | OROR { true } _ { false } }
}
-#[doc = "
-All the valid words that have meaning in the Rust language.
-
-Rust keywords are either 'contextual' or 'restricted'. Contextual
-keywords may be used as identifiers because their appearance in
-the grammar is unambiguous. Restricted keywords may not appear
-in positions that might otherwise contain _value identifiers_.
-"]
+/**
+ * All the valid words that have meaning in the Rust language.
+ *
+ * Rust keywords are either 'contextual' or 'restricted'. Contextual
+ * keywords may be used as identifiers because their appearance in
+ * the grammar is unambiguous. Restricted keywords may not appear
+ * in positions that might otherwise contain _value identifiers_.
+ */
fn keyword_table() -> hashmap<str, ()> {
let keywords = str_hash();
for contextual_keyword_table().each_key |word| {
keywords
}
-#[doc = "Keywords that may be used as identifiers"]
+/// Keywords that may be used as identifiers
fn contextual_keyword_table() -> hashmap<str, ()> {
let words = str_hash();
let keys = ~[
words
}
-#[doc = "
-Keywords that may not appear in any position that might otherwise contain a
-_value identifier_. Restricted keywords may still be used as other types of
-identifiers.
-
-Reasons:
-
-* For some (most?), if used at the start of a line, they will cause the line
- to be interpreted as a specific kind of statement, which would be confusing.
-
-* `true` or `false` as identifiers would always be shadowed by
- the boolean constants
-"]
+/**
+ * Keywords that may not appear in any position that might otherwise contain a
+ * _value identifier_. Restricted keywords may still be used as other types of
+ * identifiers.
+ *
+ * Reasons:
+ *
+ * * For some (most?), if used at the start of a line, they will cause the
+ * line to be interpreted as a specific kind of statement, which would be
+ * confusing.
+ *
+ * * `true` or `false` as identifiers would always be shadowed by
+ * the boolean constants
+ */
fn restricted_keyword_table() -> hashmap<str, ()> {
let words = str_hash();
let keys = ~[
mod comments;
mod attr;
- #[doc = "Common routines shared by parser mods"]
+ /// Common routines shared by parser mods
mod common;
- #[doc = "Functions dealing with operator precedence"]
+ /// Functions dealing with operator precedence
mod prec;
- #[doc = "Routines the parser uses to classify AST nodes"]
+ /// Routines the parser uses to classify AST nodes
mod classify;
}
enum pp_mode {ppm_normal, ppm_expanded, ppm_typed, ppm_identified,
ppm_expanded_identified }
-#[doc = "
-The name used for source code that doesn't originate in a file
-(e.g. source from stdin or a string)
-"]
+/**
+ * The name used for source code that doesn't originate in a file
+ * (e.g. source from stdin or a string)
+ */
fn anon_src() -> str { "<anon>" }
fn source_name(input: input) -> str {
}
enum input {
- #[doc = "Load source from file"]
+ /// Load source from file
file_input(str),
- #[doc = "The string is the source"]
+ /// The string is the source
str_input(str)
}
fn fast_resolve() -> bool { self.debugging_opt(fast_resolve) }
}
-#[doc = "Some reasonable defaults"]
+/// Some reasonable defaults
fn basic_options() -> @options {
@{
crate_type: session::lib_crate,
-#[doc = "
-
-Validates all used crates and extern libraries and loads their metadata
-
-"];
+//! Validates all used crates and extern libraries and loads their metadata
import syntax::diagnostic::span_handler;
import syntax::{ast, ast_util};
ret result;
}
-#[doc="Iterates over all the paths in the given crate."]
+/// Iterates over all the paths in the given crate.
fn each_path(cstore: cstore::cstore, cnum: ast::crate_num,
f: fn(decoder::path_entry) -> bool) {
let crate_data = cstore::get_crate_data(cstore, cnum);
}
}
-#[doc="Iterates over all the paths in the given crate."]
+/// Iterates over all the paths in the given crate.
fn each_path(cdata: cmd, f: fn(path_entry) -> bool) {
let root = ebml::doc(cdata.data);
let items = ebml::get_doc(root, tag_items);
-#[doc = "
-
-Finds crate binaries and loads their metadata
-
-"];
+//! Finds crate binaries and loads their metadata
import syntax::diagnostic::span_handler;
import syntax::{ast, attr};
-#[doc = "
-
-# Borrow check
-
-This pass is in job of enforcing *memory safety* and *purity*. As
-memory safety is by far the more complex topic, I'll focus on that in
-this description, but purity will be covered later on. In the context
-of Rust, memory safety means three basic things:
-
-- no writes to immutable memory;
-- all pointers point to non-freed memory;
-- all pointers point to memory of the same type as the pointer.
-
-The last point might seem confusing: after all, for the most part,
-this condition is guaranteed by the type check. However, there are
-two cases where the type check effectively delegates to borrow check.
-
-The first case has to do with enums. If there is a pointer to the
-interior of an enum, and the enum is in a mutable location (such as a
-local variable or field declared to be mutable), it is possible that
-the user will overwrite the enum with a new value of a different
-variant, and thus effectively change the type of the memory that the
-pointer is pointing at.
-
-The second case has to do with mutability. Basically, the type
-checker has only a limited understanding of mutability. It will allow
-(for example) the user to get an immutable pointer with the address of
-a mutable local variable. It will also allow a `@mut T` or `~mut T`
-pointer to be borrowed as a `&r.T` pointer. These seeming oversights
-are in fact intentional; they allow the user to temporarily treat a
-mutable value as immutable. It is up to the borrow check to guarantee
-that the value in question is not in fact mutated during the lifetime
-`r` of the reference.
-
-# Summary of the safety check
-
-In order to enforce mutability, the borrow check has three tricks up
-its sleeve.
-
-First, data which is uniquely tied to the current stack frame (that'll
-be defined shortly) is tracked very precisely. This means that, for
-example, if an immutable pointer to a mutable local variable is
-created, the borrowck will simply check for assignments to that
-particular local variable: no other memory is affected.
-
-Second, if the data is not uniquely tied to the stack frame, it may
-still be possible to ensure its validity by rooting garbage collected
-pointers at runtime. For example, if there is a mutable local
-variable `x` of type `@T`, and its contents are borrowed with an
-expression like `&*x`, then the value of `x` will be rooted (today,
-that means its ref count will be temporary increased) for the lifetime
-of the reference that is created. This means that the pointer remains
-valid even if `x` is reassigned.
-
-Finally, if neither of these two solutions are applicable, then we
-require that all operations within the scope of the reference be
-*pure*. A pure operation is effectively one that does not write to
-any aliasable memory. This means that it is still possible to write
-to local variables or other data that is uniquely tied to the stack
-frame (there's that term again; formal definition still pending) but
-not to data reached via a `&T` or `@T` pointer. Such writes could
-possibly have the side-effect of causing the data which must remain
-valid to be overwritten.
-
-# Possible future directions
-
-There are numerous ways that the `borrowck` could be strengthened, but
-these are the two most likely:
-
-- flow-sensitivity: we do not currently consider flow at all but only
- block-scoping. This means that innocent code like the following is
- rejected:
-
- let mut x: int;
- ...
- x = 5;
- let y: &int = &x; // immutable ptr created
- ...
-
- The reason is that the scope of the pointer `y` is the entire
- enclosing block, and the assignment `x = 5` occurs within that
- block. The analysis is not smart enough to see that `x = 5` always
- happens before the immutable pointer is created. This is relatively
- easy to fix and will surely be fixed at some point.
-
-- finer-grained purity checks: currently, our fallback for
- guaranteeing random references into mutable, aliasable memory is to
- require *total purity*. This is rather strong. We could use local
- type-based alias analysis to distinguish writes that could not
- possibly invalid the references which must be guaranteed. This
- would only work within the function boundaries; function calls would
- still require total purity. This seems less likely to be
- implemented in the short term as it would make the code
- significantly more complex; there is currently no code to analyze
- the types and determine the possible impacts of a write.
-
-# Terminology
-
-A **loan** is .
-
-# How the code works
-
-The borrow check code is divided into several major modules, each of
-which is documented in its own file.
-
-The `gather_loans` and `check_loans` are the two major passes of the
-analysis. The `gather_loans` pass runs over the IR once to determine
-what memory must remain valid and for how long. Its name is a bit of
-a misnomer; it does in fact gather up the set of loans which are
-granted, but it also determines when @T pointers must be rooted and
-for which scopes purity must be required.
-
-The `check_loans` pass walks the IR and examines the loans and purity
-requirements computed in `gather_loans`. It checks to ensure that (a)
-the conditions of all loans are honored; (b) no contradictory loans
-were granted (for example, loaning out the same memory as mutable and
-immutable simultaneously); and (c) any purity requirements are
-honored.
-
-The remaining modules are helper modules used by `gather_loans` and
-`check_loans`:
-
-- `categorization` has the job of analyzing an expression to determine
- what kind of memory is used in evaluating it (for example, where
- dereferences occur and what kind of pointer is dereferenced; whether
- the memory is mutable; etc)
-- `loan` determines when data uniquely tied to the stack frame can be
- loaned out.
-- `preserve` determines what actions (if any) must be taken to preserve
- aliasable data. This is the code which decides when to root
- an @T pointer or to require purity.
-
-# Maps that are created
-
-Borrowck results in two maps.
-
-- `root_map`: identifies those expressions or patterns whose result
- needs to be rooted. Conceptually the root_map maps from an
- expression or pattern node to a `node_id` identifying the scope for
- which the expression must be rooted (this `node_id` should identify
- a block or call). The actual key to the map is not an expression id,
- however, but a `root_map_key`, which combines an expression id with a
- deref count and is used to cope with auto-deref.
-
-- `mutbl_map`: identifies those local variables which are modified or
- moved. This is used by trans to guarantee that such variables are
- given a memory location and not used as immediates.
-
-"];
+/*!
+ * # Borrow check
+ *
+ * This pass is in job of enforcing *memory safety* and *purity*. As
+ * memory safety is by far the more complex topic, I'll focus on that in
+ * this description, but purity will be covered later on. In the context
+ * of Rust, memory safety means three basic things:
+ *
+ * - no writes to immutable memory;
+ * - all pointers point to non-freed memory;
+ * - all pointers point to memory of the same type as the pointer.
+ *
+ * The last point might seem confusing: after all, for the most part,
+ * this condition is guaranteed by the type check. However, there are
+ * two cases where the type check effectively delegates to borrow check.
+ *
+ * The first case has to do with enums. If there is a pointer to the
+ * interior of an enum, and the enum is in a mutable location (such as a
+ * local variable or field declared to be mutable), it is possible that
+ * the user will overwrite the enum with a new value of a different
+ * variant, and thus effectively change the type of the memory that the
+ * pointer is pointing at.
+ *
+ * The second case has to do with mutability. Basically, the type
+ * checker has only a limited understanding of mutability. It will allow
+ * (for example) the user to get an immutable pointer with the address of
+ * a mutable local variable. It will also allow a `@mut T` or `~mut T`
+ * pointer to be borrowed as a `&r.T` pointer. These seeming oversights
+ * are in fact intentional; they allow the user to temporarily treat a
+ * mutable value as immutable. It is up to the borrow check to guarantee
+ * that the value in question is not in fact mutated during the lifetime
+ * `r` of the reference.
+ *
+ * # Summary of the safety check
+ *
+ * In order to enforce mutability, the borrow check has three tricks up
+ * its sleeve.
+ *
+ * First, data which is uniquely tied to the current stack frame (that'll
+ * be defined shortly) is tracked very precisely. This means that, for
+ * example, if an immutable pointer to a mutable local variable is
+ * created, the borrowck will simply check for assignments to that
+ * particular local variable: no other memory is affected.
+ *
+ * Second, if the data is not uniquely tied to the stack frame, it may
+ * still be possible to ensure its validity by rooting garbage collected
+ * pointers at runtime. For example, if there is a mutable local
+ * variable `x` of type `@T`, and its contents are borrowed with an
+ * expression like `&*x`, then the value of `x` will be rooted (today,
+ * that means its ref count will be temporary increased) for the lifetime
+ * of the reference that is created. This means that the pointer remains
+ * valid even if `x` is reassigned.
+ *
+ * Finally, if neither of these two solutions are applicable, then we
+ * require that all operations within the scope of the reference be
+ * *pure*. A pure operation is effectively one that does not write to
+ * any aliasable memory. This means that it is still possible to write
+ * to local variables or other data that is uniquely tied to the stack
+ * frame (there's that term again; formal definition still pending) but
+ * not to data reached via a `&T` or `@T` pointer. Such writes could
+ * possibly have the side-effect of causing the data which must remain
+ * valid to be overwritten.
+ *
+ * # Possible future directions
+ *
+ * There are numerous ways that the `borrowck` could be strengthened, but
+ * these are the two most likely:
+ *
+ * - flow-sensitivity: we do not currently consider flow at all but only
+ * block-scoping. This means that innocent code like the following is
+ * rejected:
+ *
+ * let mut x: int;
+ * ...
+ * x = 5;
+ * let y: &int = &x; // immutable ptr created
+ * ...
+ *
+ * The reason is that the scope of the pointer `y` is the entire
+ * enclosing block, and the assignment `x = 5` occurs within that
+ * block. The analysis is not smart enough to see that `x = 5` always
+ * happens before the immutable pointer is created. This is relatively
+ * easy to fix and will surely be fixed at some point.
+ *
+ * - finer-grained purity checks: currently, our fallback for
+ * guaranteeing random references into mutable, aliasable memory is to
+ * require *total purity*. This is rather strong. We could use local
+ * type-based alias analysis to distinguish writes that could not
+ * possibly invalid the references which must be guaranteed. This
+ * would only work within the function boundaries; function calls would
+ * still require total purity. This seems less likely to be
+ * implemented in the short term as it would make the code
+ * significantly more complex; there is currently no code to analyze
+ * the types and determine the possible impacts of a write.
+ *
+ * # Terminology
+ *
+ * A **loan** is .
+ *
+ * # How the code works
+ *
+ * The borrow check code is divided into several major modules, each of
+ * which is documented in its own file.
+ *
+ * The `gather_loans` and `check_loans` are the two major passes of the
+ * analysis. The `gather_loans` pass runs over the IR once to determine
+ * what memory must remain valid and for how long. Its name is a bit of
+ * a misnomer; it does in fact gather up the set of loans which are
+ * granted, but it also determines when @T pointers must be rooted and
+ * for which scopes purity must be required.
+ *
+ * The `check_loans` pass walks the IR and examines the loans and purity
+ * requirements computed in `gather_loans`. It checks to ensure that (a)
+ * the conditions of all loans are honored; (b) no contradictory loans
+ * were granted (for example, loaning out the same memory as mutable and
+ * immutable simultaneously); and (c) any purity requirements are
+ * honored.
+ *
+ * The remaining modules are helper modules used by `gather_loans` and
+ * `check_loans`:
+ *
+ * - `categorization` has the job of analyzing an expression to determine
+ * what kind of memory is used in evaluating it (for example, where
+ * dereferences occur and what kind of pointer is dereferenced; whether
+ * the memory is mutable; etc)
+ * - `loan` determines when data uniquely tied to the stack frame can be
+ * loaned out.
+ * - `preserve` determines what actions (if any) must be taken to preserve
+ * aliasable data. This is the code which decides when to root
+ * an @T pointer or to require purity.
+ *
+ * # Maps that are created
+ *
+ * Borrowck results in two maps.
+ *
+ * - `root_map`: identifies those expressions or patterns whose result
+ * needs to be rooted. Conceptually the root_map maps from an
+ * expression or pattern node to a `node_id` identifying the scope for
+ * which the expression must be rooted (this `node_id` should identify
+ * a block or call). The actual key to the map is not an expression id,
+ * however, but a `root_map_key`, which combines an expression id with a
+ * deref count and is used to cope with auto-deref.
+ *
+ * - `mutbl_map`: identifies those local variables which are modified or
+ * moved. This is used by trans to guarantee that such variables are
+ * given a memory location and not used as immediates.
+ */
import syntax::ast;
import syntax::ast::{mutability, m_mutbl, m_imm, m_const};
ret u;
}
-#[doc = "Creates and returns a new root_map"]
+/// Creates and returns a new root_map
fn root_map() -> root_map {
ret hashmap(root_map_key_hash, root_map_key_eq);
-#[doc = "
-
-# Categorization
-
-The job of the categorization module is to analyze an expression to
-determine what kind of memory is used in evaluating it (for example,
-where dereferences occur and what kind of pointer is dereferenced;
-whether the memory is mutable; etc)
-
-Categorization effectively transforms all of our expressions into
-expressions of the following forms (the actual enum has many more
-possibilities, naturally, but they are all variants of these base
-forms):
-
- E = rvalue // some computed rvalue
- | x // address of a local variable, arg, or upvar
- | *E // deref of a ptr
- | E.comp // access to an interior component
-
-Imagine a routine ToAddr(Expr) that evaluates an expression and returns an
-address where the result is to be found. If Expr is an lvalue, then this
-is the address of the lvalue. If Expr is an rvalue, this is the address of
-some temporary spot in memory where the result is stored.
-
-Now, cat_expr() classies the expression Expr and the address A=ToAddr(Expr)
-as follows:
-
-- cat: what kind of expression was this? This is a subset of the
- full expression forms which only includes those that we care about
- for the purpose of the analysis.
-- mutbl: mutability of the address A
-- ty: the type of data found at the address A
-
-The resulting categorization tree differs somewhat from the expressions
-themselves. For example, auto-derefs are explicit. Also, an index a[b] is
-decomposed into two operations: a derefence to reach the array data and
-then an index to jump forward to the relevant item.
-"];
+/*!
+ * # Categorization
+ *
+ * The job of the categorization module is to analyze an expression to
+ * determine what kind of memory is used in evaluating it (for example,
+ * where dereferences occur and what kind of pointer is dereferenced;
+ * whether the memory is mutable; etc)
+ *
+ * Categorization effectively transforms all of our expressions into
+ * expressions of the following forms (the actual enum has many more
+ * possibilities, naturally, but they are all variants of these base
+ * forms):
+ *
+ * E = rvalue // some computed rvalue
+ * | x // address of a local variable, arg, or upvar
+ * | *E // deref of a ptr
+ * | E.comp // access to an interior component
+ *
+ * Imagine a routine ToAddr(Expr) that evaluates an expression and returns an
+ * address where the result is to be found. If Expr is an lvalue, then this
+ * is the address of the lvalue. If Expr is an rvalue, this is the address of
+ * some temporary spot in memory where the result is stored.
+ *
+ * Now, cat_expr() classies the expression Expr and the address A=ToAddr(Expr)
+ * as follows:
+ *
+ * - cat: what kind of expression was this? This is a subset of the
+ * full expression forms which only includes those that we care about
+ * for the purpose of the analysis.
+ * - mutbl: mutability of the address A
+ * - ty: the type of data found at the address A
+ *
+ * The resulting categorization tree differs somewhat from the expressions
+ * themselves. For example, auto-derefs are explicit. Also, an index a[b] is
+ * decomposed into two operations: a derefence to reach the array data and
+ * then an index to jump forward to the relevant item.
+ */
export public_methods;
export opt_deref_kind;
export check_crate, build_settings_crate, mk_warning_settings;
export warning_settings;
-#[doc="
-
-A 'lint' check is a kind of miscellaneous constraint that a user _might_ want
-to enforce, but might reasonably want to permit as well, on a module-by-module
-basis. They contrast with static constraints enforced by other phases of the
-compiler, which are generally required to hold in order to compile the program
-at all.
-
-We also build up a table containing information about lint settings, in order
-to allow other passes to take advantage of the warning attribute
-infrastructure. To save space, the table is keyed by the id of /items/, not of
-every expression. When an item has the default settings, the entry will be
-omitted. If we start allowing warn attributes on expressions, we will start
-having entries for expressions that do not share their enclosing items
-settings.
-
-This module then, exports two passes: one that populates the warning settings
-table in the session and is run early in the compile process, and one that
-does a variety of lint checks, and is run late in the compile process.
-
-"]
+/**
+ * A 'lint' check is a kind of miscellaneous constraint that a user _might_
+ * want to enforce, but might reasonably want to permit as well, on a
+ * module-by-module basis. They contrast with static constraints enforced by
+ * other phases of the compiler, which are generally required to hold in order
+ * to compile the program at all.
+ *
+ * We also build up a table containing information about lint settings, in
+ * order to allow other passes to take advantage of the warning attribute
+ * infrastructure. To save space, the table is keyed by the id of /items/, not
+ * of every expression. When an item has the default settings, the entry will
+ * be omitted. If we start allowing warn attributes on expressions, we will
+ * start having entries for expressions that do not share their enclosing
+ * items settings.
+ *
+ * This module then, exports two passes: one that populates the warning
+ * settings table in the session and is run early in the compile process, and
+ * one that does a variety of lint checks, and is run late in the compile
+ * process.
+ */
enum lint {
ctypes,
self.sess.span_lint_level(level, span, msg);
}
- #[doc="
- Merge the warnings specified by any `warn(...)` attributes into the
- current lint context, call the provided function, then reset the
- warnings in effect to their previous state.
- "]
+ /**
+ * Merge the warnings specified by any `warn(...)` attributes into the
+ * current lint context, call the provided function, then reset the
+ * warnings in effect to their previous state.
+ */
fn with_warn_attrs(attrs: ~[ast::attribute], f: fn(ctxt)) {
let mut new_ctxt = self;
-#[doc = "
-
-A classic liveness analysis based on dataflow over the AST. Computes,
-for each local variable in a function, whether that variable is live
-at a given point. Program execution points are identified by their
-id.
-
-# Basic idea
-
-The basic model is that each local variable is assigned an index. We
-represent sets of local variables using a vector indexed by this
-index. The value in the vector is either 0, indicating the variable
-is dead, or the id of an expression that uses the variable.
-
-We conceptually walk over the AST in reverse execution order. If we
-find a use of a variable, we add it to the set of live variables. If
-we find an assignment to a variable, we remove it from the set of live
-variables. When we have to merge two flows, we take the union of
-those two flows---if the variable is live on both paths, we simply
-pick one id. In the event of loops, we continue doing this until a
-fixed point is reached.
-
-## Checking initialization
-
-At the function entry point, all variables must be dead. If this is
-not the case, we can report an error using the id found in the set of
-live variables, which identifies a use of the variable which is not
-dominated by an assignment.
-
-## Checking moves
-
-After each explicit move, the variable must be dead.
-
-## Computing last uses
-
-Any use of the variable where the variable is dead afterwards is a
-last use.
-
-# Extension to handle constructors
-
-Each field is assigned an index just as with local variables. A use of
-`self` is considered a use of all fields. A use of `self.f` is just a use
-of `f`.
-
-# Implementation details
-
-The actual implementation contains two (nested) walks over the AST.
-The outer walk has the job of building up the ir_maps instance for the
-enclosing function. On the way down the tree, it identifies those AST
-nodes and variable IDs that will be needed for the liveness analysis
-and assigns them contiguous IDs. The liveness id for an AST node is
-called a `live_node` (it's a newtype'd uint) and the id for a variable
-is called a `variable` (another newtype'd uint).
-
-On the way back up the tree, as we are about to exit from a function
-declaration we allocate a `liveness` instance. Now that we know
-precisely how many nodes and variables we need, we can allocate all
-the various arrays that we will need to precisely the right size. We then
-perform the actual propagation on the `liveness` instance.
-
-This propagation is encoded in the various `propagate_through_*()`
-methods. It effectively does a reverse walk of the AST; whenever we
-reach a loop node, we iterate until a fixed point is reached.
-
-## The `users` struct
-
-At each live node `N`, we track three pieces of information for each
-variable `V` (these are encapsulated in the `users` struct):
-
-- `reader`: the `live_node` ID of some node which will read the value
- that `V` holds on entry to `N`. Formally: a node `M` such
- that there exists a path `P` from `N` to `M` where `P` does not
- write `V`. If the `reader` is `invalid_node()`, then the current
- value will never be read (the variable is dead, essentially).
-
-- `writer`: the `live_node` ID of some node which will write the
- variable `V` and which is reachable from `N`. Formally: a node `M`
- such that there exists a path `P` from `N` to `M` and `M` writes
- `V`. If the `writer` is `invalid_node()`, then there is no writer
- of `V` that follows `N`.
-
-- `used`: a boolean value indicating whether `V` is *used*. We
- distinguish a *read* from a *use* in that a *use* is some read that
- is not just used to generate a new value. For example, `x += 1` is
- a read but not a use. This is used to generate better warnings.
-
-## Special Variables
-
-We generate various special variables for various, well, special purposes.
-These are described in the `specials` struct:
-
-- `exit_ln`: a live node that is generated to represent every 'exit' from the
- function, whether it be by explicit return, fail, or other means.
-
-- `fallthrough_ln`: a live node that represents a fallthrough
-
-- `no_ret_var`: a synthetic variable that is only 'read' from, the
- fallthrough node. This allows us to detect functions where we fail
- to return explicitly.
-
-- `self_var`: a variable representing 'self'
-
-"];
+/*!
+ * A classic liveness analysis based on dataflow over the AST. Computes,
+ * for each local variable in a function, whether that variable is live
+ * at a given point. Program execution points are identified by their
+ * id.
+ *
+ * # Basic idea
+ *
+ * The basic model is that each local variable is assigned an index. We
+ * represent sets of local variables using a vector indexed by this
+ * index. The value in the vector is either 0, indicating the variable
+ * is dead, or the id of an expression that uses the variable.
+ *
+ * We conceptually walk over the AST in reverse execution order. If we
+ * find a use of a variable, we add it to the set of live variables. If
+ * we find an assignment to a variable, we remove it from the set of live
+ * variables. When we have to merge two flows, we take the union of
+ * those two flows---if the variable is live on both paths, we simply
+ * pick one id. In the event of loops, we continue doing this until a
+ * fixed point is reached.
+ *
+ * ## Checking initialization
+ *
+ * At the function entry point, all variables must be dead. If this is
+ * not the case, we can report an error using the id found in the set of
+ * live variables, which identifies a use of the variable which is not
+ * dominated by an assignment.
+ *
+ * ## Checking moves
+ *
+ * After each explicit move, the variable must be dead.
+ *
+ * ## Computing last uses
+ *
+ * Any use of the variable where the variable is dead afterwards is a
+ * last use.
+ *
+ * # Extension to handle constructors
+ *
+ * Each field is assigned an index just as with local variables. A use of
+ * `self` is considered a use of all fields. A use of `self.f` is just a use
+ * of `f`.
+ *
+ * # Implementation details
+ *
+ * The actual implementation contains two (nested) walks over the AST.
+ * The outer walk has the job of building up the ir_maps instance for the
+ * enclosing function. On the way down the tree, it identifies those AST
+ * nodes and variable IDs that will be needed for the liveness analysis
+ * and assigns them contiguous IDs. The liveness id for an AST node is
+ * called a `live_node` (it's a newtype'd uint) and the id for a variable
+ * is called a `variable` (another newtype'd uint).
+ *
+ * On the way back up the tree, as we are about to exit from a function
+ * declaration we allocate a `liveness` instance. Now that we know
+ * precisely how many nodes and variables we need, we can allocate all
+ * the various arrays that we will need to precisely the right size. We then
+ * perform the actual propagation on the `liveness` instance.
+ *
+ * This propagation is encoded in the various `propagate_through_*()`
+ * methods. It effectively does a reverse walk of the AST; whenever we
+ * reach a loop node, we iterate until a fixed point is reached.
+ *
+ * ## The `users` struct
+ *
+ * At each live node `N`, we track three pieces of information for each
+ * variable `V` (these are encapsulated in the `users` struct):
+ *
+ * - `reader`: the `live_node` ID of some node which will read the value
+ * that `V` holds on entry to `N`. Formally: a node `M` such
+ * that there exists a path `P` from `N` to `M` where `P` does not
+ * write `V`. If the `reader` is `invalid_node()`, then the current
+ * value will never be read (the variable is dead, essentially).
+ *
+ * - `writer`: the `live_node` ID of some node which will write the
+ * variable `V` and which is reachable from `N`. Formally: a node `M`
+ * such that there exists a path `P` from `N` to `M` and `M` writes
+ * `V`. If the `writer` is `invalid_node()`, then there is no writer
+ * of `V` that follows `N`.
+ *
+ * - `used`: a boolean value indicating whether `V` is *used*. We
+ * distinguish a *read* from a *use* in that a *use* is some read that
+ * is not just used to generate a new value. For example, `x += 1` is
+ * a read but not a use. This is used to generate better warnings.
+ *
+ * ## Special Variables
+ *
+ * We generate various special variables for various, well, special purposes.
+ * These are described in the `specials` struct:
+ *
+ * - `exit_ln`: a live node that is generated to represent every 'exit' from
+ * the function, whether it be by explicit return, fail, or other means.
+ *
+ * - `fallthrough_ln`: a live node that represents a fallthrough
+ *
+ * - `no_ret_var`: a synthetic variable that is only 'read' from, the
+ * fallthrough node. This allows us to detect functions where we fail
+ * to return explicitly.
+ *
+ * - `self_var`: a variable representing 'self'
+ */
import dvec::{dvec, extensions};
import std::map::{hashmap, int_hash, str_hash, box_str_hash};
ModuleDef(@Module), // Defines a module.
}
-#[doc="Contains data for specific types of import directives."]
+/// Contains data for specific types of import directives.
enum ImportDirectiveSubclass {
SingleImport(Atom /* target */, Atom /* source */),
GlobImport
}
-#[doc="The context that we thread through while building the reduced graph."]
+/// The context that we thread through while building the reduced graph.
enum ReducedGraphParent {
ModuleReducedGraphParent(@Module)
}
}
}
-#[doc="Creates a hash table of atoms."]
+/// Creates a hash table of atoms.
fn atom_hashmap<V:copy>() -> hashmap<Atom,V> {
ret hashmap::<Atom,V>(|a| a, |a, b| a == b);
}
-#[doc="
- One local scope. In Rust, local scopes can only contain value bindings.
- Therefore, we don't have to worry about the other namespaces here.
-"]
+/**
+ * One local scope. In Rust, local scopes can only contain value bindings.
+ * Therefore, we don't have to worry about the other namespaces here.
+ */
class Rib {
let bindings: hashmap<Atom,def_like>;
let kind: RibKind;
}
}
-#[doc="One import directive."]
+/// One import directive.
class ImportDirective {
let module_path: @dvec<Atom>;
let subclass: @ImportDirectiveSubclass;
}
}
-#[doc="The item that an import resolves to."]
+/// The item that an import resolves to.
class Target {
let target_module: @Module;
let bindings: @NameBindings;
}
}
-#[doc="The link from a module up to its nearest parent node."]
+/// The link from a module up to its nearest parent node.
enum ParentLink {
NoParentLink,
ModuleParentLink(@Module, Atom),
BlockParentLink(@Module, node_id)
}
-#[doc="One node in the tree of modules."]
+/// One node in the tree of modules.
class Module {
let parent_link: ParentLink;
let mut def_id: option<def_id>;
}
}
-#[doc="
- Records the definitions (at most one for each namespace) that a name is
- bound to.
-"]
+/**
+ * Records the definitions (at most one for each namespace) that a name is
+ * bound to.
+ */
class NameBindings {
let mut module_def: ModuleDef; //< Meaning in the module namespace.
let mut type_def: option<def>; //< Meaning in the type namespace.
self.impl_defs = ~[];
}
- #[doc="Creates a new module in this set of name bindings."]
+ /// Creates a new module in this set of name bindings.
fn define_module(parent_link: ParentLink, def_id: option<def_id>) {
if self.module_def == NoModuleDef {
let module = @Module(parent_link, def_id);
}
}
- #[doc="Records a type definition."]
+ /// Records a type definition.
fn define_type(def: def) {
self.type_def = some(def);
}
- #[doc="Records a value definition."]
+ /// Records a value definition.
fn define_value(def: def) {
self.value_def = some(def);
}
- #[doc="Records an impl definition."]
+ /// Records an impl definition.
fn define_impl(implementation: @Impl) {
self.impl_defs += ~[implementation];
}
- #[doc="Returns the module node if applicable."]
+ /// Returns the module node if applicable.
fn get_module_if_available() -> option<@Module> {
alt self.module_def {
NoModuleDef { ret none; }
}
}
- #[doc="
- Returns the module node. Fails if this node does not have a module
- definition.
- "]
+ /**
+ * Returns the module node. Fails if this node does not have a module
+ * definition.
+ */
fn get_module() -> @Module {
alt self.module_def {
NoModuleDef {
}
}
-#[doc="Interns the names of the primitive types."]
+/// Interns the names of the primitive types.
class PrimitiveTypeTable {
let primitive_types: hashmap<Atom,prim_ty>;
}
}
-#[doc="The main resolver class."]
+/// The main resolver class.
class Resolver {
let session: session;
let ast_map: ASTMap;
self.export_map = int_hash();
}
- #[doc="The main name resolution procedure."]
+ /// The main name resolution procedure.
fn resolve(this: @Resolver) {
self.build_reduced_graph(this);
self.resolve_imports();
// any imports resolved.
//
- #[doc="Constructs the reduced graph for the entire crate."]
+ /// Constructs the reduced graph for the entire crate.
fn build_reduced_graph(this: @Resolver) {
let initial_parent =
ModuleReducedGraphParent((*self.graph_root).get_module());
}));
}
- #[doc="Returns the current module tracked by the reduced graph parent."]
+ /// Returns the current module tracked by the reduced graph parent.
fn get_module_from_parent(reduced_graph_parent: ReducedGraphParent)
-> @Module {
alt reduced_graph_parent {
}
}
- #[doc="
- Adds a new child item to the module definition of the parent node and
- returns its corresponding name bindings as well as the current parent.
- Or, if we're inside a block, creates (or reuses) an anonymous module
- corresponding to the innermost block ID and returns the name bindings
- as well as the newly-created parent.
-
- If this node does not have a module definition and we are not inside
- a block, fails.
- "]
+ /**
+ * Adds a new child item to the module definition of the parent node and
+ * returns its corresponding name bindings as well as the current parent.
+ * Or, if we're inside a block, creates (or reuses) an anonymous module
+ * corresponding to the innermost block ID and returns the name bindings
+ * as well as the newly-created parent.
+ *
+ * If this node does not have a module definition and we are not inside
+ * a block, fails.
+ */
fn add_child(name: Atom,
reduced_graph_parent: ReducedGraphParent)
-> (@NameBindings, ReducedGraphParent) {
}
}
- #[doc="Constructs the reduced graph for one item."]
+ /// Constructs the reduced graph for one item.
fn build_reduced_graph_for_item(item: @item,
parent: ReducedGraphParent,
&&visitor: vt<ReducedGraphParent>) {
}
}
- #[doc="
- Constructs the reduced graph for one variant. Variants exist in the
- type namespace.
- "]
+ /**
+ * Constructs the reduced graph for one variant. Variants exist in the
+ * type namespace.
+ */
fn build_reduced_graph_for_variant(variant: variant,
item_id: def_id,
parent: ReducedGraphParent,
local_def(variant.node.id)));
}
- #[doc="
- Constructs the reduced graph for one 'view item'. View items consist
- of imports and use directives.
- "]
+ /**
+ * Constructs the reduced graph for one 'view item'. View items consist
+ * of imports and use directives.
+ */
fn build_reduced_graph_for_view_item(view_item: @view_item,
parent: ReducedGraphParent,
&&_visitor: vt<ReducedGraphParent>) {
}
}
- #[doc="Constructs the reduced graph for one foreign item."]
+ /// Constructs the reduced graph for one foreign item.
fn build_reduced_graph_for_foreign_item(foreign_item: @foreign_item,
parent: ReducedGraphParent,
&&visitor:
visit_block(block, new_parent, visitor);
}
- #[doc="
- Builds the reduced graph rooted at the 'use' directive for an external
- crate.
- "]
+ /**
+ * Builds the reduced graph rooted at the 'use' directive for an external
+ * crate.
+ */
fn build_reduced_graph_for_external_crate(root: @Module) {
// Create all the items reachable by paths.
for each_path(self.session.cstore, get(root.def_id).crate)
}
}
- #[doc="Creates and adds an import directive to the given module."]
+ /// Creates and adds an import directive to the given module.
fn build_import_directive(module: @Module,
module_path: @dvec<Atom>,
subclass: @ImportDirectiveSubclass) {
// remain or unsuccessfully when no forward progress in resolving imports
// is made.
- #[doc="
- Resolves all imports for the crate. This method performs the fixed-
- point iteration.
- "]
+ /**
+ * Resolves all imports for the crate. This method performs the fixed-
+ * point iteration.
+ */
fn resolve_imports() {
let mut i = 0u;
let mut prev_unresolved_imports = 0u;
}
}
- #[doc="
- Attempts to resolve imports for the given module and all of its
- submodules.
- "]
+ /**
+ * Attempts to resolve imports for the given module and all of its
+ * submodules.
+ */
fn resolve_imports_for_module_subtree(module: @Module) {
#debug("(resolving imports for module subtree) resolving %s",
self.module_to_str(module));
}
}
- #[doc="Attempts to resolve imports for the given module only."]
+ /// Attempts to resolve imports for the given module only.
fn resolve_imports_for_module(module: @Module) {
if (*module).all_imports_resolved() {
#debug("(resolving imports for module) all imports resolved for \
}
}
- #[doc="
- Attempts to resolve the given import. The return value indicates
- failure if we're certain the name does not exist, indeterminate if we
- don't know whether the name exists at the moment due to other
- currently-unresolved imports, or success if we know the name exists.
- If successful, the resolved bindings are written into the module.
- "]
+ /**
+ * Attempts to resolve the given import. The return value indicates
+ * failure if we're certain the name does not exist, indeterminate if we
+ * don't know whether the name exists at the moment due to other
+ * currently-unresolved imports, or success if we know the name exists.
+ * If successful, the resolved bindings are written into the module.
+ */
fn resolve_import_for_module(module: @Module,
import_directive: @ImportDirective)
-> ResolveResult<()> {
ret Success(());
}
- #[doc="
- Resolves a glob import. Note that this function cannot fail; it either
- succeeds or bails out (as importing * from an empty module or a module
- that exports nothing is valid).
- "]
+ /**
+ * Resolves a glob import. Note that this function cannot fail; it either
+ * succeeds or bails out (as importing * from an empty module or a module
+ * that exports nothing is valid).
+ */
fn resolve_glob_import(module: @Module, containing_module: @Module)
-> ResolveResult<()> {
ret Success(search_module);
}
- #[doc="
- Attempts to resolve the module part of an import directive rooted at
- the given module.
- "]
+ /**
+ * Attempts to resolve the module part of an import directive rooted at
+ * the given module.
+ */
fn resolve_module_path_for_import(module: @Module,
module_path: @dvec<Atom>,
xray: XrayFlag)
module.exported_names.contains_key(name);
}
- #[doc="
- Attempts to resolve the supplied name in the given module for the
- given namespace. If successful, returns the target corresponding to
- the name.
- "]
+ /**
+ * Attempts to resolve the supplied name in the given module for the
+ * given namespace. If successful, returns the target corresponding to
+ * the name.
+ */
fn resolve_name_in_module(module: @Module,
name: Atom,
namespace: Namespace,
ret Failed;
}
- #[doc="
- Resolves a one-level renaming import of the kind `import foo = bar;`
- This needs special handling, as, unlike all of the other imports, it
- needs to look in the scope chain for modules and non-modules alike.
- "]
+ /**
+ * Resolves a one-level renaming import of the kind `import foo = bar;`
+ * This needs special handling, as, unlike all of the other imports, it
+ * needs to look in the scope chain for modules and non-modules alike.
+ */
fn resolve_one_level_renaming_import(module: @Module,
import_directive: @ImportDirective)
-> ResolveResult<()> {
}
}
- #[doc="
- If `check_ribs` is true, checks the local definitions first; i.e.
- doesn't skip straight to the containing module.
- "]
+ /**
+ * If `check_ribs` is true, checks the local definitions first; i.e.
+ * doesn't skip straight to the containing module.
+ */
fn resolve_path(path: @path, namespace: Namespace, check_ribs: bool,
visitor: ResolveVisitor)
-> option<def> {
// hit.
//
- #[doc="A somewhat inefficient routine to print out the name of a module."]
+ /// A somewhat inefficient routine to print out the name of a module.
fn module_to_str(module: @Module) -> str {
let atoms = dvec();
let mut current_module = module;
}
}
-#[doc="Entry point to crate resolution."]
+/// Entry point to crate resolution.
fn resolve_crate(session: session, ast_map: ASTMap, crate: @crate)
-> { def_map: DefMap, exp_map: ExportMap, impl_map: ImplMap } {
}
}
-#[doc = "
-Get the type of a box in the default address space.
-
-Shared box pointers live in address space 1 so the GC strategy can find them.
-Before taking a pointer to the inside of a box it should be cast into address
-space 0. Otherwise the resulting (non-box) pointer will be in the wrong
-address space and thus be the wrong type.
-"]
+/**
+ * Get the type of a box in the default address space.
+ *
+ * Shared box pointers live in address space 1 so the GC strategy can find
+ * them. Before taking a pointer to the inside of a box it should be cast into
+ * address space 0. Otherwise the resulting (non-box) pointer will be in the
+ * wrong address space and thus be the wrong type.
+ */
fn non_gc_box_cast(cx: block, val: ValueRef) -> ValueRef {
#debug("non_gc_box_cast");
add_comment(cx, "non_gc_box_cast");
})
}
-#[doc = "
-Returns an equivalent type with all the typedefs and self regions removed.
-"]
+/// Returns an equivalent type with all the typedefs and self regions removed.
fn normalize_ty(cx: ctxt, t: t) -> t {
alt cx.normalized_cache.find(t) {
some(t) { ret t; }
-#[doc = "
-
-Conversion from AST representation of types to the ty.rs
-representation. The main routine here is `ast_ty_to_ty()`: each use
-is parameterized by an instance of `ast_conv` and a `region_scope`.
-
-The parameterization of `ast_ty_to_ty()` is because it behaves
-somewhat differently during the collect and check phases, particularly
-with respect to looking up the types of top-level items. In the
-collect phase, the crate context is used as the `ast_conv` instance;
-in this phase, the `get_item_ty()` function triggers a recursive call
-to `ty_of_item()` (note that `ast_ty_to_ty()` will detect recursive
-types and report an error). In the check phase, when the @fn_ctxt is
-used as the `ast_conv`, `get_item_ty()` just looks up the item type in
-`tcx.tcache`.
-
-The `region_scope` interface controls how region references are
-handled. It has two methods which are used to resolve anonymous
-region references (e.g., `&T`) and named region references (e.g.,
-`&a.T`). There are numerous region scopes that can be used, but most
-commonly you want either `empty_rscope`, which permits only the static
-region, or `type_rscope`, which permits the self region if the type in
-question is parameterized by a region.
-
-Unlike the `ast_conv` iface, the region scope can change as we descend
-the type. This is to accommodate the fact that (a) fn types are binding
-scopes and (b) the default region may change. To understand case (a),
-consider something like:
-
- type foo = { x: &a.int, y: fn(&a.int) }
-
-The type of `x` is an error because there is no region `a` in scope.
-In the type of `y`, however, region `a` is considered a bound region
-as it does not already appear in scope.
-
-Case (b) says that if you have a type:
- type foo/& = ...;
- type bar = fn(&foo, &a.foo)
-The fully expanded version of type bar is:
- type bar = fn(&foo/&, &a.foo/&a)
-Note that the self region for the `foo` defaulted to `&` in the first
-case but `&a` in the second. Basically, defaults that appear inside
-an rptr (`&r.T`) use the region `r` that appears in the rptr.
-
-"];
+/*!
+ * Conversion from AST representation of types to the ty.rs
+ * representation. The main routine here is `ast_ty_to_ty()`: each use
+ * is parameterized by an instance of `ast_conv` and a `region_scope`.
+ *
+ * The parameterization of `ast_ty_to_ty()` is because it behaves
+ * somewhat differently during the collect and check phases, particularly
+ * with respect to looking up the types of top-level items. In the
+ * collect phase, the crate context is used as the `ast_conv` instance;
+ * in this phase, the `get_item_ty()` function triggers a recursive call
+ * to `ty_of_item()` (note that `ast_ty_to_ty()` will detect recursive
+ * types and report an error). In the check phase, when the @fn_ctxt is
+ * used as the `ast_conv`, `get_item_ty()` just looks up the item type in
+ * `tcx.tcache`.
+ *
+ * The `region_scope` interface controls how region references are
+ * handled. It has two methods which are used to resolve anonymous
+ * region references (e.g., `&T`) and named region references (e.g.,
+ * `&a.T`). There are numerous region scopes that can be used, but most
+ * commonly you want either `empty_rscope`, which permits only the static
+ * region, or `type_rscope`, which permits the self region if the type in
+ * question is parameterized by a region.
+ *
+ * Unlike the `ast_conv` iface, the region scope can change as we descend
+ * the type. This is to accommodate the fact that (a) fn types are binding
+ * scopes and (b) the default region may change. To understand case (a),
+ * consider something like:
+ *
+ * type foo = { x: &a.int, y: fn(&a.int) }
+ *
+ * The type of `x` is an error because there is no region `a` in scope.
+ * In the type of `y`, however, region `a` is considered a bound region
+ * as it does not already appear in scope.
+ *
+ * Case (b) says that if you have a type:
+ * type foo/& = ...;
+ * type bar = fn(&foo, &a.foo)
+ * The fully expanded version of type bar is:
+ * type bar = fn(&foo/&, &a.foo/&a)
+ * Note that the self region for the `foo` defaulted to `&` in the first
+ * case but `&a` in the second. Basically, defaults that appear inside
+ * an rptr (`&r.T`) use the region `r` that appears in the rptr.
+ */
import check::fn_ctxt;
import rscope::{anon_rscope, binding_rscope, empty_rscope, in_anon_rscope};
}
}
-#[doc = "
-Checks that a method from an impl/class conforms to the signature of
-the same method as declared in the iface.
-
-# Parameters
-
-- impl_m: the method in the impl
-- impl_tps: the type params declared on the impl itself (not the method!)
-- if_m: the method in the iface
-- if_substs: the substitutions used on the type of the iface
-- self_ty: the self type of the impl
-"]
+/**
+ * Checks that a method from an impl/class conforms to the signature of
+ * the same method as declared in the iface.
+ *
+ * # Parameters
+ *
+ * - impl_m: the method in the impl
+ * - impl_tps: the type params declared on the impl itself (not the method!)
+ * - if_m: the method in the iface
+ * - if_substs: the substitutions used on the type of the iface
+ * - self_ty: the self type of the impl
+ */
fn compare_impl_method(tcx: ty::ctxt, sp: span,
impl_m: ty::method, impl_tps: uint,
if_m: ty::method, if_substs: ty::substs,
}
impl transaction_methods for infer_ctxt {
- #[doc = "Execute `f` and commit the bindings if successful"]
+ /// Execute `f` and commit the bindings if successful
fn commit<T,E>(f: fn() -> result<T,E>) -> result<T,E> {
assert self.tvb.bindings.len() == 0u;
ret r;
}
- #[doc = "Execute `f`, unroll bindings on failure"]
+ /// Execute `f`, unroll bindings on failure
fn try<T,E>(f: fn() -> result<T,E>) -> result<T,E> {
let tvbl = self.tvb.bindings.len();
ret r;
}
- #[doc = "Execute `f` then unroll any bindings it creates"]
+ /// Execute `f` then unroll any bindings it creates
fn probe<T,E>(f: fn() -> result<T,E>) -> result<T,E> {
assert self.tvb.bindings.len() == 0u;
assert self.rb.bindings.len() == 0u;
attrs: ~[ast::attribute]
) -> option<@ast::meta_item> {
- #[doc =
- "Given a vec of attributes, extract the meta_items contained in the \
- doc attribute"];
+ /*!
+ * Given a vec of attributes, extract the meta_items contained in the \
+ * doc attribute
+ */
let doc_attrs = attr::find_attrs_by_name(attrs, "doc");
let doc_metas = do doc_attrs.map |attr| {
export parse_config;
export usage;
-#[doc = "The type of document to output"]
+/// The type of document to output
enum output_format {
- #[doc = "Markdown"]
+ /// Markdown
markdown,
- #[doc = "HTML, via markdown and pandoc"]
+ /// HTML, via markdown and pandoc
pandoc_html
}
-#[doc = "How to organize the output"]
+/// How to organize the output
enum output_style {
- #[doc = "All in a single document"]
+ /// All in a single document
doc_per_crate,
- #[doc = "Each module in its own document"]
+ /// Each module in its own document
doc_per_mod
}
-#[doc = "The configuration for a rustdoc session"]
+/// The configuration for a rustdoc session
type config = {
input_crate: str,
output_dir: str,
// no-reformat
-#[doc = "
-
- A demonstration module
-
- Contains documentation in various forms that rustdoc understands,
- for testing purposes. It doesn't surve any functional
- purpose. This here, for instance, is just some filler text.
-
- FIXME (#1654): It would be nice if we could run some automated
- tests on this file
-
-"];
-
-#[doc = "The base price of a muffin on a non-holiday"]
+/*!
+ * A demonstration module
+ *
+ * Contains documentation in various forms that rustdoc understands,
+ * for testing purposes. It doesn't surve any functional
+ * purpose. This here, for instance, is just some filler text.
+ *
+ * FIXME (#1654): It would be nice if we could run some automated
+ * tests on this file
+ */
+
+/// The base price of a muffin on a non-holiday
const price_of_a_muffin: float = 70f;
type waitress = {
hair_color: str
};
-#[doc = "The type of things that produce omnomnom"]
+/// The type of things that produce omnomnom
enum omnomnomy {
- #[doc = "Delicious sugar cookies"]
+ /// Delicious sugar cookies
cookie,
- #[doc = "It's pizza"]
+ /// It's pizza
pizza_pie(~[uint])
}
_order: ~[omnomnomy]
) -> uint {
- #[doc = "
- OMG would you take my order already?
-
- # Arguments
-
- * _waitress - The waitress that you want to bother
- * _order - The order vector. It should be filled with food
-
- # Return
-
- The price of the order, including tax
-
- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec
- molestie nisl. Duis massa risus, pharetra a scelerisque a,
- molestie eu velit. Donec mattis ligula at ante imperdiet ut
- dapibus mauris malesuada.
-
- Sed gravida nisi a metus elementum sit amet hendrerit dolor
- bibendum. Aenean sit amet neque massa, sed tempus tortor. Sed ut
- lobortis enim. Proin a mauris quis nunc fermentum ultrices eget a
- erat. Mauris in lectus vitae metus sodales auctor. Morbi nunc
- quam, ultricies at venenatis non, pellentesque ac dui.
-
- # Failure
-
- This function is full of fail
- "];
+ /*!
+ * OMG would you take my order already?
+ *
+ * # Arguments
+ *
+ * * _waitress - The waitress that you want to bother
+ * * _order - The order vector. It should be filled with food
+ *
+ * # Return
+ *
+ * The price of the order, including tax
+ *
+ * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec
+ * molestie nisl. Duis massa risus, pharetra a scelerisque a,
+ * molestie eu velit. Donec mattis ligula at ante imperdiet ut
+ * dapibus mauris malesuada.
+ *
+ * Sed gravida nisi a metus elementum sit amet hendrerit dolor
+ * bibendum. Aenean sit amet neque massa, sed tempus tortor. Sed ut
+ * lobortis enim. Proin a mauris quis nunc fermentum ultrices eget a
+ * erat. Mauris in lectus vitae metus sodales auctor. Morbi nunc
+ * quam, ultricies at venenatis non, pellentesque ac dui.
+ *
+ * # Failure
+ *
+ * This function is full of fail
+ */
fail;
}
mod fortress_of_solitude {
- #[doc = "
- Superman's vacation home
-
- The fortress of solitude is located in the Arctic and it is
- cold. What you may not know about the fortress of solitude
- though is that it contains two separate bowling alleys. One of
- them features bumper-bowling and is kind of lame.
-
- Really, it's pretty cool.
-
- "];
+ /*!
+ * Superman's vacation home
+ *
+ * The fortress of solitude is located in the Arctic and it is
+ * cold. What you may not know about the fortress of solitude
+ * though is that it contains two separate bowling alleys. One of
+ * them features bumper-bowling and is kind of lame.
+ *
+ * Really, it's pretty cool.
+ */
}
mod blade_runner {
- #[doc = "
- Blade Runner is probably the best movie ever
-
- I like that in the world of Blade Runner it is always
- raining, and that it's always night time. And Aliens
- was also a really good movie.
-
- Alien 3 was crap though.
- "];
+ /*!
+ * Blade Runner is probably the best movie ever
+ *
+ * I like that in the world of Blade Runner it is always
+ * raining, and that it's always night time. And Aliens
+ * was also a really good movie.
+ *
+ * Alien 3 was crap though.
+ */
}
-#[doc = "
-Bored
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec
-molestie nisl. Duis massa risus, pharetra a scelerisque a,
-molestie eu velit. Donec mattis ligula at ante imperdiet ut
-dapibus mauris malesuada. Sed gravida nisi a metus elementum sit
-amet hendrerit dolor bibendum. Aenean sit amet neque massa, sed
-tempus tortor. Sed ut lobortis enim. Proin a mauris quis nunc
-fermentum ultrices eget a erat. Mauris in lectus vitae metus
-sodales auctor. Morbi nunc quam, ultricies at venenatis non,
-pellentesque ac dui.
-
-Quisque vitae est id eros placerat laoreet sit amet eu
-nisi. Curabitur suscipit neque porttitor est euismod
-lacinia. Curabitur non quam vitae ipsum adipiscing
-condimentum. Mauris ut ante eget metus sollicitudin
-blandit. Aliquam erat volutpat. Morbi sed nisl mauris. Nulla
-facilisi. Phasellus at mollis ipsum. Maecenas sed convallis
-sapien. Nullam in ligula turpis. Pellentesque a neque augue. Sed
-eget ante feugiat tortor congue auctor ac quis ante. Proin
-condimentum lacinia tincidunt.
-
-"]
+/**
+ * Bored
+ *
+ * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec
+ * molestie nisl. Duis massa risus, pharetra a scelerisque a,
+ * molestie eu velit. Donec mattis ligula at ante imperdiet ut
+ * dapibus mauris malesuada. Sed gravida nisi a metus elementum sit
+ * amet hendrerit dolor bibendum. Aenean sit amet neque massa, sed
+ * tempus tortor. Sed ut lobortis enim. Proin a mauris quis nunc
+ * fermentum ultrices eget a erat. Mauris in lectus vitae metus
+ * sodales auctor. Morbi nunc quam, ultricies at venenatis non,
+ * pellentesque ac dui.
+ *
+ * Quisque vitae est id eros placerat laoreet sit amet eu
+ * nisi. Curabitur suscipit neque porttitor est euismod
+ * lacinia. Curabitur non quam vitae ipsum adipiscing
+ * condimentum. Mauris ut ante eget metus sollicitudin
+ * blandit. Aliquam erat volutpat. Morbi sed nisl mauris. Nulla
+ * facilisi. Phasellus at mollis ipsum. Maecenas sed convallis
+ * sapien. Nullam in ligula turpis. Pellentesque a neque augue. Sed
+ * eget ante feugiat tortor congue auctor ac quis ante. Proin
+ * condimentum lacinia tincidunt.
+ */
class bored {
let bored: bool;
new(bored: bool) { self.bored = bored; }
drop { log(error, self.bored); }
}
-#[doc = "
-The Shunned House
-
-From even the greatest of horrors irony is seldom absent. Sometimes it
-enters directly into the composition of the events, while sometimes it
-relates only to their fortuitous position among persons and
-places. The latter sort is splendidly exemplified by a case in the
-ancient city of Providence, where in the late forties Edgar Allan Poe
-used to sojourn often during his unsuccessful wooing of the gifted
-poetess, Mrs. Whitman. Poe generally stopped at the Mansion House in
-Benefit Street--the renamed Golden Ball Inn whose roof has sheltered
-Washington, Jefferson, and Lafayette--and his favorite walk led
-northward along the same street to Mrs. Whitman's home and the
-neighboring hillside churchyard of St. John's, whose hidden expanse of
-Eighteenth Century gravestones had for him a peculiar fascination.
-
-"]
+/**
+ * The Shunned House
+ *
+ * From even the greatest of horrors irony is seldom absent. Sometimes it
+ * enters directly into the composition of the events, while sometimes it
+ * relates only to their fortuitous position among persons and
+ * places. The latter sort is splendidly exemplified by a case in the
+ * ancient city of Providence, where in the late forties Edgar Allan Poe
+ * used to sojourn often during his unsuccessful wooing of the gifted
+ * poetess, Mrs. Whitman. Poe generally stopped at the Mansion House in
+ * Benefit Street--the renamed Golden Ball Inn whose roof has sheltered
+ * Washington, Jefferson, and Lafayette--and his favorite walk led
+ * northward along the same street to Mrs. Whitman's home and the
+ * neighboring hillside churchyard of St. John's, whose hidden expanse of
+ * Eighteenth Century gravestones had for him a peculiar fascination.
+ */
iface the_shunned_house {
- #[doc = "
- Now the irony is this. In this walk, so many times repeated, the
- world's greatest master of the terrible and the bizarre was
- obliged to pass a particular house on the eastern side of the
- street; a dingy, antiquated structure perched on the abruptly
- rising side hill, with a great unkempt yard dating from a time
- when the region was partly open country. It does not appear that
- he ever wrote or spoke of it, nor is there any evidence that he
- even noticed it. And yet that house, to the two persons in
- possession of certain information, equals or outranks in horror
- the wildest fantasy of the genius who so often passed it
- unknowingly, and stands starkly leering as a symbol of all that is
- unutterably hideous.
-
- # Arguments
-
- * unkempt_yard - A yard dating from a time when the region was partly
- open country
- "]
+ /**
+ * Now the irony is this. In this walk, so many times repeated, the
+ * world's greatest master of the terrible and the bizarre was
+ * obliged to pass a particular house on the eastern side of the
+ * street; a dingy, antiquated structure perched on the abruptly
+ * rising side hill, with a great unkempt yard dating from a time
+ * when the region was partly open country. It does not appear that
+ * he ever wrote or spoke of it, nor is there any evidence that he
+ * even noticed it. And yet that house, to the two persons in
+ * possession of certain information, equals or outranks in horror
+ * the wildest fantasy of the genius who so often passed it
+ * unknowingly, and stands starkly leering as a symbol of all that is
+ * unutterably hideous.
+ *
+ * # Arguments
+ *
+ * * unkempt_yard - A yard dating from a time when the region was partly
+ * open country
+ */
fn dingy_house(unkempt_yard: int);
- #[doc = "
- The house was--and for that matter still is--of a kind to attract
- the attention of the curious. Originally a farm or semi-farm
- building, it followed the average New England colonial lines of
- the middle Eighteenth Century--the prosperous peaked-roof sort,
- with two stories and dormerless attic, and with the Georgian
- doorway and interior panelling dictated by the progress of taste
- at that time. It faced south, with one gable end buried to the
- lower windows in the eastward rising hill, and the other exposed
- to the foundations toward the street. Its construction, over a
- century and a half ago, had followed the grading and straightening
- of the road in that especial vicinity; for Benefit Street--at
- first called Back Street--was laid out as a lane winding amongst
- the graveyards of the first settlers, and straightened only when
- the removal of the bodies to the North Burial Ground made it
- decently possible to cut through the old family plots.
- "]
+ /**
+ * The house was--and for that matter still is--of a kind to attract
+ * the attention of the curious. Originally a farm or semi-farm
+ * building, it followed the average New England colonial lines of
+ * the middle Eighteenth Century--the prosperous peaked-roof sort,
+ * with two stories and dormerless attic, and with the Georgian
+ * doorway and interior panelling dictated by the progress of taste
+ * at that time. It faced south, with one gable end buried to the
+ * lower windows in the eastward rising hill, and the other exposed
+ * to the foundations toward the street. Its construction, over a
+ * century and a half ago, had followed the grading and straightening
+ * of the road in that especial vicinity; for Benefit Street--at
+ * first called Back Street--was laid out as a lane winding amongst
+ * the graveyards of the first settlers, and straightened only when
+ * the removal of the bodies to the North Burial Ground made it
+ * decently possible to cut through the old family plots.
+ */
fn construct() -> bool;
}
-#[doc = "Whatever"]
+/// Whatever
impl of the_shunned_house for omnomnomy {
fn dingy_house(_unkempt_yard: int) {
}
-#[doc = "
-
-Pulls a brief description out of a long description.
-
-If the first paragraph of a long description is short enough then it
-is interpreted as the brief description.
-
-"];
+/*!
+ * Pulls a brief description out of a long description.
+ *
+ * If the first paragraph of a long description is short enough then it
+ * is interpreted as the brief description.
+ */
export mk_pass;
-#[doc = "The document model"];
+//! The document model
type ast_id = int;
itempage(itemtag)
}
-#[doc = "
-Most rustdocs can be parsed into 'sections' according to their markdown
-headers
-"]
+/**
+ * Most rustdocs can be parsed into 'sections' according to their markdown
+ * headers
+ */
type section = {
header: str,
body: str
entries: ~[index_entry]
};
-#[doc = "
-
-A single entry in an index
-
-Fields:
-
-* kind - The type of thing being indexed, e.g. 'Module'
-* name - The name of the thing
-* brief - The brief description
-* link - A format-specific string representing the link target
-
-"]
+/**
+ * A single entry in an index
+ *
+ * Fields:
+ *
+ * * kind - The type of thing being indexed, e.g. 'Module'
+ * * name - The name of the thing
+ * * brief - The brief description
+ * * link - A format-specific string representing the link target
+ */
type index_entry = {
kind: str,
name: str,
}
}
-#[doc = "Some helper methods on moddoc, mostly for testing"]
+/// Some helper methods on moddoc, mostly for testing
impl util for moddoc {
fn mods() -> ~[moddoc] {
-#[doc = "Escapes text sequences"];
+//! Escapes text sequences
export mk_pass;
-#[doc = "Converts the Rust AST to the rustdoc document model"];
+//! Converts the Rust AST to the rustdoc document model
import syntax::ast;
default_name: str
) -> doc::doc {
- #[doc = "Use the AST service to create a document tree"];
+ //! Use the AST service to create a document tree
do astsrv::exec(srv) |ctxt| {
extract(ctxt.ast, default_name)
-#[doc = "Build indexes as appropriate for the markdown pass"];
+//! Build indexes as appropriate for the markdown pass
export mk_pass;
-#[doc = "Generate markdown from a document tree"];
+//! Generate markdown from a document tree
import markdown_writer::writer;
import markdown_writer::writer_util;
-#[doc = "
-
-Divides the document tree into pages.
-
-Each page corresponds is a logical section. There may be pages for individual
-modules, pages for the crate, indexes, etc.
-
-"];
+/*!
+ * Divides the document tree into pages.
+ *
+ * Each page corresponds is a logical section. There may be pages for
+ * individual modules, pages for the crate, indexes, etc.
+ */
import syntax::ast;
-#[doc = "AST-parsing helpers"];
+//! AST-parsing helpers
import rustc::driver::driver;
import driver::{file_input, str_input};
-#[doc = "Records the full path to items"];
+//! Records the full path to items
import syntax::ast;
-#[doc = "Prunes things with the #[doc(hidden)] attribute"];
+//! Prunes things with the #[doc(hidden)] attribute
import std::map::hashmap;
export mk_pass;
-#[doc = "Prunes branches of the tree that are not exported"];
+//! Prunes branches of the tree that are not exported
import syntax::ast;
import syntax::ast_util;
-#[doc = "Finds docs for reexported items and duplicates them"];
+//! Finds docs for reexported items and duplicates them
import std::map;
import std::map::hashmap;
-#[doc = "Rustdoc - The Rust documentation generator"];
+//! Rustdoc - The Rust documentation generator
#[link(name = "rustdoc",
vers = "0.2",
import doc::item;
import doc::util;
-#[doc = "A single operation on the document model"]
+/// A single operation on the document model
type pass = {
name: str,
f: fn~(srv: astsrv::srv, doc: doc::doc) -> doc::doc
ret rv;
}
-#[doc = "Runs rustdoc over the given file"]
+/// Runs rustdoc over the given file
fn run(config: config::config) {
let source_file = config.input_crate;
-#[doc = "Breaks rustdocs into sections according to their headers"];
+//! Breaks rustdocs into sections according to their headers
export mk_pass;
fn sectionalize(desc: option<str>) -> (option<str>, ~[doc::section]) {
- #[doc = "
-
- Take a description of the form
-
- General text
-
- # Section header
-
- Section text
-
- # Section header
-
- Section text
-
- and remove each header and accompanying text into section records.
-
- "];
+ /*!
+ * Take a description of the form
+ *
+ * General text
+ *
+ * # Section header
+ *
+ * Section text
+ *
+ * # Section header
+ *
+ * Section text
+ *
+ * and remove each header and accompanying text into section records.
+ */
if option::is_none(desc) {
ret (none, ~[]);
-#[doc = "Sorts items by name"];
+//! Sorts items by name
export mk_pass;
-#[doc = "Sorts items by type"];
+//! Sorts items by type
export mk_pass;
-#[doc = "A general sorting pass"];
+//! A general sorting pass
import std::sort;
-#[doc = "Generic pass for performing an operation on all descriptions"];
+//! Generic pass for performing an operation on all descriptions
export mk_pass;
-#[doc = "
-
-Pulls a brief description out of a long description.
-
-If the first paragraph of a long description is short enough then it
-is interpreted as the brief description.
-
-"];
+/*!
+ * Pulls a brief description out of a long description.
+ *
+ * If the first paragraph of a long description is short enough then it
+ * is interpreted as the brief description.
+ */
export mk_pass;
-#[doc =
- "Pulls type information out of the AST and attaches it to the document"];
+//! Pulls type information out of the AST and attaches it to the document
import syntax::ast;
import syntax::print::pprust;
-#[doc = "
-
-Removes the common level of indention from description strings. For
-instance, if an entire doc comment is indented 8 spaces we want to
-remove those 8 spaces from every line.
-
-The first line of a string is allowed to be intend less than
-subsequent lines in the same paragraph in order to account for
-instances where the string containing the doc comment is opened in the
-middle of a line, and each of the following lines is indented.
-
-"];
+/*!
+ * Removes the common level of indention from description strings. For
+ * instance, if an entire doc comment is indented 8 spaces we want to
+ * remove those 8 spaces from every line.
+ *
+ * The first line of a string is allowed to be intend less than
+ * subsequent lines in the same paragraph in order to account for
+ * instances where the string containing the doc comment is opened in the
+ * middle of a line, and each of the following lines is indented.
+ */
export mk_pass;
export recv;
-#[doc = "
-A communication endpoint that can receive messages
-
-Each port has a unique per-task identity and may not be replicated or
-transmitted. If a port value is copied, both copies refer to the same
-port. Ports may be associated with multiple `chan`s.
-"]
+/**
+ * A communication endpoint that can receive messages
+ *
+ * Each port has a unique per-task identity and may not be replicated or
+ * transmitted. If a port value is copied, both copies refer to the same
+ * port. Ports may be associated with multiple `chan`s.
+ */
enum port<T: send> {
port_t(@port_ptr<T>)
}
-#[doc = "Constructs a port"]
+/// Constructs a port
fn port<T: send>() -> port<T> {
port_t(@port_ptr(rustrt::new_port(sys::size_of::<T>() as size_t)))
}
}
-#[doc = "
-Receive from a port. If no data is available on the port then the
-task will block until data becomes available.
-"]
+/**
+ * Receive from a port. If no data is available on the port then the
+ * task will block until data becomes available.
+ */
fn recv<T: send>(p: port<T>) -> T { recv_((**p).po) }
-#[doc = "Receive on a raw port pointer"]
+/// Receive on a raw port pointer
fn recv_<T: send>(p: *rust_port) -> T {
let yield = 0u;
let yieldp = ptr::addr_of(yield);
map::vec_from_set(keys)
}
-#[doc="Returns a vector of all the parents in the BFS tree rooted at key.
-
-Nodes that are unreachable have a parent of -1."]
+/**
+ * Returns a vector of all the parents in the BFS tree rooted at key.
+ *
+ * Nodes that are unreachable have a parent of -1.
+ */
fn bfs(graph: graph, key: node_id) -> bfs_result {
let marks : ~[mut node_id]
= vec::to_mut(vec::from_elem(vec::len(graph), -1i64));
vec::from_mut(marks)
}
-#[doc="Another version of the bfs function.
-
-This one uses the same algorithm as the parallel one, just without
-using the parallel vector operators."]
+/**
+ * Another version of the bfs function.
+ *
+ * This one uses the same algorithm as the parallel one, just without
+ * using the parallel vector operators.
+ */
fn bfs2(graph: graph, key: node_id) -> bfs_result {
// This works by doing functional updates of a color vector.
}
}
-#[doc="A parallel version of the bfs function."]
+/// A parallel version of the bfs function.
fn pbfs(&&graph: arc::arc<graph>, key: node_id) -> bfs_result {
// This works by doing functional updates of a color vector.
}
}
-#[doc="Performs at least some of the validation in the Graph500 spec."]
+/// Performs at least some of the validation in the Graph500 spec.
fn validate(edges: ~[(node_id, node_id)],
root: node_id, tree: bfs_result) -> bool {
// There are 5 things to test. Below is code for each of them.
fn a() { }
fn b() {
- //~ some single line inner-docs
+ //! some single line inner-docs
}
/*
import intrinsic::ty_visitor;
import libc::c_void;
-#[doc = "High-level interfaces to `intrinsic::visit_ty` reflection system."]
+/// High-level interfaces to `intrinsic::visit_ty` reflection system.
-#[doc = "Iface for visitor that wishes to reflect on data."]
+/// Iface for visitor that wishes to reflect on data.
iface movable_ptr {
fn move_ptr(adjustment: fn(*c_void) -> *c_void);
}
-#[doc = "Helper function for alignment calculation."]
+/// Helper function for alignment calculation.
#[inline(always)]
fn align(size: uint, align: uint) -> uint {
((size + align) - 1u) & !(align - 1u)
projects / rust.git / commitdiff