---

yaml
---
r: 139511
b: refs/heads/try2
c: dbeea18
h: refs/heads/master
i:
  139509: ab296f7
  139507: f29f624
  139503: 3c43485
v: v3

Author: catamorphism

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: dc60788215afc61b3f5b5e57cf786478218b919e
+refs/heads/try2: dbeea18fc5f94d29db74144e55089cc55aa8e11d
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/doc/rust.md

@@ -1420,13 +1420,111 @@ names are effectively reserved. Some significant attributes include:
 
 * The `doc` attribute, for documenting code in-place.
 * The `cfg` attribute, for conditional-compilation by build-configuration.
+* The `lang` attribute, for custom definitions of traits and functions that are known to the Rust compiler (see [Language items](#language-items)).
 * The `link` attribute, for describing linkage metadata for a crate.
 * The `test` attribute, for marking functions as unit tests.
-* The `allow`, `warn`, `forbid`, and `deny` attributes, for controling lint checks. Lint checks supported
+* The `allow`, `warn`, `forbid`, and `deny` attributes, for controlling lint checks. Lint checks supported
 by the compiler can be found via `rustc -W help`.
 
 Other attributes may be added or removed during development of the language.
 
+### Language items
+
+Some primitive Rust operations are defined in Rust code,
+rather than being implemented directly in C or assembly language.
+The definitions of these operations have to be easy for the compiler to find.
+The `lang` attribute makes it possible to declare these operations.
+For example, the `str` module in the Rust core library defines the string equality function:
+
+~~~
+#[lang="str_eq"]
+pub fn eq_slice(a: &str, b: &str) -> bool {
+    true // not actually the implementation
+}
+~~~
+
+The name `str_eq` has a special meaning to the Rust compiler,
+and the presence of this definition means that it will use this definition
+when generating calls to the string equality function.
+
+A complete list of the built-in language items follows:
+
+#### Traits
+
+`const`
+  : Cannot be mutated.
+`copy`
+  : Can be implicitly copied.
+`owned`
+  : Are uniquely owned.
+`durable`
+  : Contain borrowed pointers.
+`drop`
+  : Have finalizers.
+`add`
+  : Elements can be added (for example, integers and floats).
+`sub`
+  : Elements can be subtracted.
+`mul`
+  : Elements can be multiplied.
+`div`
+  : Elements can be divided.
+`mod`
+  : Elements have a modulo operation.
+`neg`
+  : Elements can be negated arithmetically.
+`not`
+  : Elements can be negated logically.
+`bitxor`
+  : Elements have an exclusive-or operation.
+`bitand`
+  : Elements have a bitwise `and` operation.
+`bitor`
+  : Elements have a bitwise `or` operation.
+`shl`
+  : Elements have a left shift operation.
+`shr`
+  : Elements have a right shift operation.
+`index`
+  : Elements can be indexed.
+`eq`
+  : Elements can be compared for equality.
+`ord`
+  : Elements have a partial ordering.
+
+#### Operations
+
+`str_eq`
+  : Compare two strings for equality.
+`uniq_str_eq`
+  : Compare two owned strings for equality.
+`annihilate`
+  : Destroy a box before freeing it.
+`log_type`
+  : Generically print a string representation of any type.
+`fail_`
+  : Abort the program with an error.
+`fail_bounds_check`
+  : Abort the program with a bounds check error.
+`exchange_malloc`
+  : Allocate memory on the exchange heap.
+`exchange_free`
+  : Free memory that was allocated on the exchange heap.
+`malloc`
+  : Allocate memory on the managed heap.
+`free`
+  : Free memory that was allocated on the managed heap.
+`borrow_as_imm`
+  : Create an immutable borrowed pointer to a mutable value.
+`return_to_mut`
+  : Release a borrowed pointer created with `return_to_mut`
+`check_not_borrowed`
+  : Fail if a value has existing borrowed pointers to it.
+`strdup_uniq`
+  : Return a new unique string containing a copy of the contents of a unique string.
+
+> **Note:** This list is likely to become out of date. We should auto-generate it
+> from `librustc/middle/lang_items.rs`.
 
 # Statements and expressions
 

branches/try2/doc/tutorial.md

@@ -2554,65 +2554,26 @@ a hash representing the crate metadata.
 
 ## The core library
 
-The Rust core library provides runtime features required by the language,
-including the task scheduler and memory allocators, as well as library
-support for Rust built-in types, platform abstractions, and other commonly
-used features.
-
-[`core`] includes modules corresponding to each of the integer types, each of
-the floating point types, the [`bool`] type, [tuples], [characters], [strings],
-[vectors], [managed boxes], [owned boxes],
-and unsafe and borrowed [pointers].  Additionally, `core` provides
-some pervasive types ([`option`] and [`result`]),
-[task] creation and [communication] primitives,
-platform abstractions ([`os`] and [`path`]), basic
-I/O abstractions ([`io`]), [containers] like [`hashmap`],
-common traits ([`kinds`], [`ops`], [`cmp`], [`num`],
-[`to_str`], [`clone`]), and complete bindings to the C standard library ([`libc`]).
-
-### Core injection and the Rust prelude
-
-`core` is imported at the topmost level of every crate by default, as
-if the first line of each crate was
-
-    extern mod core;
-
-This means that the contents of core can be accessed from from any context
-with the `core::` path prefix, as in `use core::vec`, `use core::task::spawn`,
-etc.
-
-Additionally, `core` contains a `prelude` module that reexports many of the
-most common core modules, types and traits. The contents of the prelude are
-imported into every *module* by default.  Implicitly, all modules behave as if
-they contained the following prologue:
-
-    use core::prelude::*;
-
-[`core`]: core/index.html
-[`bool`]: core/bool.html
-[tuples]: core/tuple.html
-[characters]: core/char.html
-[strings]: core/str.html
+The Rust [core] library is the language runtime and contains
+required memory management and task scheduling code as well as a
+number of modules necessary for effective usage of the primitive
+types. Methods on [vectors] and [strings], implementations of most
+comparison and math operators, and pervasive types like [`Option`]
+and [`Result`] live in core.
+
+All Rust programs link to the core library and import its contents,
+as if the following were written at the top of the crate.
+
+~~~ {.xfail-test}
+extern mod core;
+use core::*;
+~~~
+
+[core]: core/index.html
 [vectors]: core/vec.html
-[managed boxes]: core/managed.html
-[owned boxes]: core/owned.html
-[pointers]: core/ptr.html
-[`option`]: core/option.html
-[`result`]: core/result.html
-[task]: core/task.html
-[communication]: core/comm.html
-[`os`]: core/os.html
-[`path`]: core/path.html
-[`io`]: core/io.html
-[containers]: core/container.html
-[`hashmap`]: core/hashmap.html
-[`kinds`]: core/kinds.html
-[`ops`]: core/ops.html
-[`cmp`]: core/cmp.html
-[`num`]: core/num.html
-[`to_str`]: core/to_str.html
-[`clone`]: core/clone.html
-[`libc`]: core/libc.html
+[strings]: core/str.html
+[`Option`]: core/option.html
+[`Result`]: core/result.html
 
 # What next?
 
@@ -2624,7 +2585,10 @@ tutorials on individual topics.
 * [Macros][macros]
 * [The foreign function interface][ffi]
 
-There is further documentation on the [wiki].
+There is further documentation on the [wiki], including articles about
+[unit testing] in Rust, [documenting][rustdoc] and [packaging][cargo]
+Rust code, and a discussion of the [attributes] used to apply metadata
+to code.
 
 [borrow]: tutorial-borrowed-ptr.html
 [tasks]: tutorial-tasks.html

branches/try2/src/libcore/core.rc

@@ -39,7 +39,7 @@ etc.
 
 Additionally, `core` contains a `prelude` module that reexports many of the
 most common core modules, types and traits. The contents of the prelude are
-imported into every *module* by default.  Implicitly, all modules behave as if
+imported inte every *module* by default.  Implicitly, all modules behave as if
 they contained the following prologue:
 
     use core::prelude::*;

branches/try2/src/libcore/libc.rs

@@ -9,19 +9,7 @@
 // except according to those terms.
 
 /*!
-* Bindings for the C standard library and other platform libraries
-*
-* This module contains bindings to the C standard library,
-* organized into modules by their defining standard.
-* Additionally, it contains some assorted platform-specific definitions.
-* For convenience, most functions and types are reexported from `core::libc`,
-* so `pub use core::libc::*` will import the available
-* C bindings as appropriate for the target platform. The exact
-* set of functions available are platform specific.
-*
-* *Note* Rustdoc does not indicate reexports currently. Also, because these
-* definitions are platform-specific, some may not
-* appear in the generated documentation.
+* Bindings for libc.
 *
 * We consider the following specs reasonably normative with respect
 * to interoperating with the C standard library (libc/msvcrt):