Tipping Cows, a Primer on Rust’s Most Bovine Data Structure

If we run over to the Zoo of Rust's Creatures, we find a Cow in captivity:

1
2
3
4
5
6
7

pub enum Cow<'a, B>
where
    B: 'a + ToOwned + ?Sized,
 {
    Borrowed(&'a B),
    Owned(<B as ToOwned>::Owned),
}

The zoo helpfully informs us,

 _________________________________________
/ The type Cow is a smart pointer         \
| providing clone-on-write functionality: |
| it can enclose and provide immutable    |
| access to borrowed data, and clone the  |
| data lazily when mutation or ownership  |
| is required. The type is designed to    |
| work with general borrowed data via the |
\ Borrow trait.                           /
 -----------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Moo. That's a lot to parse. There's roughly three concepts baked into that definition:

• What is clone-on-write functionality, and what's the diff to copy-on-write
• Why this elitist smart pointer
• Where do lifetimes enter in

If you know the answer to all of those questions, you can probably skip ahead to examples. Don't know? Read on!

Let's start with why we care about these concepts: what do we win if we collect them all? Well, in simplest form, we win an runtime optimization technique, for when the data we're handling will sometimes be acceptable to immutably borrow (which is cheap), but other times will have to be owned, which would happen if we had to mutate the data in some way. Back to the concepts.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// u32 implements Copy
let i : u32 = 42;
let i_copy = i; // copy occurs implicitly
println!("Can use original int and copy: {}, {}", i, i_copy);

let i_clone = i.clone();
println!("Can use original int and clone: {}, {}", i, i_clone);

// String implements Clone but not Copy.
let s: String::From("Don't Panic")
let s_clone = s.clone();
println!("Can use original string and clone: {}, {}", s, s_clone);

// this will fail, since String does not implement Copy
// let copy_s = s;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

use std::borrow::Cow;
fn lazy_abs(input: &mut Cow<[i32]>) {
  for i in 0..input.len(){
    let v = input[i];
		if v < 0 {
		  // Clone into vector if not already owned
			input.to_mut()[i] = -v;
		}
	}
}

1
2
3
4
5
6
7
8

pub enum Cow<'a, B> // Cow doesn't outlive data with lifetime 'a
where
    // if Cow takes ownership, stay with the herd, keep lifetime 'a
    B: 'a + ToOwned + ?Sized,
 {
    Borrowed(&'a B), // Borrow a generic reference to data B, with lifetime 'a
    Owned(<B as ToOwned>::Owned), // We haven't gotten here yet.
}

You made it this far cowpoke. Hold onto your milk, because it's time for a pop quiz.

Suppose we've got a struct containing an immutable generic vector. How would we update it to wrap a Cow?

1
2
3
4
5
6
7
8
9

struct VecWrapper<T> {
  v: Vec<T>,
}

impl<T> VecWrapper<T>{
  fn new(v: Vec<T>) -> Self{
    VecWrapper{ v }
  }
}

Well, for starters, we're going to need to import Cow, add lifetimes, and modify some definitions. Let's sprinkle lifetimes everywhere a generic definition appears, and wrap our Vector in a Cow.

1
2
3
4
5
6
7
8
9

use std::borrow::Cow;
struct VecWrapper<'a, T>{
  v: Cow<'a, Vec<T>>,
}
impl<'a, T> VecWrapper<'a, T>{
  fn new(v: Cow<'a, Vec<T>>) -> Self{
    VecWrapper{ v }
  }
}

error[E0277]: the trait bound `T: std::clone::Clone` is not satisfied
   --> src/lib.rs:5:3
    |
5   |   v: Cow<'a, Vec<T>>,
    |   ^^^^^^^^^^^^^^^^^^ the trait `std::clone::Clone` is not implemented for `T`
    |
    = note: required because of the requirements on the impl of `std::clone::Clone` for `std::vec::Vec<T>`
    = note: required because of the requirements on the impl of `std::borrow::ToOwned` for `std::vec::Vec<T>`
help: consider restricting type parameter `T`
    |
2   | struct VecWrapper<'a, T: std::clone::Clone>
    |                        ^^^^^^^^^^^^^^^^^^^
...

Well, it was a noble first try. In the wise words of Rust Sage Gankra, "It should be noted that the authentic Rust learning experience involves writing code, having the compiler scream at you, and trying to figure out what the heck that means." We're living that dream. But the rust compiler is actually pretty helpful here. We need to put a trait bound on T, so that our pet Cow can clone T if and when it needs to.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

use std::borrow::Cow;
struct VecWrapper<'a, T: Clone>
where T: Clone
{
  v: Cow<'a, Vec<T>>,
}

impl<'a, T> VecWrapper<'a, T>
where T: Clone
{
  fn new(v: Cow<'a, Vec<T>>) -> Self{
    VecWrapper{ v }
  }
}

warning: struct is never constructed: `VecWrapper`
 --> src/lib.rs:2:8
  |
2 | struct VecWrapper<'a, T: Clone>
  |        ^^^^^^^^^^
  |
  = note: `#[warn(dead_code)]` on by default
...

Success! If we wanted to take our implementation one step further, the documentation gives an example of wrapping a generic array with a Cow, which would require a couple more trait bounds.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

use std::borrow::Cow
struct Items<'a, X: 'a> where [X]: ToOwned<Owned = Vec<X>> {
    values: Cow<'a, [X]>,
}

impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned<Owned = Vec<X>> {
    fn new(v: Cow<'a, [X]>) -> Self {
        Items { values: v }
    }
}

Which ends up looking pretty close to our vector wrapper, but since the Vec type implements ToOwned for us and the array doesn't, a we'd have to implement `ToOwned` for our generic array by hand.

Alright, so there's a lot more that can be done with Cows than we got into here. But I'm hoping this was enough of a prod to get you up and mooving with cows. Thanks for joining me, and best of luck in all your future Rust endeavors.

Documentation std::borrow::Cow

Smart Pointers Wikipedia

Secret Life of Cows