this is nontrivial enough that it could use an example in the docstring.