- Appendix chapters providing rationale and references to languages that
influenced the design.
-This document does not serve as a tutorial introduction to the
+This document does not serve as an introduction to the
language. Background familiarity with the language is assumed. A separate
-[tutorial] document is available to help acquire such background familiarity.
+[guide] is available to help acquire such background familiarity.
This document also does not serve as a reference to the [standard]
library included in the language distribution. Those libraries are
documented separately by extracting documentation attributes from their
source code.
-[tutorial]: tutorial.html
+[guide]: guide.html
[standard]: std/index.html
## Disclaimer
with the exception of `U+0022` itself,
which must be _escaped_ by a preceding `U+005C` character (`\`),
or a _raw byte string literal_.
-It is equivalent to a `&'static [u8]` borrowed vector of unsigned 8-bit integers.
+It is equivalent to a `&'static [u8]` borrowed array of unsigned 8-bit integers.
Some additional _escapes_ are available in either byte or non-raw byte string
literals. An escape starts with a `U+005C` (`\`) and continues with one of
- `repr` - specifies the representation to use for this struct. Takes a list
of options. The currently accepted ones are `C` and `packed`, which may be
- combined. `C` will use a C ABI comptible struct layout, and `packed` will
+ combined. `C` will use a C ABI compatible struct layout, and `packed` will
remove any padding between fields (note that this is very fragile and may
break platforms which require aligned access).
* `begin_unwind`
: ___Needs filling in___
+* `managed_bound`
+ : This type implements "managed"
* `no_copy_bound`
: This type does not implement "copy", even if eligible
* `no_send_bound`
: This type does not implement "send", even if eligible
* `no_sync_bound`
: This type does not implement "sync", even if eligible
-* `managed_bound`
- : This type implements "managed"
* `eh_personality`
: ___Needs filling in___
* `exchange_free`
These levels are directly inspired by
[Node.js' "stability index"](http://nodejs.org/api/documentation.html).
-Stability levels are inherited, so an items's stability attribute is the
+Stability levels are inherited, so an item's stability attribute is the
default stability for everything nested underneath it.
There are lints for disallowing items marked with certain levels: `deprecated`,
* `concat_idents` - Allows use of the `concat_idents` macro, which is in many
ways insufficient for concatenating identifiers, and may
- be removed entirely for something more wholsome.
+ be removed entirely for something more wholesome.
* `default_type_params` - Allows use of default type parameters. The future of
this feature is uncertain.
which is considered wildly unsafe and will be
obsoleted by language improvements.
+* `tuple_indexing` - Allows use of tuple indexing (expressions like `expr.0`)
+
If a feature is promoted to a language feature, then all existing programs will
start to receive compilation warnings about #[feature] directives which enabled
the new feature (because the directive is no longer necessary). However, if
Also, if the type of the expression to the left of the dot is a pointer,
it is automatically dereferenced to make the field access possible.
-### Vector expressions
+### Array expressions
~~~~ {.ebnf .gram}
-vec_expr : '[' "mut" ? vec_elems? ']' ;
+array_expr : '[' "mut" ? vec_elems? ']' ;
-vec_elems : [expr [',' expr]*] | [expr ',' ".." expr] ;
+array_elems : [expr [',' expr]*] | [expr ',' ".." expr] ;
~~~~
-A [_vector_](#vector-types) _expression_ is written by enclosing zero or
-more comma-separated expressions of uniform type in square brackets.
+An [array](#vector,-array,-and-slice-types) _expression_ is written by
+enclosing zero or more comma-separated expressions of uniform type in square
+brackets.
In the `[expr ',' ".." expr]` form, the expression after the `".."`
must be a constant expression that can be evaluated at compile time, such
~~~~
[1i, 2, 3, 4];
["a", "b", "c", "d"];
-[0i, ..128]; // vector with 128 zeros
+[0i, ..128]; // array with 128 zeros
[0u8, 0u8, 0u8, 0u8];
~~~~
idx_expr : expr '[' expr ']' ;
~~~~
-[Vector](#vector-types)-typed expressions can be indexed by writing a
+[Array](#vector,-array,-and-slice-types)-typed expressions can be indexed by writing a
square-bracket-enclosed expression (the index) after them. When the
-vector is mutable, the resulting [lvalue](#lvalues,-rvalues-and-temporaries) can be assigned to.
+array is mutable, the resulting [lvalue](#lvalues,-rvalues-and-temporaries) can be assigned to.
Indices are zero-based, and may be of any integral type. Vector access
is bounds-checked at run-time. When the check fails, it will put the
The default meaning of the operators on standard types is given here.
* `+`
- : Addition and vector/string concatenation.
+ : Addition and array/string concatenation.
Calls the `add` method on the `std::ops::Add` trait.
* `-`
: Subtraction.
A `for` expression is a syntactic construct for looping over elements
provided by an implementation of `std::iter::Iterator`.
-An example of a for loop over the contents of a vector:
+An example of a for loop over the contents of an array:
~~~~
# type Foo = int;
A `match` expression branches on a *pattern*. The exact form of matching that
occurs depends on the pattern. Patterns consist of some combination of
-literals, destructured vectors or enum constructors, structures and
+literals, destructured arrays or enum constructors, structures and
tuples, variable binding specifications, wildcards (`..`), and placeholders
(`_`). A `match` expression has a *head expression*, which is the value to
compare to the patterns. The type of the patterns must equal the type of the
exactly one argument, while the pattern `C(..)` is type-correct for any enum
variant `C`, regardless of how many arguments `C` has.
-Used inside a vector pattern, `..` stands for any number of elements. This
-wildcard can be used at most once for a given vector, which implies that it
-cannot be used to specifically match elements that are at an unknown distance
-from both ends of a vector, like `[.., 42, ..]`. If followed by a variable name,
-it will bind the corresponding slice to the variable. Example:
+Used inside a array pattern, `..` stands for any number of elements, when the
+`advanced_slice_patterns` feature gate is turned on. This wildcard can be used
+at most once for a given array, which implies that it cannot be used to
+specifically match elements that are at an unknown distance from both ends of a
+array, like `[.., 42, ..]`. If followed by a variable name, it will bind the
+corresponding slice to the variable. Example:
~~~~
+# #![feature(advanced_slice_patterns)]
fn is_symmetric(list: &[uint]) -> bool {
match list {
[] | [_] => true,
- [x, ..inside, y] if x == y => is_symmetric(inside),
+ [x, inside.., y] if x == y => is_symmetric(inside),
_ => false
}
}
~~~~
Range patterns only work on scalar types
-(like integers and characters; not like vectors and structs, which have sub-components).
+(like integers and characters; not like arrays and structs, which have sub-components).
A range pattern may not be a sub-range of another range pattern inside the same `match`.
Finally, match patterns can accept *pattern guards* to further refine the
(ie. a code point that is not a surrogate),
represented as a 32-bit unsigned word in the 0x0000 to 0xD7FF
or 0xE000 to 0x10FFFF range.
-A `[char]` vector is effectively an UCS-4 / UTF-32 string.
+A `[char]` array is effectively an UCS-4 / UTF-32 string.
A value of type `str` is a Unicode string,
-represented as a vector of 8-bit unsigned bytes holding a sequence of UTF-8 codepoints.
+represented as a array of 8-bit unsigned bytes holding a sequence of UTF-8 codepoints.
Since `str` is of unknown size, it is not a _first class_ type,
but can only be instantiated through a pointer type,
such as `&str` or `String`.
New instances of a `struct` can be constructed with a [struct expression](#structure-expressions).
-The memory layout of a `struct` is undefined by default to allow for compiler optimziations like
+The memory layout of a `struct` is undefined by default to allow for compiler optimizations like
field reordering, but it can be fixed with the `#[repr(...)]` attribute.
In either case, fields may be given in any order in a corresponding struct *expression*;
the resulting `struct` value will always have the same memory layout.
* Recursive types must include a nominal type in the recursion
(not mere [type definitions](#type-definitions),
- or other structural types such as [vectors](#vector-types) or [tuples](#tuple-types)).
+ or other structural types such as [arrays](#vector,-array,-and-slice-types) or [tuples](#tuple-types)).
* A recursive `enum` item must have at least one non-recursive constructor
(in order to give the recursion a basis case).
* The size of a recursive type must be finite;
All pointers in Rust are explicit first-class values.
They can be copied, stored into data structures, and returned from functions.
-There are four varieties of pointer in Rust:
-
-* Owning pointers (`Box`)
- : These point to owned heap allocations (or "boxes") in the shared, inter-task heap.
- Each owned box has a single owning pointer; pointer and pointee retain a 1:1 relationship at all times.
- Owning pointers are written `Box<content>`,
- for example `Box<int>` means an owning pointer to an owned box containing an integer.
- Copying an owned box is a "deep" operation:
- it involves allocating a new owned box and copying the contents of the old box into the new box.
- Releasing an owning pointer immediately releases its corresponding owned box.
+There are two varieties of pointer in Rust:
* References (`&`)
: These point to memory _owned by some other value_.
- References arise by (automatic) conversion from owning pointers, managed pointers,
- or by applying the borrowing operator `&` to some other value,
- including [lvalues, rvalues or temporaries](#lvalues,-rvalues-and-temporaries).
- A borrow expression is written `&content`.
-
- A reference type is written `&'f type` for some lifetime-variable `f`,
- or just `&type` when the lifetime can be elided;
- for example `&int` means a reference to an integer.
+ A reference type is written `&type` for some lifetime-variable `f`,
+ or just `&'a type` when you need an explicit lifetime.
Copying a reference is a "shallow" operation:
it involves only copying the pointer itself.
Releasing a reference typically has no effect on the value it points to,
- with the exception of temporary values,
- which are released when the last reference to them is released.
+ with the exception of temporary values, which are released when the last
+ reference to them is released.
* Raw pointers (`*`)
: Raw pointers are pointers without safety or liveness guarantees.
they exist to support interoperability with foreign code,
and writing performance-critical or low-level functions.
+The standard library contains additional 'smart pointer' types beyond references
+and raw pointers.
+
### Function types
The function type constructor `fn` forms new function types.
### Built in types
The runtime provides C and Rust code to assist with various built-in types,
-such as vectors, strings, and the low level communication system (ports,
+such as arrays, strings, and the low level communication system (ports,
channels, tasks).
Support for other built-in types such as simple types, tuples and
The Rust compiler supports various methods to link crates together both
statically and dynamically. This section will explore the various methods to
link Rust crates together, and more information about native libraries can be
-found in the [ffi tutorial][ffi].
+found in the [ffi guide][ffi].
In one session of compilation, the compiler can generate multiple artifacts
through the usage of either command line flags or the `crate_type` attribute.
purpose of this output type is to create a static library containing all of
the local crate's code along with all upstream dependencies. The static
library is actually a `*.a` archive on linux and osx and a `*.lib` file on
- windows. This format is recommended for use in situtations such as linking
+ windows. This format is recommended for use in situations such as linking
Rust code into an existing non-Rust application because it will not have
dynamic dependencies on other Rust code.
projects / rust.git / blobdiff