De-mode vec::each() and many of the str iteration routines

Note that the method foo.each() is not de-moded, nor the other
vec routines.

Author: nikomatsakis

doc/tutorial.md

@@ -1235,14 +1235,14 @@ let crayons = ~[Almond, AntiqueBrass, Apricot];
 assert crayons.len() == 3;
 assert !crayons.is_empty();
 
-// Iterate over a vector
+// Iterate over a vector, obtaining a pointer to each element
 for crayons.each |crayon| {
     let delicious_crayon_wax = unwrap_crayon(crayon);
     eat_crayon_wax(delicious_crayon_wax);
 }
 
 // Map vector elements
-let crayon_names = crayons.map(crayon_to_str);
+let crayon_names = crayons.map(|v| crayon_to_str(v));
 let favorite_crayon_name = crayon_names[0];
 
 // Remove whitespace from before and after the string
@@ -1384,40 +1384,44 @@ call_twice(bare_function);
 Closures in Rust are frequently used in combination with higher-order
 functions to simulate control structures like `if` and
 `loop`. Consider this function that iterates over a vector of
-integers, applying an operator to each:
+integers, passing in a pointer to each integer in the vector:
 
 ~~~~
-fn each(v: ~[int], op: fn(int)) {
+fn each(v: ~[int], op: fn(v: &int)) {
    let mut n = 0;
    while n < v.len() {
-       op(v[n]);
+       op(&v[n]);
        n += 1;
    }
 }
 ~~~~
 
-As a caller, if we use a closure to provide the final operator
-argument, we can write it in a way that has a pleasant, block-like
-structure.
+The reason we pass in a *pointer* to an integer rather than the
+integer itself is that this is how the actual `each()` function for
+vectors works.  Using a pointer means that the function can be used
+for vectors of any type, even large records that would be impractical
+to copy out of the vector on each iteration.  As a caller, if we use a
+closure to provide the final operator argument, we can write it in a
+way that has a pleasant, block-like structure.
 
 ~~~~
-# fn each(v: ~[int], op: fn(int)) {}
+# fn each(v: ~[int], op: fn(v: &int)) { }
 # fn do_some_work(i: int) { }
 each(~[1, 2, 3], |n| {
-    debug!("%i", n);
-    do_some_work(n);
+    debug!("%i", *n);
+    do_some_work(*n);
 });
 ~~~~
 
 This is such a useful pattern that Rust has a special form of function
 call that can be written more like a built-in control structure:
 
 ~~~~
-# fn each(v: ~[int], op: fn(int)) {}
+# fn each(v: ~[int], op: fn(v: &int)) { }
 # fn do_some_work(i: int) { }
 do each(~[1, 2, 3]) |n| {
-    debug!("%i", n);
-    do_some_work(n);
+    debug!("%i", *n);
+    do_some_work(*n);
 }
 ~~~~
 
@@ -1461,10 +1465,10 @@ Consider again our `each` function, this time improved to
 break early when the iteratee returns `false`:
 
 ~~~~
-fn each(v: ~[int], op: fn(int) -> bool) {
+fn each(v: ~[int], op: fn(v: &int) -> bool) {
    let mut n = 0;
    while n < v.len() {
-       if !op(v[n]) {
+       if !op(&v[n]) {
            break;
        }
        n += 1;
@@ -1478,7 +1482,7 @@ And using this function to iterate over a vector:
 # use each = vec::each;
 # use println = io::println;
 each(~[2, 4, 8, 5, 16], |n| {
-    if n % 2 != 0 {
+    if *n % 2 != 0 {
         println(~"found odd number!");
         false
     } else { true }
@@ -1495,7 +1499,7 @@ to the next iteration, write `again`.
 # use each = vec::each;
 # use println = io::println;
 for each(~[2, 4, 8, 5, 16]) |n| {
-    if n % 2 != 0 {
+    if *n % 2 != 0 {
         println(~"found odd number!");
         break;
     }
@@ -1511,7 +1515,7 @@ function, not just the loop body.
 # use each = vec::each;
 fn contains(v: ~[int], elt: int) -> bool {
     for each(v) |x| {
-        if (x == elt) { return true; }
+        if (*x == elt) { return true; }
     }
     false
 }
@@ -1529,9 +1533,9 @@ every type they apply to. Thus, Rust allows functions and datatypes to have
 type parameters.
 
 ~~~~
-fn map<T, U>(vector: &[T], function: fn(T) -> U) -> ~[U] {
+fn map<T, U>(vector: &[T], function: fn(v: &T) -> U) -> ~[U] {
     let mut accumulator = ~[];
-    for vector.each |element| {
+    for vec::each(vector) |element| {
         vec::push(accumulator, function(element));
     }
     return accumulator;
@@ -1544,7 +1548,12 @@ type of the vector's content agree with each other.
 
 Inside a generic function, the names of the type parameters
 (capitalized by convention) stand for opaque types. You can't look
-inside them, but you can pass them around.
+inside them, but you can pass them around.  Note that instances of
+generic types are almost always passed by pointer.  For example, the
+parameter `function()` is supplied with a pointer to a value of type
+`T` and not a value of type `T` itself.  This ensures that the
+function works with the broadest set of types possible, since some
+types are expensive or illegal to copy and pass by value.
 
 ## Generic datatypes
 
@@ -1686,12 +1695,12 @@ generalized sequence types is:
 ~~~~
 trait Seq<T> {
     fn len() -> uint;
-    fn iter(fn(T));
+    fn iter(b: fn(v: &T));
 }
 impl<T> ~[T]: Seq<T> {
     fn len() -> uint { vec::len(self) }
-    fn iter(b: fn(T)) {
-        for self.each |elt| { b(elt); }
+    fn iter(b: fn(v: &T)) {
+        for vec::each(self) |elt| { b(elt); }
     }
 }
 ~~~~
@@ -2186,7 +2195,7 @@ Here is the function that implements the child task:
 ~~~~
 # use std::comm::DuplexStream;
 # use pipes::{Port, Chan};
-fn stringifier(channel: DuplexStream<~str, uint>) {
+fn stringifier(channel: &DuplexStream<~str, uint>) {
     let mut value: uint;
     loop {
         value = channel.recv();
@@ -2210,7 +2219,7 @@ Here is the code for the parent task:
 # use std::comm::DuplexStream;
 # use pipes::{Port, Chan};
 # use task::spawn;
-# fn stringifier(channel: DuplexStream<~str, uint>) {
+# fn stringifier(channel: &DuplexStream<~str, uint>) {
 #     let mut value: uint;
 #     loop {
 #         value = channel.recv();
@@ -2223,7 +2232,7 @@ Here is the code for the parent task:
 let (from_child, to_child) = DuplexStream();
 
 do spawn || {
-    stringifier(to_child);
+    stringifier(&to_child);
 };
 
 from_child.send(22u);

src/cargo/cargo.rs

@@ -1502,7 +1502,7 @@ fn print_source(s: source) {
     print(io::with_str_writer(|writer| {
         let mut list = ~"   >> ";
 
-        do vec::iteri(pks) |i, pk| {
+        for vec::eachi(pks) |i, pk| {
             if str::len(list) > 78u {
                 writer.write_line(list);
                 list = ~"   >> ";
@@ -1518,16 +1518,17 @@ fn cmd_list(c: &cargo) {
     sync(c);
 
     if vec::len(c.opts.free) >= 3u {
-        do vec::iter_between(c.opts.free, 2u, vec::len(c.opts.free)) |name| {
-            if !valid_pkg_name(name) {
-                error(fmt!("'%s' is an invalid source name", name));
+        let v = vec::view(c.opts.free, 2u, vec::len(c.opts.free));
+        for vec::each(v) |name| {
+            if !valid_pkg_name(*name) {
+                error(fmt!("'%s' is an invalid source name", *name));
             } else {
-                match c.sources.find(name) {
+                match c.sources.find(*name) {
                     Some(source) => {
                         print_source(source);
                     }
                     None => {
-                        error(fmt!("no such source: %s", name));
+                        error(fmt!("no such source: %s", *name));
                     }
                 }
             }

src/compiletest/runtest.rs

@@ -425,8 +425,8 @@ fn compose_and_run_compiler(
     let extra_link_args = ~[~"-L",
                             aux_output_dir_name(config, testfile).to_str()];
 
-    do vec::iter(props.aux_builds) |rel_ab| {
-        let abs_ab = config.aux_base.push_rel(&Path(rel_ab));
+    for vec::each(props.aux_builds) |rel_ab| {
+        let abs_ab = config.aux_base.push_rel(&Path(*rel_ab));
         let aux_args =
             make_compile_args(config, props, ~[~"--lib"] + extra_link_args,
                               |a,b| make_lib_name(a, b, testfile), &abs_ab);

src/libcore/at_vec.rs

@@ -91,7 +91,7 @@ pure fn build_sized_opt<A>(size: Option<uint>,
 #[inline(always)]
 pure fn append<T: Copy>(lhs: @[T], rhs: &[const T]) -> @[T] {
     do build_sized(lhs.len() + rhs.len()) |push| {
-        for vec::each(lhs) |x| { push(x); }
+        for vec::each(lhs) |x| { push(*x); }
         for uint::range(0, rhs.len()) |i| { push(rhs[i]); }
     }
 }
@@ -101,7 +101,7 @@ pure fn append<T: Copy>(lhs: @[T], rhs: &[const T]) -> @[T] {
 pure fn map<T, U>(v: &[T], f: fn(T) -> U) -> @[U] {
     do build_sized(v.len()) |push| {
         for vec::each(v) |elem| {
-            push(f(elem));
+            push(f(*elem));
         }
     }
 }

src/libcore/cast.rs

@@ -4,7 +4,7 @@ export reinterpret_cast, forget, bump_box_refcount, transmute;
 export transmute_mut, transmute_immut, transmute_region, transmute_mut_region;
 export transmute_mut_unsafe, transmute_immut_unsafe;
 
-export copy_lifetime;
+export copy_lifetime, copy_lifetime_vec;
 
 #[abi = "rust-intrinsic"]
 extern mod rusti {
@@ -85,8 +85,9 @@ unsafe fn copy_lifetime<S,T>(_ptr: &a/S, ptr: &T) -> &a/T {
 }
 
 /// Transforms lifetime of the second pointer to match the first.
-unsafe fn copy_lifetime_to_unsafe<S,T>(_ptr: &a/S, +ptr: *T) -> &a/T {
-    transmute(ptr)
+#[inline(always)]
+unsafe fn copy_lifetime_vec<S,T>(_ptr: &a/[S], ptr: &T) -> &a/T {
+    transmute_region(ptr)
 }
 
 

src/libcore/either.rs

@@ -34,7 +34,7 @@ fn lefts<T: Copy, U>(eithers: &[Either<T, U>]) -> ~[T] {
 
     let mut result: ~[T] = ~[];
     for vec::each(eithers) |elt| {
-        match elt {
+        match *elt {
           Left(l) => vec::push(result, l),
           _ => { /* fallthrough */ }
         }
@@ -47,7 +47,7 @@ fn rights<T, U: Copy>(eithers: &[Either<T, U>]) -> ~[U] {
 
     let mut result: ~[U] = ~[];
     for vec::each(eithers) |elt| {
-        match elt {
+        match *elt {
           Right(r) => vec::push(result, r),
           _ => { /* fallthrough */ }
         }
@@ -67,7 +67,7 @@ fn partition<T: Copy, U: Copy>(eithers: &[Either<T, U>])
     let mut lefts: ~[T] = ~[];
     let mut rights: ~[U] = ~[];
     for vec::each(eithers) |elt| {
-        match elt {
+        match *elt {
           Left(l) => vec::push(lefts, l),
           Right(r) => vec::push(rights, r)
         }

src/libcore/hash.rs

@@ -390,7 +390,9 @@ impl &SipState : Streaming {
     fn result_str() -> ~str {
         let r = self.result_bytes();
         let mut s = ~"";
-        for vec::each(r) |b| { s += uint::to_str(b as uint, 16u); }
+        for vec::each(r) |b| {
+            s += uint::to_str(*b as uint, 16u);
+        }
         move s
     }
 
@@ -483,7 +485,9 @@ fn test_siphash() {
 
     fn to_hex_str(r:  &[u8]/8) -> ~str {
         let mut s = ~"";
-        for vec::each(*r) |b| { s += uint::to_str(b as uint, 16u); }
+        for vec::each(*r) |b| {
+            s += uint::to_str(*b as uint, 16u);
+        }
         return s;
     }
 

src/libcore/io.rs

@@ -451,7 +451,7 @@ fn mk_file_writer(path: &Path, flags: ~[FileFlag])
 
     let mut fflags: c_int = wb();
     for vec::each(flags) |f| {
-        match f {
+        match *f {
           Append => fflags |= O_APPEND as c_int,
           Create => fflags |= O_CREAT as c_int,
           Truncate => fflags |= O_TRUNC as c_int,

src/libcore/iter-trait/dvec.rs

@@ -7,7 +7,12 @@ type IMPL_T<A> = dvec::DVec<A>;
  * Attempts to access this dvec during iteration will fail.
  */
 pure fn EACH<A>(self: IMPL_T<A>, f: fn(A) -> bool) {
-    unsafe { self.swap(|v| { vec::each(v, f); move v }) }
+    unsafe {
+        do self.swap |v| {
+            v.each(f);
+            move v
+        }
+    }
 }
 
 pure fn SIZE_HINT<A>(self: IMPL_T<A>) -> Option<uint> {