Convenience methods

Provide small, coherent sets of convenience methods. [FIXME: needs RFC]

Convenience methods wrap up existing functionality in a more convenient way. The work done by a convenience method varies widely:

• Re-providing functions as methods. For example, the std::path::Path type provides methods like stat`staton` on Path`Paths that simply invoke the corresponding function instd::io::fs`.
• Skipping through conversions. For example, the str`strtype provides a.len()convenience method which is also expressible as.as_bytes().len(). Sometimes the conversion is more complex: thestrmodule also providesfrom_chars`, which encapsulates a simple use of iterators.
• Encapsulating common arguments. For example, vectors of &str`&strs provide aconnectas well as a special case,concat, that is expressible usingconnectwith a fixed separator of""`.

• Providing more efficient special cases. The connect`connectand` and concat`concatexample also applies here: singling outconcat` as a special case allows for a more efficient implementation.

  Note, however, that the connect`connectmethod actually detects the special case internally and invokesconcat`. Usually, it is not necessary to add a public convenience method just for efficiency gains; there should also be a conceptual reason to add it, e.g. because it is such a common special case.

It is tempting to add convenience methods in a one-off, haphazard way as common use patterns emerge. Avoid this temptation, and instead design small, coherent sets of convenience methods that are easy to remember:

• Small: Avoid combinatorial explosions of convenience methods. For example, instead of adding _str`_strvariants of methods that provide astroutput, instead ensure that the normal output type of methods is easily convertible tostr`.
• Coherent: Look for small groups of convenience methods that make sense to include together. For example, the Path`PathAPI mentioned above includes a small selection of the most common filesystem operations that take aPath` argument. If one convenience method strongly suggests the existence of others, consider adding the whole group.
• Memorable: It is not worth saving a few characters of typing if you have to look up the name of a convenience method every time you use it. Add convenience methods with names that are obvious and easy to remember, and add them for the most common or painful use cases.