// Underscore-contrib (underscore.array.builders.js 0.3.0)
// (c) 2013 Michael Fogus, DocumentCloud and Investigative Reporters & Editors
// Underscore-contrib may be freely distributed under the MIT license.

// Helpers
// -------

// Create quick reference variables for speed access to core prototypes.
var slice   = Array.prototype.slice;
var existy = function(x) { return x != null; };

// Mixing in the array builders
// ----------------------------

_.mixin({
  // Concatenates one or more arrays given as arguments.  If given objects and
  // scalars as arguments `cat` will plop them down in place in the result
  // array.  If given an `arguments` object, `cat` will treat it like an array
  // and concatenate it likewise.
  cat: function() {
    return _.flatten(arguments, true);
  },

  // 'Constructs' an array by putting an element at its front
  cons: function(head, tail) {
    return _.cat([head], tail);
  },

  // Takes an array and chunks it some number of times into
  // sub-arrays of size n.  Allows and optional padding array as
  // the third argument to fill in the tail chunk when n is
  // not sufficient to build chunks of the same size.
  chunk: function(array, n, pad) {
    var p = function(array) {
      if (array == null) return [];

      var part = _.take(array, n);

      if (n === _.size(part)) {
        return _.cons(part, p(_.drop(array, n)));
      }
      else {
        return pad ? [_.take(_.cat(part, pad), n)] : [];
      }
    };

    return p(array);
  },

  // Takes an array and chunks it some number of times into
  // sub-arrays of size n.  If the array given cannot fill the size
  // needs of the final chunk then a smaller chunk is used
  // for the last.
  chunkAll: function(array, n, step) {
    step = (step != null) ? step : n;

    var p = function(array, n, step) {
      if (_.isEmpty(array)) return [];

      return _.cons(_.take(array, n),
                    p(_.drop(array, step), n, step));
    };

    return p(array, n, step);
  },

  // Maps a function over an array and concatenates all of the results.
  mapcat: function(array, fun) {
    return _.flatten(_.map(array, fun), true);
  },

  // Returns an array with some item between each element
  // of a given array.
  interpose: function(array, inter) {
    if (!_.isArray(array)) throw new TypeError;
    var sz = _.size(array);
    if (sz === 0) return array;
    if (sz === 1) return array;

    return slice.call(_.mapcat(array, function(elem) {
      return _.cons(elem, [inter]);
    }), 0, -1);
  },

  // Weaves two or more arrays together
  weave: function(/* args */) {
    if (!_.some(arguments)) return [];
    if (arguments.length == 1) return arguments[0];

    return _.filter(_.flatten(_.zip.apply(null, arguments), true), function(elem) {
      return elem != null;
    });
  },
  interleave: _.weave,

  // Returns an array of a value repeated a certain number of
  // times.
  repeat: function(t, elem) {
    return _.times(t, function() { return elem; });
  },

  // Returns an array built from the contents of a given array repeated
  // a certain number of times.
  cycle: function(t, elems) {
    return _.flatten(_.times(t, function() { return elems; }), true);
  },

  // Returns an array with two internal arrays built from
  // taking an original array and spliting it at an index.
  splitAt: function(array, index) {
    return [_.take(array, index), _.drop(array, index)];
  },

  // Call a function recursively f(f(f(args))) until a second
  // given function goes falsey.  Expects a seed value to start.
  iterateUntil: function(doit, checkit, seed) {
    var ret = [];
    var result = doit(seed);

    while (checkit(result)) {
      ret.push(result);
      result = doit(result);
    }

    return ret;
  },

  // Takes every nth item from an array, returning an array of
  // the results.
  takeSkipping: function(array, n) {
    var ret = [];
    var sz = _.size(array);

    if (n <= 0) return [];
    if (n === 1) return array;

    for(var index = 0; index < sz; index += n) {
      ret.push(array[index]);
    }

    return ret;
  },

  // Returns an array of each intermediate stage of a call to
  // a `reduce`-like function.
  reductions: function(array, fun, init) {
    var ret = [];
    var acc = init;

    _.each(array, function(v,k) {
      acc = fun(acc, array[k]);
      ret.push(acc);
    });

    return ret;
  },

  // Runs its given function on the index of the elements rather than
  // the elements themselves, keeping all of the truthy values in the end.
  keepIndexed: function(array, pred) {
    return _.filter(_.map(_.range(_.size(array)), function(i) {
      return pred(i, array[i]);
    }),
    existy);
  },

  // Accepts an array-like object (other than strings) as an argument and
  // returns an array whose elements are in the reverse order. Unlike the
  // built-in `Array.prototype.reverse` method, this does not mutate the
  // original object. Note: attempting to use this method on a string will
  // result in a `TypeError`, as it cannot properly reverse unicode strings.
  reverseOrder: function(obj) {
    if (typeof obj == 'string')
      throw new TypeError('Strings cannot be reversed by _.reverseOrder');
    return slice.call(obj).reverse();
  },

  // Creates an array with all possible combinations of elements from
  // the given arrays
  combinations: function(){
    return _.reduce(slice.call(arguments, 1),function(ret,newarr){
      return _.reduce(ret,function(memo,oldi){
        return memo.concat(_.map(newarr,function(newi){
          return oldi.concat([newi]);
        }));
      },[]);
    },_.map(arguments[0],function(i){return [i];}));
  }

});