diff --git a/src/libcore/bool.rs b/src/libcore/bool.rs index 63a38e7846a..4ceb384d7aa 100644 --- a/src/libcore/bool.rs +++ b/src/libcore/bool.rs @@ -10,55 +10,36 @@ export from_str, to_str, all_values, to_bit; #[doc = "The type of boolean logic values"] type t = bool; -#[doc( - brief = "Negation/Inverse" -)] +#[doc = "Negation/Inverse"] pure fn not(v: t) -> t { !v } -#[doc( - brief = "Conjunction" -)] +#[doc = "Conjunction"] pure fn and(a: t, b: t) -> t { a && b } -#[doc( - brief = "Disjunction" -)] +#[doc = "Disjunction"] pure fn or(a: t, b: t) -> t { a || b } -#[doc( - brief = "Exclusive or, i.e. `or(and(a, not(b)), and(not(a), b))`" -)] +#[doc = "Exclusive or, i.e. `or(and(a, not(b)), and(not(a), b))`"] pure fn xor(a: t, b: t) -> t { (a && !b) || (!a && b) } -#[doc( - brief = "Implication in the logic, i.e. from `a` follows `b`" -)] +#[doc = "Implication in the logic, i.e. from `a` follows `b`"] pure fn implies(a: t, b: t) -> t { !a || b } -#[doc( - brief = "true if truth values `a` and `b` \ - are indistinguishable in the logic" -)] +#[doc = " +true if truth values `a` and `b` are indistinguishable in the logic +"] pure fn eq(a: t, b: t) -> bool { a == b } -#[doc( - brief = "true if truth values `a` and `b` are distinguishable in the logic" -)] +#[doc = "true if truth values `a` and `b` are distinguishable in the logic"] pure fn ne(a: t, b: t) -> bool { a != b } -#[doc( - brief = "true if `v` represents truth in the logic" -)] +#[doc = "true if `v` represents truth in the logic"] pure fn is_true(v: t) -> bool { v } -#[doc( - brief = "true if `v` represents falsehood in the logic" -)] +#[doc = "true if `v` represents falsehood in the logic"] pure fn is_false(v: t) -> bool { !v } -#[doc( - brief = "Parse logic value from `s`" -)] +#[doc = "Parse logic value from `s`"] pure fn from_str(s: str) -> option { alt check s { "true" { some(true) } @@ -67,23 +48,19 @@ pure fn from_str(s: str) -> option { } } -#[doc( - brief = "Convert `v` into a string" -)] +#[doc = "Convert `v` into a string"] pure fn to_str(v: t) -> str { if v { "true" } else { "false" } } -#[doc( - brief = "Iterates over all truth values by passing them to `blk` \ - in an unspecified order" -)] +#[doc = " +Iterates over all truth values by passing them to `blk` in an unspecified +order +"] fn all_values(blk: fn(v: t)) { blk(true); blk(false); } -#[doc( - brief = "converts truth value to an 8 bit byte" -)] +#[doc = "converts truth value to an 8 bit byte"] pure fn to_bit(v: t) -> u8 { if v { 1u8 } else { 0u8 } } #[test] diff --git a/src/libcore/box.rs b/src/libcore/box.rs index dc96aebcebc..28323f49ff0 100644 --- a/src/libcore/box.rs +++ b/src/libcore/box.rs @@ -1,9 +1,9 @@ +#[doc = "Operations on shared box types"]; + export ptr_eq; -#[doc( - brief = "Determine if two shared boxes point to the same object" -)] pure fn ptr_eq(a: @T, b: @T) -> bool unchecked { + #[doc = "Determine if two shared boxes point to the same object"]; ptr::addr_of(*a) == ptr::addr_of(*b) } diff --git a/src/libcore/char.rs b/src/libcore/char.rs index 123d739ba2c..a06669dfe03 100644 --- a/src/libcore/char.rs +++ b/src/libcore/char.rs @@ -45,27 +45,27 @@ import is_XID_start = unicode::derived_property::XID_Start; import is_XID_continue = unicode::derived_property::XID_Continue; -#[doc( - brief = "Indicates whether a character is in lower case, defined \ - in terms of the Unicode General Category 'Ll'." -)] +#[doc = " +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( - brief = "Indicates whether a character is in upper case, defined \ - in terms of the Unicode General Category 'Lu'." -)] +#[doc = " +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( - brief = "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]" -)] +#[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] +"] pure fn is_whitespace(c: char) -> bool { ret ('\x09' <= c && c <= '\x0d') || unicode::general_category::Zs(c) @@ -73,11 +73,11 @@ pure fn is_whitespace(c: char) -> bool { || unicode::general_category::Zp(c); } -#[doc( - brief = "Indicates whether a character is alphanumeric, defined \ - in terms of the Unicode General Categories 'Nd', \ - 'Nl', 'No' and the Derived Core Property 'Alphabetic'." -)] +#[doc = " +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) || @@ -85,26 +85,32 @@ pure fn is_alphanumeric(c: char) -> bool { unicode::general_category::No(c); } -#[doc( brief = "Indicates whether the character is an ASCII character" )] +#[doc = "Indicates whether the character is an ASCII character"] pure fn is_ascii(c: char) -> bool { c - ('\x7F' & c) == '\x00' } -#[doc( brief = "Indicates whether the character is numeric (Nd, Nl, or No)" )] +#[doc = "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( - brief = "Convert a char to the corresponding digit. \ - Safety note: This function fails if `c` is not a valid char", - return = "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." -)] +#[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. +"] pure fn to_digit(c: char, radix: uint) -> option { let val = alt c { '0' to '9' { c as uint - ('0' as uint) } @@ -119,9 +125,7 @@ pure fn to_digit(c: char, radix: uint) -> option { /* FIXME: works only on ASCII */ -#[doc( - brief = "Convert a char to the corresponding lower case." -)] +#[doc = "Convert a char to the corresponding lower case."] pure fn to_lower(c: char) -> char { alt c { 'A' to 'Z' { ((c as u8) + 32u8) as char } @@ -132,9 +136,7 @@ pure fn to_lower(c: char) -> char { /* FIXME: works only on ASCII */ -#[doc( - brief = "Convert a char to the corresponding upper case." -)] +#[doc = "Convert a char to the corresponding upper case."] pure fn to_upper(c: char) -> char { alt c { 'a' to 'z' { ((c as u8) - 32u8) as char } @@ -142,10 +144,13 @@ pure fn to_upper(c: char) -> char { } } -#[doc( - brief = "Compare two chars.", - return = "-1 if ab" -)] +#[doc = " +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 } diff --git a/src/libcore/comm.rs b/src/libcore/comm.rs index 280464e35f5..413144aff69 100644 --- a/src/libcore/comm.rs +++ b/src/libcore/comm.rs @@ -1,6 +1,5 @@ -#[doc( - brief = "Communication between tasks", - desc = " +#[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 @@ -11,15 +10,19 @@ vectors, strings, and records, tags, tuples and unique boxes (`~T`) thereof. Most notably, shared boxes (`@T`) may not be transmitted across channels. -Example: +# Example - let p = comm::port(); - task::spawn(comm::chan(p), fn (c: chan) { - comm::send(c, \"Hello, World\"); - }); - io::println(comm::recv(p)); +~~~ +let po = comm::port(); +let ch = comm::chan(po); -")]; +task::spawn {|| + comm::send(ch, \"Hello, World\"); +}); + +io::println(comm::recv(p)); +~~~ +"]; import sys; import task; @@ -65,18 +68,16 @@ type port_id = int; // 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( - brief = "A communication endpoint that can send messages. \ - Channels send messages to ports.", - desc = "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." -)] +#[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. +"] enum chan { chan_t(task_id, port_id) } @@ -104,21 +105,19 @@ resource port_ptr(po: *rust_port) { rustrt::del_port(po); } -#[doc( - brief = "A communication endpoint that can receive messages. \ - Ports receive messages from channels.", - desc = "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 s." -)] +#[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. +"] enum port { port_t(@port_ptr) } -#[doc( - brief = "Sends data over a channel. The sent data is moved \ - into the channel, whereupon the caller loses \ - access to it." -)] +#[doc = " +Sends data over a channel. The sent data is moved into the channel, +whereupon the caller loses access to it. +"] fn send(ch: chan, -data: T) { let chan_t(t, p) = ch; let res = rustrt::chan_id_send(sys::get_type_desc::(), t, p, data); @@ -129,23 +128,18 @@ fn send(ch: chan, -data: T) { task::yield(); } -#[doc( - brief = "Constructs a port." -)] +#[doc = "Constructs a port"] fn port() -> port { port_t(@port_ptr(rustrt::new_port(sys::size_of::()))) } -#[doc( - brief = "Receive from a port. \ - If no data is available on the port then the task will \ - block until data becomes available." -)] +#[doc = " +Receive from a port. If no data is available on the port then the +task will block until data becomes available. +"] fn recv(p: port) -> T { recv_(***p) } -#[doc( - brief = "Receive on a raw port pointer" -)] +#[doc = "Receive on a raw port pointer"] fn recv_(p: *rust_port) -> T { // FIXME: Due to issue 1185 we can't use a return pointer when // calling C code, and since we can't create our own return @@ -218,10 +212,10 @@ fn peek(p: port) -> bool { rustrt::rust_port_size(***p) != 0u as ctypes::size_t } -#[doc( - brief = "Constructs a channel. The channel is bound to the \ - port used to construct it." -)] +#[doc = " +Constructs a channel. The channel is bound to the port used to +construct it. +"] fn chan(p: port) -> chan { chan_t(rustrt::get_task_id(), rustrt::get_port_id(***p)) } diff --git a/src/libcore/core.rc b/src/libcore/core.rc index 0badc7569f1..4edea85dd53 100644 --- a/src/libcore/core.rc +++ b/src/libcore/core.rc @@ -10,9 +10,8 @@ // Don't link to core. We are core. #[no_core]; -#[doc( - brief = "The Rust core library", - desc = " +#[doc = " +The Rust core library The core library provides functionality that is closely tied to the Rust built-in types and runtime services, or that is used in nearly every @@ -24,9 +23,8 @@ as though the user had written the following: use core; import core::*; -This behavior can be disabled with the `no_core` crate attribute." - -)]; +This behavior can be disabled with the `no_core` crate attribute. +"]; export int, i8, i16, i32, i64; export uint, u8, u16, u32, u64; diff --git a/src/libcore/core.rs b/src/libcore/core.rs index 5ea8fcb545f..f83065ff501 100644 --- a/src/libcore/core.rs +++ b/src/libcore/core.rs @@ -40,13 +40,11 @@ mod std { import std::test; } -/* -Function: unreachable - +#[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. -*/ +"] fn unreachable() -> ! { fail "Internal error: entered unreachable code"; } diff --git a/src/libcore/ctypes.rs b/src/libcore/ctypes.rs index 22428e41ca3..009ce986631 100644 --- a/src/libcore/ctypes.rs +++ b/src/libcore/ctypes.rs @@ -19,103 +19,73 @@ export enum; #[doc = "A signed integer with the same size as a C `char`."] type c_char = i8; -#[doc( - brief = "A signed integer with the same size as a C `int`." -)] +#[doc = "A signed integer with the same size as a C `int`."] type c_int = i32; -#[doc( - brief = "An unsigned integer with the same size as a C `unsigned int`." -)] +#[doc = "An unsigned integer with the same size as a C `unsigned int`."] type c_uint = u32; -#[doc( - brief = "A signed integer with the same size as a C `long`." -)] +#[doc = "A signed integer with the same size as a C `long`."] type long = int; -#[doc( - brief = "A signed integer with the same size as a C `long long`." -)] +#[doc = "A signed integer with the same size as a C `long long`."] type longlong = i64; -#[doc( - brief = "A signed integer with the same size as a C `unsigned int`." -)] +#[doc = "A signed integer with the same size as a C `unsigned int`."] type unsigned = u32; -#[doc( - brief = "A signed integer with the same size as a C `unsigned long`." -)] +#[doc = "A signed integer with the same size as a C `unsigned long`."] type ulong = uint; -#[doc( - brief = "A signed integer with the same size as a C `unsigned long long`." -)] +#[doc = "A signed integer with the same size as a C `unsigned long long`."] type ulonglong = u64; -#[doc( - brief = "A signed integer with the same size as a pointer. \ - This is guaranteed to always be the same type as a \ - Rust `int`." -)] +#[doc = " +A signed integer with the same size as a pointer. This is guaranteed +to always be the same type as a Rust `int`. +"] type intptr_t = uint; // FIXME: int -#[doc( - brief = "An unsigned integer with the same size as a pointer. \ - This is guaranteed to always be the same type as a Rust \ - `uint`." -)] +#[doc = " +An unsigned integer with the same size as a pointer. This is +guaranteed to always be the same type as a Rust `uint`. +"] type uintptr_t = uint; type uint32_t = u32; -#[doc( - brief = "A type, a pointer to which can be used as C `void *`.", - desc = "The void type cannot be constructed or destructured, \ - but using pointers to this type when interoperating \ - with C void pointers can help in documentation." -)] +#[doc = " +A type, a pointer to which can be used as C `void *`. + +The void type cannot be constructed or destructured, but using +pointers to this type when interoperating with C void pointers can +help in documentation. +"] enum void {} -#[doc( - brief = "A float value with the same size as a C `float`." -)] +#[doc = "A float value with the same size as a C `float`."] type c_float = f32; -#[doc( - brief = "A float value with the same size as a C `double`." -)] +#[doc = "A float value with the same size as a C `double`."] type c_double = f64; -#[doc( - brief = "An unsigned integer corresponding to the C `size_t`." -)] +#[doc = "An unsigned integer corresponding to the C `size_t`."] type size_t = uint; -#[doc( - brief = "A signed integer corresponding to the C `ssize_t`." -)] +#[doc = "A signed integer corresponding to the C `ssize_t`."] type ssize_t = int; -#[doc( - brief = "An unsigned integer corresponding to the C `off_t`." -)] +#[doc = "An unsigned integer corresponding to the C `off_t`."] type off_t = uint; -#[doc( - brief = "A type that can be used for C file descriptors." -)] +#[doc = "A type that can be used for C file descriptors."] type fd_t = i32; // not actually a C type, but should be. -#[doc( - brief = "A type for representing process ID's, corresponding to C `pid_t`." -)] +#[doc = "A type for representing process ID's, corresponding to C `pid_t`."] type pid_t = i32; -#[doc( - brief = "An unsigned integer with the same size as a C enum. \ - enum is implementation-defined, but is 32-bits in \ - practice" -)] +#[doc = " +An unsigned integer with the same size as a C enum. enum is +implementation-defined, but is 32-bits in practice +"] type enum = u32; diff --git a/src/libcore/either.rs b/src/libcore/either.rs index 0daee24650d..175c93a3409 100644 --- a/src/libcore/either.rs +++ b/src/libcore/either.rs @@ -1,45 +1,27 @@ -/* -Module: either +#[doc = "A type that represents one of two alternatives"]; -A type that represents one of two alternatives -*/ - - -/* -Tag: t - -The either type -*/ +#[doc = "The either type"] enum t { - /* Variant: left */ left(T), - /* Variant: right */ right(U) } -/* Section: Operations */ +fn either(f_left: fn(T) -> V, + f_right: fn(U) -> V, value: t) -> V { + #[doc = " + Applies a function based on the given either value -/* -Function: either + 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. -*/ -fn either(f_left: fn(T) -> V, f_right: fn(U) -> V, value: t) -> - V { alt value { left(l) { f_left(l) } right(r) { f_right(r) } } } -/* -Function: lefts - -Extracts from a vector of either all the left values. -*/ fn lefts(eithers: [t]) -> [T] { + #[doc = "Extracts from a vector of either all the left values"]; + let mut result: [T] = []; for elt: t in eithers { alt elt { left(l) { result += [l]; } _ {/* fallthrough */ } } @@ -47,12 +29,9 @@ fn lefts(eithers: [t]) -> [T] { ret result; } -/* -Function: rights - -Extracts from a vector of either all the right values -*/ fn rights(eithers: [t]) -> [U] { + #[doc = "Extracts from a vector of either all the right values"]; + let mut result: [U] = []; for elt: t in eithers { alt elt { right(r) { result += [r]; } _ {/* fallthrough */ } } @@ -60,16 +39,15 @@ fn rights(eithers: [t]) -> [U] { ret result; } -/* -Function: partition - -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. -*/ fn partition(eithers: [t]) -> {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. + "]; + let mut lefts: [T] = []; let mut rights: [U] = []; for elt: t in eithers { @@ -78,59 +56,41 @@ fn partition(eithers: [t]) ret {lefts: lefts, rights: rights}; } -/* -Function: flip - -Flips between left and right of a given either -*/ pure fn flip(eith: t) -> t { + #[doc = "Flips between left and right of a given either"]; + alt eith { right(r) { left(r) } left(l) { right(l) } } } -/* -Function: to_result - -Converts either::t to a result::t, making the "right" choice -an ok result, and the "left" choice a fail -*/ pure fn to_result(eith: t) -> result::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 + "]; + alt eith { right(r) { result::ok(r) } left(l) { result::err(l) } } } -/* -Function: is_left - -Checks whether the given value is a left -*/ pure fn is_left(eith: t) -> bool { + #[doc = "Checks whether the given value is a left"]; + alt eith { left(_) { true } _ { false } } } -/* -Function: is_right - -Checks whether the given value is a right -*/ pure fn is_right(eith: t) -> bool { + #[doc = "Checks whether the given value is a right"]; + alt eith { right(_) { true } _ { false } } } -// -// Local Variables: -// mode: rust -// fill-column: 78; -// indent-tabs-mode: nil -// c-basic-offset: 4 -// buffer-file-coding-system: utf-8-unix -// End: -// - #[test] fn test_either_left() { let val = left(10); @@ -223,3 +183,13 @@ fn test_partition_empty() { assert (vec::len(result.lefts) == 0u); assert (vec::len(result.rights) == 0u); } + +// +// Local Variables: +// mode: rust +// fill-column: 78; +// indent-tabs-mode: nil +// c-basic-offset: 4 +// buffer-file-coding-system: utf-8-unix +// End: +// diff --git a/src/libcore/extfmt.rs b/src/libcore/extfmt.rs index 106b478e9bf..85a74ba6ed5 100644 --- a/src/libcore/extfmt.rs +++ b/src/libcore/extfmt.rs @@ -1,3 +1,5 @@ +#[doc(hidden)]; + /* Syntax Extension: fmt diff --git a/src/libcore/f32.rs b/src/libcore/f32.rs index d46a3bda312..3e3a172ba81 100644 --- a/src/libcore/f32.rs +++ b/src/libcore/f32.rs @@ -58,56 +58,49 @@ pure fn gt(x: f32, y: f32) -> bool { ret x > y; } // FIXME replace the predicates below with llvm intrinsics or calls // to the libmath macros in the rust runtime for performance -#[doc( - brief = "Returns true if `x` is a positive number, including +0.0f320 \ - and +Infinity." -)] +#[doc = " +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( - brief = "Returns true if `x` is a negative number, including -0.0f320 \ - and -Infinity." -)] +#[doc = " +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( - brief = "Returns true if `x` is a negative number, including \ - -0.0f320 and -Infinity. (This is the same as \ - `f32::negative`.)" -)] +#[doc = " +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( - brief = "Returns true if `x` is a positive number, \ - including +0.0f320 and +Infinity. (This is \ - the same as `f32::positive`.)" -)] +#[doc = " +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( - brief = "Returns true if `x` is a zero number \ - (positive or negative zero)" -)] +#[doc = " +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( - brief = "Returns true if `x`is an infinite number" -)] +#[doc = "Returns true if `x`is an infinite number"] pure fn is_infinite(x: f32) -> bool { ret x == infinity || x == neg_infinity; } -#[doc( - brief = "Returns true if `x`is a finite number" -)] +#[doc = "Returns true if `x`is a finite number"] pure fn is_finite(x: f32) -> bool { ret !(is_NaN(x) || is_infinite(x)); } @@ -118,69 +111,43 @@ pure fn is_finite(x: f32) -> bool { mod consts { // FIXME replace with mathematical constants from cmath - #[doc( - brief = "Archimedes' constant" - )] + #[doc = "Archimedes' constant"] const pi: f32 = 3.14159265358979323846264338327950288_f32; - #[doc( - brief = "pi/2.0" - )] + #[doc = "pi/2.0"] const frac_pi_2: f32 = 1.57079632679489661923132169163975144_f32; - #[doc( - brief = "pi/4.0" - )] + #[doc = "pi/4.0"] const frac_pi_4: f32 = 0.785398163397448309615660845819875721_f32; - #[doc( - brief = "1.0/pi" - )] + #[doc = "1.0/pi"] const frac_1_pi: f32 = 0.318309886183790671537767526745028724_f32; - #[doc( - brief = "2.0/pi" - )] + #[doc = "2.0/pi"] const frac_2_pi: f32 = 0.636619772367581343075535053490057448_f32; - #[doc( - brief = "2.0/sqrt(pi)" - )] + #[doc = "2.0/sqrt(pi)"] const frac_2_sqrtpi: f32 = 1.12837916709551257389615890312154517_f32; - #[doc( - brief = "sqrt(2.0)" - )] + #[doc = "sqrt(2.0)"] const sqrt2: f32 = 1.41421356237309504880168872420969808_f32; - #[doc( - brief = "1.0/sqrt(2.0)" - )] + #[doc = "1.0/sqrt(2.0)"] const frac_1_sqrt2: f32 = 0.707106781186547524400844362104849039_f32; - #[doc( - brief = "Euler's number" - )] + #[doc = "Euler's number"] const e: f32 = 2.71828182845904523536028747135266250_f32; - #[doc( - brief = "log2(e)" - )] + #[doc = "log2(e)"] const log2_e: f32 = 1.44269504088896340735992468100189214_f32; - #[doc( - brief = "log10(e)" - )] + #[doc = "log10(e)"] const log10_e: f32 = 0.434294481903251827651128918916605082_f32; - #[doc( - brief = "ln(2.0)" - )] + #[doc = "ln(2.0)"] const ln_2: f32 = 0.693147180559945309417232121458176568_f32; - #[doc( - brief = "ln(10.0)" - )] + #[doc = "ln(10.0)"] const ln_10: f32 = 2.30258509299404568401799145468436421_f32; } diff --git a/src/libcore/f64.rs b/src/libcore/f64.rs index 6d0f838d557..214fcc80188 100644 --- a/src/libcore/f64.rs +++ b/src/libcore/f64.rs @@ -76,56 +76,47 @@ pure fn ge(x: f64, y: f64) -> bool { ret x >= y; } pure fn gt(x: f64, y: f64) -> bool { ret x > y; } -#[doc( - brief = "Returns true if `x` is a positive number, including \ - +0.0f640 and +Infinity." -)] +#[doc = " +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( - brief = "Returns true if `x` is a negative number, including \ - -0.0f640 and -Infinity." -)] +#[doc = " +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( - brief = "Returns true if `x` is a negative number, including \ - -0.0f640 and -Infinity. (This is the same as \ - `f64::negative`.)" -)] +#[doc = " +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( - brief = "Returns true if `x` is a positive number, including \ - +0.0f640 and +Infinity.(This is the same as \ - `f64::positive`.)" -)] +#[doc = " +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( - brief = "Returns true if `x` is a zero number (positive or \ - negative zero)" -)] +#[doc = "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( - brief = "Returns true if `x`is an infinite number." -)] +#[doc = "Returns true if `x`is an infinite number"] pure fn is_infinite(x: f64) -> bool { ret x == infinity || x == neg_infinity; } -#[doc( - brief = "Returns true if `x`is a finite number." -)] +#[doc = "Returns true if `x`is a finite number"] pure fn is_finite(x: f64) -> bool { ret !(is_NaN(x) || is_infinite(x)); } @@ -137,69 +128,43 @@ mod consts { // FIXME replace with mathematical constants from cmath - #[doc( - brief = "Archimedes' constant" - )] + #[doc = "Archimedes' constant"] const pi: f64 = 3.14159265358979323846264338327950288_f64; - #[doc( - brief = "pi/2.0" - )] + #[doc = "pi/2.0"] const frac_pi_2: f64 = 1.57079632679489661923132169163975144_f64; - #[doc( - brief = "pi/4.0" - )] + #[doc = "pi/4.0"] const frac_pi_4: f64 = 0.785398163397448309615660845819875721_f64; - #[doc( - brief = "1.0/pi" - )] + #[doc = "1.0/pi"] const frac_1_pi: f64 = 0.318309886183790671537767526745028724_f64; - #[doc( - brief = "2.0/pi" - )] + #[doc = "2.0/pi"] const frac_2_pi: f64 = 0.636619772367581343075535053490057448_f64; - #[doc( - brief = "2.0/sqrt(pi)" - )] + #[doc = "2.0/sqrt(pi)"] const frac_2_sqrtpi: f64 = 1.12837916709551257389615890312154517_f64; - #[doc( - brief = "sqrt(2.0)" - )] + #[doc = "sqrt(2.0)"] const sqrt2: f64 = 1.41421356237309504880168872420969808_f64; - #[doc( - brief = "1.0/sqrt(2.0)" - )] + #[doc = "1.0/sqrt(2.0)"] const frac_1_sqrt2: f64 = 0.707106781186547524400844362104849039_f64; - #[doc( - brief = "Euler's number" - )] + #[doc = "Euler's number"] const e: f64 = 2.71828182845904523536028747135266250_f64; - #[doc( - brief = "log2(e)" - )] + #[doc = "log2(e)"] const log2_e: f64 = 1.44269504088896340735992468100189214_f64; - #[doc( - brief = "log10(e)" - )] + #[doc = "log10(e)"] const log10_e: f64 = 0.434294481903251827651128918916605082_f64; - #[doc( - brief = "ln(2.0)" - )] + #[doc = "ln(2.0)"] const ln_2: f64 = 0.693147180559945309417232121458176568_f64; - #[doc( - brief = "ln(10.0)" - )] + #[doc = "ln(10.0)"] const ln_10: f64 = 2.30258509299404568401799145468436421_f64; } diff --git a/src/libcore/float.rs b/src/libcore/float.rs index 09aa575e003..aec7fd8b0ed 100644 --- a/src/libcore/float.rs +++ b/src/libcore/float.rs @@ -1,9 +1,5 @@ #[doc = "Operations and constants for `float`"]; -/* -Module: float -*/ - // FIXME find out why these have to be exported explicitly export to_str_common, to_str_exact, to_str, from_str; @@ -36,17 +32,15 @@ type t = float; * Section: String Conversions */ -/* -Function: to_str_common - +#[doc = " Converts a float to a string -Parameters: +# Arguments -num - The float value -digits - The number of significant digits -exact - Whether to enforce the exact number of significant digits -*/ +* 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"; } let mut (num, accum) = if num < 0.0 { (-num, "-") } else { (num, "") }; @@ -69,17 +63,15 @@ fn to_str_common(num: float, digits: uint, exact: bool) -> str { } -/* -Function: to_str +#[doc = " +Converts a float to a string with exactly the number of +provided significant digits -Converts a float to a string with exactly the number of provided significant -digits +# Arguments -Parameters: - -num - The float value -digits - The number of significant digits -*/ +* 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) } @@ -90,47 +82,45 @@ fn test_to_str_exact_do_decimal() { assert s == "5.0000"; } -/* -Function: to_str -Converts a float to a string with a maximum number of significant digits +#[doc = " +Converts a float to a string with a maximum number of +significant digits -Parameters: +# Arguments -num - The float value -digits - The number of significant digits -*/ +* num - The float value +* digits - The number of significant digits +"] fn to_str(num: float, digits: uint) -> str { to_str_common(num, digits, false) } -/* -Function: from_str - +#[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" + +* '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' Leading and trailing whitespace are ignored. -Parameters: +# Arguments -num - A string +* num - A string -Returns: +# 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]. -*/ +`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 { let mut pos = 0u; //Current byte position in the string. //Used to walk the string in O(n). @@ -256,18 +246,18 @@ fn from_str(num: str) -> option { * Section: Arithmetics */ -/* -Function: pow_with_uint +#[doc = " +Compute the exponentiation of an integer by another integer as a float -Compute the exponentiation of an integer by another integer as a float. +# Arguments -Parameters: -x - The base. -pow - The exponent. +* x - The base +* pow - The exponent -Returns: - of both `x` and `pow` are `0u`, otherwise `x^pow`. -*/ +# 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 { diff --git a/src/libcore/future.rs b/src/libcore/future.rs index 43d0e55edf0..faf5cca0e6c 100644 --- a/src/libcore/future.rs +++ b/src/libcore/future.rs @@ -1,14 +1,14 @@ #[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_sandwitch(); -> io::println(#fmt(\"fib(5000) = %?\", delayed_fib.get())) +# Example +~~~ +let delayed_fib = future::spawn {|| fib(5000) }; +make_a_sandwitch(); +io::println(#fmt(\"fib(5000) = %?\", delayed_fib.get())) +~~~ "]; export future; @@ -45,10 +45,10 @@ impl future for future { fn from_value(+val: A) -> future { #[doc = " + Create a future from a value - Create a future from a value. The value is immediately available - and calling `get` later will not block. - + The value is immediately available and calling `get` later will + not block. "]; future({ @@ -58,11 +58,10 @@ fn from_value(+val: A) -> future { fn from_port(-port: comm::port) -> future { #[doc = " + Create a future from a 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. - + The first time that the value is requested the task will block + waiting for the result to be received on the port. "]; from_fn {|| @@ -72,12 +71,11 @@ fn from_port(-port: comm::port) -> future { fn from_fn(f: fn@() -> A) -> future { #[doc = " + Create a future from a function. - 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. + 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({ @@ -87,10 +85,10 @@ fn from_fn(f: fn@() -> A) -> future { fn spawn(+blk: fn~() -> A) -> future { #[doc = " + Create a future from a unique closure. - 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. - + The closure will be run in a new task and its result used as the + value of the future. "]; let mut po = comm::port(); diff --git a/src/libcore/int.rs b/src/libcore/int.rs index 8c3b8f195f7..b0e918fdd99 100644 --- a/src/libcore/int.rs +++ b/src/libcore/int.rs @@ -1,25 +1,11 @@ #[doc = "Operations and constants for `int`"]; -/* -Module: int -*/ - -/* -Const: min_value - -The minumum value of an integer -*/ #[cfg(target_arch="x86")] const min_value: int = -1 << 31; #[cfg(target_arch="x86_64")] const min_value: int = -1 << 63; -/* -Const: max_value - -The maximum value of an integer -*/ // FIXME: Find another way to access the machine word size in a const expr #[cfg(target_arch="x86")] const max_value: int = (-1 << 31)-1; @@ -30,80 +16,43 @@ const max_value: int = (-1 << 63)-1; pure fn min(x: int, y: int) -> int { if x < y { x } else { y } } pure fn max(x: int, y: int) -> int { if x > y { x } else { y } } -/* Function: add */ pure fn add(x: int, y: int) -> int { ret x + y; } - -/* Function: sub */ pure fn sub(x: int, y: int) -> int { ret x - y; } - -/* Function: mul */ pure fn mul(x: int, y: int) -> int { ret x * y; } - -/* Function: div */ pure fn div(x: int, y: int) -> int { ret x / y; } - -/* Function: rem */ pure fn rem(x: int, y: int) -> int { ret x % y; } -/* Predicate: lt */ pure fn lt(x: int, y: int) -> bool { ret x < y; } - -/* Predicate: le */ pure fn le(x: int, y: int) -> bool { ret x <= y; } - -/* Predicate: eq */ pure fn eq(x: int, y: int) -> bool { ret x == y; } - -/* Predicate: ne */ pure fn ne(x: int, y: int) -> bool { ret x != y; } - -/* Predicate: ge */ pure fn ge(x: int, y: int) -> bool { ret x >= y; } - -/* Predicate: gt */ pure fn gt(x: int, y: int) -> bool { ret x > y; } -/* Predicate: positive */ pure fn positive(x: int) -> bool { ret x > 0; } - -/* Predicate: negative */ pure fn negative(x: int) -> bool { ret x < 0; } - -/* Predicate: nonpositive */ pure fn nonpositive(x: int) -> bool { ret x <= 0; } - -/* Predicate: nonnegative */ pure fn nonnegative(x: int) -> bool { ret x >= 0; } // FIXME: Make sure this works with negative integers. -/* -Function: hash - -Produce a uint suitable for use in a hash table -*/ +#[doc = "Produce a uint suitable for use in a hash table"] fn hash(x: int) -> uint { ret x as uint; } -/* -Function: range - -Iterate over the range [`lo`..`hi`) -*/ +#[doc = "Iterate over the range `[lo..hi)`"] fn range(lo: int, hi: int, it: fn(int)) { let mut i = lo; while i < hi { it(i); i += 1; } } -/* -Function: parse_buf - +#[doc = " Parse a buffer of bytes -Parameters: +# Arguments -buf - A byte buffer -radix - The base of the number -*/ +* buf - A byte buffer +* radix - The base of the number +"] fn parse_buf(buf: [u8], radix: uint) -> option { if vec::len(buf) == 0u { ret none; } let mut i = vec::len(buf) - 1u; @@ -127,18 +76,10 @@ fn parse_buf(buf: [u8], radix: uint) -> option { fail; } -/* -Function: from_str - -Parse a string to an int -*/ +#[doc = "Parse a string to an int"] fn from_str(s: str) -> option { parse_buf(str::bytes(s), 10u) } -/* -Function: to_str - -Convert to a string in a given base -*/ +#[doc = "Convert to a string in a given base"] fn to_str(n: int, radix: uint) -> str { assert (0u < radix && radix <= 16u); ret if n < 0 { @@ -146,18 +87,10 @@ fn to_str(n: int, radix: uint) -> str { } else { uint::to_str(n as uint, radix) }; } -/* -Function: str - -Convert to a string -*/ +#[doc = "Convert to a string"] fn str(i: int) -> str { ret to_str(i, 10u); } -/* -Function: pow - -Returns `base` raised to the power of `exponent` -*/ +#[doc = "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; } diff --git a/src/libcore/logging.rs b/src/libcore/logging.rs index d9c0274f390..48e3fcc2ff2 100644 --- a/src/libcore/logging.rs +++ b/src/libcore/logging.rs @@ -13,14 +13,13 @@ fn console_on() { rustrt::rust_log_console_on(); } -#[doc( - brief = - "Turns off logging to stdout globally", - desc = - "Turns off the console unless the user has overridden the \ - runtime environment's logging spec, e.g. by setting \ - the RUST_LOG environment variable" -)] +#[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 +"] fn console_off() { rustrt::rust_log_console_off(); } \ No newline at end of file diff --git a/src/libcore/math.rs b/src/libcore/math.rs index 2552d58b4a2..9e14091a532 100644 --- a/src/libcore/math.rs +++ b/src/libcore/math.rs @@ -1,19 +1,13 @@ -// Generic functions that have been defined for all numeric types -// -// (may very well go away again soon) +#[doc = " +Generic functions that have been defined for all numeric types -/* -Function: min +(may very well go away again soon) +"]; -Returns the minimum of two values -*/ +#[doc = "Returns the minimum of two values"] pure fn min(x: T, y: T) -> T { if x < y { x } else { y} } -/* -Function: max - -Returns the maximum of two values -*/ +#[doc = "Returns the maximum of two values"] pure fn max(x: T, y: T) -> T { if x < y { y } else { x } } #[test] diff --git a/src/libcore/option.rs b/src/libcore/option.rs index 84421975425..47e407e4952 100644 --- a/src/libcore/option.rs +++ b/src/libcore/option.rs @@ -1,107 +1,83 @@ -/* -Module: option +#[doc = " +Operations on the ubiquitous `option` type. -Represents the presence or absence of a value. +Type `option` represents an optional value. -Every option 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. -*/ +Every `option` 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. +"]; -/* -Tag: t - -The option type -*/ +#[doc = "The option type"] enum t { - /* Variant: none */ none, - /* Variant: some */ some(T), } -/* Section: Operations */ - -/* -Function: get - -Gets the value out of an option - -Failure: - -Fails if the value equals `none`. -*/ pure fn get(opt: t) -> T { + #[doc = " + Gets the value out of an option + + # Failure + + Fails if the value equals `none` + "]; + alt opt { some(x) { ret x; } none { fail "option none"; } } } -/* -*/ fn map(opt: t, f: fn(T) -> U) -> t { + #[doc = "Maps a `some` value from one type to another"]; + alt opt { some(x) { some(f(x)) } none { none } } } -/* -Function: chain - -Update an optional value by optionally running its content through a function -that returns an option. -*/ fn chain(opt: t, f: fn(T) -> t) -> t { + #[doc = " + Update an optional value by optionally running its content through a + function that returns an option. + "]; + alt opt { some(x) { f(x) } none { none } } } -/* -Function: is_none - -Returns true if the option equals none -*/ pure fn is_none(opt: t) -> bool { + #[doc = "Returns true if the option equals `none`"]; + alt opt { none { true } some(_) { false } } } -/* -Function: is_some +pure fn is_some(opt: t) -> bool { + #[doc = "Returns true if the option contains some value"]; -Returns true if the option contains some value -*/ -pure fn is_some(opt: t) -> bool { !is_none(opt) } + !is_none(opt) +} -/* -Function: from_maybe - -Returns the contained value or a default -*/ pure fn from_maybe(def: T, opt: t) -> T { + #[doc = "Returns the contained value or a default"]; + alt opt { some(x) { x } none { def } } } -/* -Function: maybe - -Applies a function to the contained value or returns a default -*/ fn maybe(def: U, opt: t, f: fn(T) -> U) -> U { + #[doc = "Applies a function to the contained value or returns a default"]; + alt opt { none { def } some(t) { f(t) } } } -// FIXME: Can be defined in terms of the above when/if we have const bind. -/* -Function: may - -Performs an operation on the contained value or does nothing -*/ fn may(opt: t, f: fn(T)) { - alt opt { none {/* nothing */ } some(t) { f(t); } } + #[doc = "Performs an operation on the contained value or does nothing"]; + + alt opt { none { } some(t) { f(t); } } } -/* -Function: unwrap - -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. -*/ fn unwrap(-opt: t) -> T unsafe { + #[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. + "]; + let addr = alt opt { some(x) { ptr::addr_of(x) } none { fail "option none" } diff --git a/src/libcore/os.rs b/src/libcore/os.rs index 43192afca8e..42d74e4a94c 100644 --- a/src/libcore/os.rs +++ b/src/libcore/os.rs @@ -1,18 +1,20 @@ -// 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. +#[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. +"]; import libc::{c_char, c_void, c_int, c_uint, size_t, ssize_t, mode_t, pid_t, FILE}; @@ -327,21 +329,19 @@ fn self_exe_path() -> option { } -/* -Function: homedir - +#[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 +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 +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 +'USERPROFILE' environment variable if it is set and not equal to the empty string. Otherwise, homedir returns option::none. -*/ +"] fn homedir() -> option { ret alt getenv("HOME") { some(p) { @@ -377,22 +377,14 @@ fn homedir() -> option { -/* -Function: path_is_dir - -Indicates whether a path represents a directory. -*/ +#[doc = "Indicates whether a path represents a directory"] fn path_is_dir(p: path) -> bool { str::as_buf(p) {|buf| rustrt::rust_path_is_dir(buf) != 0 as c_int } } -/* -Function: path_exists - -Indicates whether a path exists. -*/ +#[doc = "Indicates whether a path exists"] fn path_exists(p: path) -> bool { str::as_buf(p) {|buf| rustrt::rust_path_exists(buf) != 0 as c_int @@ -401,15 +393,13 @@ fn path_exists(p: path) -> bool { // FIXME: under Windows, we should prepend the current drive letter to paths // that start with a slash. -/* -Function: make_absolute - +#[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. -*/ +"] // 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. @@ -422,11 +412,7 @@ fn make_absolute(p: path) -> path { } -/* -Function: make_dir - -Creates a directory at the specified path. -*/ +#[doc = "Creates a directory at the specified path"] fn make_dir(p: path, mode: c_int) -> bool { ret mkdir(p, mode); @@ -453,11 +439,7 @@ fn make_dir(p: path, mode: c_int) -> bool { } } -/* -Function: list_dir - -Lists the contents of a directory. -*/ +#[doc = "Lists the contents of a directory"] fn list_dir(p: path) -> [str] { #[cfg(target_os = "linux")] @@ -485,11 +467,7 @@ fn list_dir(p: path) -> [str] { ret full_paths; } -/* -Function: remove_dir - -Removes a directory at the specified path. -*/ +#[doc = "Removes a directory at the specified path"] fn remove_dir(p: path) -> bool { ret rmdir(p); @@ -538,11 +516,7 @@ fn change_dir(p: path) -> bool { } } -/* -Function: remove_file - -Deletes an existing file. -*/ +#[doc = "Deletes an existing file"] fn remove_file(p: path) -> bool { ret unlink(p); diff --git a/src/libcore/path.rs b/src/libcore/path.rs index 5658e57f68a..4e0d64b6d44 100644 --- a/src/libcore/path.rs +++ b/src/libcore/path.rs @@ -1,8 +1,4 @@ -/* -Module: path - -Path data type and helper functions. -*/ +#[doc = "Path data type and helper functions"] #[cfg(target_os = "macos")] #[cfg(target_os = "freebsd")] @@ -18,14 +14,12 @@ mod consts { const alt_path_sep: char = '\\'; } -/* -Function: path_is_absolute - +#[doc = " Indicates whether a path is absolute. -A path is considered absolute if it begins at the filesystem root ("/") or, +A path is considered absolute if it begins at the filesystem root (\"/\") or, on Windows, begins with a drive letter. -*/ +"] #[cfg(target_os = "macos")] #[cfg(target_os = "freebsd")] #[cfg(target_os = "linux")] @@ -43,19 +37,11 @@ fn path_is_absolute(p: str) -> bool { -/* -Function: path_sep - -Get the default path separator for the host platform -*/ +#[doc = "Get the default path separator for the host platform"] fn path_sep() -> str { ret str::from_char(consts::path_sep); } // FIXME: This type should probably be constrained -/* -Type: path - -A path or fragment of a filesystem path -*/ +#[doc = "A path or fragment of a filesystem path"] type path = str; fn split_dirname_basename (pp: path) -> {dirname: str, basename: str} { @@ -70,47 +56,40 @@ fn split_dirname_basename (pp: path) -> {dirname: str, basename: str} { } } -/* -Function: dirname - +#[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". +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. -*/ +If the path is not prefixed with a directory, then \".\" is returned. +"] fn dirname(pp: path) -> path { ret split_dirname_basename(pp).dirname; } -/* -Function: basename - +#[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 +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; } // FIXME: Need some typestate to avoid bounds check when len(pre) == 0 -/* -Function: connect - +#[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. -*/ - +"] fn connect(pre: path, post: path) -> path unsafe { let mut pre_ = pre; let mut post_ = post; @@ -122,13 +101,11 @@ fn connect(pre: path, post: path) -> path unsafe { ret pre_ + path_sep() + post_; } -/* -Function: connect_many - +#[doc = " 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] @@ -138,31 +115,29 @@ fn connect_many(paths: [path]) -> path { } } -/* -Function: split - +#[doc = " Split a path into it's 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 }) } -/* -Function: splitext +#[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. -*/ +"] fn splitext(p: path) -> (str, str) { if str::is_empty(p) { ("", "") } else { @@ -204,13 +179,11 @@ fn splitext(p: path) -> (str, str) { } } -/* -Function: normalize - -Removes extra "." and ".." entries from paths. +#[doc = " +Removes extra '.' and '..' entries from paths Does not follow symbolic links. -*/ +"] fn normalize(p: path) -> path { let s = split(p); let s = strip_dots(s); diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs index 636a076abb9..9377940243d 100644 --- a/src/libcore/ptr.rs +++ b/src/libcore/ptr.rs @@ -1,8 +1,5 @@ -/* -Module: ptr +#[doc = "Unsafe pointer utility functions"] -Unsafe pointer utility functions -*/ #[abi = "rust-intrinsic"] native mod rusti { fn addr_of(val: T) -> *T; @@ -11,70 +8,50 @@ native mod rusti { fn memmove(dst: *T, src: *T, count: ctypes::uintptr_t); } -/* -Function: addr_of - -Get an unsafe pointer to a value -*/ +#[doc = "Get an unsafe pointer to a value"] #[inline(always)] fn addr_of(val: T) -> *T { ret rusti::addr_of(val); } -/* -Function: mut_addr_of - -Get an unsafe mutable pointer to a value -*/ +#[doc = "Get an unsafe mutable pointer to a value"] #[inline(always)] fn mut_addr_of(val: T) -> *mutable T unsafe { ret unsafe::reinterpret_cast(rusti::addr_of(val)); } -/* -Function: offset - -Calculate the offset from a pointer -*/ +#[doc = "Calculate the offset from a pointer"] #[inline(always)] fn offset(ptr: *T, count: uint) -> *T { ret rusti::ptr_offset(ptr, count); } -/* -Function: mut_offset - -Calculate the offset from a mutable pointer -*/ +#[doc = "Calculate the offset from a mutable pointer"] #[inline(always)] fn mut_offset(ptr: *mutable T, count: uint) -> *mutable T { ret rusti::ptr_offset(ptr as *T, count) as *mutable T; } -/* -Function: null - -Create an unsafe null pointer -*/ +#[doc = "Create an unsafe null pointer"] #[inline(always)] fn null() -> *T unsafe { ret unsafe::reinterpret_cast(0u); } -/* -Function: memcpy +#[doc = " +Copies data from one location to another -Copies data from one src to dst that is not overlapping each other. -Count is the number of elements to copy and not the number of bytes. -*/ +Copies `count` elements (not bytes) from `src` to `dst`. The source +and destination may not overlap. +"] #[inline(always)] unsafe fn memcpy(dst: *T, src: *T, count: uint) { rusti::memcpy(dst, src, count); } -/* -Function: memmove +#[doc = " +Copies data from one location to another -Copies data from one src to dst, overlap between the two pointers may occur. -Count is the number of elements to copy and not the number of bytes. -*/ +Copies `count` elements (not bytes) from `src` to `dst`. The source +and destination may overlap. +"] #[inline(always)] unsafe fn memmove(dst: *T, src: *T, count: uint) { rusti::memmove(dst, src, count); diff --git a/src/libcore/result.rs b/src/libcore/result.rs index 52c3ff95d23..b3c01f62f9d 100644 --- a/src/libcore/result.rs +++ b/src/libcore/result.rs @@ -1,42 +1,20 @@ -/* -Module: result +#[doc = "A type representing either success or failure"]; -A type representing either success or failure -*/ - -/* Section: Types */ - -/* -Tag: t - -The result type -*/ +#[doc = "The result type"] enum t { - /* - Variant: ok - - Contains the result value - */ + #[doc = "Contains the successful result value"] ok(T), - /* - Variant: err - - Contains the error value - */ + #[doc = "Contains the error value"] err(U) } -/* Section: Operations */ - -/* -Function: get - +#[doc = " Get the value out of a successful result -Failure: +# Failure If the result is an error -*/ +"] fn get(res: t) -> T { alt res { ok(t) { t } @@ -48,15 +26,13 @@ fn get(res: t) -> T { } } -/* -Function: get_err - +#[doc = " Get the value out of an error result -Failure: +# Failure If the result is not an error -*/ +"] fn get_err(res: t) -> U { alt res { err(u) { u } @@ -66,11 +42,7 @@ fn get_err(res: t) -> U { } } -/* -Function: success - -Returns true if the result is -*/ +#[doc = "Returns true if the result is `ok`"] pure fn success(res: t) -> bool { alt res { ok(_) { true } @@ -78,15 +50,17 @@ pure fn success(res: t) -> bool { } } -/* -Function: failure - -Returns true if the result is -*/ +#[doc = "Returns true if the result is `error`"] pure fn failure(res: t) -> bool { !success(res) } +#[doc = " +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(res: t) -> either::t { alt res { ok(res) { either::right(res) } @@ -94,22 +68,19 @@ pure fn to_either(res: t) -> either::t { } } -/* -Function: chain - +#[doc = " Call a function based on a previous result -If `res` is then the value is extracted and passed to `op` whereupon -`op`s result is returned. if `res` is then it is immediately returned. +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)) -> }) - -*/ + let res = chain(read_file(file)) { |buf| + ok(parse_buf(buf)) + } +"] fn chain(res: t, op: fn(T) -> t) -> t { alt res { diff --git a/src/libcore/str.rs b/src/libcore/str.rs index 0325e90c18b..52f342c81d5 100644 --- a/src/libcore/str.rs +++ b/src/libcore/str.rs @@ -1,13 +1,11 @@ -/* -Module: str - +#[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. -*/ +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. +"]; export // Creating a string @@ -110,21 +108,25 @@ native mod rustrt { Section: Creating a string */ -/* -Function: from_bytes +#[doc = " +Convert a vector of bytes to a UTF-8 string -Convert a vector of bytes to a UTF-8 string. Fails if invalid UTF-8. -*/ +# Failure + +Fails if invalid UTF-8 +"] fn from_bytes(vv: [u8]) -> str unsafe { assert is_utf8(vv); ret unsafe::from_bytes(vv); } -/* -Function: from_byte +#[doc = " +Convert a byte to a UTF-8 string -Convert a byte to a UTF-8 string. Fails if invalid UTF-8. -*/ +# Failure + +Fails if invalid UTF-8 +"] fn from_byte(b: u8) -> str unsafe { assert b < 128u8; let mut v = [b, 0u8]; @@ -133,11 +135,7 @@ fn from_byte(b: u8) -> str unsafe { s } -/* -Function: push_char - -Appends a character at the end of a string. -*/ +#[doc = "Appends a character at the end of a string"] fn push_char(&s: str, ch: char) unsafe { let code = ch as uint; if code < max_one_b { @@ -170,22 +168,14 @@ fn push_char(&s: str, ch: char) unsafe { } } -/* -Function: from_char - -Convert a char to a string -*/ +#[doc = "Convert a char to a string"] fn from_char(ch: char) -> str { let mut buf = ""; push_char(buf, ch); ret buf; } -/* -Function: from_chars - -Convert a vector of chars to a string -*/ +#[doc = "Convert a vector of chars to a string"] fn from_chars(chs: [char]) -> str { let mut buf = ""; reserve(buf, chs.len()); @@ -193,11 +183,7 @@ fn from_chars(chs: [char]) -> str { ret buf; } -/* -Function: from_cstr - -Create a Rust string from a null-terminated C string -*/ +#[doc = "Create a Rust string from a null-terminated C string"] fn from_cstr(cstr: sbuf) -> str unsafe { let mut curr = cstr, i = 0u; while *curr != 0u8 { @@ -207,11 +193,7 @@ fn from_cstr(cstr: sbuf) -> str unsafe { ret from_cstr_len(cstr, i); } -/* -Function: from_cstr_len - -Create a Rust string from a C string of the given length -*/ +#[doc = "Create a Rust string from a C string of the given length"] fn from_cstr_len(cstr: sbuf, len: uint) -> str unsafe { let mut buf: [u8] = []; vec::reserve(buf, len + 1u); @@ -225,22 +207,16 @@ fn from_cstr_len(cstr: sbuf, len: uint) -> str unsafe { ret s; } -/* -Function: concat - -Concatenate a vector of strings -*/ +#[doc = "Concatenate a vector of strings"] fn concat(v: [str]) -> str { let mut s: str = ""; for ss: str in v { s += ss; } ret s; } -/* -Function: connect - +#[doc = " Concatenate a vector of strings, placing a given separator between each -*/ +"] fn connect(v: [str], sep: str) -> str { let mut s = "", first = true; for ss: str in v { @@ -254,14 +230,13 @@ fn connect(v: [str], sep: str) -> str { Section: Adding to and removing from a string */ -/* -Function: pop_char +#[doc = " +Remove the final character from a string and return it -Remove the final character from a string and return it. +# Failure -Failure: -If the string does not contain any characters. -*/ +If the string does not contain any characters +"] fn pop_char(&s: str) -> char { let end = len(s); assert end > 0u; @@ -270,33 +245,23 @@ fn pop_char(&s: str) -> char { ret ch; } -/* -Function: shift_char +#[doc = " +Remove the first character from a string and return it -Remove the first character from a string and return it. +# Failure -Failure: - -If the string does not contain any characters. -*/ +If the string does not contain any characters +"] fn shift_char(&s: str) -> char unsafe { let {ch, next} = char_range_at(s, 0u); s = unsafe::slice_bytes(s, next, len(s)); ret ch; } -/* -Function: unshift_char - -Prepend a char to a string -*/ +#[doc = "Prepend a char to a string"] fn unshift_char(&s: str, ch: char) { s = from_char(ch) + s; } -/* -Function: trim_left - -Returns a string with leading whitespace removed. -*/ +#[doc = "Returns a string with leading whitespace removed"] fn trim_left(+s: str) -> str { alt find(s, {|c| !char::is_whitespace(c)}) { none { "" } @@ -307,11 +272,7 @@ fn trim_left(+s: str) -> str { } } -/* -Function: trim_right - -Returns a string with trailing whitespace removed. -*/ +#[doc = "Returns a string with trailing whitespace removed"] fn trim_right(+s: str) -> str { alt rfind(s, {|c| !char::is_whitespace(c)}) { none { "" } @@ -323,32 +284,23 @@ fn trim_right(+s: str) -> str { } } -/* -Function: trim - -Returns a string with leading and trailing whitespace removed -*/ +#[doc = "Returns a string with leading and trailing whitespace removed"] fn trim(+s: str) -> str { trim_left(trim_right(s)) } /* Section: Transforming strings */ -/* -Function: bytes +#[doc = " +Converts a string to a vector of bytes -Converts a string to a vector of bytes. The result vector is not -null-terminated. -*/ +The result vector is not null-terminated. +"] fn bytes(s: str) -> [u8] unsafe { as_bytes(s) { |v| vec::slice(v, 0u, vec::len(v) - 1u) } } -/* -Function: chars - -Convert a string to a vector of characters -*/ +#[doc = "Convert a string to a vector of characters"] fn chars(s: str) -> [char] { let mut buf = [], i = 0u; let len = len(s); @@ -360,48 +312,48 @@ fn chars(s: str) -> [char] { ret buf; } -/* -Function: substr +#[doc = " +Take a substring of another. -Take a substring of another. Returns a string containing `n` -characters starting at byte offset `begin`. -*/ +Returns a string containing `n` characters starting at byte offset +`begin`. +"] fn substr(s: str, begin: uint, n: uint) -> str { slice(s, begin, begin + count_bytes(s, begin, n)) } -// Function: slice -// -// Return a slice of the given string from the byte range [`begin`..`end`) -// or else fail when `begin` and `end` do not point to valid characters or -// beyond the last character of the string +#[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 +"] fn slice(s: str, begin: uint, end: uint) -> str unsafe { assert is_char_boundary(s, begin); assert is_char_boundary(s, end); unsafe::slice_bytes(s, begin, end) } -// Function: split_char -// -// Splits a string into substrings at each occurrence of a given -// character +#[doc = " +Splits a string into substrings at each occurrence of a given character +"] fn split_char(s: str, sep: char) -> [str] { split_char_inner(s, sep, len(s), true) } -// Function: splitn_char -// -// 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 +#[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 +"] fn splitn_char(s: str, sep: char, count: uint) -> [str] { split_char_inner(s, sep, count, true) } -// Function: split_char_nonempty -// -// Like `split_char`, but omits empty strings from the returned vector. +#[doc = " +Like `split_char`, but omits empty strings from the returned vector +"] fn split_char_nonempty(s: str, sep: char) -> [str] { split_char_inner(s, sep, len(s), false) } @@ -432,28 +384,20 @@ fn split_char_inner(s: str, sep: char, count: uint, allow_empty: bool) } -/* -Function: split - -Splits a string into substrings using a character function -*/ +#[doc = "Splits a string into substrings using a character function"] fn split(s: str, sepfn: fn(char) -> bool) -> [str] { split_inner(s, sepfn, len(s), true) } -/* -Function: splitn - +#[doc = " Splits a string into substrings using a character function, cutting at -most [count] times. -*/ +most `count` times. +"] fn splitn(s: str, sepfn: fn(char) -> bool, count: uint) -> [str] { split_inner(s, sepfn, count, true) } -// Function: split_nonempty -// -// Like `split`, but omits empty strings from the returned vector. +#[doc = "Like `split`, but omits empty strings from the returned vector"] fn split_nonempty(s: str, sepfn: fn(char) -> bool) -> [str] { split_inner(s, sepfn, len(s), false) } @@ -516,14 +460,15 @@ fn iter_between_matches(s: str, sep: str, f: fn(uint, uint)) { f(last_end, len(s)); } -/* -Function: split_str - +#[doc = " Splits a string into a vector of the substrings separated by a given string -Note that this has recently been changed. For example: -> assert ["", "XXX", "YYY", ""] == split_str(".XXX.YYY.", ".") -*/ +# Example + +~~~ +assert [\"\", \"XXX\", \"YYY\", \"\"] == split_str(\".XXX.YYY.\", \".\") +~~~ +"] fn split_str(s: str, sep: str) -> [str] { let mut result = []; iter_between_matches(s, sep) {|from, to| @@ -542,20 +487,15 @@ fn split_str_nonempty(s: str, sep: str) -> [str] { result } -/* -Function: lines - -Splits a string into a vector of the substrings -separated by LF ('\n') -*/ +#[doc = " +Splits a string into a vector of the substrings separated by LF ('\n') +"] fn lines(s: str) -> [str] { split_char(s, '\n') } -/* -Function: lines_any - -Splits a string into a vector of the substrings -separated by LF ('\n') and/or CR LF ('\r\n') -*/ +#[doc = " +Splits a string into a vector of the substrings separated by LF ('\n') +and/or CR LF ('\r\n') +"] fn lines_any(s: str) -> [str] { vec::map(lines(s), {|s| let l = len(s); @@ -567,49 +507,36 @@ fn lines_any(s: str) -> [str] { }) } -/* -Function: words - -Splits a string into a vector of the substrings -separated by whitespace -*/ +#[doc = " +Splits a string into a vector of the substrings separated by whitespace +"] fn words(s: str) -> [str] { split_nonempty(s, {|c| char::is_whitespace(c)}) } -/* -Function: to_lower - -Convert a string to lowercase -*/ +#[doc = "Convert a string to lowercase"] fn to_lower(s: str) -> str { map(s, char::to_lower) } -/* -Function: to_upper - -Convert a string to uppercase -*/ +#[doc = "Convert a string to uppercase"] fn to_upper(s: str) -> str { map(s, char::to_upper) } -/* -Function: replace - +#[doc = " Replace all occurances of one string with another -Parameters: +# Arguments -s - The string containing substrings to replace -from - The string to replace -to - The replacement string +* s - The string containing substrings to replace +* from - The string to replace +* to - The replacement string -Returns: +# Return value The original string with all occurances of `from` replaced with `to` -*/ +"] fn replace(s: str, from: str, to: str) -> str unsafe { let mut result = "", first = true; iter_between_matches(s, from) {|start, end| @@ -623,25 +550,13 @@ fn replace(s: str, from: str, to: str) -> str unsafe { Section: Comparing strings */ -/* -Function: eq - -Bytewise string equality -*/ +#[doc = "Bytewise string equality"] pure fn eq(&&a: str, &&b: str) -> bool { a == b } -/* -Function: le - -Bytewise less than or equal -*/ +#[doc = "Bytewise less than or equal"] pure fn le(&&a: str, &&b: str) -> bool { a <= b } -/* -Function: hash - -String hash function -*/ +#[doc = "String hash function"] fn hash(&&s: str) -> uint { // djb hash. // FIXME: replace with murmur. @@ -654,31 +569,23 @@ fn hash(&&s: str) -> uint { Section: Iterating through strings */ -/* -Function: all - -Return true if a predicate matches all characters or -if the string contains no characters -*/ +#[doc = " +Return true if a predicate matches all characters or if the string +contains no characters +"] fn all(s: str, it: fn(char) -> bool) -> bool { all_between(s, 0u, len(s), it) } -/* -Function: any - -Return true if a predicate matches any character -(and false if it matches none or there are no characters) -*/ +#[doc = " +Return true if a predicate matches any character (and false if it +matches none or there are no characters) +"] fn any(ss: str, pred: fn(char) -> bool) -> bool { !all(ss, {|cc| !pred(cc)}) } -/* -Function: map - -Apply a function to each character -*/ +#[doc = "Apply a function to each character"] fn map(ss: str, ff: fn(char) -> char) -> str { let mut result = ""; reserve(result, len(ss)); @@ -686,11 +593,7 @@ fn map(ss: str, ff: fn(char) -> char) -> str { result } -/* -Function: bytes_iter - -Iterate over the bytes in a string -*/ +#[doc = "Iterate over the bytes in a string"] fn bytes_iter(ss: str, it: fn(u8)) { let mut pos = 0u; let len = len(ss); @@ -701,11 +604,7 @@ fn bytes_iter(ss: str, it: fn(u8)) { } } -/* -Function: chars_iter - -Iterate over the characters in a string -*/ +#[doc = "Iterate over the characters in a string"] fn chars_iter(s: str, it: fn(char)) { let mut pos = 0u; let len = len(s); @@ -716,40 +615,27 @@ fn chars_iter(s: str, it: fn(char)) { } } -/* -Function: split_char_iter - -Apply a function to each substring after splitting -by character -*/ +#[doc = " +Apply a function to each substring after splitting by character +"] fn split_char_iter(ss: str, cc: char, ff: fn(&&str)) { vec::iter(split_char(ss, cc), ff) } -/* -Function: splitn_char_iter - -Apply a function to each substring after splitting -by character, up to `count` times -*/ +#[doc = " +Apply a function to each substring after splitting by character, up to +`count` times +"] fn splitn_char_iter(ss: str, sep: char, count: uint, ff: fn(&&str)) unsafe { vec::iter(splitn_char(ss, sep, count), ff) } -/* -Function: words_iter - -Apply a function to each word -*/ +#[doc = "Apply a function to each word"] fn words_iter(ss: str, ff: fn(&&str)) { vec::iter(words(ss), ff) } -/* -Function: lines_iter - -Apply a function to each lines (by '\n') -*/ +#[doc = "Apply a function to each lines (by '\n')"] fn lines_iter(ss: str, ff: fn(&&str)) { vec::iter(lines(ss), ff) } @@ -758,26 +644,25 @@ fn lines_iter(ss: str, ff: fn(&&str)) { Section: Searching */ -// Function: find_char -// -// Returns the byte index of the first matching char -// (as option some/none) +#[doc = " +Returns the byte index of the first matching char (as option some/none) +"] fn find_char(s: str, c: char) -> option { find_char_between(s, c, 0u, len(s)) } -// Function: find_char_from -// -// Returns the byte index of the first matching char -// (as option some/none), starting from `start` +#[doc = " +Returns the byte index of the first matching char as option +some/none), starting from `start` +"] fn find_char_from(s: str, c: char, from: uint) -> option { find_char_between(s, c, from, len(s)) } -// Function: find_char_between -// -// Returns the byte index of the first matching char -// (as option some/none), between `start` and `end` +#[doc = " +Returns the byte index of the first matching char (as option +some/none), between `start` and `end` +"] fn find_char_between(s: str, c: char, start: uint, end: uint) -> option { if c < 128u as char { @@ -795,27 +680,26 @@ fn find_char_between(s: str, c: char, start: uint, end: uint) } } -// Function: rfind_char -// -// Returns the byte index of the last matching char -// (as option some/none) +#[doc = " +Returns the byte index of the last matching char as option some/none) +"] fn rfind_char(s: str, c: char) -> option { rfind_char_between(s, c, len(s), 0u) } -// Function: rfind_char_from -// -// Returns the byte index of the last matching char -// (as option some/none), starting from `start` +#[doc = " +Returns the byte index of the last matching char (as option +some/none), starting from `start` +"] fn rfind_char_from(s: str, c: char, start: uint) -> option { rfind_char_between(s, c, start, 0u) } -// Function: rfind_char_between -// -// Returns the byte index of the last matching char (as option -// some/none), between from `start` and `end` (start must be greater -// than or equal to end) +#[doc = " +Returns the byte index of the last matching char (as option +some/none), between from `start` and `end` (start must be greater +than or equal to end) +"] fn rfind_char_between(s: str, c: char, start: uint, end: uint) -> option { if c < 128u as char { @@ -833,26 +717,26 @@ fn rfind_char_between(s: str, c: char, start: uint, end: uint) } } -// Function: find -// -// Returns, as an option, the first character that passes the given -// predicate +#[doc = " +Returns, as an option, the first character that passes the given +predicate +"] fn find(s: str, f: fn(char) -> bool) -> option { find_between(s, 0u, len(s), f) } -// Function: find_from -// -// Returns, as an option, the first character that passes the given -// predicate, starting at byte offset `start` +#[doc = " +Returns, as an option, the first character that passes the given +predicate, starting at byte offset `start` +"] fn find_from(s: str, start: uint, f: fn(char) -> bool) -> option { find_between(s, start, len(s), f) } -// Function: find_between -// -// Returns, as an option, the first character that passes the given -// predicate, between byte offsets `start` and `end` +#[doc = " +Returns, as an option, the first character that passes the given +predicate, between byte offsets `start` and `end` +"] fn find_between(s: str, start: uint, end: uint, f: fn(char) -> bool) -> option { assert start <= end; @@ -867,27 +751,27 @@ fn find_between(s: str, start: uint, end: uint, f: fn(char) -> bool) ret none; } -// Function: rfind -// -// Returns, as an option, the last character in the string that passes -// the given predicate +#[doc = " +Returns, as an option, the last character in the string that passes +the given predicate +"] fn rfind(s: str, f: fn(char) -> bool) -> option { rfind_between(s, len(s), 0u, f) } -// Function: rfind_from -// -// Returns, as an option, the last character that passes the given -// predicate, up until byte offset `start` +#[doc = " +Returns, as an option, the last character that passes the given +predicate, up until byte offset `start` +"] fn rfind_from(s: str, start: uint, f: fn(char) -> bool) -> option { rfind_between(s, start, 0u, f) } -// Function: rfind_between -// -// Returns, as an option, the last character that passes the given -// predicate, between byte offsets `start` and `end` (`start` must be -// greater than or equal to `end`) +#[doc = " +Returns, as an option, the last character that passes the given +predicate, between byte offsets `start` and `end` (`start` must be +greater than or equal to `end`) +"] fn rfind_between(s: str, start: uint, end: uint, f: fn(char) -> bool) -> option { assert start >= end; @@ -909,27 +793,27 @@ fn match_at(haystack: str, needle: str, at: uint) -> bool { ret true; } -//Function: find_str -// -// Find the byte position of the first instance of one string -// within another, or return option::none +#[doc = " +Find the byte position of the first instance of one string +within another, or return `option::none` +"] fn find_str(haystack: str, needle: str) -> option { find_str_between(haystack, needle, 0u, len(haystack)) } -//Function: find_str_from -// -// Find the byte position of the first instance of one string -// within another, or return option::none +#[doc = " +Find the byte position of the first instance of one string +within another, or return `option::none` +"] fn find_str_from(haystack: str, needle: str, start: uint) -> option { find_str_between(haystack, needle, start, len(haystack)) } -//Function: find_str_between -// -// Find the byte position of the first instance of one string -// within another, or return option::none +#[doc = " +Find the byte position of the first instance of one string +within another, or return `option::none` +"] fn find_str_between(haystack: str, needle: str, start: uint, end:uint) -> option { // FIXME: Boyer-Moore should be significantly faster @@ -947,30 +831,26 @@ fn find_str_between(haystack: str, needle: str, start: uint, end:uint) ret none; } -/* -Function: contains - +#[doc = " Returns true if one string contains another -Parameters: +# Arguments -haystack - The string to look in -needle - The string to look for -*/ +* haystack - The string to look in +* needle - The string to look for +"] fn contains(haystack: str, needle: str) -> bool { option::is_some(find_str(haystack, needle)) } -/* -Function: starts_with - +#[doc = " Returns true if one string starts with another -Parameters: +# Arguments -haystack - The string to look in -needle - The string to look for -*/ +* haystack - The string to look in +* needle - The string to look for +"] fn starts_with(haystack: str, needle: str) -> bool unsafe { let haystack_len = len(haystack), needle_len = len(needle); if needle_len == 0u { true } @@ -978,14 +858,14 @@ fn starts_with(haystack: str, needle: str) -> bool unsafe { else { match_at(haystack, needle, 0u) } } -/* -Function: ends_with - +#[doc = " Returns true if one string ends with another -haystack - The string to look in -needle - The string to look for -*/ +# Arguments + +* haystack - The string to look in +* needle - The string to look for +"] fn ends_with(haystack: str, needle: str) -> bool { let haystack_len = len(haystack), needle_len = len(needle); if needle_len == 0u { true } @@ -997,64 +877,44 @@ fn ends_with(haystack: str, needle: str) -> bool { Section: String properties */ -/* -Function: is_ascii - -Determines if a string contains only ASCII characters -*/ +#[doc = "Determines if a string contains only ASCII characters"] 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; } -/* -Predicate: is_empty - -Returns true if the string has length 0 -*/ +#[doc = "Returns true if the string has length 0"] pure fn is_empty(s: str) -> bool { for c: u8 in s { ret false; } ret true; } -/* -Predicate: is_not_empty - -Returns true if the string has length greater than 0 -*/ +#[doc = "Returns true if the string has length greater than 0"] pure fn is_not_empty(s: str) -> bool { !is_empty(s) } -/* -Function: is_whitespace - +#[doc = " Returns true if the string contains only whitespace -*/ + +Whitespace characters are determined by `char::is_whitespace` +"] fn is_whitespace(s: str) -> bool { ret all(s, char::is_whitespace); } - -// Function: len -// -// Returns the string length/size in bytes -// not counting the null terminator +#[doc = " +Returns the string length/size in bytes not counting the null terminator +"] pure fn len(s: str) -> uint unsafe { let repr: *vec::unsafe::vec_repr = ::unsafe::reinterpret_cast(s); (*repr).fill - 1u } -// Function: char_len -// -// Returns the number of characters that a string holds +#[doc = "Returns the number of characters that a string holds"] fn char_len(s: str) -> uint { count_chars(s, 0u, len(s)) } /* Section: Misc */ -/* -Function: is_utf8 - -Determines if a vector of bytes contains valid UTF-8 -*/ +#[doc = "Determines if a vector of bytes contains valid UTF-8"] fn is_utf8(v: [const u8]) -> bool { let mut i = 0u; let total = vec::len::(v); @@ -1072,7 +932,6 @@ fn is_utf8(v: [const u8]) -> bool { ret true; } - fn is_utf16(v: [const u16]) -> bool { let len = v.len(); let mut i = 0u; @@ -1148,19 +1007,19 @@ fn from_utf16(v: [const u16]) -> str { } -/* -Function: count_chars - +#[doc = " As char_len but for a slice of a string -Parameters: - s - A valid string - start - The position inside `s` where to start counting in bytes. - end - The position where to stop counting +# Arguments -Returns: - The number of Unicode characters in `s` between the given indices. -*/ +* 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. +"] fn count_chars(s: str, start: uint, end: uint) -> uint { assert is_char_boundary(s, start); assert is_char_boundary(s, end); @@ -1173,10 +1032,9 @@ fn count_chars(s: str, start: uint, end: uint) -> uint { ret len; } -// Function count_bytes -// -// Counts the number of bytes taken by the `n` in `s` starting from -// `start`. +#[doc = " +Counts the number of bytes taken by the `n` in `s` starting from `start`. +"] fn count_bytes(s: str, start: uint, n: uint) -> uint { assert is_char_boundary(s, start); let mut end = start, cnt = n; @@ -1190,12 +1048,9 @@ fn count_bytes(s: str, start: uint, n: uint) -> uint { end - start } -/* -Function: utf8_char_width - +#[doc = " 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; } @@ -1208,61 +1063,63 @@ pure fn utf8_char_width(b: u8) -> uint { ret 6u; } -/* -Function is_char_boundary - +#[doc = " 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; } -/* -Function: char_range_at - +#[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 -Example output: +~~~ +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; +} +~~~ - 0: 中 - 3: 华 - 6: V - 7: i - 8: ệ - 11: t - 12: - 13: N - 14: a - 15: m +# Example output -Parameters: +~~~ +0: 中 +3: 华 +6: V +7: i +8: ệ +11: t +12: +13: N +14: a +15: m +~~~ -s - The string -i - The byte offset of the char to extract +# Arguments -Returns: +* 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: +# 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. -*/ +"] fn char_range_at(s: str, i: uint) -> {ch: char, next: uint} { let b0 = s[i]; let w = utf8_char_width(b0); @@ -1285,17 +1142,14 @@ fn char_range_at(s: str, i: uint) -> {ch: char, next: uint} { ret {ch: val as char, next: i}; } -/* -Function: char_at - -Pluck a character out of a string -*/ +#[doc = "Pluck a character out of a string"] fn char_at(s: str, i: uint) -> char { ret char_range_at(s, i).ch; } -// Function: char_range_at_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. +#[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. +"] fn char_range_at_reverse(ss: str, start: uint) -> {ch: char, prev: uint} { let mut prev = start; @@ -1311,28 +1165,28 @@ fn char_range_at_reverse(ss: str, start: uint) -> {ch: char, prev: uint} { ret {ch:ch, prev:prev}; } -/* -Function: all_between - +#[doc = " Loop through a substring, char by char -Parameters: -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. +# Safety note -Returns: +* This function does not check whether the substring is valid. +* This function fails if `byte_offset` or `byte_len` 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. - -Safety note: -- This function does not check whether the substring is valid. -- This function fails if `byte_offset` or `byte_len` do not - represent valid positions inside `s` - */ +"] fn all_between(s: str, start: uint, end: uint, it: fn(char) -> bool) -> bool { assert is_char_boundary(s, start); let mut i = start; @@ -1362,17 +1216,19 @@ const tag_five_b: uint = 248u; const max_five_b: uint = 67108864u; const tag_six_b: uint = 252u; -/* -Function: as_bytes -Work with the byte buffer of a string. Allows for unsafe manipulation -of strings, which is useful for native interop. +#[doc = " +Work with the byte buffer of a string. -Example: +Allows for unsafe manipulation of strings, which is useful for native +interop. -> let i = str::as_bytes("Hello World") { |bytes| vec::len(bytes) }; +# Example -*/ +~~~ +let i = str::as_bytes(\"Hello World\") { |bytes| vec::len(bytes) }; +~~~ +"] fn as_bytes(s: str, f: fn([u8]) -> T) -> T unsafe { let mut v: [u8] = ::unsafe::reinterpret_cast(s); let r = f(v); @@ -1380,38 +1236,31 @@ fn as_bytes(s: str, f: fn([u8]) -> T) -> T unsafe { r } -/* -Function: as_buf +#[doc = " +Work with the byte buffer of a string. -Work with the byte buffer of a string. Allows for unsafe manipulation -of strings, which is useful for native interop. +Allows for unsafe manipulation of strings, which is useful for native +interop. -Example: +# Example -> let s = str::as_buf("PATH", { |path_buf| libc::getenv(path_buf) }); - -*/ +``` +let s = str::as_buf(\"PATH\", { |path_buf| libc::getenv(path_buf) }); +``` +"] fn as_buf(s: str, f: fn(sbuf) -> T) -> T unsafe { as_bytes(s) { |v| vec::as_buf(v, f) } } -/* -Type: sbuf - -An unsafe buffer of bytes. -*/ +#[doc = "An unsafe buffer of bytes"] type sbuf = *u8; -// Function: reserve -// -// Allocate more memory for a string, up to `nn` + 1 bytes +#[doc = "Allocate more memory for a string, up to `nn` + 1 bytes"] fn reserve(&ss: str, nn: uint) { rustrt::str_reserve_shared(ss, nn); } -// Module: unsafe -// -// These functions may create invalid UTF-8 strings and eat your baby. +#[doc = "These functions may create invalid UTF-8 strings and eat your baby"] mod unsafe { export // FIXME: stop exporting several of these @@ -1424,10 +1273,11 @@ mod unsafe { shift_byte, set_len; - // Function: unsafe::from_bytes - // - // Converts a vector of bytes to a string. Does not verify that the - // vector contains valid UTF-8. + #[doc = " + 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: [u8] = v + [0u8]; let scopy: str = ::unsafe::reinterpret_cast(vcopy); @@ -1435,23 +1285,23 @@ mod unsafe { ret scopy; } - // Function: unsafe::from_byte - // - // Converts a byte to a string. Does not verify that the byte is - // valid UTF-8. + #[doc = " + 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]) } - /* - Function: slice_bytes - + #[doc = " Takes a bytewise (not UTF-8) slice from a string. + Returns the substring from [`begin`..`end`). - Failure: + # Failure - - If begin is greater than end. - - If end is greater than the length of the string. - */ + 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 unsafe { assert (begin <= end); assert (end <= len(s)); @@ -1463,23 +1313,19 @@ mod unsafe { ret s; } - // Function: push_byte - // - // Appends a byte to a string. (Not UTF-8 safe). + #[doc = "Appends a byte to a string. (Not UTF-8 safe)."] unsafe fn push_byte(&s: str, b: u8) { rustrt::rust_str_push(s, b); } - // Function: push_bytes - // - // Appends a vector of bytes to a string. (Not UTF-8 safe). + #[doc = "Appends a vector of bytes to a string. (Not UTF-8 safe)."] unsafe fn push_bytes(&s: str, bytes: [u8]) { for byte in bytes { rustrt::rust_str_push(s, byte); } } - // Function: pop_byte - // - // Removes the last byte from a string and returns it. (Not UTF-8 safe). + #[doc = " + Removes the last byte from a string and returns it. (Not UTF-8 safe). + "] unsafe fn pop_byte(&s: str) -> u8 unsafe { let len = len(s); assert (len > 0u); @@ -1488,9 +1334,9 @@ mod unsafe { ret b; } - // Function: shift_byte - // - // Removes the first byte from a string and returns it. (Not UTF-8 safe). + #[doc = " + Removes the first byte from a string and returns it. (Not UTF-8 safe). + "] unsafe fn shift_byte(&s: str) -> u8 unsafe { let len = len(s); assert (len > 0u); diff --git a/src/libcore/sys.rs b/src/libcore/sys.rs index 7532177246c..b05022c1985 100644 --- a/src/libcore/sys.rs +++ b/src/libcore/sys.rs @@ -1,8 +1,5 @@ -/* -Module: sys +#[doc = "Misc low level stuff"] -Misc low level stuff -*/ enum type_desc = { first_param: **ctypes::c_int, size: ctypes::size_t, @@ -31,48 +28,32 @@ native mod rusti { fn frame_address(n: ctypes::c_uint) -> ctypes::uintptr_t; } -/* -Function: get_type_desc +#[doc = " +Returns a pointer to a type descriptor. -Returns a pointer to a type descriptor. Useful for calling certain -function in the Rust runtime or otherwise performing dark magick. -*/ +Useful for calling certain function in the Rust runtime or otherwise +performing dark magick. +"] fn get_type_desc() -> *type_desc { ret rusti::get_type_desc::(); } -/* -Function: last_os_error - -Get a string representing the platform-dependent last error -*/ +#[doc = "Get a string representing the platform-dependent last error"] fn last_os_error() -> str { rustrt::last_os_error() } -/* -Function: size_of - -Returns the size of a type -*/ +#[doc = "Returns the size of a type"] fn size_of() -> uint unsafe { ret (*get_type_desc::()).size; } -/* -Function: align_of - -Returns the alignment of a type -*/ +#[doc = "Returns the alignment of a type"] fn align_of() -> uint unsafe { ret (*get_type_desc::()).align; } -/* -Function: refcount - -Returns the refcount of a shared box -*/ +#[doc = "Returns the refcount of a shared box"] fn refcount(t: @T) -> uint { ret rustrt::refcount::(t); } @@ -81,14 +62,14 @@ fn log_str(t: T) -> str { rustrt::shape_log_str(get_type_desc::(), t) } -#[doc( - brief = "Sets the process exit code", - desc = "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." -)] +#[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 +"] fn set_exit_status(code: int) { rustrt::rust_set_exit_status(code as ctypes::intptr_t); } diff --git a/src/libcore/task.rs b/src/libcore/task.rs index 12a02411715..322b43e223d 100644 --- a/src/libcore/task.rs +++ b/src/libcore/task.rs @@ -1,5 +1,4 @@ #[doc = " - Task management. An executing Rust program consists of a tree of tasks, each with their own @@ -14,12 +13,13 @@ process. Tasks may execute in parallel and are scheduled automatically by the runtime. -Example: - - spawn {|| - log(error, \"Hello, World!\"); - } +# Example +~~~ +spawn {|| + log(error, \"Hello, World!\"); +} +~~~ "]; export task; @@ -58,7 +58,6 @@ export get_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 @@ -66,18 +65,13 @@ without failing is considered to exit successfully. FIXME: 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 - -"] +#[doc = "A message type for notifying of task lifecycle events"] enum notification { #[doc = "Sent when a task exits with the task handle and result"] exit(task, task_result) @@ -96,10 +90,9 @@ enum sched_mode { } #[doc = " - Scheduler configuration options -Fields: +# Fields * sched_mode - The operating mode of the scheduler @@ -110,7 +103,6 @@ Fields: appropriate for running code written in languages like C. By default these native stacks have unspecified size, but with this option their size can be precisely specified. - "] type sched_opts = { mode: sched_mode, @@ -118,10 +110,9 @@ type sched_opts = { }; #[doc = " - Task configuration options -Fields: +# Fields * supervise - Do not propagate failure to the parent task @@ -152,11 +143,9 @@ type task_opts = { }; #[doc = " - 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 @@ -176,12 +165,10 @@ enum task_builder = { 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. - "]; { @@ -211,7 +198,6 @@ fn get_opts(builder: task_builder) -> task_opts { fn set_opts(builder: task_builder, opts: task_opts) { #[doc = " - Set the task_opts associated with a task_builder To update a single option use a pattern like the following: @@ -220,7 +206,6 @@ fn set_opts(builder: task_builder, opts: task_opts) { supervise: false with get_opts(builder) }); - "]; builder.opts = opts; @@ -228,7 +213,6 @@ fn set_opts(builder: task_builder, opts: task_opts) { fn add_wrapper(builder: task_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' @@ -239,7 +223,6 @@ fn add_wrapper(builder: task_builder, gen_body: fn@(+fn~()) -> fn~()) { 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; @@ -249,20 +232,18 @@ fn add_wrapper(builder: task_builder, gen_body: fn@(+fn~()) -> fn~()) { } fn run(-builder: task_builder, +f: fn~()) { - #[doc(desc = " - + #[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 = " + # 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); @@ -273,7 +254,6 @@ fn run(-builder: task_builder, +f: fn~()) { fn future_result(builder: task_builder) -> future::future { #[doc = " - Get a future representing the exit status of the task. Taking the value of the future will block until the child task terminates. @@ -283,7 +263,6 @@ fn future_result(builder: task_builder) -> future::future { 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 @@ -332,7 +311,6 @@ fn unsupervise(builder: task_builder) { fn run_listener(-builder: task_builder, +f: fn~(comm::port)) -> comm::chan { #[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 @@ -362,7 +340,6 @@ fn run_listener(-builder: task_builder, fn spawn(+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 @@ -376,7 +353,6 @@ fn spawn(+f: fn~()) { fn spawn_listener(+f: fn~(comm::port)) -> comm::chan { #[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 @@ -399,27 +375,24 @@ fn spawn_listener(+f: fn~(comm::port)) -> comm::chan { // Likewise, the parent has both a 'po' and 'ch' This function is equivalent to `run_listener(mk_task_builder(), f)`. - "]; run_listener(mk_task_builder(), f) } fn spawn_sched(mode: sched_mode, +f: fn~()) { - #[doc(desc = " - + #[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 = " + # Failure In manual threads mode the number of threads requested must be greater than zero. - - ")]; + "]; let mut builder = mk_task_builder(); set_opts(builder, { @@ -433,18 +406,16 @@ fn spawn_sched(mode: sched_mode, +f: fn~()) { } fn try(+f: fn~() -> T) -> result::t { - #[doc(desc = " - + #[doc = " Execute a function in another task and return either the return value of the function or result::err. - ", return = " + # 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); diff --git a/src/libcore/tuple.rs b/src/libcore/tuple.rs index b8f8dafc1aa..2f92ae08f0e 100644 --- a/src/libcore/tuple.rs +++ b/src/libcore/tuple.rs @@ -1,7 +1,3 @@ -/* -Module: tuple -*/ - fn first(pair: (T, U)) -> T { let (t, _) = pair; ret t; diff --git a/src/libcore/u32.rs b/src/libcore/u32.rs index 267f3666554..da60b7a5a1d 100644 --- a/src/libcore/u32.rs +++ b/src/libcore/u32.rs @@ -1,64 +1,25 @@ #[doc = "Operations and constants for `u32`"]; -/* -Module: u32 -*/ - -/* -Const: min_value - -Return the minimal value for a u32 -*/ const min_value: u32 = 0u32; - -/* -Const: max_value - -Return the maximal value for a u32 -*/ const max_value: u32 = 0u32 - 1u32; pure fn min(x: u32, y: u32) -> u32 { if x < y { x } else { y } } pure fn max(x: u32, y: u32) -> u32 { if x > y { x } else { y } } -/* Function: add */ pure fn add(x: u32, y: u32) -> u32 { ret x + y; } - -/* Function: sub */ pure fn sub(x: u32, y: u32) -> u32 { ret x - y; } - -/* Function: mul */ pure fn mul(x: u32, y: u32) -> u32 { ret x * y; } - -/* Function: div */ pure fn div(x: u32, y: u32) -> u32 { ret x / y; } - -/* Function: rem */ pure fn rem(x: u32, y: u32) -> u32 { ret x % y; } -/* Predicate: lt */ pure fn lt(x: u32, y: u32) -> bool { ret x < y; } - -/* Predicate: le */ pure fn le(x: u32, y: u32) -> bool { ret x <= y; } - -/* Predicate: eq */ pure fn eq(x: u32, y: u32) -> bool { ret x == y; } - -/* Predicate: ne */ pure fn ne(x: u32, y: u32) -> bool { ret x != y; } - -/* Predicate: ge */ pure fn ge(x: u32, y: u32) -> bool { ret x >= y; } - -/* Predicate: gt */ pure fn gt(x: u32, y: u32) -> bool { ret x > y; } -/* -Function: range - -Iterate over the range [`lo`..`hi`) -*/ +#[doc = "Iterate over the range [`lo`..`hi`)"] fn range(lo: u32, hi: u32, it: fn(u32)) { let mut i = lo; while i < hi { it(i); i += 1u32; } diff --git a/src/libcore/u64.rs b/src/libcore/u64.rs index 1e6b02ef1b4..6907ad5fe03 100644 --- a/src/libcore/u64.rs +++ b/src/libcore/u64.rs @@ -1,74 +1,31 @@ #[doc = "Operations and constants for `u64`"]; -/* -Module: u64 -*/ - -/* -Const: min_value - -Return the minimal value for a u64 -*/ const min_value: u64 = 0u64; - -/* -Const: max_value - -Return the maximal value for a u64 -*/ const max_value: u64 = 0u64 - 1u64; pure fn min(x: u64, y: u64) -> u64 { if x < y { x } else { y } } pure fn max(x: u64, y: u64) -> u64 { if x > y { x } else { y } } -/* Function: add */ pure fn add(x: u64, y: u64) -> u64 { ret x + y; } - -/* Function: sub */ pure fn sub(x: u64, y: u64) -> u64 { ret x - y; } - -/* Function: mul */ pure fn mul(x: u64, y: u64) -> u64 { ret x * y; } - -/* Function: div */ pure fn div(x: u64, y: u64) -> u64 { ret x / y; } - -/* Function: rem */ pure fn rem(x: u64, y: u64) -> u64 { ret x % y; } -/* Predicate: lt */ pure fn lt(x: u64, y: u64) -> bool { ret x < y; } - -/* Predicate: le */ pure fn le(x: u64, y: u64) -> bool { ret x <= y; } - -/* Predicate: eq */ pure fn eq(x: u64, y: u64) -> bool { ret x == y; } - -/* Predicate: ne */ pure fn ne(x: u64, y: u64) -> bool { ret x != y; } - -/* Predicate: ge */ pure fn ge(x: u64, y: u64) -> bool { ret x >= y; } - -/* Predicate: gt */ pure fn gt(x: u64, y: u64) -> bool { ret x > y; } -/* -Function: range - -Iterate over the range [`lo`..`hi`) -*/ +#[doc = "Iterate over the range [`lo`..`hi`)"] fn range(lo: u64, hi: u64, it: fn(u64)) { let mut i = lo; while i < hi { it(i); i += 1u64; } } -/* -Function: to_str - -Convert to a string in a given base -*/ +#[doc = "Convert to a string in a given base"] fn to_str(n: u64, radix: uint) -> str { assert (0u < radix && radix <= 16u); @@ -105,18 +62,10 @@ fn to_str(n: u64, radix: uint) -> str { ret s; } -/* -Function: str - -Convert to a string -*/ +#[doc = "Convert to a string"] fn str(n: u64) -> str { ret to_str(n, 10u); } -/* -Function: from_str - -Parse a string as an unsigned integer. -*/ +#[doc = "Parse a string as an unsigned integer."] fn from_str(buf: str, radix: u64) -> option { if str::len(buf) == 0u { ret none; } let mut i = str::len(buf) - 1u; diff --git a/src/libcore/u8.rs b/src/libcore/u8.rs index eb433f4e9b3..397d78572a3 100644 --- a/src/libcore/u8.rs +++ b/src/libcore/u8.rs @@ -1,64 +1,27 @@ #[doc = "Operations and constants for `u8`"]; -/* -Module: u8 -*/ - -/* -Const: min_value - -The minumum value of a u8. -*/ const min_value: u8 = 0u8; - -/* -Const: max_value - -The maximum value of a u8. -*/ const max_value: u8 = 0u8 - 1u8; -/* Function: add */ +pure fn min(x: u8, y: u8) -> u8 { if x < y { x } else { y } } +pure fn max(x: u8, y: u8) -> u8 { if x > y { x } else { y } } + pure fn add(x: u8, y: u8) -> u8 { ret x + y; } - -/* Function: sub */ pure fn sub(x: u8, y: u8) -> u8 { ret x - y; } - -/* Function: mul */ pure fn mul(x: u8, y: u8) -> u8 { ret x * y; } - -/* Function: div */ pure fn div(x: u8, y: u8) -> u8 { ret x / y; } - -/* Function: rem */ pure fn rem(x: u8, y: u8) -> u8 { ret x % y; } -/* Predicate: lt */ pure fn lt(x: u8, y: u8) -> bool { ret x < y; } - -/* Predicate: le */ pure fn le(x: u8, y: u8) -> bool { ret x <= y; } - -/* Predicate: eq */ pure fn eq(x: u8, y: u8) -> bool { ret x == y; } - -/* Predicate: ne */ pure fn ne(x: u8, y: u8) -> bool { ret x != y; } - -/* Predicate: ge */ pure fn ge(x: u8, y: u8) -> bool { ret x >= y; } - -/* Predicate: gt */ pure fn gt(x: u8, y: u8) -> bool { ret x > y; } -/* Predicate: is_ascii */ pure fn is_ascii(x: u8) -> bool { ret 0u8 == x & 128u8; } -/* -Function: range - -Iterate over the range [`lo`..`hi`) -*/ +#[doc = "Iterate over the range [`lo`..`hi`)"] fn range(lo: u8, hi: u8, it: fn(u8)) { let mut i = lo; while i < hi { it(i); i += 1u8; } diff --git a/src/libcore/uint.rs b/src/libcore/uint.rs index 776965d350a..8e57eab7ea7 100644 --- a/src/libcore/uint.rs +++ b/src/libcore/uint.rs @@ -1,158 +1,103 @@ #[doc = "Operations and constants for `uint`"]; -/* -Module: uint -*/ - -/* -Const: min_value - -Return the minimal value for an uint. - -This is always 0 -*/ const min_value: uint = 0u; - -/* -Const: max_value - -Return the maximal value for an uint. - -This is 2^wordsize - 1 -*/ const max_value: uint = 0u - 1u; -/* -Function: min -*/ -pure fn min(x: uint, y: uint) -> uint { - if x < y { x } else { y } -} +pure fn min(x: uint, y: uint) -> uint { if x < y { x } else { y } } +pure fn max(x: uint, y: uint) -> uint { if x > y { x } else { y } } -/* -Function: max -*/ -pure fn max(x: uint, y: uint) -> uint { - if x > y { x } else { y } -} - -/* Function: add */ pure fn add(x: uint, y: uint) -> uint { ret x + y; } - -/* Function: sub */ pure fn sub(x: uint, y: uint) -> uint { ret x - y; } - -/* Function: mul */ pure fn mul(x: uint, y: uint) -> uint { ret x * y; } - -/* Function: div */ pure fn div(x: uint, y: uint) -> uint { ret x / y; } -/* Function: div_ceil +pure fn rem(x: uint, y: uint) -> uint { ret x % y; } +pure fn lt(x: uint, y: uint) -> bool { ret x < y; } +pure fn le(x: uint, y: uint) -> bool { ret x <= y; } +pure fn eq(x: uint, y: uint) -> bool { ret x == y; } +pure fn ne(x: uint, y: uint) -> bool { ret x != y; } +pure fn ge(x: uint, y: uint) -> bool { ret x >= y; } +pure fn gt(x: uint, y: uint) -> bool { ret x > y; } - Divide two numbers, return the result, rounded up. - Parameters: - x - an integer - y - an integer distinct from 0u +#[doc = " +Divide two numbers, return the result, rounded up. - Return: - The smallest integer `q` such that `x/y <= q`. -*/ +# 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; } } -/* Function: div_ceil +#[doc = " +Divide two numbers, return the result, rounded to the closest integer. - Divide two numbers, return the result, rounded to the closest integer. +# Arguments - Parameters: - x - an integer - y - an integer distinct from 0u +* x - an integer +* y - an integer distinct from 0u - Return: - The integer `q` closest to `x/y`. -*/ +# 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; } } -/* Function: div_ceil +#[doc = " +Divide two numbers, return the result, rounded down. - Divide two numbers, return the result, rounded down. +Note: This is the same function as `div`. - Parameters: - x - an integer - y - an integer distinct from 0u +# Arguments - Note: This is the same function as `div`. +* x - an integer +* y - an integer distinct from 0u - Return: - The smallest integer `q` such that `x/y <= q`. This - is either `x/y` or `x/y + 1`. -*/ +# 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; } -/* Function: rem */ -pure fn rem(x: uint, y: uint) -> uint { ret x % y; } - -/* Predicate: lt */ -pure fn lt(x: uint, y: uint) -> bool { ret x < y; } - -/* Predicate: le */ -pure fn le(x: uint, y: uint) -> bool { ret x <= y; } - -/* Predicate: eq */ -pure fn eq(x: uint, y: uint) -> bool { ret x == y; } - -/* Predicate: ne */ -pure fn ne(x: uint, y: uint) -> bool { ret x != y; } - -/* Predicate: ge */ -pure fn ge(x: uint, y: uint) -> bool { ret x >= y; } - -/* Predicate: gt */ -pure fn gt(x: uint, y: uint) -> bool { ret x > y; } - -/* -Function: hash - -Produce a uint suitable for use in a hash table -*/ +#[doc = "Produce a uint suitable for use in a hash table"] fn hash(x: uint) -> uint { ret x; } -/* -Function: range - -Iterate over the range [`lo`..`hi`) -*/ +#[doc = "Iterate over the range [`lo`..`hi`)"] #[inline(always)] fn range(lo: uint, hi: uint, it: fn(uint)) { let mut i = lo; while i < hi { it(i); i += 1u; } } -/* -Function: iterate - +#[doc = " Iterate over the range [`lo`..`hi`), or stop when requested -Parameters: -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. +# Arguments -Returns: +* 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 { @@ -162,11 +107,7 @@ fn iterate(lo: uint, hi: uint, it: fn(uint) -> bool) -> bool { ret true; } -/* -Function: next_power_of_two - -Returns the smallest power of 2 greater than or equal to `n` -*/ +#[doc = "Returns the smallest power of 2 greater than or equal to `n`"] fn next_power_of_two(n: uint) -> uint { let halfbits: uint = sys::size_of::() * 4u; let mut tmp: uint = n - 1u; @@ -175,20 +116,18 @@ fn next_power_of_two(n: uint) -> uint { ret tmp + 1u; } -/* -Function: parse_buf - +#[doc = " Parse a buffer of bytes -Parameters: +# Arguments -buf - A byte buffer -radix - The base of the number +* buf - A byte buffer +* radix - The base of the number -Failure: +# Failure -buf must not be empty -*/ +`buf` must not be empty +"] fn parse_buf(buf: [u8], radix: uint) -> option { if vec::len(buf) == 0u { ret none; } let mut i = vec::len(buf) - 1u; @@ -206,18 +145,10 @@ fn parse_buf(buf: [u8], radix: uint) -> option { fail; } -/* -Function: from_str - -Parse a string to an int -*/ +#[doc = "Parse a string to an int"] fn from_str(s: str) -> option { parse_buf(str::bytes(s), 10u) } -/* -Function: to_str - -Convert to a string in a given base -*/ +#[doc = "Convert to a string in a given base"] fn to_str(num: uint, radix: uint) -> str { let mut n = num; assert (0u < radix && radix <= 16u); @@ -254,18 +185,10 @@ fn to_str(num: uint, radix: uint) -> str { ret s1; } -/* -Function: str - -Convert to a string -*/ +#[doc = "Convert to a string"] fn str(i: uint) -> str { ret to_str(i, 10u); } -/* -Function: compl - -Computes the bitwise complement. -*/ +#[doc = "Computes the bitwise complement"] fn compl(i: uint) -> uint { max_value ^ i } diff --git a/src/libcore/unicode.rs b/src/libcore/unicode.rs index aacf40d2548..de120b8cc78 100644 --- a/src/libcore/unicode.rs +++ b/src/libcore/unicode.rs @@ -2565,6 +2565,7 @@ mod general_category { } mod derived_property { + #[doc = "Check if a character has the alphabetic unicode property"] pure fn Alphabetic(c: char) -> bool { ret alt c { '\x41' to '\x5a' diff --git a/src/libcore/unsafe.rs b/src/libcore/unsafe.rs index d3d2f4ee088..c7ba9ffe154 100644 --- a/src/libcore/unsafe.rs +++ b/src/libcore/unsafe.rs @@ -1,8 +1,4 @@ -/* -Module: unsafe - -Unsafe operations -*/ +#[doc = "Unsafe operations"]; export reinterpret_cast, leak; @@ -12,11 +8,9 @@ native mod rusti { fn leak(-thing: T); } -/* -Function: reinterpret_cast - +#[doc = " Casts the value at `src` to U. The two types must have the same length. -*/ +"] #[inline(always)] unsafe fn reinterpret_cast(src: T) -> U { let t1 = sys::get_type_desc::(); @@ -27,16 +21,14 @@ unsafe fn reinterpret_cast(src: T) -> U { ret rusti::cast(src); } -/* -Function: leak - -Move `thing` into the void. +#[doc =" +Move a thing into the void The leak 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 leak(-thing: T) { rusti::leak(thing); } diff --git a/src/libcore/vec.rs b/src/libcore/vec.rs index f1aac380886..e5bc29b5295 100644 --- a/src/libcore/vec.rs +++ b/src/libcore/vec.rs @@ -1,7 +1,3 @@ -/* -Module: vec -*/ - import option::{some, none}; import uint::next_power_of_two; import ptr::addr_of; @@ -21,74 +17,49 @@ native mod rustrt { count: ctypes::size_t) -> [T]; } -/* -Type: init_op - -A function used to initialize the elements of a vector. -*/ +#[doc = "A function used to initialize the elements of a vector"] type init_op = fn(uint) -> T; - -/* -Predicate: is_empty - -Returns true if a vector contains no elements. -*/ +#[doc = "Returns true if a vector contains no elements"] pure fn is_empty(v: [const T]) -> bool { // FIXME: This would be easier if we could just call len for t: T in v { ret false; } ret true; } -/* -Predicate: is_not_empty - -Returns true if a vector contains some elements. -*/ +#[doc = "Returns true if a vector contains some elements"] pure fn is_not_empty(v: [const T]) -> bool { ret !is_empty(v); } -/* -Predicate: same_length - -Returns true if two vectors have the same length -*/ +#[doc = "Returns true if two vectors have the same length"] pure fn same_length(xs: [const T], ys: [const U]) -> bool { vec::len(xs) == vec::len(ys) } -/* -Function: reserve - +#[doc = " Reserves capacity for `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. -Parameters: +# Arguments -v - A vector -n - The number of elements to reserve space for -*/ +* v - A vector +* n - The number of elements to reserve space for +"] fn reserve(&v: [const T], n: uint) { rustrt::vec_reserve_shared(sys::get_type_desc::(), v, n); } -/* -Function: len - -Returns the length of a vector -*/ +#[doc = "Returns the length of a vector"] #[inline(always)] pure fn len(v: [const T]) -> uint { unchecked { rusti::vec_len(v) } } -/* -Function: init_fn - +#[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`. -*/ +"] fn init_fn(n_elts: uint, op: init_op) -> [T] { let mut v = []; reserve(v, n_elts); @@ -97,14 +68,12 @@ fn init_fn(n_elts: uint, op: init_op) -> [T] { ret v; } -/* -Function: init_elt - +#[doc = " Creates and initializes an immutable vector. Creates an immutable vector of size `n_elts` and initializes the elements to the value `t`. -*/ +"] fn init_elt(n_elts: uint, t: T) -> [T] { let mut v = []; reserve(v, n_elts); @@ -115,22 +84,14 @@ fn init_elt(n_elts: uint, t: T) -> [T] { // FIXME: Possible typestate postcondition: // len(result) == len(v) (needs issue #586) -/* - - -Produces a mutable vector from an immutable vector. -*/ +#[doc = "Produces a mutable vector from an immutable vector."] fn to_mut(+v: [T]) -> [mutable T] unsafe { let r = ::unsafe::reinterpret_cast(v); ::unsafe::leak(v); r } -/* -Function: from_mut - -Produces an immutable vector from a mutable vector. -*/ +#[doc = "Produces an immutable vector from a mutable vector."] fn from_mut(+v: [mutable T]) -> [T] unsafe { let r = ::unsafe::reinterpret_cast(v); ::unsafe::leak(v); @@ -139,31 +100,15 @@ fn from_mut(+v: [mutable T]) -> [T] unsafe { // Accessors -/* -Function: head - -Returns the first element of a vector - -Predicates: - (v) -*/ +#[doc = "Returns the first element of a vector"] pure fn head(v: [const T]) -> T { v[0] } -/* -Function: tail - -Returns all but the first element of a vector -*/ +#[doc = "Returns all but the first element of a vector"] fn tail(v: [const T]) -> [T] { ret slice(v, 1u, len(v)); } -/* -Function tail_n - -Returns all but the first N elements of a vector -*/ - +#[doc = "Returns all but the first `n` elements of a vector"] fn tail_n(v: [const T], n: uint) -> [T] { slice(v, n, len(v)) } @@ -171,47 +116,30 @@ fn tail_n(v: [const T], n: uint) -> [T] { // FIXME: This name is sort of confusing next to init_fn, etc // but this is the name haskell uses for this function, // along with head/tail/last. -/* -Function: init - -Returns all but the last elemnt of a vector - -Preconditions: -`v` is not empty -*/ +#[doc = "Returns all but the last elemnt of a vector"] fn init(v: [const T]) -> [T] { assert len(v) != 0u; slice(v, 0u, len(v) - 1u) } -/* -Function: last - +#[doc = " Returns the last element of a `v`, failing if the vector is empty. - -*/ +"] pure fn last(v: [const T]) -> T { if len(v) == 0u { fail "last_unsafe: empty vector" } v[len(v) - 1u] } -/* -Function: last_opt - +#[doc = " Returns some(x) where `x` is the last element of a vector `v`, or none if the vector is empty. - -*/ +"] pure fn last_opt(v: [const T]) -> option { - if len(v) == 0u { ret none; } + if len(v) == 0u { ret none; } some(v[len(v) - 1u]) } -/* -Function: slice - -Returns a copy of the elements from [`start`..`end`) from `v`. -*/ +#[doc = "Returns a copy of the elements from [`start`..`end`) from `v`."] fn slice(v: [const T], start: uint, end: uint) -> [T] { assert (start <= end); assert (end <= len(v)); @@ -222,11 +150,9 @@ fn slice(v: [const T], start: uint, end: uint) -> [T] { ret result; } -/* -Function: split - +#[doc = " Split the vector `v` by applying each element against the predicate `f`. -*/ +"] fn split(v: [const T], f: fn(T) -> bool) -> [[T]] { let ln = len(v); if (ln == 0u) { ret [] } @@ -246,12 +172,10 @@ fn split(v: [const T], f: fn(T) -> bool) -> [[T]] { result } -/* -Function: splitn - +#[doc = " Split the vector `v` by applying each element against the predicate `f` up to `n` times. -*/ +"] fn splitn(v: [const T], n: uint, f: fn(T) -> bool) -> [[T]] { let ln = len(v); if (ln == 0u) { ret [] } @@ -274,12 +198,10 @@ fn splitn(v: [const T], n: uint, f: fn(T) -> bool) -> [[T]] { result } -/* -Function: rsplit - +#[doc = " Reverse split the vector `v` by applying each element against the predicate `f`. -*/ +"] fn rsplit(v: [const T], f: fn(T) -> bool) -> [[T]] { let ln = len(v); if (ln == 0u) { ret [] } @@ -299,12 +221,10 @@ fn rsplit(v: [const T], f: fn(T) -> bool) -> [[T]] { reversed(result) } -/* -Function: rsplitn - +#[doc = " Reverse split the vector `v` by applying each element against the predicate `f` up to `n times. -*/ +"] fn rsplitn(v: [const T], n: uint, f: fn(T) -> bool) -> [[T]] { let ln = len(v); if (ln == 0u) { ret [] } @@ -329,11 +249,7 @@ fn rsplitn(v: [const T], n: uint, f: fn(T) -> bool) -> [[T]] { // Mutators -/* -Function: shift - -Removes the first element from a vector and return it -*/ +#[doc = "Removes the first element from a vector and return it"] fn shift(&v: [const T]) -> T { let ln = len::(v); assert (ln > 0u); @@ -342,11 +258,7 @@ fn shift(&v: [const T]) -> T { ret e; } -/* -Function: pop - -Remove the last element from a vector and return it -*/ +#[doc = "Remove the last element from a vector and return it"] fn pop(&v: [const T]) -> T unsafe { let ln = len(v); assert ln > 0u; @@ -356,67 +268,56 @@ fn pop(&v: [const T]) -> T unsafe { val } -/* -Function: push - -Append an element to a vector -*/ +#[doc = "Append an element to a vector"] fn push(&v: [const T], initval: T) { v += [initval]; } -// TODO: More. - // Appending -/* -Function: grow - +#[doc = " Expands a vector in place, initializing the new elements to a given value -Parameters: +# Arguments -v - The vector to grow -n - The number of elements to add -initval - The value for the new elements -*/ +* v - The vector to grow +* n - The number of elements to add +* initval - The value for the new elements +"] fn grow(&v: [const T], n: uint, initval: T) { reserve(v, next_power_of_two(len(v) + n)); let mut i: uint = 0u; while i < n { v += [initval]; i += 1u; } } -/* -Function: grow_fn - -Expands a vector in place, initializing the new elements to the result of a -function +#[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`) -Parameters: +# 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 -*/ +* 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(&v: [const T], n: uint, op: init_op) { reserve(v, next_power_of_two(len(v) + n)); let mut i: uint = 0u; while i < n { v += [op(i)]; i += 1u; } } -/* -Function: grow_set - +#[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. -*/ +"] fn grow_set(&v: [mutable T], index: uint, initval: T, val: T) { if index >= len(v) { grow(v, index - len(v) + 1u, initval); } v[index] = val; @@ -425,11 +326,9 @@ fn grow_set(&v: [mutable T], index: uint, initval: T, val: T) { // Functional utilities -/* -Function: map - +#[doc =" Apply a function to each element of a vector and return the results -*/ +"] fn map(v: [T], f: fn(T) -> U) -> [U] { let mut result = []; reserve(result, len(v)); @@ -437,11 +336,9 @@ fn map(v: [T], f: fn(T) -> U) -> [U] { ret result; } -/* -Function: map2 - +#[doc = " Apply a function to each pair of elements and return the results -*/ +"] fn map2(v0: [const T], v1: [const U], f: fn(T, U) -> V) -> [V] { let v0_len = len(v0); @@ -452,14 +349,12 @@ fn map2(v0: [const T], v1: [const U], ret u; } -/* -Function: filter_map - +#[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. -*/ +"] fn filter_map(v: [const T], f: fn(T) -> option) -> [U] { let mut result = []; @@ -472,15 +367,13 @@ fn filter_map(v: [const T], f: fn(T) -> option) ret result; } -/* -Function: filter - +#[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. -*/ +"] fn filter(v: [T], f: fn(T) -> bool) -> [T] { let mut result = []; for elem: T in v { @@ -489,23 +382,20 @@ fn filter(v: [T], f: fn(T) -> bool) -> [T] { ret result; } -/* -Function: concat +#[doc = " +Concatenate a vector of vectors. -Concatenate a vector of vectors. Flattens a vector of vectors of T into -a single vector of T. -*/ +Flattens a vector of vectors of T into a single vector of T. +"] fn concat(v: [const [const T]]) -> [T] { let mut new: [T] = []; for inner: [T] in v { new += inner; } ret new; } -/* -Function: connect - +#[doc = " Concatenate a vector of vectors, placing a given separator between each -*/ +"] fn connect(v: [const [const T]], sep: T) -> [T] { let mut new: [T] = []; let mut first = true; @@ -516,11 +406,7 @@ fn connect(v: [const [const T]], sep: T) -> [T] { ret new; } -/* -Function: foldl - -Reduce a vector from left to right -*/ +#[doc = "Reduce a vector from left to right"] fn foldl(z: T, v: [const U], p: fn(T, U) -> T) -> T { let mut accum = z; iter(v) { |elt| @@ -529,11 +415,7 @@ fn foldl(z: T, v: [const U], p: fn(T, U) -> T) -> T { ret accum; } -/* -Function: foldr - -Reduce a vector from right to left -*/ +#[doc = "Reduce a vector from right to left"] fn foldr(v: [const T], z: U, p: fn(T, U) -> U) -> U { let mut accum = z; riter(v) { |elt| @@ -542,25 +424,21 @@ fn foldr(v: [const T], z: U, p: fn(T, U) -> U) -> U { ret accum; } -/* -Function: any - +#[doc = " Return true if a predicate matches any elements If the vector contains no elements then false is returned. -*/ +"] fn any(v: [T], f: fn(T) -> bool) -> bool { for elem: T in v { if f(elem) { ret true; } } ret false; } -/* -Function: any2 - +#[doc = " Return true if a predicate matches any elements in both vectors. If the vectors contains no elements then false is returned. -*/ +"] fn any2(v0: [const T], v1: [U], f: fn(T, U) -> bool) -> bool { let v0_len = len(v0); let v1_len = len(v1); @@ -572,25 +450,21 @@ fn any2(v0: [const T], v1: [U], f: fn(T, U) -> bool) -> bool { ret false; } -/* -Function: all - +#[doc = " Return true if a predicate matches all elements If the vector contains no elements then true is returned. -*/ +"] fn all(v: [T], f: fn(T) -> bool) -> bool { for elem: T in v { if !f(elem) { ret false; } } ret true; } -/* -Function: all2 - +#[doc = " Return true if a predicate matches all elements in both vectors. If the vectors are not the same size then false is returned. -*/ +"] fn all2(v0: [const T], v1: [const U], f: fn(T, U) -> bool) -> bool { let v0_len = len(v0); if v0_len != len(v1) { ret false; } @@ -599,117 +473,88 @@ fn all2(v0: [const T], v1: [const U], f: fn(T, U) -> bool) -> bool { ret true; } -/* -Function: contains - -Return true if a vector contains an element with the given value -*/ +#[doc = "Return true if a vector contains an element with the given value"] fn contains(v: [const T], x: T) -> bool { for elt: T in v { if x == elt { ret true; } } ret false; } -/* -Function: count - -Returns the number of elements that are equal to a given value -*/ +#[doc = "Returns the number of elements that are equal to a given value"] fn count(v: [const T], x: T) -> uint { let mut cnt = 0u; for elt: T in v { if x == elt { cnt += 1u; } } ret cnt; } -/* -Function: find - +#[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. -*/ +"] fn find(v: [const T], f: fn(T) -> bool) -> option { find_from(v, 0u, len(v), f) } -/* -Function: find_from - +#[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. -*/ +"] fn find_from(v: [const T], start: uint, end: uint, f: fn(T) -> bool) -> option { option::map(position_from(v, start, end, f)) { |i| v[i] } } -/* -Function: rfind - +#[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. -*/ +"] fn rfind(v: [const T], f: fn(T) -> bool) -> option { rfind_from(v, 0u, len(v), f) } -/* -Function: rfind_from - +#[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. -*/ +"] fn rfind_from(v: [const T], start: uint, end: uint, f: fn(T) -> bool) -> option { option::map(rposition_from(v, start, end, f)) { |i| v[i] } } -/* -Function: position_elt - -Find the first index containing a matching value - -Returns: - -option::some(uint) - The first index containing a matching value -option::none - No elements matched -*/ +#[doc = "Find the first index containing a matching value"] fn position_elt(v: [const T], x: T) -> option { position(v) { |y| x == y } } -/* -Function: position - +#[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. -*/ +"] fn position(v: [const T], f: fn(T) -> bool) -> option { position_from(v, 0u, len(v), f) } -/* -Function: position_from - +#[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. -*/ +"] fn position_from(v: [const T], start: uint, end: uint, f: fn(T) -> bool) -> option { assert start <= end; @@ -719,42 +564,29 @@ fn position_from(v: [const T], start: uint, end: uint, ret none; } -/* -Function: rposition_elt - -Find the last index containing a matching value - -Returns: - -option::some(uint) - The last index containing a matching value -option::none - No elements matched -*/ +#[doc = "Find the last index containing a matching value"] fn rposition_elt(v: [const T], x: T) -> option { rposition(v) { |y| x == y } } -/* -Function: rposition - +#[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. -*/ +"] fn rposition(v: [const T], f: fn(T) -> bool) -> option { rposition_from(v, 0u, len(v), f) } -/* -Function: rposition_from - +#[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. -*/ +"] fn rposition_from(v: [const T], start: uint, end: uint, f: fn(T) -> bool) -> option { assert start <= end; @@ -771,34 +603,26 @@ fn rposition_from(v: [const T], start: uint, end: uint, // 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) -/* -Function: unzip - +#[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. -*/ +"] fn unzip(v: [const (T, U)]) -> ([T], [U]) { let mut as = [], bs = []; for (a, b) in v { as += [a]; bs += [b]; } ret (as, bs); } -/* -Function: zip - +#[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. - -Preconditions: - - (v, u) -*/ +"] fn zip(v: [const T], u: [const U]) -> [(T, U)] { let mut zipped = []; let sz = len(v); @@ -808,25 +632,20 @@ fn zip(v: [const T], u: [const U]) -> [(T, U)] { ret zipped; } -/* -Function: swap - +#[doc = " Swaps two elements in a vector -Parameters: -v - The input vector -a - The index of the first element -b - The index of the second element -*/ +# Arguments + +* v The input vector +* a - The index of the first element +* b - The index of the second element +"] fn swap(v: [mutable T], a: uint, b: uint) { v[a] <-> v[b]; } -/* -Function: reverse - -Reverse the order of elements in a vector, in place -*/ +#[doc = "Reverse the order of elements in a vector, in place"] fn reverse(v: [mutable T]) { let mut i: uint = 0u; let ln = len::(v); @@ -834,11 +653,7 @@ fn reverse(v: [mutable T]) { } -/* -Function: reversed - -Returns a vector with the order of elements reversed -*/ +#[doc = "Returns a vector with the order of elements reversed"] fn reversed(v: [const T]) -> [T] { let mut rs: [T] = []; let mut i = len::(v); @@ -849,11 +664,7 @@ fn reversed(v: [const T]) -> [T] { } // FIXME: Seems like this should take char params. Maybe belongs in char -/* -Function: enum_chars - -Returns a vector containing a range of chars -*/ +#[doc = "Returns a vector containing a range of chars"] fn enum_chars(start: u8, end: u8) -> [char] { assert start < end; let mut i = start; @@ -863,11 +674,7 @@ fn enum_chars(start: u8, end: u8) -> [char] { } // FIXME: Probably belongs in uint. Compare to uint::range -/* -Function: enum_uints - -Returns a vector containing a range of uints -*/ +#[doc = "Returns a vector containing a range of uints"] fn enum_uints(start: uint, end: uint) -> [uint] { assert start < end; let mut i = start; @@ -876,15 +683,12 @@ fn enum_uints(start: uint, end: uint) -> [uint] { ret r; } -/* -Function: iter - +#[doc = " Iterates over a vector Iterates over vector `v` and, for each element, calls function `f` with the element's value. - -*/ +"] #[inline(always)] fn iter(v: [const T], f: fn(T)) { unsafe { @@ -898,26 +702,19 @@ fn iter(v: [const T], f: fn(T)) { } } -/* -Function: iter2 - -Iterates over two vectors in parallel - -*/ +#[doc = "Iterates over two vectors in parallel"] #[inline] fn iter2(v: [ U], v2: [const T], f: fn(U, T)) { let mut i = 0; for elt in v { f(elt, v2[i]); i += 1; } } -/* -Function: iteri - +#[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. -*/ +"] #[inline(always)] fn iteri(v: [const T], f: fn(uint, T)) { let mut i = 0u; @@ -925,27 +722,22 @@ fn iteri(v: [const T], f: fn(uint, T)) { while i < l { f(i, v[i]); i += 1u; } } -/* -Function: riter - +#[doc = " Iterates over a vector in reverse Iterates over vector `v` and, for each element, calls function `f` with the element's value. - -*/ +"] fn riter(v: [const T], f: fn(T)) { riteri(v) { |_i, v| f(v) } } -/* -Function: riteri - +#[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. -*/ +"] fn riteri(v: [const T], f: fn(uint, T)) { let mut i = len(v); while 0u < i { @@ -954,16 +746,16 @@ fn riteri(v: [const T], f: fn(uint, T)) { }; } -/* -Function: permute +#[doc = " +Iterate over all permutations of vector `v`. -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). +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. -*/ +"] fn permute(v: [T], put: fn([T])) { let ln = len(v); if ln == 0u { @@ -996,13 +788,12 @@ fn windowed (nn: uint, xx: [const TT]) -> [[TT]] { ret ww; } -/* -Function: as_buf +#[doc = " +Work with the buffer of a vector. -Work with the buffer of a vector. Allows for unsafe manipulation -of vector contents, which is useful for native interop. - -*/ +Allows for unsafe manipulation of vector contents, which is useful for native +interop. +"] fn as_buf(v: [const E], f: fn(*E) -> T) -> T unsafe { let buf = unsafe::to_ptr(v); f(buf) } @@ -1016,46 +807,37 @@ impl vec_len for [T] { fn len() -> uint { len(self) } } -/* -Module: unsafe -*/ mod unsafe { type vec_repr = {mutable fill: uint, mutable alloc: uint, data: u8}; - /* - Function: from_buf - + #[doc = " Constructs a vector from an unsafe pointer to a buffer - Parameters: + # Arguments - ptr - An unsafe pointer to a buffer of `T` - elts - The number of elements in the buffer - */ + * ptr - An unsafe pointer to a buffer of `T` + * elts - The number of elements in the buffer + "] #[inline(always)] unsafe fn from_buf(ptr: *T, elts: uint) -> [T] { ret rustrt::vec_from_buf_shared(sys::get_type_desc::(), ptr, elts); } - /* - Function: set_len - + #[doc = " Sets the length of a vector This well 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(&v: [const T], new_len: uint) { let repr: **vec_repr = ::unsafe::reinterpret_cast(addr_of(v)); (**repr).fill = new_len * sys::size_of::(); } - /* - Function: to_ptr - + #[doc = " Returns an unsafe pointer to the vector's buffer The caller must ensure that the vector outlives the pointer this @@ -1063,7 +845,7 @@ mod unsafe { 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(v: [const T]) -> *T { let repr: **vec_repr = ::unsafe::reinterpret_cast(addr_of(v)); @@ -1071,19 +853,12 @@ mod unsafe { } } -/* -Module: u8 -*/ mod u8 { export cmp; export lt, le, eq, ne, ge, gt; export hash; - /* - Function cmp - - Bytewise string comparison - */ + #[doc = "Bytewise string comparison"] pure fn cmp(&&a: [u8], &&b: [u8]) -> int unsafe { let a_len = len(a); let b_len = len(b); @@ -1102,53 +877,25 @@ mod u8 { } } - /* - Function: lt - - Bytewise less than or equal - */ + #[doc = "Bytewise less than or equal"] pure fn lt(&&a: [u8], &&b: [u8]) -> bool { cmp(a, b) < 0 } - /* - Function: le - - Bytewise less than or equal - */ + #[doc = "Bytewise less than or equal"] pure fn le(&&a: [u8], &&b: [u8]) -> bool { cmp(a, b) <= 0 } - /* - Function: eq - - Bytewise equality - */ + #[doc = "Bytewise equality"] pure fn eq(&&a: [u8], &&b: [u8]) -> bool unsafe { cmp(a, b) == 0 } - /* - Function: ne - - Bytewise inequality - */ + #[doc = "Bytewise inequality"] pure fn ne(&&a: [u8], &&b: [u8]) -> bool unsafe { cmp(a, b) != 0 } - /* - Function: ge - - Bytewise greater than or equal - */ + #[doc ="Bytewise greater than or equal"] pure fn ge(&&a: [u8], &&b: [u8]) -> bool { cmp(a, b) >= 0 } - /* - Function: gt - - Bytewise greater than - */ + #[doc = "Bytewise greater than"] pure fn gt(&&a: [u8], &&b: [u8]) -> bool { cmp(a, b) > 0 } - /* - Function: hash - - String hash function - */ + #[doc = "String hash function"] fn hash(&&s: [u8]) -> uint { // djb hash. // FIXME: replace with murmur.