/****************************************************************************/
/*	Copyright (c) 2009, Bendor Research Pty. Ltd. All rights reserved.		*/
/*	This software is released under the GNU General Public License, version	*/
/*	3, with the exemptions that 1) the header files installed by this 	 	*/
/*	package can be included in closed-source code and 2) the libraries		*/
/*	built by this package can be statically linked into a closed-source 	*/
/*	binary. See the file LICENSE for the details.							*/
/*	This software is provided "AS IS", without any warranty or guarantee.	*/
/*	By using this software you acknowledge that neither Bendor Research nor	*/
/*	any of its personnel or affiliates can be held liable for any damages,	*/
/*	including, but not limited to, loss of business, loss of money, loss of */
/*	life, loss or reputation, arising out of this software being faulty or	*/
/*	not performing as advertised, even if Bendor Research was aware of such	*/
/*	faults in the software. You use this software at your own risk, any and */
/*	all liabilities that arise out of your using this software are strictly	*/
/*	yours.																	*/
/****************************************************************************/

#include <nanu-nanu.h>

/** @addtogroup nanu */
/** @{ */

/**
*	Rolls a given number of elements on the stack
*
*	Rotates the topmost n-1 elements of the stack. The signum of n determines
*	the direction of the rotation. If the number if positive, then all elements
*	from the top to the n-1 -th element will be pushed <i>down</i> so that the
*	top of the stack moves from position 0 to position 1, the element under it
*	from position 1 to 2 and so on, element n-1 moving to the n-th slot of
*	the stack. The n-th element is moving up to the 0-th position, vacated by
*	the topmost element. For a negative number the rotation is in the opposite
*	direction, the n-th element (where n is the absolute value of the argument)
*	will move up to the n-1 -th slot and so on, the 1st element moving to the
*	top while the former top element will move to the n-th slot.
*
*	Rolling 0 elements is a no-op and rolling 1 or -1 elements is the same
*	as BC_NanuSwap().
*
*	@param	nanu			The natural number machine state descriptor
*	@param	n				The index of the deepest element to roll
*
*	@retval	BC_NANU_NANU	The operation succeeded
*	@retval	BC_NANU_SUND	The stack does not have enough elements
*
*	@par Stack image
*		<i>In the image below k=|n|</i><br>
*		x<sub>0</sub> x<sub>1</sub> x<sub>2</sub> ...
*		x<sub>k-1</sub> x<sub>k</sub> ...  ==>
*		x<sub>k</sub> x<sub>0</sub> x<sub>1</sub> x<sub>2</sub> ...
*		x<sub>k-1</sub> ...	(n > 0)<br>
*		x<sub>0</sub> x<sub>1</sub> x<sub>2</sub> ...
*		x<sub>k-1</sub> x<sub>k</sub> ...  ==>
*		x<sub>1</sub> x<sub>2</sub> ...
*		x<sub>k-1</sub> x<sub>k</sub> x<sub>0</sub> ... (n < 0)
*/

int	BC_NanuRoll( BC_NANU nanu, int n )
{
	return( _bc_NanuError( nanu, _bc_NanuStkRol( nanu, n ) ) );
}

/** @} */

