Related to #970. If you have opinions on the design or implementation of this function, please come join us in #970 before it is frozen for release.