Merge pull request #1554 from rtanglao/master
rustdocs for box.rs, comm.rs, ctypes.rs, char.rs
This commit is contained in:
Graydon Hoare
commit
c4553caab3
@ -1,15 +1,8 @@
|
||||
/*
|
||||
Module: box
|
||||
*/
|
||||
|
||||
|
||||
export ptr_eq;
|
||||
|
||||
/*
|
||||
Function: ptr_eq
|
||||
|
||||
Determine if two shared boxes point to the same object
|
||||
*/
|
||||
#[doc(
|
||||
brief = "Determine if two shared boxes point to the same object"
|
||||
)]
|
||||
pure fn ptr_eq<T>(a: @T, b: @T) -> bool {
|
||||
// FIXME: ptr::addr_of
|
||||
unsafe {
|
||||
|
||||
@ -1,8 +1,4 @@
|
||||
/*
|
||||
Module: char
|
||||
|
||||
Utilities for manipulating the char type
|
||||
*/
|
||||
#[doc = "Utilities for manipulating the char type"];
|
||||
|
||||
/*
|
||||
Lu Uppercase_Letter an uppercase letter
|
||||
@ -47,34 +43,28 @@ import is_alphabetic = unicode::derived_property::Alphabetic;
|
||||
import is_XID_start = unicode::derived_property::XID_Start;
|
||||
import is_XID_continue = unicode::derived_property::XID_Continue;
|
||||
|
||||
/*
|
||||
Function: is_lowercase
|
||||
|
||||
Indicates whether a character is in lower case, defined in terms of the
|
||||
Unicode General Category 'Ll'.
|
||||
*/
|
||||
#[doc(
|
||||
brief = "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);
|
||||
}
|
||||
|
||||
/*
|
||||
Function: is_uppercase
|
||||
|
||||
Indicates whether a character is in upper case, defined in terms of the
|
||||
Unicode General Category 'Lu'.
|
||||
*/
|
||||
#[doc(
|
||||
brief = "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);
|
||||
}
|
||||
|
||||
/*
|
||||
Function: is_whitespace
|
||||
|
||||
Indicates whether a character is whitespace, defined in terms of
|
||||
the Unicode General Categories 'Zs', 'Zl', 'Zp' and the additional
|
||||
'Cc'-category control codes in the range [0x09, 0x0d].
|
||||
|
||||
*/
|
||||
#[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]"
|
||||
)]
|
||||
pure fn is_whitespace(c: char) -> bool {
|
||||
ret ('\x09' <= c && c <= '\x0d')
|
||||
|| unicode::general_category::Zs(c)
|
||||
@ -82,15 +72,11 @@ pure fn is_whitespace(c: char) -> bool {
|
||||
|| unicode::general_category::Zp(c);
|
||||
}
|
||||
|
||||
/*
|
||||
Function: is_alphanumeric
|
||||
|
||||
Indicates whether a character is alphanumeric, defined in terms of
|
||||
the Unicode General Categories 'Nd', 'Nl', 'No' and the Derived
|
||||
Core Property 'Alphabetic'.
|
||||
|
||||
*/
|
||||
|
||||
#[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'."
|
||||
)]
|
||||
pure fn is_alphanumeric(c: char) -> bool {
|
||||
ret unicode::derived_property::Alphabetic(c) ||
|
||||
unicode::general_category::Nd(c) ||
|
||||
@ -99,21 +85,13 @@ pure fn is_alphanumeric(c: char) -> bool {
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
Function: to_digit
|
||||
|
||||
Convert a char to the corresponding digit.
|
||||
|
||||
Parameters:
|
||||
c - a char, either '0' to '9', 'a' to 'z' or 'A' to 'Z'
|
||||
|
||||
Returns:
|
||||
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.
|
||||
|
||||
Safety note:
|
||||
This function fails if `c` is not a valid char
|
||||
*/
|
||||
#[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."
|
||||
)]
|
||||
pure fn to_digit(c: char) -> u8 unsafe {
|
||||
alt maybe_digit(c) {
|
||||
option::some(x) { x }
|
||||
@ -121,12 +99,10 @@ pure fn to_digit(c: char) -> u8 unsafe {
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
Function: maybe_digit
|
||||
|
||||
Convert a char to the corresponding digit. Returns none when the
|
||||
character is not a valid hexadecimal digit.
|
||||
*/
|
||||
#[doc(
|
||||
brief = "Convert a char to the corresponding digit. Returns none when \
|
||||
character is not a valid hexadecimal digit."
|
||||
)]
|
||||
pure fn maybe_digit(c: char) -> option::t<u8> {
|
||||
alt c {
|
||||
'0' to '9' { option::some(c as u8 - ('0' as u8)) }
|
||||
@ -137,12 +113,11 @@ pure fn maybe_digit(c: char) -> option::t<u8> {
|
||||
}
|
||||
|
||||
/*
|
||||
Function: to_lower
|
||||
|
||||
Convert a char to the corresponding lower case.
|
||||
|
||||
FIXME: works only on ASCII
|
||||
*/
|
||||
#[doc(
|
||||
brief = "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 }
|
||||
@ -151,12 +126,11 @@ pure fn to_lower(c: char) -> char {
|
||||
}
|
||||
|
||||
/*
|
||||
Function: to_upper
|
||||
|
||||
Convert a char to the corresponding upper case.
|
||||
|
||||
FIXME: works only on ASCII
|
||||
*/
|
||||
#[doc(
|
||||
brief = "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 }
|
||||
@ -164,18 +138,10 @@ pure fn to_upper(c: char) -> char {
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
Function: cmp
|
||||
|
||||
Compare two chars.
|
||||
|
||||
Parameters:
|
||||
a - a char
|
||||
b - a char
|
||||
|
||||
Returns:
|
||||
-1 if a<b, 0 if a==b, +1 if a>b
|
||||
*/
|
||||
#[doc(
|
||||
brief = "Compare two chars.",
|
||||
return = "-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 }
|
||||
|
||||
@ -1,28 +1,21 @@
|
||||
/*
|
||||
Module: comm
|
||||
|
||||
Communication between tasks
|
||||
|
||||
Communication between tasks is facilitated by ports (in the receiving task),
|
||||
and channels (in the sending task). Any number of channels may feed into a
|
||||
single port.
|
||||
|
||||
Ports and channels may only transmit values of unique types; that is,
|
||||
values that are statically guaranteed to be accessed by a single
|
||||
'owner' at a time. Unique types include scalars, vectors, strings,
|
||||
and records, tags, tuples and unique boxes (~T) thereof. Most notably,
|
||||
shared boxes (@T) may not be transmitted across channels.
|
||||
|
||||
Example:
|
||||
|
||||
> let p = comm::port();
|
||||
> task::spawn(comm::chan(p), fn (c: chan<str>) {
|
||||
> comm::send(c, "Hello, World");
|
||||
> });
|
||||
>
|
||||
> io::println(comm::recv(p));
|
||||
|
||||
*/
|
||||
#[doc(
|
||||
brief = "Communication between tasks",
|
||||
desc = "Communication between tasks is facilitated by ports (in the \
|
||||
receiving task), and channels (in the sending task). Any \
|
||||
number of channels may feed into a single port. \
|
||||
Ports and channels may only transmit values of unique \
|
||||
types; that is, values that are statically guaranteed to \
|
||||
be accessed by a single 'owner' at a time. Unique types \
|
||||
include scalars, vectors, strings, and records, tags, \
|
||||
tuples and unique boxes (~T) thereof. Most notably, \
|
||||
shared boxes (@T) may not be transmitted across channels. \
|
||||
Example: \
|
||||
let p = comm::port(); \
|
||||
task::spawn(comm::chan(p), fn (c: chan<str>) { \
|
||||
comm::send(c, \"Hello, World\"); \
|
||||
}); \
|
||||
io::println(comm::recv(p));"
|
||||
)];
|
||||
|
||||
import sys;
|
||||
import task;
|
||||
@ -59,22 +52,18 @@ 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.
|
||||
/*
|
||||
Type: chan
|
||||
|
||||
A communication endpoint that can send messages. Channels send
|
||||
messages to ports.
|
||||
|
||||
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(
|
||||
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."
|
||||
)]
|
||||
tag chan<T: send> {
|
||||
chan_t(task::task, port_id);
|
||||
}
|
||||
@ -92,27 +81,21 @@ resource port_ptr<T: send>(po: *rustrt::rust_port) {
|
||||
rustrt::del_port(po);
|
||||
}
|
||||
|
||||
/*
|
||||
Type: port
|
||||
|
||||
A communication endpoint that can receive messages. Ports receive
|
||||
messages from channels.
|
||||
|
||||
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.
|
||||
*/
|
||||
#[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 <chan>s."
|
||||
)]
|
||||
tag port<T: send> { port_t(@port_ptr<T>); }
|
||||
|
||||
/*
|
||||
Function: send
|
||||
|
||||
Sends data over a channel.
|
||||
|
||||
The sent data is moved into the channel, whereupon the caller loses access
|
||||
to it.
|
||||
*/
|
||||
#[doc(
|
||||
brief = "Sends data over a channel. The sent data is moved \
|
||||
into the channel, whereupon the caller loses \
|
||||
access to it."
|
||||
)]
|
||||
fn send<T: send>(ch: chan<T>, -data: T) {
|
||||
let chan_t(t, p) = ch;
|
||||
let res = rustrt::chan_id_send(sys::get_type_desc::<T>(), t, p, data);
|
||||
@ -123,26 +106,23 @@ fn send<T: send>(ch: chan<T>, -data: T) {
|
||||
task::yield();
|
||||
}
|
||||
|
||||
/*
|
||||
Function: port
|
||||
|
||||
Constructs a port.
|
||||
*/
|
||||
#[doc(
|
||||
brief = "Constructs a port."
|
||||
)]
|
||||
fn port<T: send>() -> port<T> {
|
||||
port_t(@port_ptr(rustrt::new_port(sys::size_of::<T>())))
|
||||
}
|
||||
|
||||
/*
|
||||
Function: recv
|
||||
|
||||
Receive from a port.
|
||||
|
||||
If no data is available on the port then the task will block until data
|
||||
becomes available.
|
||||
*/
|
||||
#[doc(
|
||||
brief = "Receive from a port. \
|
||||
If no data is available on the port then the task will \
|
||||
block until data becomes available."
|
||||
)]
|
||||
fn recv<T: send>(p: port<T>) -> T { recv_(***p) }
|
||||
|
||||
// Receive on a raw port pointer
|
||||
#[doc(
|
||||
brief = "Receive on a raw port pointer"
|
||||
)]
|
||||
fn recv_<T: send>(p: *rustrt::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
|
||||
@ -169,13 +149,10 @@ fn recv_<T: send>(p: *rustrt::rust_port) -> T {
|
||||
ret res;
|
||||
}
|
||||
|
||||
/*
|
||||
Function: chan
|
||||
|
||||
Constructs a channel.
|
||||
|
||||
The channel is bound to the port used to construct it.
|
||||
*/
|
||||
#[doc(
|
||||
brief = "Constructs a channel. The channel is bound to the \
|
||||
port used to construct it."
|
||||
)]
|
||||
fn chan<T: send>(p: port<T>) -> chan<T> {
|
||||
chan_t(task::get_task(), rustrt::get_port_id(***p))
|
||||
}
|
||||
|
||||
@ -1,8 +1,4 @@
|
||||
/*
|
||||
Module: ctypes
|
||||
|
||||
Definitions useful for C interop
|
||||
*/
|
||||
#[doc = "Definitions useful for C interop"];
|
||||
|
||||
/*
|
||||
FIXME: Add a test that uses some native code to verify these sizes,
|
||||
@ -20,81 +16,62 @@ export enum;
|
||||
|
||||
// PORT adapt to architecture
|
||||
|
||||
/*
|
||||
Type: c_int
|
||||
|
||||
A signed integer with the same size as a C `int`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A signed integer with the same size as a C `int`."
|
||||
)]
|
||||
type c_int = i32;
|
||||
|
||||
/*
|
||||
Type: c_uint
|
||||
|
||||
An unsigned integer with the same size as a C `unsigned int`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "An unsigned integer with the same size as a C `unsigned int`."
|
||||
)]
|
||||
type c_uint = u32;
|
||||
|
||||
/*
|
||||
Type: long
|
||||
|
||||
A signed integer with the same size as a C `long`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A signed integer with the same size as a C `long`."
|
||||
)]
|
||||
type long = int;
|
||||
|
||||
/*
|
||||
Type: longlong
|
||||
|
||||
A signed integer with the same size as a C `long long`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A signed integer with the same size as a C `long long`."
|
||||
)]
|
||||
type longlong = i64;
|
||||
|
||||
/*
|
||||
Type: unsigned
|
||||
|
||||
An unsigned integer with the same size as a C `unsigned int`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A signed integer with the same size as a C `unsigned int`."
|
||||
)]
|
||||
type unsigned = u32;
|
||||
|
||||
/*
|
||||
Type: ulong
|
||||
|
||||
An unsigned integer with the same size as a C `unsigned long`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A signed integer with the same size as a C `unsigned long`."
|
||||
)]
|
||||
type ulong = uint;
|
||||
|
||||
/*
|
||||
Type: ulonglong
|
||||
|
||||
An unsigned integer with the same size as a C `unsigned long long`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A signed integer with the same size as a C `unsigned long long`."
|
||||
)]
|
||||
type ulonglong = u64;
|
||||
|
||||
/*
|
||||
Type: intptr_t
|
||||
|
||||
A signed integer with the same size as a pointer. This is
|
||||
guaranteed to always be the same type as a Rust `int`
|
||||
*/
|
||||
#[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`."
|
||||
)]
|
||||
type intptr_t = uint; // FIXME: int
|
||||
|
||||
/*
|
||||
Type: uintptr_t
|
||||
|
||||
An unsigned integer with the same size as a pointer. This is
|
||||
guaranteed to always be the same type as a Rust `uint`.
|
||||
*/
|
||||
#[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`."
|
||||
)]
|
||||
type uintptr_t = uint;
|
||||
type uint32_t = u32;
|
||||
|
||||
/*
|
||||
Type: void
|
||||
|
||||
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.
|
||||
*/
|
||||
#[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."
|
||||
)]
|
||||
tag void {
|
||||
// Making the only variant reference itself makes it impossible to
|
||||
// construct. Not exporting it makes it impossible to destructure.
|
||||
@ -103,60 +80,45 @@ tag void {
|
||||
void_private2(@void);
|
||||
}
|
||||
|
||||
/*
|
||||
Type: c_float
|
||||
|
||||
A float value with the same size as a C `float`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A float value with the same size as a C `float`."
|
||||
)]
|
||||
type c_float = f32;
|
||||
|
||||
/*
|
||||
Type: c_float
|
||||
|
||||
A float value with the same size as a C `double`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A float value with the same size as a C `double`."
|
||||
)]
|
||||
type c_double = f64;
|
||||
|
||||
/*
|
||||
Type: size_t
|
||||
|
||||
An unsigned integer corresponding to the C `size_t`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "An unsigned integer corresponding to the C `size_t`."
|
||||
)]
|
||||
type size_t = uint;
|
||||
|
||||
/*
|
||||
Type: ssize_t
|
||||
|
||||
A signed integer correpsonding to the C `ssize_t`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A signed integer corresponding to the C `ssize_t`."
|
||||
)]
|
||||
type ssize_t = int;
|
||||
|
||||
/*
|
||||
Type: off_t
|
||||
|
||||
An unsigned integer corresponding to the C `off_t`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "An unsigned integer corresponding to the C `off_t`."
|
||||
)]
|
||||
type off_t = uint;
|
||||
|
||||
/*
|
||||
Type: fd_t
|
||||
|
||||
A type that can be used for C file descriptors
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A type that can be used for C file descriptors."
|
||||
)]
|
||||
type fd_t = i32; // not actually a C type, but should be.
|
||||
|
||||
/*
|
||||
Type: pid_t
|
||||
|
||||
A type for representing process ID's, corresponding to C `pid_t`
|
||||
*/
|
||||
#[doc(
|
||||
brief = "A type for representing process ID's, corresponding to C `pid_t`."
|
||||
)]
|
||||
type pid_t = i32;
|
||||
|
||||
// enum is implementation-defined, but is 32-bits in practice
|
||||
/*
|
||||
Type: enum
|
||||
|
||||
An unsigned integer with the same size as a C enum
|
||||
*/
|
||||
#[doc(
|
||||
brief = "An unsigned integer with the same size as a C enum. \
|
||||
enum is implementation-defined, but is 32-bits in \
|
||||
practice"
|
||||
)]
|
||||
type enum = u32;
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user