---

yaml
---
r: 149986
b: refs/heads/try2
c: bf67783
h: refs/heads/master
v: v3

Author: alexcrichton

[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: 1d828eb3a4f63c38231c1fdc0aa2197a9b2a333f
+refs/heads/try2: bf67783332ff9f9bdf40da2d9dff860964600420
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/mk/crates.mk

@@ -37,7 +37,7 @@
 #
 #   DEPS_<crate>
 #	These lists are the dependencies of the <crate> that is to be built.
-#	Rust dependencies are listed bare (i.e. std, green) and native
+#	Rust dependencies are listed bare (i.e. std, extra, green) and native
 #	dependencies have a "native:" prefix (i.e. native:sundown). All deps
 #	will be built before the crate itself is built.
 #
@@ -49,23 +49,23 @@
 # automatically generated for all stage/host/target combinations.
 ################################################################################
 
-TARGET_CRATES := std green rustuv native flate arena glob term semver \
-                 uuid serialize sync getopts collections num test time rand \
-		 workcache url
+TARGET_CRATES := std extra green rustuv native flate arena glob term semver \
+                 uuid serialize sync getopts collections num test time rand
 HOST_CRATES := syntax rustc rustdoc fourcc hexfloat
 CRATES := $(TARGET_CRATES) $(HOST_CRATES)
 TOOLS := compiletest rustdoc rustc
 
 DEPS_std := native:rustrt native:compiler-rt native:backtrace
+DEPS_extra := std term sync serialize getopts collections time rand
 DEPS_green := std rand native:context_switch
 DEPS_rustuv := std native:uv native:uv_support
 DEPS_native := std
 DEPS_syntax := std term serialize collections
 DEPS_rustc := syntax native:rustllvm flate arena serialize sync getopts \
-              collections time
+              collections time extra
 DEPS_rustdoc := rustc native:sundown serialize sync getopts collections \
                 test time
-DEPS_flate := std native:miniz
+DEPS_flate := std extra native:miniz
 DEPS_arena := std collections
 DEPS_glob := std
 DEPS_serialize := std collections
@@ -78,11 +78,9 @@ DEPS_collections := std rand
 DEPS_fourcc := syntax std
 DEPS_hexfloat := syntax std
 DEPS_num := std rand
-DEPS_test := std collections getopts serialize term time
+DEPS_test := std extra collections getopts serialize term
 DEPS_time := std serialize
 DEPS_rand := std
-DEPS_url := std collections
-DEPS_workcache := std serialize collections std
 
 TOOL_DEPS_compiletest := test green rustuv getopts
 TOOL_DEPS_rustdoc := rustdoc native

branches/try2/src/doc/index.md

@@ -50,8 +50,6 @@ li {list-style-type: none; }
 * [The `test` library containing the unit-testing & micro-benchmark framework](test/index.html)
 * [The `time` library](time/index.html)
 * [The `uuid` 128-bit universally unique identifier library](uuid/index.html)
-* [The `url` library](url/index.html)
-* [The `workcache` library](workcache/index.html)
 
 # Tooling
 

branches/try2/src/doc/rust.md

@@ -787,9 +787,9 @@ Four examples of `extern crate` declarations:
 ~~~~ {.ignore}
 extern crate pcre;
 
-extern crate std; // equivalent to: extern crate std = "std";
+extern crate extra; // equivalent to: extern crate extra = "extra";
 
-extern crate ruststd = "std"; // linking to 'std' under another name
+extern crate rustextra = "extra"; // linking to 'extra' under another name
 
 extern crate foo = "some/where/rust-foo#foo:1.0"; // a full package ID for external tools
 ~~~~

branches/try2/src/doc/tutorial.md

@@ -3228,6 +3228,17 @@ See the [API documentation][stddoc] for details.
 
 [stddoc]: std/index.html
 
+## The extra library
+
+Rust ships with crates such as the [extra library], an accumulation of useful things,
+that are however not important enough to deserve a place in the standard
+library.  You can link to a library such as `extra` with an `extern crate extra;`.
+
+[extra library]: extra/index.html
+
+Right now `extra` contains those definitions directly, but in the future it will likely just
+re-export a bunch of 'officially blessed' crates that get managed with a package manager.
+
 # What next?
 
 Now that you know the essentials, check out any of the additional

branches/try2/src/etc/combine-tests.py

@@ -56,6 +56,7 @@ def scrub(b):
 #[feature(globs, macro_rules, struct_variant, managed_boxes)];
 #[allow(warnings)];
 extern crate collections;
+extern crate extra;
 """
 )
 for t in stage2_tests:
@@ -72,6 +73,7 @@ def scrub(b):
 """
 // AUTO-GENERATED FILE: DO NOT EDIT
 #[feature(globs, managed_boxes)];
+extern crate extra;
 extern crate run_pass_stage2;
 use run_pass_stage2::*;
 use std::io;

branches/try2/src/etc/generate-deriving-span-tests.py

@@ -38,6 +38,7 @@
 // This file was auto-generated using 'src/etc/generate-keyword-span-tests.py'
 
 #[feature(struct_variant)];
+extern crate extra;
 extern crate rand;
 
 {error_deriving}

branches/try2/src/libextra/c_vec.rs

@@ -0,0 +1,240 @@
+// Copyright 2012 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+/*!
+ * Library to interface with chunks of memory allocated in C.
+ *
+ * It is often desirable to safely interface with memory allocated from C,
+ * encapsulating the unsafety into allocation and destruction time.  Indeed,
+ * allocating memory externally is currently the only way to give Rust shared
+ * mut state with C programs that keep their own references; vectors are
+ * unsuitable because they could be reallocated or moved at any time, and
+ * importing C memory into a vector takes a one-time snapshot of the memory.
+ *
+ * This module simplifies the usage of such external blocks of memory.  Memory
+ * is encapsulated into an opaque object after creation; the lifecycle of the
+ * memory can be optionally managed by Rust, if an appropriate destructor
+ * closure is provided.  Safety is ensured by bounds-checking accesses, which
+ * are marshalled through get and set functions.
+ *
+ * There are three unsafe functions: the two constructors, and the
+ * unwrap method. The constructors are unsafe for the
+ * obvious reason (they act on a pointer that cannot be checked inside the
+ * method), but `unwrap()` is somewhat more subtle in its unsafety.
+ * It returns the contained pointer, but at the same time destroys the CVec
+ * without running its destructor. This can be used to pass memory back to
+ * C, but care must be taken that the ownership of underlying resources are
+ * handled correctly, i.e. that allocated memory is eventually freed
+ * if necessary.
+ */
+
+use std::cast;
+use std::ptr;
+use std::raw;
+
+/**
+ * The type representing a foreign chunk of memory
+ */
+pub struct CVec<T> {
+    priv base: *mut T,
+    priv len: uint,
+    priv rsrc: DtorRes,
+}
+
+struct DtorRes {
+    dtor: Option<proc()>,
+}
+
+#[unsafe_destructor]
+impl Drop for DtorRes {
+    fn drop(&mut self) {
+        let dtor = self.dtor.take();
+        match dtor {
+            None => (),
+            Some(f) => f()
+        }
+    }
+}
+
+impl DtorRes {
+    fn new(dtor: Option<proc()>) -> DtorRes {
+        DtorRes {
+            dtor: dtor,
+        }
+    }
+}
+
+impl <T> CVec<T> {
+    /**
+     * Create a `CVec` from a raw pointer to a buffer with a given length.
+     *
+     * Fails if the given pointer is null.
+     *
+     * # Arguments
+     *
+     * * base - A raw pointer to a buffer
+     * * len - The number of elements in the buffer
+     */
+    pub unsafe fn new(base: *mut T, len: uint) -> CVec<T> {
+        assert!(base != ptr::mut_null());
+        CVec {
+            base: base,
+            len: len,
+            rsrc: DtorRes::new(None)
+        }
+    }
+
+    /**
+     * Create a `CVec` from a foreign buffer, with a given length,
+     * and a function to run upon destruction.
+     *
+     * Fails if the given pointer is null.
+     *
+     * # Arguments
+     *
+     * * base - A foreign pointer to a buffer
+     * * len - The number of elements in the buffer
+     * * dtor - A proc to run when the value is destructed, useful
+     *          for freeing the buffer, etc.
+     */
+    pub unsafe fn new_with_dtor(base: *mut T, len: uint, dtor: proc()) -> CVec<T> {
+        assert!(base != ptr::mut_null());
+        CVec {
+            base: base,
+            len: len,
+            rsrc: DtorRes::new(Some(dtor))
+        }
+    }
+
+    /// View the stored data as a slice.
+    pub fn as_slice<'a>(&'a self) -> &'a [T] {
+        unsafe {
+            cast::transmute(raw::Slice { data: self.base as *T, len: self.len })
+        }
+    }
+
+    /// View the stored data as a mutable slice.
+    pub fn as_mut_slice<'a>(&'a mut self) -> &'a mut [T] {
+        unsafe {
+            cast::transmute(raw::Slice { data: self.base as *T, len: self.len })
+        }
+    }
+
+    /**
+     * Retrieves an element at a given index
+     *
+     * Fails if `ofs` is greater or equal to the length of the vector
+     */
+    pub fn get<'a>(&'a self, ofs: uint) -> &'a T {
+        assert!(ofs < self.len);
+        unsafe {
+            &*self.base.offset(ofs as int)
+        }
+    }
+
+    /**
+     * Retrieves a mutable element at a given index
+     *
+     * Fails if `ofs` is greater or equal to the length of the vector
+     */
+    pub fn get_mut<'a>(&'a mut self, ofs: uint) -> &'a mut T {
+        assert!(ofs < self.len);
+        unsafe {
+            &mut *self.base.offset(ofs as int)
+        }
+    }
+
+    /**
+     * Unwrap the pointer without running the destructor
+     *
+     * This method retrieves the underlying pointer, and in the process
+     * destroys the CVec but without running the destructor. A use case
+     * would be transferring ownership of the buffer to a C function, as
+     * in this case you would not want to run the destructor.
+     *
+     * Note that if you want to access the underlying pointer without
+     * cancelling the destructor, you can simply call `transmute` on the return
+     * value of `get(0)`.
+     */
+    pub unsafe fn unwrap(mut self) -> *mut T {
+        self.rsrc.dtor = None;
+        self.base
+    }
+}
+
+impl <T> Container for CVec<T> {
+    /// Returns the length of the vector
+    fn len(&self) -> uint { self.len }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use std::libc::*;
+    use std::libc;
+    use std::ptr;
+    use std::rt::global_heap::malloc_raw;
+
+    fn malloc(n: uint) -> CVec<u8> {
+        unsafe {
+            let mem = malloc_raw(n);
+
+            CVec::new_with_dtor(mem as *mut u8, n,
+                proc() { libc::free(mem as *mut c_void); })
+        }
+    }
+
+    #[test]
+    fn test_basic() {
+        let mut cv = malloc(16);
+
+        *cv.get_mut(3) = 8;
+        *cv.get_mut(4) = 9;
+        assert_eq!(*cv.get(3), 8);
+        assert_eq!(*cv.get(4), 9);
+        assert_eq!(cv.len(), 16);
+    }
+
+    #[test]
+    #[should_fail]
+    fn test_fail_at_null() {
+        unsafe {
+            CVec::new(ptr::mut_null::<u8>(), 9);
+        }
+    }
+
+    #[test]
+    #[should_fail]
+    fn test_overrun_get() {
+        let cv = malloc(16);
+
+        cv.get(17);
+    }
+
+    #[test]
+    #[should_fail]
+    fn test_overrun_set() {
+        let mut cv = malloc(16);
+
+        *cv.get_mut(17) =  0;
+    }
+
+    #[test]
+    fn test_unwrap() {
+        unsafe {
+            let cv = CVec::new_with_dtor(1 as *mut int, 0,
+                proc() { fail!("Don't run this destructor!") });
+            let p = cv.unwrap();
+            assert_eq!(p, 1 as *mut int);
+        }
+    }
+
+}