# Paramater and Return stack utilities

A collection of words for manipulating the parameter stack.

## PS "to" semantics

In the spirit of local variables [doc/usage/rs], this unit supplies PS1 PS2 PS3
and PS4 which obey "to" semantics and target PS instead of RS.

These words are trickier to use than local variables, but they can be pretty
useful sometimes. For example, a "swap 1+ swap" pattern (increasing second
element of PS by 1) can be replaced with "to1+ PS1".

Things to remember when using these:

1. Dusk has a top of stack register. PS1 refers to *second* element of PS.
2. Be mindful of the elements placed on PS right before you "use" PS{1,2,3,4}.
   For example, "3 to+ PS1" might not do what you think it does because the "3"
   part pushes top of stack to PS right before the operation.
3. In the implementation of "to" words that result in nipping an element from
   PS, this nipping always happens after the "main" operation. For example,
   "3 to+ PS1" might do what you think it does.
4. So, what does "3 to+ PS1" does? Effectively, the equivalent of "3 +" (but
   less efficient). It adds top of stack to second top of stack, then does a
   "drop" of the "3" that was pushed previously.

So yeah, tricky to use, but might be quite useful sometimes to avoid tricky
stack juggling.

## API

dipdup ( a b -- a a b )
  Equivalent of "dip dup |" but faster and not involving RS.

dipswap ( a b c -- b a c )
  Equivalent of "dip swap |".

dipnip ( a b c -- b c )
  Equivalent of "dip nip |".

dipover ( a b c -- a b a c )
  Equivalent of "dip over |".

dig ( ... n -- ... val )
  Copy the nth value of PS to top of stack. "0 dig" is the equivalent of "dup",
  "1 dig", of "over".

roll ( ... n -- ... )
  Rotate n elements of the stack to the "left". "0 roll" is the equivalent of
  "swap", "1 roll" of "rot".

roll> ( ... n -- ... )
  Rotate n elements of the stack to the "right". "0 roll>" is the equivalent of
  "swap", "1 roll>" of "rot>".

rswap ( R: a b -- R: b a )
  Swap RS' top elements
