the one and only public function of this module. It takes any string and munges
it according to the options. By default it uses a random encoding.


@param {String} str any string to munge, for example 'spacemonkey@moon.com'
@param {Object} options for munging
@param options.encoding can be 'ascii', 'utf8' or 'random' (default)
@return {String} the munged string
@api public
function munge(str, options) {

    var aMunged = [];
    var aChars, i;

    //  initialize default options
    options = options || {};

    if (options.encoding) {
        // validate encoding option

        if (encoder.TYPES.indexOf(options.encoding) < 0)
            throw Error('Invalid encoding option given: ' + options.encoding);
    } else
        options.encoding = encoder.DEFAULT;

    if (str) {

        aChars = str.split('');

        for (i in aChars)
            aMunged[i] = '&#' + encoder[options.encoding](aChars[i]) + ';';
    }

    return aMunged.join('');
}