adding ability to specify total as a function, and adding example of giv...

...ing complete control of the data to the caller