---

yaml
---
r: 29947
b: refs/heads/incoming
c: 6c36dc8
h: refs/heads/master
i:
  29945: 5966863
  29943: f44bbe8
v: v3

Author: Vincent-Belliard

[refs]

@@ -6,7 +6,7 @@ refs/heads/try: d324a424d8f84b1eb049b12cf34182bda91b0024
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: d0c6ce338884ee21843f4b40bf6bf18d222ce5df
-refs/heads/incoming: 8ee79c79aada1b5943b5ada11570f9b903c74579
+refs/heads/incoming: 6c36dc86600186db285534eda0948dea2af71e9d
 refs/heads/dist-snap: 2f32a1581f522e524009138b33b1c7049ced668d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/incoming/AUTHORS.txt

@@ -49,7 +49,6 @@ Jeff Muizelaar <[email protected]>
 Jeff Olson <[email protected]>
 Jeffrey Yasskin <[email protected]>
 Jesse Ruderman <[email protected]>
-Jim Blandy <[email protected]>
 Joe Pletcher <[email protected]>
 Jon Morton <[email protected]>
 Jonathan Sternberg <[email protected]>

branches/incoming/doc/rust.md

@@ -211,7 +211,7 @@ The keywords in [source files](#source-files) are the following strings:
 ~~~~~~~~ {.keyword}
 again assert
 break
-check const copy
+check class const copy
 drop
 else enum export extern
 fail false fn for
@@ -220,7 +220,6 @@ let log loop
 match mod mut
 pure
 return
-struct
 true trait type
 unchecked unsafe
 while
@@ -1098,6 +1097,151 @@ enum list<T> {
 let a: list<int> = cons(7, @cons(13, @nil));
 ~~~~
 
+### Classes
+
+A _class_ is a named record type that collects together fields and
+methods. It must have a _constructor_ (a function called `new` that
+returns a new instance of the class), and may have a destructor (a
+nullary function called `drop` that executes before the memory manager
+frees the memory for a given class). For historical reasons, we may
+call a class with a destructor and a single field a "resource".
+
+A _class item_ declares a class type:
+
+~~~~
+class file_descriptor {
+    let fd: libc::c_int;
+    new(fd: libc::c_int) { self.fd = fd; }
+    drop { libc::close(self.fd); }
+}
+~~~~
+
+Calling the `file_descriptor` constructor function on an integer will
+produce a value with the `file_descriptor` type.
+
+_Fields_ are immutable by default, so instances of `file_descriptor`
+can't have their `fd` fields reassigned. A mutable field declaration
+looks like:
+
+~~~~
+    let mut fd: libc::c_int;
+~~~~
+
+The only exception is that the body of the class constructor begins
+with all the class's fields uninitialized, and is allowed to -- in
+fact, must -- initialize all the fields. The compiler enforces this
+invariant.
+
+Usually, the class constructor stores its argument or arguments in the
+class's named fields. In this case, the `file_descriptor`'s data field
+would be accessed like `f.fd`, if `f` is a value of type
+`file_descriptor`. By default, class fields are _public_: they can be
+accessed both from methods inside the class, and code outside the
+class. Classes can also have private fields:
+
+~~~~
+class file_descriptor {
+    let fd: *libc::FILE;
+    new(fd: *libc::FILE) {
+      self.fd = fd; self.name = none;
+    }
+    priv {
+      let mut name: option<~str>;
+    }
+    fn get_name() -> ~str {
+      match self.name {
+         none    => fail ~"File has no name!",
+         some(n) => n
+      }
+    }
+}
+~~~~
+
+Private fields are instance-private: methods in a class `C` can access
+`self`'s private fields, but not private fields of other values of
+type `C`. Code outside a class can't access any private fields.
+
+A class item may contain _methods_, which take an implicit `self`
+argument:
+
+~~~~
+class file_descriptor {
+    let fd: *libc::FILE;
+    new(fd: *libc::FILE) { self.fd = fd; }
+    fn flush() {
+       libc::fflush(self.fd);
+    }
+}
+~~~~
+
+In this case, ```open``` is a nullary method that calls the
+```fopen``` function, defined in another library, on the ```fd```
+field. As in this example, methods must refer to their self's fields
+as fields of ```self```; bare references to ```fd``` can't
+occur. Methods can be public or private; just like fields, they are
+public by default and private if enclosed in a `priv` section.
+
+Classes may be polymorphic:
+
+~~~~
+class file<A: copy> {
+  let data: A;
+  let fd: *libc::FILE;
+  new(data: A, fd: *libc::FILE) { self.data = data; self.fd = fd; }
+}
+~~~~
+
+Methods may also be polymorphic, and can have additional type
+parameters other than those bound in the class:
+
+~~~~
+class file<A: copy> {
+  let data: A;
+  let fd: *libc::FILE;
+  new(fd: *libc::FILE, data: A) { self.fd = fd; self.data = data; }
+  fn map_data<B>(f: fn(A) -> B) -> B {
+     f(self.data)
+  }
+}
+~~~~
+
+Classes do not support inheritance, except through traits. As a
+result, all class method dispatch is static (non-virtual).
+
+A class may implement a trait (see [traits](#traits)):
+
+~~~~
+trait to_str {
+  fn to_str() -> ~str;
+}
+
+class file : to_str {
+  let fd: *libc::FILE;
+  new(fd: *libc::FILE) { self.fd = fd; }
+  fn to_str() -> ~str { ~"a file" }
+}
+~~~~
+
+The syntax `class file: to_str` is pronounced "class `file`
+implements trait `to_str`".
+
+Class instances may be allocated on the stack, in the exchange heap,
+or on the task heap. A value with a class type ```C``` has a
+noncopyable [type kind](#type-kinds) if ```C``` has a destructor, and
+thus may not be copied. Class types that don't have destructors may be
+copied if all their fields are copyable.
+
+The semantics guarantee that for each constructed resource value, the
+destructor will run once: when the value is disposed of (barring
+drastic program termination that somehow prevents unwinding from
+taking place). For stack-allocated values, disposal happens when the
+value goes out of scope. For values in shared boxes, it happens when
+the reference count of the box reaches zero.
+
+The order of fields in a class instance is significant; its runtime
+representation is the same as that of a record with identical fields
+laid out in the same order.
+
 ### Traits
 
 A _trait item_ describes a set of method types. [_implementation
@@ -1204,7 +1348,7 @@ trait.  The methods in such an implementation can only be used
 statically (as direct calls on the values of the type that the
 implementation targets). In such an implementation, the `of` clause is
 not given, and the name is mandatory.  Such implementations are
-limited to nominal types (enums, structs) and the implementation must
+limited to nominal types (enums, classes) and the implementation must
 appear in the same module or a sub-module as the receiver type.
 
 _When_ a trait is specified, all methods declared as part of the
@@ -2600,9 +2744,9 @@ fn main() {
 In this example, the trait `printable` occurs as a type in both the type signature of
 `print`, and the cast expression in `main`.
 
-### Struct types
+### Class types
 
-Every struct item defines a type.
+Every class item defines a type. See [classes](#classes).
 
 ### Type parameters
 
@@ -2622,7 +2766,7 @@ type `~[B]`, a vector type with element type `B`.
 
 ### Self type
 
-The special type `self` has a meaning within methods inside an
+The special type `self` has a meaning within methods inside a class or
 impl item. It refers to the type of the implicit `self` argument. For
 example, in:
 
@@ -2637,7 +2781,19 @@ impl ~str: printable {
 ~~~~~~
 
 `self` refers to the value of type `str` that is the receiver for a
-call to the method `to_str`.
+call to the method `to_str`. Similarly, in a class declaration:
+
+~~~~~~
+class cat {
+  let mut meows: uint;
+  new() { self.meows = 0; }
+  fn meow() { self.meows = self.meows + 1; }
+}
+~~~~~~
+
+`self` refers to the class instance that is the receiver of the method
+(except in the constructor `new`, where `self` is the class instance
+that the constructor implicitly returns).
 
 ## Type kinds
 

branches/incoming/doc/tutorial.md

@@ -1560,7 +1560,7 @@ if favorite_crayon_name.len() > 5 {
 
 Named functions, like those we've seen so far, may not refer to local
 variables declared outside the function - they do not "close over
-their environment". For example, you couldn't write the following:
+their environment". For example you couldn't write the following:
 
 ~~~~ {.ignore}
 let foo = 10;
@@ -1821,6 +1821,85 @@ fn contains(v: ~[int], elt: int) -> bool {
 
 `for` syntax only works with stack closures.
 
+# Classes
+
+Rust lets users define new types with fields and methods, called 'classes', in
+the style of object-oriented languages.
+
+> ***Warning:*** Rust's classes are in the process of changing rapidly. Some more
+> information about some of the potential changes is [here][classchanges].
+
+[classchanges]: http://pcwalton.github.com/blog/2012/06/03/maximally-minimal-classes-for-rust/
+
+An example of a class:
+
+~~~~
+class example {
+  let mut x: int;
+  let y: int;
+
+  priv {
+    let mut private_member: int;
+    fn private_method() {}
+  }
+
+  new(x: int) {
+    // Constructor
+    self.x = x;
+    self.y = 7;
+    self.private_member = 8;
+  }
+
+  fn a() {
+    io::println(~"a");
+  }
+
+  drop {
+    // Destructor
+    self.x = 0;
+  }
+}
+
+fn main() {
+  let x: example = example(1);
+  let y: @example = @example(2);
+  x.a();
+  x.x = 5;
+}
+~~~~
+
+Fields and methods are declared just like functions and local variables, using
+'fn' and 'let'. As usual, 'let mut' can be used to create mutable fields. At
+minimum, Rust classes must have at least one field.
+
+Rust classes must also have a constructor, and can optionally have a destructor
+as well. The constructor and destructor are declared as shown in the example:
+like methods named 'new' and 'drop', but without 'fn', and without arguments
+for drop.
+
+In the constructor, the compiler will enforce that all fields are initialized
+before doing anything that might allow them to be accessed. This includes
+returning from the constructor, calling any method on 'self', calling any
+function with 'self' as an argument, or taking a reference to 'self'. Mutation
+of immutable fields is possible only in the constructor, and only before doing
+any of these things; afterwards it is an error.
+
+Private fields and methods are declared as shown above, using a `priv { ... }`
+block within the class. They are accessible only from within the same instance
+of the same class. (For example, even from within class A, you cannot call
+private methods, or access private fields, on other instances of class A; only
+on `self`.) This accessibility restriction may change in the future.
+
+As mentioned below, in the section on copying types, classes with destructors
+are considered 'resource' types and are not copyable.
+
+Declaring a class also declares its constructor as a function of the same name.
+You can construct an instance of the class, as in the example, by calling that
+function. The function and the type, though they have the same name, are
+otherwise independent. As with other Rust types, you can use `@` or `~` to
+construct a heap-allocated instance of a class, either shared or unique; just
+call e.g. `@example(...)` as shown above.
+
 # Argument passing
 
 Rust datatypes are not trivial to copy (the way, for example,
@@ -1859,13 +1938,6 @@ match my_rec {
 }
 ~~~~
 
-It's unsafe to dereference `b` in the second `log` expression, because `b` is
-a _pointer_ to the inside of `my_rec`, and the assignment statement has
-allocated a new record and assigned `my_rec` to point to it. Thus, the old
-contents of `my_rec` are no longer live, and `b` is dangling at this point.
-The borrow-checking analysis inside the compiler recognizes this situation
-and rejects the program.
-
 ## Argument passing styles
 
 The fact that arguments are conceptually passed by safe reference does