cleaning up some function names, adding some documentation, and doing a refactoring.  Also adding a utility function.  need to add tests and examples etc.