Convenience methods wrap up existing functionality in a more convenient way. The work done by a convenience method varies widely:
std::path::Path
type
provides methods like stat
on Path
s that simply invoke the corresponding
function in std::io::fs
.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.&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:
_str
variants of methods that provide a str
output,
instead ensure that the normal output type of methods is easily convertible to
str
.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.