Cow is... not misleadingly named, exactly, because the copy-on-write functionality is important and forms a large part of the interface. But I feel like it sells short the true power of the type.

Cow is essentially* this:

enum Cow<T> {
    Borrowed(&T),
    Owned(T),
}

It's an enum that lets you choose whether you want the borrowed or owned version of a type, and it's in cases where that choice is important that the type is most useful / powerful.

My favorite example is a hypothetical JSON parser. Consider JSON, read from a file into a Vec<u8>, containing JSON strings. Most of the time the actual bytes in the file of the string are a perfectly accurate representation of how Rust will treat the string, which means a parser could return a &str representing a slice of the original file. On the other hand, if there are any escaped characters (\n, etc), that won't suffice; the JSON parser needs to turn those into real code points in a string. This means that the borrowed version won't suffice, you need a real String to be built. This is where Cow shines; it allows a rust function to say "I'm going to return either a borrowed form of this data or an owned form, I'm not sure which.

A great real-life example is shell_escape::escape. This pretty much does exactly what I just described: it processes a string to make it safe for use in a shell. Most of the time, the string can be returned unchanged, but if any changes need to be made (adding escaped spaces, for example) then it needs to return a String containing the corrections.

Like I said, I don't want to undersell the usefulness of the copy-on-write functionality. But when considering types for your use case, Cow should be what you reach for to express "either a reference or an owned type".

* The real definition of Cow is slightly more general; it allows you to express things like Borrowed(&str) / Owned(String), whereas my example would require something like Borrowed(&String) / Owned(String). But the idea is the same. Similarly, to answer your other questions, ToOwned is like the slightly more general version of Clone. Clone requires the new object to have an identical type as the old one, whereas ToOwned can represent a &str → String or &[u8] → Vec<u8>, in addition to inheriting the &T → T behavior of Clone.

My main use case for `Cow` is avoiding (string) copies. Consider

fn how_many_potions(num: usize) -> std::borrow::Cow<'static, str> {
    match num {
        0 => "out of potions".into(),
        1 => "last potion".into(),
        _ => format!("{} potions remaining", num).into()
    }
}

Essentially, we want to return a String here, but there are cases in which we can do better because we actually have a &'static str containing the data, so we don't need to allocate and copy a brand new String for this purpose.

This is exactly what Cow is for.

Does this example make sense to you?

I'm going to paraphrase what I picked up from other comments here as I've also been struggling to understand this. Please let me know if this is wrong:

It's useful for when you maybe need to mutate a string. If your function returns a &str then you couldn't mutate it, if it returns a String then you have to allocate memory for no reason. A Cow allows the best of both worlds. It allows expressions to type check because it's an enum.

Just like Result is maybe success, Option is maybe exists, Cow is maybe mutation-needed.

Look at holy Cow.

This is one of the main reason quick-xml / quick-protobuf are fast too.

Thanks everyone for the kind responses!

1. I don't understand this question

2. Cow allows sharing data. If I have 10 Cow's referencing the static string of data I only have 1 copy of that data. With RefCell you'll have 10 copies assuming that it's a RefCell<String> versus Cow<'static, str>

3. In a card game engine I have skills which are an enum. On instances there's a mapping HashMap<Event, Cow<'static, [Skill]>>. There's a statically generated list of cards which have a &'static [Skill] which is easily inserted into this HashMap without copying the list. If the list is modified by some effect then it gets converted to an owned Cow. I tend to have lots of clones of game state, so this provides value in two ways: cloning a reference is cheap & a cloned reference doesn't multiply the memory usage by the size of the slice. It's also useful in effects where I add a skill as a plain Cow::from(&[Skill::constantthing])

Another example of how Cow could be used: imagine you're parsing JSON. If the Cow only needs to live as long as the JSON string, then you could have Cow<'a, str> reference substrings of the JSON string. For "asdf" this works. But if you have "qu\"ote" then you'll want the Cow to be an owned String qu"ote since you don't want the reference qu\"ote. This allows you to be nearly zero copy