auto merge of #19252 : japaric/rust/cow, r=aturon

- Add `IntoCow` trait, and put it in the prelude
- Add `is_owned`/`is_borrowed` methods to `Cow`
- Add `CowString`/`CowVec` type aliases (to `Cow<'_, String, str>`/`Cow<'_, Vec, [T]>` respectively)
- `Cow` implements: `Show`, `Hash`, `[Partial]{Eq,Ord}`
- `impl BorrowFrom<Cow<'a, T, B>> for B`

[breaking-change]s:

- `IntoMaybeOwned` has been removed from the prelude
- libcollections: `SendStr` is now an alias to `CowString<'static>` (it was aliased to `MaybeOwned<'static>`)
- libgraphviz:
  - `LabelText` variants now wrap `CowString` instead of `MaybeOwned`
  - `Nodes` and `Edges` are now type aliases to `CowVec` (they were aliased to `MaybeOwnedVec`)
- libstd/path: `Display::as_maybe_owned` has been renamed to `Display::as_cow` and now returns a `CowString`
- These functions now accept/return `Cow` instead of `MaybeOwned[Vector]`:
  - libregex: `Replacer::reg_replace`
  - libcollections: `str::from_utf8_lossy`
  - libgraphviz: `Id::new`, `Id::name`, `LabelText::pre_escaped_content`
  - libstd: `TaskBuilder::named`

r? @aturon

Author: bors

lib.rs

@@ -37,7 +37,7 @@ pairs of ints, representing the edges (the node set is implicit).
 Each node label is derived directly from the int representing the node,
 while the edge labels are all empty strings.
 
-This example also illustrates how to use `MaybeOwnedVector` to return
+This example also illustrates how to use `CowVec` to return
 an owned vector or a borrowed slice as appropriate: we construct the
 node vector from scratch, but borrow the edge list (rather than
 constructing a copy of all the edges from scratch).
@@ -48,7 +48,6 @@ which is cyclic.
 
 ```rust
 use graphviz as dot;
-use graphviz::maybe_owned_vec::IntoMaybeOwnedVector;
 
 type Nd = int;
 type Ed = (int,int);
@@ -77,12 +76,12 @@ impl<'a> dot::GraphWalk<'a, Nd, Ed> for Edges {
         }
         nodes.sort();
         nodes.dedup();
-        nodes.into_maybe_owned()
+        nodes.into_cow()
     }
 
     fn edges(&'a self) -> dot::Edges<'a,Ed> {
         let &Edges(ref edges) = self;
-        edges.as_slice().into_maybe_owned()
+        edges.as_slice().into_cow()
     }
 
     fn source(&self, e: &Ed) -> Nd { let &(s,_) = e; s }
@@ -137,8 +136,8 @@ edges stored in `self`.
 Since both the set of nodes and the set of edges are always
 constructed from scratch via iterators, we use the `collect()` method
 from the `Iterator` trait to collect the nodes and edges into freshly
-constructed growable `Vec` values (rather use the `into_maybe_owned`
-from the `IntoMaybeOwnedVector` trait as was used in the first example
+constructed growable `Vec` values (rather use the `into_cow`
+from the `IntoCow` trait as was used in the first example
 above).
 
 The output from this example renders four nodes that make up the
@@ -148,7 +147,6 @@ entity `&sube`).
 
 ```rust
 use graphviz as dot;
-use std::str;
 
 type Nd = uint;
 type Ed<'a> = &'a (uint, uint);
@@ -168,10 +166,10 @@ impl<'a> dot::Labeller<'a, Nd, Ed<'a>> for Graph {
         dot::Id::new(format!("N{}", n)).unwrap()
     }
     fn node_label<'a>(&'a self, n: &Nd) -> dot::LabelText<'a> {
-        dot::LabelStr(str::Slice(self.nodes[*n].as_slice()))
+        dot::LabelStr(self.nodes[*n].as_slice().into_cow())
     }
     fn edge_label<'a>(&'a self, _: &Ed) -> dot::LabelText<'a> {
-        dot::LabelStr(str::Slice("&sube;"))
+        dot::LabelStr("&sube;".into_cow())
     }
 }
 
@@ -204,7 +202,6 @@ Hasse-diagram for the subsets of the set `{x, y}`.
 
 ```rust
 use graphviz as dot;
-use std::str;
 
 type Nd<'a> = (uint, &'a str);
 type Ed<'a> = (Nd<'a>, Nd<'a>);
@@ -225,10 +222,10 @@ impl<'a> dot::Labeller<'a, Nd<'a>, Ed<'a>> for Graph {
     }
     fn node_label<'a>(&'a self, n: &Nd<'a>) -> dot::LabelText<'a> {
         let &(i, _) = n;
-        dot::LabelStr(str::Slice(self.nodes[i].as_slice()))
+        dot::LabelStr(self.nodes[i].as_slice().into_cow())
     }
     fn edge_label<'a>(&'a self, _: &Ed<'a>) -> dot::LabelText<'a> {
-        dot::LabelStr(str::Slice("&sube;"))
+        dot::LabelStr("&sube;".into_cow())
     }
 }
 
@@ -279,8 +276,8 @@ pub fn main() {
 pub use self::LabelText::*;
 
 use std::io;
-use std::str;
-use self::maybe_owned_vec::MaybeOwnedVector;
+use std::str::CowString;
+use std::vec::CowVec;
 
 pub mod maybe_owned_vec;
 
@@ -290,7 +287,7 @@ pub enum LabelText<'a> {
     ///
     /// Occurrences of backslashes (`\`) are escaped, and thus appear
     /// as backslashes in the rendered label.
-    LabelStr(str::MaybeOwned<'a>),
+    LabelStr(CowString<'a>),
 
     /// This kind of label uses the graphviz label escString type:
     /// http://www.graphviz.org/content/attrs#kescString
@@ -302,7 +299,7 @@ pub enum LabelText<'a> {
     /// to break a line (centering the line preceding the `\n`), there
     /// are also the escape sequences `\l` which left-justifies the
     /// preceding line and `\r` which right-justifies it.
-    EscStr(str::MaybeOwned<'a>),
+    EscStr(CowString<'a>),
 }
 
 // There is a tension in the design of the labelling API.
@@ -339,7 +336,7 @@ pub enum LabelText<'a> {
 
 /// `Id` is a Graphviz `ID`.
 pub struct Id<'a> {
-    name: str::MaybeOwned<'a>,
+    name: CowString<'a>,
 }
 
 impl<'a> Id<'a> {
@@ -357,10 +354,10 @@ impl<'a> Id<'a> {
     ///
     /// Passing an invalid string (containing spaces, brackets,
     /// quotes, ...) will return an empty `Err` value.
-    pub fn new<Name:str::IntoMaybeOwned<'a>>(name: Name) -> Result<Id<'a>, ()> {
-        let name = name.into_maybe_owned();
+    pub fn new<Name: IntoCow<'a, String, str>>(name: Name) -> Result<Id<'a>, ()> {
+        let name = name.into_cow();
         {
-            let mut chars = name.as_slice().chars();
+            let mut chars = name.chars();
             match chars.next() {
                 Some(c) if is_letter_or_underscore(c) => { ; },
                 _ => return Err(())
@@ -383,10 +380,10 @@ impl<'a> Id<'a> {
     }
 
     pub fn as_slice(&'a self) -> &'a str {
-        self.name.as_slice()
+        &*self.name
     }
 
-    pub fn name(self) -> str::MaybeOwned<'a> {
+    pub fn name(self) -> CowString<'a> {
         self.name
     }
 }
@@ -421,7 +418,7 @@ pub trait Labeller<'a,N,E> {
     /// default is in fact the empty string.
     fn edge_label(&'a self, e: &E) -> LabelText<'a> {
         let _ignored = e;
-        LabelStr(str::Slice(""))
+        LabelStr("".into_cow())
     }
 }
 
@@ -454,11 +451,11 @@ impl<'a> LabelText<'a> {
     /// yields same content as self.  The result obeys the law
     /// render(`lt`) == render(`EscStr(lt.pre_escaped_content())`) for
     /// all `lt: LabelText`.
-    fn pre_escaped_content(self) -> str::MaybeOwned<'a> {
+    fn pre_escaped_content(self) -> CowString<'a> {
         match self {
             EscStr(s) => s,
-            LabelStr(s) => if s.as_slice().contains_char('\\') {
-                str::Owned(s.as_slice().escape_default())
+            LabelStr(s) => if s.contains_char('\\') {
+                s.escape_default().into_cow()
             } else {
                 s
             },
@@ -476,12 +473,12 @@ impl<'a> LabelText<'a> {
         let suffix = suffix.pre_escaped_content();
         prefix.push_str(r"\n\n");
         prefix.push_str(suffix.as_slice());
-        EscStr(str::Owned(prefix))
+        EscStr(prefix.into_cow())
     }
 }
 
-pub type Nodes<'a,N> = MaybeOwnedVector<'a,N>;
-pub type Edges<'a,E> = MaybeOwnedVector<'a,E>;
+pub type Nodes<'a,N> = CowVec<'a,N>;
+pub type Edges<'a,E> = CowVec<'a,E>;
 
 // (The type parameters in GraphWalk should be associated items,
 // when/if Rust supports such.)
@@ -496,7 +493,7 @@ pub type Edges<'a,E> = MaybeOwnedVector<'a,E>;
 /// that is bound by the self lifetime `'a`.
 ///
 /// The `nodes` and `edges` method each return instantiations of
-/// `MaybeOwnedVector` to leave implementers the freedom to create
+/// `CowVec` to leave implementers the freedom to create
 /// entirely new vectors or to pass back slices into internally owned
 /// vectors.
 pub trait GraphWalk<'a, N, E> {
@@ -512,7 +509,7 @@ pub trait GraphWalk<'a, N, E> {
 
 /// Renders directed graph `g` into the writer `w` in DOT syntax.
 /// (Main entry point for the library.)
-pub fn render<'a, N:'a, E:'a, G:Labeller<'a,N,E>+GraphWalk<'a,N,E>, W:Writer>(
+pub fn render<'a, N:Clone+'a, E:Clone+'a, G:Labeller<'a,N,E>+GraphWalk<'a,N,E>, W:Writer>(
               g: &'a G,
               w: &mut W) -> io::IoResult<()>
 {
@@ -647,12 +644,12 @@ mod tests {
         }
         fn node_label(&'a self, n: &Node) -> LabelText<'a> {
             match self.node_labels[*n] {
-                Some(ref l) => LabelStr(str::Slice(l.as_slice())),
+                Some(ref l) => LabelStr(l.into_cow()),
                 None        => LabelStr(id_name(n).name()),
             }
         }
         fn edge_label(&'a self, e: & &'a Edge) -> LabelText<'a> {
-            LabelStr(str::Slice(e.label.as_slice()))
+            LabelStr(e.label.into_cow())
         }
     }
 

maybe_owned_vec.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#![deprecated = "use std::vec::CowVec"]
+
 pub use self::MaybeOwnedVector::*;
 
 use std::default::Default;
@@ -46,12 +48,16 @@ pub trait IntoMaybeOwnedVector<'a,T> {
     fn into_maybe_owned(self) -> MaybeOwnedVector<'a,T>;
 }
 
+#[allow(deprecated)]
 impl<'a,T:'a> IntoMaybeOwnedVector<'a,T> for Vec<T> {
+    #[allow(deprecated)]
     #[inline]
     fn into_maybe_owned(self) -> MaybeOwnedVector<'a,T> { Growable(self) }
 }
 
+#[allow(deprecated)]
 impl<'a,T> IntoMaybeOwnedVector<'a,T> for &'a [T] {
+    #[allow(deprecated)]
     #[inline]
     fn into_maybe_owned(self) -> MaybeOwnedVector<'a,T> { Borrowed(self) }
 }
@@ -66,6 +72,7 @@ impl<'a,T> MaybeOwnedVector<'a,T> {
 
     pub fn len(&self) -> uint { self.as_slice().len() }
 
+    #[allow(deprecated)]
     pub fn is_empty(&self) -> bool { self.len() == 0 }
 }
 
@@ -114,6 +121,7 @@ impl<'b,T> AsSlice<T> for MaybeOwnedVector<'b,T> {
 }
 
 impl<'a,T> FromIterator<T> for MaybeOwnedVector<'a,T> {
+    #[allow(deprecated)]
     fn from_iter<I:Iterator<T>>(iterator: I) -> MaybeOwnedVector<'a,T> {
         // If we are building from scratch, might as well build the
         // most flexible variant.
@@ -143,6 +151,7 @@ impl<'a,T:Clone> CloneSliceAllocPrelude<T> for MaybeOwnedVector<'a,T> {
 }
 
 impl<'a, T: Clone> Clone for MaybeOwnedVector<'a, T> {
+    #[allow(deprecated)]
     fn clone(&self) -> MaybeOwnedVector<'a, T> {
         match *self {
             Growable(ref v) => Growable(v.clone()),
@@ -152,6 +161,7 @@ impl<'a, T: Clone> Clone for MaybeOwnedVector<'a, T> {
 }
 
 impl<'a, T> Default for MaybeOwnedVector<'a, T> {
+    #[allow(deprecated)]
     fn default() -> MaybeOwnedVector<'a, T> {
         Growable(Vec::new())
     }