/*
 * jQuery Array - A collection of jQuery plugins to make jQuery objects behave
 * more like a Javascript Array
 *
 * Based on work by the jQuery Community (http://www.nabble.com/.each-backwards---tf2399145.html#a6690114)
 * and Kenton Simpson (http://www.brainknot.com/code/jQarray.js)
 *
 * Copyright (c) 2007 Paul McLanahan, Kenton Simpson
 *
 * Dual licensed under the MIT and GPL licenses:
 *   http://www.opensource.org/licenses/mit-license.php
 *   http://www.gnu.org/licenses/gpl.html
 *
 * Revision: $Id$
 *
 * Version: 0.1
 */
 
/**
 * Reverse the order elements appear in the jQuery element collection
 *
 * @example $("li").reverse().each(function(i) {
 *   $(this).prepend(i+": ");
 * });
 * @before <li>First Item</li>
 * <li>Second Item</li>
 * <li>Third Item</li>
 * @result <li>2: First Item</li>
 * <li>1: Second Item</li>
 * <li>0: Third Item</li>
 *
 * @name reverse
 * @type jQuery
 * @param Boolean destruct If true this function will act distructively on a cached jQuery object.
 * @cat Plugins/Array
 */
jQuery.fn.reverse = function(destruct) {
	return this[destruct?'setArray':'pushStack'](this.get().reverse());
};

/**
 * Sort the order elements appear in the jQuery element collection
 *
 * @example $("li").sort(function( a, b ){
 *   return( parseInt( a.innerHTML ) - parseInt( b.innerHTML ) );
 * });
 *
 * @name sort
 * @type jQuery
 * @param Function fn Sort function to act on jQuery element collection.
 * @param Boolean destruct If true this function will act distructively on a cached jQuery object.
 * @cat Plugins/Array
 */
jQuery.fn.sort = function(fn,destruct) {
	return this[destruct?'setArray':'pushStack'](this.get().sort(fn));
};

/**
 * Randomize the order of the elements in the current jQuery element collection.
 * Note: Does not affect the order of elements in the DOM.
 *
 * @example $("li").randomize();
 *
 * @name randomize
 * @type jQuery
 * @param Boolean destruct If true, this function will act distructively on a cached jQuery object.
 * @cat Plugins/Array
 */
jQuery.fn.randomize = function(destruct){
	return this.sort( function(){return(Math.round(Math.random())-0.5)}, destruct );
};

/**
 * Take a slice out of the current jQuery element collection
 *
 * @example $li = $("li").slice(2, 6).hide();
 * @result $li.length == 4
 *
 * @name slice
 * @type jQuery
 * @param Int Start of slice
 * @param Int End of slice
 * @param Boolean destruct If true, this function will act distructively on a cached jQuery object
 * @cat Plugins/Array
 */
jQuery.fn.slice = function(start,end,destruct) {
	return this[destruct?'setArray':'pushStack']( this.get().slice(start,end) );
};

/**
 * Remove the last element in the jQuery element collection and disregard
 * Note: This does not return the popped element, which is unlike the native Array.pop
 * Javascript function. It returns a jQuery object to maintain chainability. See
 * returnObject parameter for a workaround.
 *
 * @example $('li').pop().length == $('li').length - 1
 *
 * @name shift
 * @type jQuery
 * @param Boolean destruct If true, this function will act distructively on a cached jQuery object
 * @param Object returnObject If supplied the object will be extended with a "pop" property containing the popped element
 * @cat Plugins/Array
 */
jQuery.fn.pop = function(destruct,returnObject){
	if(returnObject)jQuery.extend(returnObject,{pop:this[this.length-1]});
	return this.slice( 0, -1, destruct );
};

/**
 * Remove the first element in the jQuery element collection and disregard
 * Note: This does not return the shifted element, which is unlike the native Array.shift
 * Javascript function. It returns a jQuery object to maintain chainability. See
 * returnObject parameter for a workaround.
 *
 * @example $('li').shift()[0] == 2nd <li> found
 *
 * @name shift
 * @type jQuery
 * @param Boolean destruct If true, this function will act distructively on a cached jQuery object
 * @param Object returnObject If supplied the object will be extended with a "shift" property containing the shifted element
 * @cat Plugins/Array
 */
jQuery.fn.shift = function(destruct,returnObject){
	if(returnObject)jQuery.extend(returnObject,{shift:this[0]});
	return this.slice( 1, this.length, destruct );
};

/**
 * Move the first jQuery element to the last
 *
 * @example $('li').rotate()[0] == 2nd <li> found
 *
 * @name rotate
 * @type jQuery
 * @param Boolean destruct If true, this function will act distructively on a cached jQuery object
 * @cat Plugins/Array
 */
jQuery.fn.rotate = function(destruct){
	var a = this.get();
	a.push(a.shift());
	return this[destruct?'setArray':'pushStack']( a );
};

/**
 * Move the last jQuery element to the first
 *
 * @example $('li').rrotate()[0] == last <li> found
 *
 * @name rrotate
 * @type jQuery
 * @param Boolean destruct If true, this function will act distructively on a cached jQuery object
 * @cat Plugins/Array
 */
jQuery.fn.rrotate = function(destruct){
  var a = this.get();
  a.unshift(a.pop());
  return this[destruct?'setArray':'pushStack']( a );
};