# 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` on `Path`s that simply invoke the corresponding function in `std::io::fs`.
- Skipping through conversions. For example, the `str` type provides a `.len()` convenience method which is also expressible as `.as_bytes().len()`. Sometimes the conversion is more complex: the `str` module also provides `from_chars`, which encapsulates a simple use of iterators.
- Encapsulating common arguments. For example, vectors of `&str`s provide a `connect` as well as a special case, `concat`, that is expressible using `connect` with a fixed separator of `""`.

- Providing more efficient special cases. The `connect` and `concat` example also applies here: singling out `concat` as a special case allows for a more efficient implementation.

  Note, however, that the `connect` method actually detects the special case internally and invokes `concat`. 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` variants of methods that provide a `str` output, instead ensure that the normal output type of methods is easily convertible to `str`.
- Coherent: Look for small groups of convenience methods that make sense to include together. For example, the `Path` API mentioned above includes a small selection of the most common filesystem operations that take a `Path` 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.