bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

docs: Give all tutorials consistent titles and intro sections

Browse source
This commit is contained in:
Brian Anderson 2012-09-26 19:00:13 -07:00
parent ae1a73029c
commit 5424f21d5d
3 changed files with 19 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

16
doc/tutorial-ffi.md
View file

@ -1,4 +1,6 @@
# Interacting with foreign code % Rust Foreign Function Interface Tutorial
# Introduction
One of Rust's aims, as a system programming language, is to One of Rust's aims, as a system programming language, is to
interoperate well with C code. interoperate well with C code.
@ -38,7 +40,7 @@ fn main(args: ~[~str]) {
} }
~~~~ ~~~~
## Foreign modules # Foreign modules
Before we can call `SHA1`, we have to declare it. That is what this Before we can call `SHA1`, we have to declare it. That is what this
part of the program is responsible for: part of the program is responsible for:
@ -68,7 +70,7 @@ extern mod something {
} }
~~~~ ~~~~
## Foreign calling conventions # Foreign calling conventions
Most foreign code will be C code, which usually uses the `cdecl` calling Most foreign code will be C code, which usually uses the `cdecl` calling
convention, so that is what Rust uses by default when calling foreign convention, so that is what Rust uses by default when calling foreign
@ -88,7 +90,7 @@ The `"abi"` attribute applies to a foreign module (it can not be applied
to a single function within a module), and must be either `"cdecl"` to a single function within a module), and must be either `"cdecl"`
or `"stdcall"`. Other conventions may be defined in the future. or `"stdcall"`. Other conventions may be defined in the future.
## Unsafe pointers # Unsafe pointers
The foreign `SHA1` function is declared to take three arguments, and The foreign `SHA1` function is declared to take three arguments, and
return a pointer. return a pointer.
@ -118,7 +120,7 @@ caution—unlike Rust's other pointer types, unsafe pointers are
completely unmanaged, so they might point at invalid memory, or be completely unmanaged, so they might point at invalid memory, or be
null pointers. null pointers.
## Unsafe blocks # Unsafe blocks
The `sha1` function is the most obscure part of the program. The `sha1` function is the most obscure part of the program.
@ -159,7 +161,7 @@ unsafe fn kaboom() { ~"I'm harmless!"; }
This function can only be called from an unsafe block or another This function can only be called from an unsafe block or another
unsafe function. unsafe function.
## Pointer fiddling # Pointer fiddling
The standard library defines a number of helper functions for dealing The standard library defines a number of helper functions for dealing
with unsafe data, casting between types, and generally subverting with unsafe data, casting between types, and generally subverting
@ -202,7 +204,7 @@ unsafe pointer that was returned by `SHA1`. SHA1 digests are always
twenty bytes long, so we can pass `20u` for the length of the new twenty bytes long, so we can pass `20u` for the length of the new
vector. vector.
## Passing structures # Passing structures
C functions often take pointers to structs as arguments. Since Rust C functions often take pointers to structs as arguments. Since Rust
structs are binary-compatible with C structs, Rust programs can call structs are binary-compatible with C structs, Rust programs can call

12
doc/tutorial-macros.md
View file

@ -1,4 +1,6 @@
# Macros % Rust Macros Tutorial
# Introduction
Functions are the programmer's primary tool of abstraction, but there are Functions are the programmer's primary tool of abstraction, but there are
cases in which they are insufficient, because the programmer wants to cases in which they are insufficient, because the programmer wants to
@ -50,7 +52,7 @@ early_return!(input_2 special_b);
Macros are defined in pattern-matching style: Macros are defined in pattern-matching style:
## Invocation syntax # Invocation syntax
On the left-hand-side of the `=>` is the macro invocation syntax. It is On the left-hand-side of the `=>` is the macro invocation syntax. It is
free-form, excepting the following rules: free-form, excepting the following rules:
@ -69,7 +71,7 @@ rules of tokenization apply,
So `($x:ident => (($e:expr)))`, though excessively fancy, would create a macro So `($x:ident => (($e:expr)))`, though excessively fancy, would create a macro
that could be invoked like `my_macro!(i=>(( 2+2 )))`. that could be invoked like `my_macro!(i=>(( 2+2 )))`.
## Transcription syntax # Transcription syntax
The right-hand side of the `=>` follows the same rules as the left-hand side, The right-hand side of the `=>` follows the same rules as the left-hand side,
except that `$` need only be followed by the name of the syntactic fragment except that `$` need only be followed by the name of the syntactic fragment
@ -80,9 +82,9 @@ an expression; currently, user-defined macros can only be invoked in
expression position (even though `macro_rules!` itself can be in item expression position (even though `macro_rules!` itself can be in item
position). position).
## Multiplicity # Multiplicity
### Invocation ## Invocation
Going back to the motivating example, suppose that we wanted each invocation Going back to the motivating example, suppose that we wanted each invocation
of `early_return` to potentially accept multiple "special" identifiers. The of `early_return` to potentially accept multiple "special" identifiers. The

4
doc/tutorial-tasks.md
View file

@ -1,4 +1,6 @@
% Tasks and communication in Rust % Rust Tasks and Communication Tutorial
# Introduction
Rust supports a system of lightweight tasks, similar to what is found Rust supports a system of lightweight tasks, similar to what is found
in Erlang or other actor systems. Rust tasks communicate via messages in Erlang or other actor systems. Rust tasks communicate via messages