Skip to content

rustdocs for box.rs, comm.rs, ctypes.rs, char.rs #1554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jan 17, 2012
Merged

rustdocs for box.rs, comm.rs, ctypes.rs, char.rs #1554

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ca55a4b
convert comments to rustdocs for box, char, comm and cytpes.rs
rtanglao Jan 17, 2012
e631df3
add spaces before newlines in rustdocs
rtanglao Jan 17, 2012
315e3ff
Forgot to add some spaces before backslashes
rtanglao Jan 17, 2012
93be00f
Remove un-needed <
rtanglao Jan 17, 2012
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 3 additions & 10 deletions src/libcore/box.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 {
Expand Down
114 changes: 40 additions & 74 deletions src/libcore/char.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -47,50 +43,40 @@ 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)
|| unicode::general_category::Zl(c)
|| 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) ||
Expand All @@ -99,34 +85,24 @@ 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 }
option::none. { fail; }
}
}

/*
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)) }
Expand All @@ -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 }
Expand All @@ -151,31 +126,22 @@ 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 }
_ { c }
}
}

/*
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 }
Expand Down
139 changes: 58 additions & 81 deletions src/libcore/comm.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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;
Expand Down Expand Up @@ -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);
}
Expand All @@ -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);
Expand All @@ -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
Expand All @@ -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))
}
Loading