C-GENERIC: When and when not to accept AsRef?

[masonk]

Why would I ever chose to write a function that takes &T when I could write a function that takes AsRef<T>?

It would help to discuss the pros and cons of these two options and give guidance. I think this would be in the Flexibility section, perhaps under C-GENERIC.

[BurntSushi]

Here are my thoughts:

1. Generics such as this can negatively influence compile times. IIRC, this can get bad enough where one might expose a function that uses AsRef<T>, but then internally calls a function defined only on &T, such that the amount of code duplication after monomorphization is minimal.
2. While AsRef<T> is about as simple as generics get, I still will prefer using simpler concrete types where practical.
3. AsRef can be very useful as a way of making APIs more flexible and ergonomic. For example, their use with methods on Path/PathBuf types is excellent, because it lets folks use string literals instead of needing to explicitly convert everything to a Path before hand. This turns out to be very useful in practice since it's fairly common to want to use a string literal with some of the various path methods.
4. When accepting an iterator of T, it's generally a good idea to accept an iterator of AsRef<T> instead (if you can). You're already paying the cost of generics by accepting an iterator, and the AsRef<T> can make things much more convenient.
5. AsRef (and AsMut) are also useful abstractions if you're hanging on to a value somewhere, but want the caller to be able to use either owned or borrowed versions of their value, when such things can be determined at compile time.